3D Visualizer

3D ビジュアライザー — Python、CLI、MCP

Python、ノートブック、または AI との会話で、点群、メッシュ、キャリブレーション済み深度データを検査できます。パッケージは 3d-visualizer、Python のインポート名は viz3d、CLI は 3d-visualizer です。Python 3.10 以降が必要です。

このチェックアウトは次のリリースを対象としています。公開中の 0.4.2 パッケージでは、引き続き以前のインポート名が使われています。公開前に新しいインターフェースを使うには、ビューアーをビルドし、必要な追加機能とともに ./packages/python をインストールしてください。

エージェントへのインストール

これらの例は 0.5.0.dev0 を対象としています。開発版は公開されるまで、このチェックアウトからインストールする必要があります。未リリースのバージョンが PyPI に存在すると想定しないでください。

エージェントには 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 では、日常的に使う 8 つのツールが公開されます。深度変換、選択、アニメーション、位置合わせ、エクスポートには --tools full を使ってください。 --renderer auto は、MCP Apps ホストがアドバタイズされていればそれを使い、そうでなければオフスクリーン Chromium を使います。ウィジェットまたは明示的なブラウザーを必須にするには --renderer inline を、無人実行には --renderer headless を使ってください。

無人実行での Python レンダリング

headless 追加機能と 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 を指定すると、エージェントまたは別のアプリケーションがその 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)

予測はオレンジ、ターゲットはシアンで表示されます。予測の RGB を上書きするには colors= を指定してください。ターゲットの点数は予測と異なっていても構いません。これは幾何学的な重ね合わせであり、計算された最近傍誤差指標ではありません。表示は標準のファイルパネルで切り替えられます。1 つのリビジョンを確認するには 更新を一時停止 を、フレーミングを明示的にリセットするには シーンに合わせる を使用してください。

バッチと拡張の確認

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() を呼び出して、明示的にフックを削除することもできます。

ビューアーの更新はメインプロセスで、分散トレーニングではいずれか1つのランクで、コンパイル済みのモデルコードの外部から実行してください。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 をブロックするノートブック環境では、ウィジェット／プロキシによる転送方式が必要です。現時点では、この転送方式はサポートされていません。

ウィジェットベースの実績ある代替手段として、K3D はノートブックでの点群やその他の3Dプリミティブに対応しています。 記録された時間ベースの診断には、Rerun も検討する価値があります。このパッケージは、既存の3Dビューアーを埋め込むことで、ファイル形式と操作コントロールをそのまま利用できます。

現在の対応範囲

• 対応入力形式：PLY、XYZ、XYZN、XYZRGB、PCD、PTS、OBJ、STL、OFF、GLB、LAS/LAZ、E57、SPZ、SPLAT、KSPLAT、SOG。
• 複数のファイルを1つのシーンにまとめて表示します。
• 現在、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 と CLI）： 3d-visualizer
• JetBrains： 署名済みプレビューとインストール
• スタンドアロンアプリ： Tauri デスクトッププレビュー

MCP に対応しています： エージェントは 3D シーンを開いて更新し、カメラを操作して、レンダリングされたスクリーンショットを確認できます。 MCP セットアップガイドをご覧ください。