3D Visualizer

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". 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 m