3D Visualizer — Python, CLI and MCP

Inspect point clouds, meshes and calibrated depth data in Python, notebooks or an AI conversation. The package is 3d-visualizer, the Python import is viz3d, and the CLI is 3d-visualizer. Python 3.10+ is required.

This checkout targets the next release. The public 0.4.2 package still uses the older import. For the new interface before publication, build the viewer and install ./packages/python with the extras you need.

Agent installation

These examples target 0.5.0.dev0. Development versions must be installed from this checkout until published; do not assume an unreleased version exists on PyPI.

For agents, use uv tool install or uvx; uv add is for using the library inside a Python project. Headless mode also needs Chromium installed once.

uv tool install "3d-visualizer[mcp,headless]==0.5.0.dev0"
uvx --from "3d-visualizer[headless]==0.5.0.dev0" playwright install chromium
3d-visualizer doctor --check-headless

Client configuration (replace the data directory):

{
  "mcpServers": {
    "3d-visualizer": {
      "command": "uvx",
      "args": [
        "--from",
        "3d-visualizer[mcp,headless]==0.5.0.dev0",
        "3d-visualizer-mcp",
        "--root",
        "/absolute/path/to/data"
      ]
    }
  }
}

Install in VS Code

The VS Code link uses the current workspace as the allowed data root.

claude mcp add --transport stdio 3d-visualizer -- uvx --from "3d-visualizer[mcp,headless]==0.5.0.dev0" 3d-visualizer-mcp --root /absolute/path/to/data

The default --tools core exposes eight everyday tools. Use --tools full for depth conversion, selections, animation, alignment and export. --renderer auto uses an advertised MCP Apps host, otherwise offscreen Chromium. Use --renderer inline to require a widget or explicit browser; use --renderer headless for unattended work.

Unattended Python rendering

With the headless extra and Chromium installed:

from pathlib import Path
from viz3d import show

with show("scan.ply", headless=True) as view:
    state = view.inspect(detail="full")
    Path("preview.png").write_bytes(view.capture())

This uses offscreen Chromium and the shared renderer. It requires no notebook, chat widget or visible browser window. Inspect and capture raise on renderer failure instead of returning a placeholder success.

Install with uv (recommended)

Install uv, then choose:

uv add 3d-visualizer            # Add to a Python project
uv add "3d-visualizer[notebook]" # Local notebook display support
uv pip install 3d-visualizer    # Install into an existing virtual environment
uv tool install 3d-visualizer   # Install the CLI independently
uvx --from 3d-visualizer 3d-visualizer scan.ply  # Run without persistent installation

The Python import is from viz3d import show. Tool installation does not add the library to a Python project or notebook kernel; use uv add or uv pip install in that environment. No Node.js build is needed for PyPI installs.

For local Jupyter, run uv run --with jupyter jupyter lab from your project and select its Python kernel. Keep that kernel alive while using the viewer.

Developing from source

From the repository root, build the bundled engine with Node 24:

npm ci
npm run build:python-viewer
uv tool install ./packages/python
# Or add the local library to your Python project:
uv add /absolute/path/to/checkout/packages/python

See publishing setup for releases.

Alternative: install with pip from this repository

After building the browser assets above:

python3 -m venv packages/python/.venv
packages/python/.venv/bin/python -m pip install ./packages/python
packages/python/.venv/bin/3d-visualizer engine/examples/example-point-cloud.ply

On Windows, replace the environment's bin/ paths with Scripts/, e.g. packages\python\.venv\Scripts\python.exe, 3d-visualizer.exe, or jupyter.exe. After activating the environment, the command is simply:

3d-visualizer scan.ply mesh.stl
3d-visualizer --no-browser scan.ply
python -m viz3d scan.ply

The command prints a local URL and keeps running until Ctrl+C. --no-browser allows an agent or another application to open that URL itself. It does not render an image or report successful browser rendering to the caller.

Python

from viz3d import show

# In an interactive Python session or local notebook:
viewer = show("scan.ply", "mesh.stl")
print(viewer.url)
# Later:
viewer.close()

from viz3d import show

# Lists, iterables, NumPy arrays, and PyTorch tensors with shape (N, 3) work.
points = [[0, 0, 0], [1, 0, 0], [0, 1, 0]]
colors = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]

# In a script, keep Python alive while the viewer is in use.
with show(points, colors=colors) as viewer:
    print(viewer.url)
    try:
        viewer.wait()
    except KeyboardInterrupt:
        pass

Coordinates must be finite float32-compatible numbers. Optional colors must match the point count and contain integer RGB values in 0..255. Point arrays are serialized to a temporary binary PLY, decoded by the existing engine, and removed when the session closes. This first implementation serializes arrays row by row; it is not a zero-copy transport for very large arrays.

NumPy and PyTorch

Pass arrays and tensors directly, including RGB colors:

import numpy as np
from viz3d import show

viewer = show(np.random.default_rng(0).normal(size=(1000, 3)))

import torch
from viz3d import show

device = "cuda" if torch.cuda.is_available() else (
    "mps" if torch.backends.mps.is_available() else "cpu"
)
points = torch.randn(1000, 3, device=device, requires_grad=True)
rgb = torch.randint(0, 256, (1000, 3), device=device, dtype=torch.uint8)
viewer = show(points, colors=rgb)
# No manual .detach(), .cpu(), or .numpy() needed.
# Keep Python alive and call viewer.close() when finished.

• NumPy arrays can be transposed, sliced, read-only, or non-contiguous.
• PyTorch inputs can be CPU or GPU tensors, detached or attached to autograd. Both coordinates and colors are handled independently, so mixing devices or NumPy/PyTorch inputs works. Float16 and bfloat16 tensors are supported.
• Visualization detaches internally, transfers to CPU, and serializes a snapshot. The original device, values, requires_grad, and autograd graph are unchanged. GPU-to-CPU transfer synchronizes; avoid calling this every training step.
• PyTorch conversion does not depend on NumPy. CPU rows are converted in bounded chunks rather than performing a GPU scalar read for every coordinate.
• Inputs must be real, dense (N, 3) data. For (B, N, 3) batches, use show(batch[0]); batches are deliberately not flattened automatically. Sparse, quantized, complex, nested, and data-free meta tensors are rejected with an error. RGB retains the integer-valued 0..255 convention, including floating-point tensors; normalized RGB can be passed as (rgb * 255).round().

Training previews

All updates reuse the same browser tab/inline view and preserve its camera. The viewer receives change notifications and loads the newest revision; intermediate revisions can be skipped. Publish at a useful training interval, not every forward pass. Serialization and GPU transfer are synchronous. Updates replace the scene; manual files added to that scene are also replaced on the next update.

viewer = show(initial_points)

# In your training loop, e.g. every 100 steps:
if step % 100 == 0:
    viewer.update(prediction[0], target=target[0], step=step)

Prediction is orange and target cyan. Supply colors= to override prediction RGB. Targets may have a different number of points. This is a geometric overlay, not a computed nearest-neighbor error metric. Visibility can be toggled in the standard file panel. Use Pause updates to inspect one revision and Fit scene to reset the framing explicitly.

Batch and augmentation inspection

from viz3d import show_batch

viewer = show_batch(batch, target=target_batch)
viewer.update_batch(next_batch, target=next_targets, step=step)

# A list of differently sized point arrays also works:
viewer = show_batch([original, augmented], labels=["Original", "Augmented"])

The sample selector switches batches in one scene and retains the camera. Colors, targets, and vectors (when supplied) must match the batch size. Batch snapshots serialize every sample; select a small inspection subset for large training batches. Only the chosen sample is loaded by the browser.

Gradient and displacement arrows

# After loss.backward(); non-leaf predictions need retain_grad() beforehand.
viewer.update(
    points,
    vectors=points.grad,
    vector_scale=-learning_rate,
    max_vectors=256,
    step=step,
)

Arrows are anchored at the corresponding input points. Negative learning-rate scaling shows a plain gradient-descent direction; it is not an exact Adam or momentum optimizer step. To inspect the actual update, pass measured coordinate displacements instead. Nonzero arrows are magenta. Up to max_vectors evenly spaced vectors are displayed (default 256, maximum 2000). All supplied vector rows are validated; no autograd hooks or gradient computation are installed by this operation.

Layer inspection with a removable forward hook

viewer = show(initial_points)
with viewer.inspect_layer(model, select=lambda output: output[0], every=100):
    train(model)

For dictionary outputs use a selector such as lambda output: output["points"][0]. The selector must return (N, 3) coordinates, not arbitrary feature channels. The hook captures the first forward call and then every every calls. It returns None, preserving the model's output. A visualization error disables the hook, emits a warning and is accessible as inspection.error; it does not invalidate training. The context manager removes the hook, while the caller owns the viewer session's lifetime. inspection.close() also removes it explicitly.

Run viewer updates in the main process, on one rank in distributed training, and outside compiled model code. GPU-to-CPU transfer introduces synchronization. PyTorch forward hooks.

The server binds only to 127.0.0.1, uses a random session URL, and serves only the explicitly supplied files and bundled viewer assets. Source files remain on your machine; the package does not upload them. Keep file paths available for the life of the session. Do not share the session URL with untrusted code.

Inline Jupyter notebooks

In a local Jupyter notebook, return the viewer as the last expression in a cell. Browser auto-opening is disabled when a notebook kernel is detected:

viewer = show(points)
viewer  # Interactive viewer appears in the output cell.

Or display explicitly, using the notebook extra:

viewer.display(height=480, ui="collapsed")

Settings are collapsed by default. A compact toolbar keeps Settings, Fit scene, Pause updates, and the batch selector accessible. Choose ui="full" to show settings immediately or ui="none" for a presentation-only canvas with mouse controls. In UI-free mode, batch selection is unavailable; choose the sample in Python before displaying it.

viewer.update(...) updates every open view, including notebook output. Keep the kernel running, call viewer.close() when done, and do not call viewer.wait() in a cell. Notebook output contains a live local iframe, not an offline saved scene. Reopen the session after restarting the kernel.

This initial inline transport requires the browser and kernel on the same machine and a notebook host that permits local iframes. Remote Jupyter, Colab, and notebook environments that block local iframe URLs need a widget/proxy transport; they are not supported by this transport yet.

For a mature widget-based alternative, K3D supports notebook point clouds and other 3D primitives. Rerun is worth considering for recorded, time-based diagnostics. This package embeds the existing 3D viewer to retain its file formats and interaction controls.

Current scope

• Supported inputs: PLY, XYZ, XYZN, XYZRGB, PCD, PTS, OBJ, STL, OFF, GLB, LAS/LAZ, E57, SPZ, SPLAT, KSPLAT, and SOG.
• Multiple files appear together in one scene.
• OBJ input currently provides geometry; automatic sidecar material/texture resolution and external-resource glTF are outside this preview.
• No separate image-viewer integration or desktop launch integration yet. The shared 3D viewer retains its existing manual controls and depth-conversion features.

Build a distributable wheel

npm run build:python-viewer
packages/python/.venv/bin/python -m pip wheel --no-deps ./packages/python --wheel-dir /tmp/3d-visualizer-wheels

The wheel includes the browser engine and its assets. Install that wheel on another machine with python -m pip install /path/to/the.whl; no Node.js or Tauri installation is necessary there. Build assets before packaging.

Verify

npm run test:python-viewer
# Also test actual NumPy/PyTorch inputs in the isolated environment:
packages/python/.venv/bin/python -m pip install numpy torch
packages/python/.venv/bin/python -m unittest discover -s packages/python/tests -v
cd engine
npx playwright test local-session.spec.ts --reporter=line

The browser test requires npm run build:python-viewer and the existing engine test server assets in engine/dist (npm run build --workspace=engine). Array tests skip optional libraries and GPU backends that are unavailable.

Available platforms

• VS Code Marketplace: Install extension
• Open VSX: Install extension
• Website: 3d.f-kleinicke.de
• PyPI (Python and CLI): 3d-visualizer
• JetBrains: Signed preview and installation
• Standalone app: Tauri desktop preview

MCP is supported: agents can open and update 3D scenes, control the camera, and inspect rendered screenshots. See the MCP setup guide.