gsplat (3D Gaussian Splatting) と 3DGUT の使い方 生成方法 – Windows環境構築

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に学習中のレンダリング画像を保存するかどうか。