【SAM 3D Objects】uv環境構築 × 隠し機能(nvdiffrast)で高品質なテクスチャ付きglbを出力する

はじめに

本記事では、2025年11月19日にMeta社が公開したImage-to-3Dモデル「sam-3d-objects」をローカル環境で構築し、テクスチャ付きの3Dモデルファイル（.glb）を出力する方法について解説します。

注意
2025年11月29日（執筆時）現在、uvによる環境構築手順は公式リポジトリにはマージされていません。本記事の手順は未マージのPull Requestを使用するため、自己責任での実行をお願いします。

背景と目的

「sam-3d-objects」はWeb上のデモも公開されていますが、そこからダウンロードできる成果物は「テクスチャなしの点群データ（.ply）」に限られています。そこで、実用的な3Dデータを得るためにローカル環境での実行を試みました。

本記事のポイント

公式リポジトリやデモコードにはいくつかの課題があったため、以下の対応を行いました。

1. パッケージ管理の刷新
   • 公式手順は mamba のみ対応でしたが、より高速な uv 環境で実行できるよう、未マージのPRを活用して環境を構築しました。
2. 出力形式の改善（高品質テクスチャ化）
   • 公式デモコードの出力は単純な点群データ（.ply）か、色の薄い頂点カラーのモデルでした。コードを修正し、高品質なテクスチャをベイクした glb 形式で保存できるようにしました。

補足：sam-3d-objectsとは

Meta社が発表した、静止画（2D）を詳細な3Dモデルに変換する技術です。セグメンテーション技術「SAM」を応用し、高品質な3D生成を実現しています。

💻 検証環境

• Python: 3.11
• パッケージ管理: uv
• GPU: NVIDIA GPU（VRAM 32GB以上推奨）
  • 今回検証には NVIDIA RTX 6000 PRO Blackwell を使用
• CUDA: Toolkit 12.9（ビルドに必須）

---

🔧 インストール手順

公式の setup.md は mamba を前提としていますが、本記事では uv を用いた構築手順を紹介します。

調査の結果、Add uv-based environment setup and Blackwell GPU inference support #11 というPRにてuv対応が進められていたため、今回はこのブランチを利用します。

1. リポジトリのクローンとPRの適用

# リポジトリのクローン
git clone https://github.com/facebookresearch/sam-3d-objects.git
cd sam-3d-objects

# PR #11 を 'uv-setup' という名前のブランチとしてフェッチしてチェックアウト
git fetch origin pull/11/head:uv-setup
git checkout uv-setup

2. uvによる環境構築

gsplat や pytorch3d のビルドには CUDA Toolkit 12.9 が必須 となっています。
システムにインストールした上で、環境変数を設定してから uv sync を実行する必要があります。

依存関係のインストール

# uvが未インストールの場合
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# 依存関係の同期（仮想環境の作成とインストール）
uv sync

# 仮想環境の有効化
source .venv/bin/activate

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

チェックポイントはHugging Faceにて公開されていますが、ダウンロードには アクセス申請 と 認証 が必要です。

1. Hugging Faceのリポジトリにアクセスし、利用規約に同意してアクセス権を申請します。
2. 承認後、以下のコマンドでダウンロードを行います。

Hugging Faceへのログインが必要なため、事前にアクセストークンを取得してください。

# Hugging Face CLIのインストール（古いバージョンを除外）
uv pip install 'huggingface-hub[cli]<1.0'

# ログイン（トークン入力が求められる）
huggingface-cli login

# ダウンロードの実行
TAG=hf
hf download \
  --repo-type model \
  --local-dir checkpoints/${TAG}-download \
  --max-workers 1 \
  facebook/sam-3d-objects

# ディレクトリの整理
mv checkpoints/${TAG}-download/checkpoints checkpoints/${TAG}
rm -rf checkpoints/${TAG}-download

🚀 デモの実行とコード修正

通常のdemo.py実行と課題

まずは標準のデモコードを実行してみます。

python demo.py

入力画像	点群出力

ご覧のとおり、デフォルトの出力は Gaussian Splat による 点群データのみ であり、
ポリゴンメッシュやテクスチャ情報は含まれていません。

そこで、GitHub の Issue（Issue #12）を参考に
demo.py のコードを修正し、頂点カラーを持った PLY 形式のメッシュとして出力できるようにしていきます。

demo.py

# 修正前
# output["gs"].save_ply(f"splat.ply")

# 修正後
output = inference(image, mask, seed=42)
mesh = output["glb"] # trimesh object
mesh.export("my_mesh.ply")  # 頂点カラー付きで保存

出力結果の比較:

点群ではなく、頂点カラー付きメッシュ（PLY）として出力した結果を可視化すると、以下のようになります。

入力画像	頂点カラー出力 (PLY)

出力結果を確認すると、色が非常に薄く、オリジナルの写真の質感が失われていることがわかります。

高品質テクスチャの生成（封印された機能の有効化）

調査を進めると、inference_pipeline.py 内に 「テクスチャ生成（Baking）処理」 が存在することが判明しました。

• 参考コード: inference_pipeline.py#L534

しかし、この機能は公式ドキュメントには記載されていません。Issue内の開発者コメントによると、以下の理由で「封印」されているようです。

開発者コメント要約:
Gaussianからテクスチャをベイクすることで、頂点カラーよりも良いテクスチャが得られます。
しかし、これには 非商用ライセンス（Non-Commercial use） である nvdiffrast が必要です。ライセンスの都合上、公式ドキュメントでは手順を提供できません。
（参考: Issue #12 Comment）

つまり、個人の非商用利用の範囲で、不足しているライブラリを追加すれば高品質なモデルが得られる ということです。

追加ライブラリのインストール

nvdiffrast と関連ライブラリをインストールします。

uv pip install ninja imageio imageio-ffmpeg
uv pip install git+https://github.com/NVlabs/nvdiffrast.git

バックエンド設定の修正

さらに、Issue #29 によると、デフォルトのバックエンド（inria）ではベイク処理が正しく動かない場合があるようです。
そのため、render_utils.py を修正してバックエンドを gsplat に変更します。

ファイルパス: sam3d_objects/model/backbone/tdfy_dit/utils/render_utils.py（77行目付近）

sam3d_objects/model/backbone/tdfy_dit/utils/render_utils.py

  # 修正前
- renderer.rendering_options.backend = options.get("backend", "inria")
  # 修正後
+ renderer.rendering_options.backend = options.get("backend", "gsplat")

完成版 demo.py

以上の準備が整ったら、demo.py を以下のように書き換えて実行します。

ライセンス注意
nvdiffrast は非商用ライセンスです。以下のコードを使用する場合、生成物の利用範囲に十分注意してください。

demo.py

import sys

# import inference code
sys.path.append("notebook")
from inference import Inference, load_image, load_single_mask

# --- オプション設定 ---
WITH_MESH_POSTPROCESS = True
WITH_TEXTURE_BAKING = True  # ここをTrueにする

# load model
tag = "hf"
config_path = f"checkpoints/{tag}/pipeline.yaml"
inference = Inference(config_path, compile=False)

# 画像とマスクの読み込み
image = load_image("notebook/images/shutterstock_stylish_kidsroom_1640806567/image.png")
mask = load_single_mask("notebook/images/shutterstock_stylish_kidsroom_1640806567", index=14)

# run model
output = inference(image, mask, seed=42)

# https://github.com/facebookresearch/sam-3d-objects/issues/1
output = inference._pipeline.postprocess_slat_output(
    output,
    with_mesh_postprocess=WITH_MESH_POSTPROCESS,
    with_texture_baking=WITH_TEXTURE_BAKING,
    use_vertex_color=not WITH_TEXTURE_BAKING,
)

# 保存処理
mesh = output["glb"]  # trimesh object
mesh_path = "my_mesh.glb" if WITH_TEXTURE_BAKING else "my_mesh.ply"
mesh.export(mesh_path)

print(f"Your reconstruction has been saved to {mesh_path}")

結果

コード修正後、出力された glb ファイルを確認すると、頂点カラーの時とは異なり、写真に近い高品質なテクスチャが適用されていることが確認できました。

入力画像	頂点カラー出力 (PLY)	テクスチャ付き出力 (glb)

12/2追記：Meta AI Demosとの比較

Meta AI Demos（Web版）の出力結果とも比較を行いました。
ローカル環境で構築したモデル（nvdiffrast使用）が、公式デモと遜色ない品質でテクスチャを再現できていることが確認できます。

入力画像	テクスチャ付き出力 (glb)	Meta AI Demos

まとめ

Meta社の最新モデル sam-3d-objects をローカル環境（uv）で構築し、高品質なテクスチャ付き3Dモデルを出力する手順を紹介しました。

• uv環境構築: 未マージPRを使用することで可能
• 高品質化: 非商用ライブラリ nvdiffrast の導入とコード修正が必要

公式には封印されている機能ですが、適切に設定することで実用的な3Dアセット生成の可能性を感じさせる結果となりました。

参考URL

公式情報

• Meta AI Blog - SAM 3D
• GitHub - facebookresearch/sam-3d-objects

GitHub Issues / PRs
本記事の執筆にあたり、以下の議論を参考にしました。

• PR #11: Add uv-based environment setup
  • uv環境構築の手順について
• Issue #12: How to save the output as mesh?
  • メッシュ保存とテクスチャベイク機能の有効化について
• Issue #29: Why does the rendering look strange?
  • レンダリングバックエンド（gsplat）の設定について