3D Visualizer

3D 可视化工具 — Python、CLI 和 MCP

使用 Python、笔记本或 AI 对话检查点云、网格和经过标定的深度数据。该软件包是 3d-visualizer，Python 导入名称是 viz3d，CLI 是 3d-visualizer。需要 Python 3.10 或更高版本。

此检出版本面向下一个发行版。公开的 0.4.2 软件包仍使用旧的导入名称。发布前如需使用新接口，请先构建查看器，然后根据需要安装带有相应 extras 的 ./packages/python。

Agent 安装

以下示例适用于 0.5.0.dev0。开发版本发布前必须从此检出版本安装；不要假定 PyPI 上存在尚未发布的版本。

对于 Agent，请使用 uv tool install 或 uvx；uv add 用于在 Python 项目中使用该库。无头模式还需要安装一次 Chromium。

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

客户端配置（替换数据目录）：

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

在 VS Code 中安装

VS Code 链接会将当前工作区用作允许访问的数据根目录。

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

默认的 --tools core 会提供八种日常工具。使用 --tools full 可进行深度转换、选择、动画、对齐和导出。 --renderer auto 会使用已声明支持 MCP Apps 的宿主，否则使用离屏 Chromium。 使用 --renderer inline 可要求使用小组件或显式指定的浏览器； 使用 --renderer headless 可执行无人值守任务。

无人值守的 Python 渲染

安装 headless extra 和 Chromium 后：

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())

此模式使用离屏 Chromium 和共享渲染器。无需笔记本、聊天小组件或可见的浏览器窗口。渲染器发生故障时，检查和捕获操作会报错，而不会返回占位成功结果。

使用 uv 安装（推荐）

安装 uv，然后选择：

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

Python 导入语句为 from viz3d import show。安装工具不会将该库添加到 Python 项目或笔记本内核中；请在相应环境中使用 uv add 或 uv pip install。从 PyPI 安装无需构建 Node.js。

对于本地 Jupyter，请在项目目录中运行 uv run --with jupyter jupyter lab，并选择该项目的 Python 内核。使用查看器时，请保持该内核运行。

从源代码开发

在仓库根目录下，使用 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

有关发行版，请参阅发布设置。

替代方案：使用 pip 从此仓库安装

完成上述浏览器资源构建后：

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

在 Windows 上，将环境路径中的 bin/ 替换为 Scripts/，例如 packages\python\.venv\Scripts\python.exe、3d-visualizer.exe 或 jupyter.exe。激活环境后，命令只需：

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

该命令会输出本地 URL，并持续运行直到按下 Ctrl+C。--no-browser 允许 Agent 或其他应用自行打开该 URL。它不会渲染图像，也不会向调用方报告浏览器渲染成功。

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

坐标必须是可转换为有限 float32 数值的数字。可选颜色必须与点数匹配，并包含范围为 0..255 的整数 RGB 值。点数组会被序列化为临时二进制 PLY，由现有引擎解码，并在会话关闭时删除。此初始实现逐行序列化数组；对于非常大的数组，这不是零拷贝传输。

NumPy 和 PyTorch

直接传入数组和张量，包括 RGB 颜色：

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 数组可以经过转置、切片、设为只读或为非连续内存布局。
• PyTorch 输入可以是 CPU 或 GPU 张量，也可以是已分离或已连接到 autograd 的张量。 坐标和颜色会分别处理，因此可以混用不同设备上的数据，也可以混用 NumPy 和 PyTorch 输入。支持 Float16 和 bfloat16 张量。
• 可视化过程会在内部分离张量、将其传输到 CPU 并序列化为快照。原始设备、 值、requires_grad 和 autograd 计算图均保持不变。从 GPU 传输到 CPU 会触发同步； 避免在每个训练步骤中都调用此操作。
• PyTorch 转换不依赖 NumPy。CPU 数据行会分块转换，并限制每块大小，而不是 对每个坐标都执行一次 GPU 标量读取。
• 输入必须是实数、稠密的 (N, 3) 数据。对于 (B, N, 3) 批次，请使用 show(batch[0])；不会有意外地自动展平批次。 稀疏、量化、复数、嵌套以及无数据的 meta 张量都会被拒绝并报错。 RGB 仍采用整数值 0..255 的约定，包括浮点张量；归一化 RGB 可以通过 (rgb * 255).round() 传入。

训练预览

所有更新都会复用同一个浏览器标签页／内嵌视图，并保留视角。查看器会收到 变更通知并加载最新版本；中间版本可能会被跳过。请以合适的训练间隔发布， 而不是在每次前向传播时都发布。序列化和 GPU 传输都是同步操作。更新会替换 场景；手动添加到该场景的文件也会在下一次更新时被替换。

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)

预测结果为橙色，目标为青色。提供 colors= 可覆盖预测结果的 RGB 颜色。 目标点的数量可以不同。这是几何叠加，不是计算得出的最近邻误差指标。 可以在标准文件面板中切换可见性。使用 Pause updates 检查某个版本， 使用 Fit scene 显式重置视图范围。

批次和数据增强检查

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"])

样本选择器可以在同一场景中切换批次，并保留视角。颜色、目标和向量（如果 提供）必须与批次大小一致。批次快照会序列化每个样本；对于较大的训练批次， 请选择较小的检查子集。浏览器只会加载选中的样本。

梯度和位移箭头

# 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,
)

箭头以对应的输入点为起点。使用负学习率缩放会显示普通的梯度下降方向； 这不是精确的 Adam 或动量优化器更新步。若要检查实际更新，请改为传入测得的 坐标位移。非零箭头为洋红色。最多显示 max_vectors 个均匀间隔的向量 （默认值为 256，最大值为 2000）。所有传入的向量行都会经过验证；此操作不会 安装 autograd 钩子，也不会计算梯度。

使用可移除的前向钩子进行层检查

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

对于字典输出，使用如下选择器： lambda output: output["points"][0]。选择器必须返回形状为 (N, 3) 的坐标，而不是任意特征通道。钩子会捕获第一次前向调用，然后每隔 every 次调用捕获一次。它会返回 None，以保留模型的输出。可视化出错时会禁用钩子并发出警告，错误可通过 inspection.error 访问；这不会影响训练。上下文管理器会移除钩子，而查看器会话的生命周期由调用方负责。 inspection.close() 也可以显式移除钩子。

在主进程中、分布式训练时仅在一个 rank 上运行查看器更新，并且不要在编译后的模型代码中运行。GPU 到 CPU 的数据传输会引入同步开销。 PyTorch 前向钩子。

服务仅绑定到 127.0.0.1，使用随机会话 URL，并且只提供显式指定的文件和随附的查看器资源。源文件会保留在你的计算机上；该软件包不会上传这些文件。请确保在会话期间文件路径始终可用。不要将会话 URL 分享给不受信任的代码。

内嵌 Jupyter 笔记本

在本地 Jupyter 笔记本中，将查看器作为单元格的最后一个表达式返回。检测到笔记本内核时会禁用自动打开浏览器：

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

或者使用笔记本扩展显式显示：

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

设置默认折叠。紧凑工具栏让你可以随时访问 Settings、Fit scene、Pause updates 和批次选择器。选择 ui="full" 可立即显示设置，选择 ui="none" 可使用仅用于演示的画布和鼠标控件。在无 UI 模式下无法选择批次；请在 Python 中选择样本后再显示。

viewer.update(...) 会更新所有打开的视图，包括笔记本输出。请保持内核运行，完成后调用 viewer.close()，不要在单元格中调用 viewer.wait()。笔记本输出包含实时的本地 iframe，而不是离线保存的场景。重启内核后，请重新打开会话。

此初始内嵌传输要求浏览器和内核位于同一台计算机，并且笔记本宿主允许使用本地 iframe。远程 Jupyter、Colab 以及会阻止本地 iframe URL 的笔记本环境需要 widget/proxy 传输；此传输目前尚不支持这些环境。

如需成熟的基于 widget 的替代方案，可考虑 K3D，它支持笔记本点云和其他 3D 基元。 对于录制式、基于时间的诊断，也值得考虑 Rerun。此软件包嵌入现有的 3D 查看器，以保留其文件格式和交互控件。

当前范围

• 支持的输入格式：PLY、XYZ、XYZN、XYZRGB、PCD、PTS、OBJ、STL、OFF、GLB、 LAS/LAZ、E57、SPZ、SPLAT、KSPLAT 和 SOG。
• 多个文件会一同显示在一个场景中。
• OBJ 输入目前仅提供几何体；自动解析旁置材质/纹理和外部资源 glTF 不在此预览范围内。
• 目前尚无单独的图像查看器集成或桌面启动集成。共享的 3D 查看器保留了现有的手动控件和深度转换功能。

构建可分发的 wheel

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

wheel 包含浏览器引擎及其资源。在另一台计算机上使用 python -m pip install /path/to/the.whl 安装该 wheel；无需安装 Node.js 或 Tauri。打包前请先构建资源。

验证

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

浏览器测试需要运行 npm run build:python-viewer，并需要 engine/dist 中现有引擎测试服务器资源（npm run build --workspace=engine）。数组测试会跳过不可用的可选库和 GPU 后端。

可用平台

• VS Code Marketplace： 安装扩展
• Open VSX： 安装扩展
• 网站： 3d.f-kleinicke.de
• PyPI（Python 和命令行）： 3d-visualizer
• JetBrains： 已签名预览版和安装说明
• 独立应用： Tauri 桌面预览版

**支持 MCP：**Agent 可以打开和更新 3D 场景、控制摄像机， 并查看渲染后的屏幕截图。请参阅 MCP 设置指南。