3D Gaussian Splatting (ガウシアンスプラッティング) 処理する方法は様々ありますが、ここでは『gsplat』の使い方、Windows環境での環境構築の手順をまとめました。
本家『Inria – 3D Gaussian Splatting』は商用利用するには別途ライセンスが必要であったりもするので、仕事で使いたい場合はこのgsplatも選択肢に入るかと思います。
※Inria 3DGSが使いたい場合は こちらの記事 にまとめています
GUIで利用できる『postshot』も便利ですが、まだベータ版であり、使える機能にも限りがあるので、より柔軟に3DGS生成したい場合にもgsplatは便利です。
※postshotの使い方については こちらの記事 にまとめました
gsplatは『nerfstudio』からも利用できますが、この記事はgsplat単独で使う方法です。
gsplat直であれば最新の機能も早いタイミングから利用できるようです。
NVIDIAから発表された『3DGUT』も使用する事ができました。
(3DGUTの使い方については記事の最後に)
nerfstudioのgsplatだとOut of memoryになってしまうデータもgsplat直ならVRAM削減用オプションを使うことで処理ができる点も大規模シーンを処理したい場合の利点になるかと思います (それでも限界はあるけれど)。
なお、gsplatで生成される3DGSデータは従来の3DGSと互換性のある.plyファイルになっています。
追記
環境構築を解説されているYouTube動画もあった。
How to Use 3D Gaussian Ray Tracing on Windows (Full Tutorial) – Pixel Reconstruct氏
準備
公式リポジトリ
https://github.com/nerfstudio-project/gsplat
公式ドキュメント
https://docs.gsplat.studio/main/
この記事では以下の環境で進めています。
- Windows 11 Pro
- CUDA Toolkit 11.8 (または 12.1, 12.4)
- PyTorch 2.4 (または 2.1, 2.2, 2.3)
- Anaconda
- Python 3.10
- gsplat v1.5.2
上記の各対応バージョンについては リリースページ のwhlファイルを参考にしました。
各ファイルの命名ルールは以下のようになってるようです。
- pt：PyTorchのバージョン pt24→PyTorch 2.4
- cu：CUDA Toolkitのバージョン cu118→CUDA Toolkit 11.8
- cp：Pythonのバージョン cu310→Python 3.10
環境構築手順
手順の途中でエラーが起きていますが、参考としてそのままエラー内容と対策方法を記しています。
まずAnaconda Promptを起動し、仮想環境を作成する。
conda create -n gsplat python=3.10
作成した仮想環境をアクティベートする。
conda activate gsplat
pipアップグレードしておく。
python -m pip install --upgrade pip
PyTorchを入れる。
利用するのは旧バージョンなので、旧バージョン用の下記リンクにアクセス。
https://pytorch.org/get-started/previous-versions/
今回はCUDA 11.8環境で構築するので、対応したコマンドを控える。
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=11.8 -c pytorch -c nvidia
依存関係をインストールしておく。
pip install ninja numpy jaxtyping rich
続いて、gsplatリポジトリからgitクローンするのでクローンする場所へ移動する。
cd D:\Git\3DGS_gsplat
クローンする。
git clone https://github.com/nerfstudio-project/gsplat.git
そのままだと最新版の状態なので、今回利用するv1.5.2にチェックアウトする。
git checkout v1.5.2
wheelファイルをインストールしたいので、
リリースページから自分の環境に対応したものをDLする。
https://github.com/nerfstudio-project/gsplat/releases
ここではgsplat-1.5.2+pt24cu118-cp310-cp310-win_amd64.whlを落とす。
.whlをダウンロードしたディレクトリに移動する。
cd D:\Downloads
wheelをインストールする。
pip install gsplat-1.5.2+pt24cu118-cp310-cp310-win_amd64.whl
リポジトリをクローンしたディレクトリへ移動する。
cd D:\Git\3DGS_gsplat\gsplat
requirements.txtから依存関係をインストールする。
pip install -r examples/requirements.txt
ここでエラーになった。
note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for fused_ssim
Running setup.py clean for fused_ssim
Successfully built pycolmap nerfview
Failed to build fused_ssim
ERROR: Failed to build installable wheels for some pyproject.toml based projects (fused_ssim)
fused_ssim のインストールで失敗していた。
詳しく原因を探るため、VERBOSE=1を使って詳細なログを表示させてみる。以下のようにfused_ssimのインストール部分だけを単独実行し確認を行う。
SET VERBOSE=1
pip install --use-pep517 --no-build-isolation git+https://github.com/rahul-goel/fused-ssim@328dc9836f513d00c4b5bc38fe30478b4435cbb5
すると以下のエラーが確認できた。
fatal error C1189: #error: -- unsupported Microsoft Visual Studio version! Only the versions between 2017 and 2022 (inclusive) are supported!
ChatGPTで確認してみるとー
これは Visual Studio 2022 の最新アップデート (v14.44) が CUDA 11.8 に未対応 であることが原因です。
CUDA 11.8 が正式にサポートする MSVC のバージョンは 14.29（Visual Studio 2019）か、Visual Studio 2022 でも古いバージョン（14.30～14.33くらい） です。
私の環境では「Visual Studio 2019」は入っているけれど「2022」も入っているので、そちらを参照してしまっているのが原因かもしれない。
Geminiに相談してみるとー
【最重要】専用のコマンドプロンプトからビルドを実行する
Windowsのスタートメニューを開き、検索ボックスに「x64 Native Tools Command Prompt for VS 2019」と入力します。
表示された「x64 Native Tools Command Prompt for VS 2019」を管理者として実行します
Visual Studio 2019専用のコマンドプロンプトを立ち上げる。
この状態で改めて環境をアクティベートする。
conda activate gsplat
しかしcondaを環境変数設定してないと以下のエラーになる。
'conda' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。
そこで簡易的な対策として以下を実行する。
call C:\Users\ryo\anaconda3\Scripts\activate.bat
これで直接Anaconda環境がアクティベートされる。
改めてgsplat環境をアクティベートする。
conda activate gsplat
この状態で再度requirements.txtを参照した依存関係のインストールを実行。
pip install -r examples/requirements.txt
すると今度は以下のエラー。
UserWarning: It seems that the VC environment is activated but DISTUTILS_USE_SDK is not set.This may lead to multiple activations of the VC env.Please set `DISTUTILS_USE_SDK=1` and try again.
これはGeminiによると、
この準備された環境をそのまま使っていい、という明確な許可（= DISTUTILS_USE_SDK=1）が出ていない。もし許可がないと、こちらで勝手に別の環境を準備し始めて二重設定になるかもしれないから、安全のために一旦止めます」と警告を出して処理を停止しています。
というもの。
なので以下を実行する。
set DISTUTILS_USE_SDK=1
setで一時的に環境変数を設定するもの。これは他環境への影響はないので安心して実行して良いらしい。
最終的な手順をまとめると、以下の流れ。
まず「x64 Native Tools Command Prompt for VS 2019」を立ち上げ、以下のコマンドを順に実行する。
call C:\Users\ryo\anaconda3\Scripts\activate.bat
conda activate gsplat
set DISTUTILS_USE_SDK=1
pip install -r examples/requirements.txt
無事に fused_ssim がインストールできた。
トレーニングの実行 3DGS生成処理
試しに処理をしたいので、サンプルデータをDLする。
Inria の 3D Gaussian Splatting のサンプルデータを使わせてもらう。
「Scenes」からデータをDL。
truckフォルダをgsplatフォルダ以下にdataフォルダを作成しその中にコピーする。
以下のような構成。
トレーニング用実行ファイルはexampleフォルダ内にあるのでそこへ移動する。
cd examples
トレーニングを実行する。
python simple_trainer.py default --data_dir ../data/truck/ --data_factor 4 --result_dir ../results/truck
しかしここでエラーになる。
struct.error: unpack requires a buffer of 4 bytes
該当Issueがあった。
https://github.com/nerfstudio-project/gsplat/issues/275
結論はC:\Users\ryo\anaconda3\envs\gsplat\lib\site-packages\pycolmap\scene_manager.pyのファイルを以下のように修正する。
https://github.com/Fabulani/pycolmap/commit/d44e03b86044cca2756a3a5fa841ee0fb393f24e
修正したら改めて学習コマンドを実行する。
python simple_trainer.py default --data_dir ../data/truck/ --result_dir ../results/truck
無事に実行できた。
以上！
更に3DGUTも試したい場合は↓
3DGUTの使い方
こちらの公式のドキュメント を参照。
mcmc モードで、–with_ut と –with_eval3d のオプションを指定することで利用できます。
利用可能なオプション (各種設定)
公式のドキュメント はありますが全て網羅されていなかったので、simple_trainer.py の中身をLLMで解析してもらったものを以下にまとめました。
※誤字脱字誤翻訳ありそうなのであくまで参考程度に
ver.1.5.2時点の内容です。
1. 全般設定 (General Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| disable_viewer | bool | False | Viserベースのインタラクティブなビューワーを無効化します。分散学習時は自動的に無効になります。 |
| ckpt | Optional[List[str]] | None | 学習済みモデルのチェックポイントファイル（.pt）へのパス。これを指定すると、学習はスキップされ評価のみが実行されます。 |
| compression | Optional[Literal[“png”]] | None | 圧縮戦略の名前。現在はpngのみ対応しています（実験的）。 |
| render_traj_path | str | “interp” | 評価時にレンダリングするカメラ軌道パスの種類。”interp”（補間）、”ellipse”（楕円）、”spiral”（螺旋）から選択できます。 |
| port | int | 8080 | ビューワーサーバーが使用するポート番号です。 |
2. データセット関連 (Dataset Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| data_dir | str | “data/360_v2/garden” | Mip-NeRF 360形式のデータセットへのパス。 |
| data_factor | int | 4 | データセットの画像をどれだけダウンサンプリング（縮小）するかを指定する係数。4は解像度を1/4にします。 |
| result_dir | str | “results/garden” | チェックポイント、レンダリング結果、ログなどの保存先ディレクトリ。 |
| test_every | int | 8 | N枚の画像ごとに1枚をテスト用データセットとして確保します。 |
| patch_size | Optional[int] | None | 学習時に画像をランダムにクロップする際のパッチサイズ。Noneの場合、画像全体を使用します。（実験的） |
| global_scale | float | 1.0 | シーンサイズに関連するパラメータ（カメラの範囲など）に適用されるグローバルなスケール係数。 |
| normalize_world_space | bool | True | データセットのワールド座標系を正規化するかどうか。 |
| camera_model | Literal[…] | “pinhole” | 使用するカメラモデル。”pinhole”（ピンホール）、”ortho”（平行投影）、”fisheye”（魚眼）から選択。 |
3. 学習プロセス関連 (Training Process Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| batch_size | int | 1 | 学習時のバッチサイズ。学習率はバッチサイズに基づいて自動的にスケーリングされます。 |
| steps_scaler | float | 1.0 | 学習ステップ数に関連する全てのパラメータ（max_steps, eval_stepsなど）をスケールする係数。0.5にすると、全ステップが半分になります。 |
| max_steps | int | 30_000 | 最大学習ステップ数。 |
| eval_steps | List[int] | [7_000, 30_000] | モデルの評価を実行するステップのリスト。 |
| save_steps | List[int] | [7_000, 30_000] | モデルのチェックポイントを保存するステップのリスト。 |
| save_ply | bool | False | PLY形式で点群ファイル（Gaussian Splat）を保存するかどうか。 |
| ply_steps | List[int] | [7_000, 30_000] | PLYファイルを保存するステップのリスト。 |
| disable_video | bool | False | 学習中および評価中の動画生成を無効にするかどうか。 |
| random_bkgd | bool | False | 学習時にランダムな背景色を使用して、モデルが透明になることを抑制するかどうか。 |
4. Gaussian Splatting 初期化関連 (Initialization Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| init_type | str | “sfm” | ガウシアンの初期化方法。”sfm”（COLMAP等のSfMツールからの点群を使用）または”random”（ランダムに点を生成）を選択。 |
| init_num_pts | int | 100_000 | init_type=”random”の場合に、初期化するガウシアンの数。 |
| init_extent | float | 3.0 | init_type=”random”の場合に、カメラの範囲に対してどのくらいの広さでガウシアンを初期化するか。 |
| sh_degree | int | 3 | 球面調和関数（SH）の最大次数。高いほど色の表現力（視点依存効果）が向上しますが、計算量とメモリが増加します。 |
| sh_degree_interval | int | 1000 | このステップ数ごとに、使用するSHの次数を1ずつ上げていきます（sh_degreeが上限）。 |
| init_opa | float | 0.1 | ガウシアンの初期不透明度（Opacity）。 |
| init_scale | float | 1.0 | ガウシアンの初期スケール（サイズ）。 |
5. 損失関数・正則化関連 (Loss & Regularization Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| ssim_lambda | float | 0.2 | 損失関数におけるSSIM損失の重み。全体の損失は (1.0 – ssim_lambda) * L1_loss + ssim_lambda * SSIM_loss で計算されます。 |
| opacity_reg | float | 0.0 | 不透明度に対する正則化の強さ。ガウシアンが過度に透明または不透明になるのを防ぎます。 |
| scale_reg | float | 0.0 | スケールに対する正則化の強さ。ガウシアンが過度に大きくなるのを防ぎます。 |
| lpips_net | Literal[…] | “alex” | LPIPS（知覚的類似性）の計算に用いるネットワーク。”alex”または”vgg”を選択できます。 |
6. 最適化・学習率関連 (Optimization & Learning Rate Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| sparse_grad | bool | False | 勾配計算にスパース（疎）なテンソルを使用するかどうか。メモリ使用量を削減できます。（実験的） |
| visible_adam | bool | False | Taming 3DGSで提案された、可視のガウシアンのみを更新するAdamオプティマイザを使用するかどうか。（実験的） |
| means_lr | float | 1.6e-4 | ガウシアンの中心位置(means)の学習率。 |
| scales_lr | float | 5e-3 | ガウシアンのスケール(scales)の学習率。 |
| opacities_lr | float | 5e-2 | ガウシアンの不透明度(opacities)の学習率。 |
| quats_lr | float | 1e-3 | ガウシアンの回転（クォータニオン, quats）の学習率。 |
| sh0_lr | float | 2.5e-3 | SHの0次係数（基本色）の学習率。 |
| shN_lr | float | 2.5e-3 / 20 | SHの高次係数（色の詳細）の学習率。 |
7. デンス化戦略 (Densification Strategy)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| strategy | Union[…] | DefaultStrategy | ガウシアンの密化（Densification）戦略。ベース設定でdefaultかmcmcを選択することで切り替わります。DefaultStrategyは元論文の手法（複製・分割）、MCMCStrategyは”3D Gaussian Splatting as MCMC”論文の手法です。 |
8. レンダリング関連 (Rendering Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| near_plane | float | 0.01 | レンダリング時の近傍クリップ面。これより手前のオブジェクトは描画されません。 |
| far_plane | float | 1e10 | レンダリング時の遠方クリップ面。これより奥のオブジェクトは描画されません。 |
| packed | bool | False | パックモードでラスタライズを行うか。メモリ使用量は減りますが、速度が若干低下します。 |
| antialiased | bool | False | ラスタライズ時にアンチエイリアシングを有効にするか。PSNRなどの指標は僅かに低下する可能性がありますが、見た目は滑らかになります。 |
9. (実験的) 最適化オプション (Experimental Optimization Options)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| pose_opt | bool | False | カメラポーズの最適化を有効にするか。 |
| pose_opt_lr | float | 1e-5 | カメラポーズの最適化の学習率。 |
| pose_opt_reg | float | 1e-6 | カメラポーズの最適化の正則化（Weight Decay）。 |
| pose_noise | float | 0.0 | カメラの外因パラメータにノイズを加える量。カメラポーズ最適化のテスト用です。 |
| app_opt | bool | False | Appearance（見た目）の最適化を有効にするか。 |
| app_embed_dim | int | 16 | Appearance埋め込みの特徴量の次元数。 |
| app_opt_lr | float | 1e-3 | Appearance最適化の学習率。 |
| app_opt_reg | float | 1e-6 | Appearance最適化の正則化（Weight Decay）。 |
10. (実験的) その他の機能 (Other Experimental Features)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| use_bilateral_grid | bool | False | Bilateral Gridを用いた色補正を有効にするか。 |
| bilateral_grid_shape | Tuple[…] | (16, 16, 8) | Bilateral Gridの形状 (X, Y, W)。 |
| depth_loss | bool | False | 深度情報（Depth）を用いた損失を有効にするか。データセットに深度情報が必要です。 |
| depth_lambda | float | 1e-2 | 深度損失の重み。 |
11. ログ・可視化関連 (Logging & Visualization Settings)
| 引数名 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| tb_every | int | 100 | TensorBoardに情報を記録するステップ間隔。 |
| tb_save_image | bool | False | TensorBoardに学習中のレンダリング画像を保存するかどうか。 |