Vggt Mps

🚀 VGGT-MPS: Apple Silicon向け3Dビジョンエージェント

🍎 Metal Performance Shaders (MPS)を使用してApple Silicon向けに最適化されたVGGT (Visual Geometry Grounded Transformer)

Facebook ResearchのVGGTモデルを使用して、単一または多視点の画像を豊富な3D再構成に変換します。これは、M1/M2/M3 Macで高速化されています。

🚀 クイックスタート

1. インストールオプション

オプションA: PyPIからインストール（近日公開予定）

# PyPIからインストール（公開されたら）
pip install vggt-mps

# モデルの重みをダウンロード（5GB）
vggt download

オプションB: UVを使用してソースからインストール（開発用に推奨）

git clone https://github.com/jmanhype/vggt-mps.git
cd vggt-mps

# uvでインストール（pipより10 - 100倍高速！）
make install

# またはuvで手動でインストール
uv pip install -e .

オプションC: ソースから従来のpipでインストール

git clone https://github.com/jmanhype/vggt-mps.git
cd vggt-mps

# 仮想環境を作成
python -m venv vggt-env
source vggt-env/bin/activate

# 依存関係をインストール
pip install -r requirements.txt

2. モデルの重みをダウンロード

# 5GBのVGGTモデルをダウンロード
vggt download

# またはソースから実行する場合:
python main.py download

または、Hugging Faceから手動でダウンロードしてください。

3. MPSサポートをテスト

# MPSの高速化をテスト
vggt test --suite mps

# またはソースから:
python main.py test --suite mps

期待される出力:

✅ MPS (Metal Performance Shaders) 利用可能！
   Apple Silicon GPUで実行中
✅ モデルの重みがmpsにロードされました
✅ MPSオペレーションが正常に動作しています！

4. 環境を設定（オプション）

# 環境設定をコピー
cp .env.example .env

# .envを自分の設定で編集
nano .env

✨ 主な機能

🎉 v2.0.0リリース

主要なアップデート: 統一されたCLI、PyPI対応の配布、および本番環境向けのツールを備えた完全なパッケージングの見直し！

🎯 v2.0.0の新機能

主要な変更

• 統一されたCLI: すべての操作にサブコマンドを持つ新しいvggtコマンド
• プロフェッショナルなパッケージング: pyproject.tomlを使用したPyPI対応、適切なsrcレイアウト
• Webインターフェース: 対話型3D再構成用のGradio UI (vggt web)
• 強化されたテスト: MPSおよびスパースアテンションテストを含む包括的なテストスイート
• 最新のツール: UVサポート、Makefile自動化、GitHub ActionsのCI/CD

コア機能

• MPS高速化: Metal Performance Shadersを使用したApple Siliconでの完全なGPU高速化
• ⚡ スパースアテンション: 都市規模の再構成に対するO(n)メモリスケーリング（100倍の節約！）
• 🎥 多視点3D再構成: 画像から深度マップ、点群、およびカメラポーズを生成
• 🔧 MCP統合: Claude Desktopとの統合のためのモデルコンテキストプロトコルサーバ
• 📦 5GBのモデル: Apple Siliconでスムーズに動作する効率的な10億パラメータのモデル
• 🛠️ 複数のエクスポート形式: 3D点群用のPLY、OBJ、GLB

🎯 VGGTの機能

VGGTは、画像から3Dシーンを再構成します。具体的には、以下を予測します。

• 深度マップ: 各ピクセルの深度推定
• カメラポーズ: 6自由度のカメラパラメータ
• 3D点群: 高密度の3D再構成
• 信頼度マップ: 予測の信頼度スコア

📦 インストール

必要条件

• Apple Silicon Mac (M1/M2/M3)
• Python 3.10以上
• 8GB以上のRAM
• モデル用に6GBのディスクスペース

💻 使用例

CLIコマンド (v2.0.0)

すべての機能は統一されたvggtコマンドを通じてアクセスできます。

# サンプル画像でのクイックデモ
vggt demo

# キッチンデータセットでのデモ（4枚の画像）
vggt demo --kitchen --images 4

# 自分の画像を処理
vggt reconstruct data/*.jpg

# 大規模なシーンにスパースアテンションを使用
vggt reconstruct --sparse data/*.jpg

# 特定の形式にエクスポート
vggt reconstruct --export ply data/*.jpg

# 対話型Webインターフェースを起動
vggt web

# 特定のポートで公開リンクを使用して開く
vggt web --port 8080 --share

# 包括的なテストを実行
vggt test --suite all

# 特にスパースアテンションをテスト
vggt test --suite sparse

# パフォーマンスをベンチマーク
vggt benchmark --compare

# モデルの重みをダウンロード
vggt download

ソースから（開発用）

インストールせずにソースから実行する場合:

python main.py demo
python main.py reconstruct data/*.jpg
python main.py web
python main.py test --suite mps
python main.py benchmark --compare

画像の処理

from src.tools.readme import vggt_quick_start_inference

result = vggt_quick_start_inference(
    image_directory="./tmp/inputs",
    device="mps",  # Apple Silicon GPUを使用
    max_images=4,
    save_outputs=True
)

ビデオフレームの抽出

from src.tools.demo_gradio import vggt_extract_video_frames

result = vggt_extract_video_frames(
    video_path="input_video.mp4",
    frame_interval_seconds=1.0
)

3Dシーンの作成

from src.tools.demo_viser import vggt_reconstruct_3d_scene

result = vggt_reconstruct_3d_scene(
    images_dir="./tmp/inputs",
    device_type="mps",
    confidence_threshold=0.5
)

⚡ スパースアテンション - 新機能！

都市規模の3D再構成が可能になりました！ 私たちは、Gabriele Bertonの研究アイデアを実装して、O(n)メモリスケーリングを実現しました。

🎯 主な利点

• 1000枚の画像に対して100倍のメモリ節約
• 再トレーニング不要 - 実行時に既存のVGGTをパッチ適用
• 通常のVGGTと同じ出力 (0.000000の差分)
• MegaLoc共視性検出によるスマートなアテンションマスキング

🚀 使用方法

from src.vggt_sparse_attention import make_vggt_sparse

# 1行で任意のVGGTをスパースに変換
sparse_vggt = make_vggt_sparse(regular_vggt, device="mps")

# 同じ使用方法で、O(n)メモリでO(n²)ではなく動作
output = sparse_vggt(images)  # 1000枚以上の画像を処理！

📊 メモリスケーリング

完全な結果を参照: docs/SPARSE_ATTENTION_RESULTS.md

🔧 技術詳細

MPS最適化

• デバイス検出: MPSの可用性を自動検出
• データ型選択: 最適なMPSパフォーマンスのためにfloat32を使用
• Autocast処理: MPSではCUDAのAutocastを無効にする
• メモリ管理: Metal上での効率的なテンソル操作

モデルアーキテクチャ

• パラメータ: 10億 (ディスク上で5GB)
• 入力: 多視点画像
• 出力: 深度、カメラポーズ、3D点
• 解像度: 518x518 (VGGT)、最大1024x1024 (入力)

📚 ドキュメント

• 開発ガイド - 開発環境のセットアップ
• 公開ガイド - PyPIリリースプロセス
• コントリビューションガイド - コントリビュートの方法
• APIドキュメント - 詳細なAPIリファレンス
• サンプル - コードサンプルとデモ

🚀 リリースノート

v2.0.0 (最新)

• ✨ vggtコマンドによる統一されたCLI
• 📦 プロフェッショナルなPythonパッケージング (PyPI対応)
• 🌐 Gradio Webインターフェース
• 🧪 包括的なテストスイート
• 🛠️ 最新のツール (UV、Makefile、GitHub Actions)
• 📝 完全なドキュメントの見直し

完全な変更履歴を参照

🔧 MCPサーバー統合

Claude Desktopに追加

1. ~/Library/Application Support/Claude/claude_desktop_config.jsonを編集:

{
  "mcpServers": {
    "vggt-agent": {
      "command": "uv",
      "args": [
        "run",
        "--python",
        "/path/to/vggt-mps/vggt-env/bin/python",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/path/to/vggt-mps/src/vggt_mps_mcp.py"
      ]
    }
  }
}

2. Claude Desktopを再起動

利用可能なMCPツール

• vggt_quick_start_inference - 画像からの高速3D再構成
• vggt_extract_video_frames - ビデオからのフレーム抽出
• vggt_process_images - 完全なVGGTパイプライン
• vggt_create_3d_scene - GLB 3Dファイルの生成
• vggt_reconstruct_3d_scene - 多視点再構成
• vggt_visualize_reconstruction - 再構成の可視化

📁 プロジェクト構造

vggt-mps/
├── main.py                      # 単一のエントリポイント
├── setup.py                     # パッケージのインストール
├── requirements.txt             # 依存関係
├── .env.example                 # 環境設定
│
├── src/                         # ソースコード
│   ├── config.py               # 集中管理された設定
│   ├── vggt_core.py            # コアVGGT処理
│   ├── vggt_sparse_attention.py # スパースアテンション (O(n)スケーリング)
│   ├── visualization.py        # 3D可視化ユーティリティ
│   │
│   ├── commands/               # CLIコマンド
│   │   ├── demo.py            # デモコマンド
│   │   ├── reconstruct.py     # 再構成コマンド
│   │   ├── test_runner.py     # テストランナー
│   │   ├── benchmark.py       # パフォーマンスベンチマーク
│   │   └── web_interface.py   # Gradio Webアプリ
│   │
│   └── utils/                  # ユーティリティ
│       ├── model_loader.py    # モデル管理
│       ├── image_utils.py     # 画像処理
│       └── export.py          # PLY/OBJ/GLBへのエクスポート
│
├── tests/                       # 整理されたテストスイート
│   ├── test_mps.py            # MPS機能テスト
│   ├── test_sparse.py         # スパースアテンションテスト
│   └── test_integration.py    # エンドツーエンドテスト
│
├── data/                        # 入力データディレクトリ
├── outputs/                     # 出力ディレクトリ
├── models/                      # モデルの保存先
│
├── docs/                        # ドキュメント
│   ├── API.md                  # APIドキュメント
│   ├── SPARSE_ATTENTION.md    # 技術詳細
│   └── BENCHMARKS.md          # パフォーマンス結果
│
└── LICENSE                      # MITライセンス

🐛 トラブルシューティング

MPSが利用できない場合

# PyTorch MPSサポートを確認
python -c "import torch; print(torch.backends.mps.is_available())"

モデルのロードに問題がある場合

# モデルファイルを確認
ls -lh repo/vggt/vggt_model.pt
# 約5GBのファイルが表示されるはず

メモリの問題

• バッチサイズを減らす
• 解像度を下げる
• CPUフォールバックを使用する

📚 参考文献

• VGGT論文
• Facebook Research VGGT
• Hugging Faceモデル

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

🙏 謝辞

• VGGTに関してはFacebook Research
• Metal Performance Shadersに関してはApple
• MPSバックエンドに関してはPyTorchチーム

AIコミュニティによる🍎 Apple Silicon向けに作成されました