📝

3DGS周りのメモ

に公開
3dgs
idea

こちらの実装に関しての個人メモ
https://github.com/nerfstudio-project/gsplat/tree/main

Configメモ ( AI生成 )

基本・実行制御

設定名 型 デフォルト 説明 / とりうる値
disable_viewer bool False viser ビューアを無効化する
ckpt List[str] | None None .pt ファイルパス。指定すると学習をスキップして評価のみ実行
compression "png" | None None 圧縮方式。現状 "png" のみ
render_traj_path str "interp" 軌道動画の経路。学習結果の確認用のオプション。学習には影響しない。"interp" / "ellipse" / "spiral" / "raw"
backend str "cuda" 学習バックエンド。"cuda"（標準マルチプロセス）/ "dgx"（単一プロセス・マルチGPU）
port int 8080 ビューアサーバのポート番号

データセット

設定名 型 デフォルト 説明 / とりうる値
data_type str "colmap" データバックエンド。"colmap" / "ncore"
data_dir str "data/360_v2/garden" データセットのパス（COLMAP or NCore meta-JSON）
data_factor int 4 データセットのダウンサンプル係数。データセットの中の画像は画像のサイズごとにimages, images_2, images_4などが用意されていてそのうちの画像を使用するかを指定するオプション。images_2を選択した場合、元画像の縦横のピクセル数が半分の画像を使用することになる。
result_dir str "results/garden" 結果の出力ディレクトリ
test_every int 8 N枚ごとに1枚をテスト画像にする
patch_size int | None None 学習用ランダムクロップサイズ（実験的）
global_scale float 1.0 シーンサイズ関連パラメータに掛かるグローバル倍率
normalize_world_space bool True ワールド空間を正規化するか
camera_model CameraModel "pinhole" カメラモデル（"pinhole" / "fisheye" / "ftheta" / "ortho" 等）
load_exposure bool True 画像からEXIF露出メタデータを読み込むか

NCore専用オプション（data_type="ncore" 時のみ）

設定名 型 デフォルト 説明 / とりうる値
ncore_camera_ids List[str] [] 読み込むカメラセンサーID（空なら自動検出）
ncore_lidar_ids List[str] [] 点群ソースID（lidar/radar/native、空なら自動検出）
ncore_seek_offset_sec float | None None 時間シーク開始オフセット（秒）
ncore_duration_sec float | None None クリップ長（秒）。None で全シーケンス
ncore_max_lidar_points int 500_000 LiDAR初期化点の最大数
ncore_lidar_color_generic_data_name str "rgb" LiDAR点のRGB色に使うgeneric-dataキー
ncore_poses_component_group str "default" NCore姿勢コンポーネントグループ名
ncore_intrinsics_component_group str "default" NCore内部パラメータコンポーネントグループ名
ncore_masks_component_group str "default" NCoreマスクコンポーネントグループ名

学習ステップ・保存・評価

設定名 型 デフォルト 説明 / とりうる値
batch_size int 1 学習バッチサイズ（学習率は自動スケール）
steps_scaler float 1.0 学習ステップ数のグローバル倍率
max_steps int 30_000 学習ステップ数
eval_steps List[int] [7000, 30000] 評価を行うステップ
save_steps List[int] [7000, 30000] モデルを保存するステップ
save_ply bool False PLYファイルを保存するか（サイズ大）
ply_steps List[int] [7000, 30000] PLYとして保存するステップ
disable_video bool False 学習・評価時の動画生成を無効化するか

ガウシアン初期化・SH

設定名 型 デフォルト 説明 / とりうる値
init_type str "sfm" 初期化戦略。"sfm" / "random" / "lidar"
init_num_pts int 100_000 初期ガウシアン数（sfm時は無視）
init_extent float 3.0 初期ガウシアンの広がり（カメラ範囲の倍数、sfm時は無視）
sh_degree int 3 球面調和関数の次数
sh_fp16 bool False SH係数をfp16にキャストしてSHカーネルへ渡す（パラメータ/Adam状態はfp32のまま）
sh_degree_interval int 1000 このステップごとにSH次数を1つ上げる
init_opa float 0.1 ガウシアンの初期不透明度
init_scale float 1.0 ガウシアンの初期スケール
ssim_lambda float 0.2 SSIM lossの重み

描画（クリッピング・戦略・モード）

設定名 型 デフォルト 説明 / とりうる値
near_plane float 0.01 ニアクリップ距離
far_plane float 1e10 ファークリップ距離
strategy DefaultStrategy | MCMCStrategy DefaultStrategy() ガウシアン密度制御の戦略
packed bool False packedモード（省メモリだがやや遅い）
sparse_grad bool False スパース勾配で最適化（実験的）
visible_adam bool False Taming 3DGS のvisible adamを使う（実験的）
antialiased bool False ラスタライズ時のアンチエイリアス（定量指標が少し落ちる場合あり）
random_bkgd bool False 学習時にランダム背景を使い透過を抑制する

学習率（LR）

設定名 型 デフォルト 説明
means_lr float 1.6e-4 3D位置のLR
scales_lr float 5e-3 スケール係数のLR
opacities_lr float 5e-2 不透明度（アルファ）のLR
quats_lr float 1e-3 回転（クォータニオン）のLR
sh0_lr float 2.5e-3 SH band 0（明るさ）のLR
shN_lr float 2.5e-3/20 高次SH（詳細）のLR

正則化

設定名 型 デフォルト 説明
opacity_reg float 0.0 不透明度の正則化係数
scale_reg float 0.0 スケールの正則化係数

カメラ姿勢最適化

設定名 型 デフォルト 説明
pose_opt bool False カメラ姿勢最適化を有効化
pose_opt_lr float 1e-5 姿勢最適化のLR
pose_opt_reg float 1e-6 姿勢最適化の正則化（weight decay）
pose_noise float 0.0 カメラ外部パラメータへのノイズ（姿勢最適化のテスト用）

外観最適化（実験的）

設定名 型 デフォルト 説明
app_opt bool False 外観最適化を有効化（実験的）
app_embed_dim int 16 外観埋め込み次元
app_opt_lr float 1e-3 外観最適化のLR
app_opt_reg float 1e-6 外観最適化の正則化（weight decay）

後処理・色補正（実験的）

設定名 型 デフォルト 説明 / とりうる値
post_processing "bilateral_grid" | "ppisp" | None None 外観補正の後処理手法
bilateral_grid_fused bool False bilateral gridでfused実装を使う（post_processing="bilateral_grid"時のみ）
bilateral_grid_shape Tuple[int,int,int] (16, 16, 8) bilateral gridの形状 (X, Y, W)
ppisp_use_controller bool True PPISPコントローラを有効化
ppisp_controller_distillation bool True PPISPでコントローラ蒸留を使う（controller有効時のみ）
ppisp_controller_activation_num_steps int 25_000 PPISPコントローラの活性化ステップ数（controller有効時のみ）
color_correct_method "affine" | "quadratic" "affine" cc_*メトリクスの色補正手法（後処理有効時のみ）
use_color_correction_metric bool False 評価時に色補正メトリクス（cc_psnr等）を計算するか

深度loss（実験的）

設定名 型 デフォルト 説明
depth_loss bool False 深度lossを有効化（実験的）
depth_lambda float 1e-2 深度lossの重み

TensorBoard・LPIPS・3DGUT

設定名 型 デフォルト 説明 / とりうる値
tb_every int 100 このステップごとにTensorBoardへ出力
tb_save_image bool False 学習画像をTensorBoardに保存するか
lpips_net "vgg" | "alex" "alex" LPIPSに使うネットワーク
with_ut bool False 3DGUT: unscented transform を使う
with_eval3d bool False 3DGUT: 3D空間での評価を使う

metrics

シーンごとの評価指標

torchmetricsの中で実装されている。

SSIM ( Structual Similarity Index Measure )

PSNR

LPIPS

学習の回し方

    CUDA_VISIBLE_DEVICES=0 python simple_trainer.py default --eval_steps -1 --disable_viewer --data_factor 4 \
        --render_traj_path eclipse \
        --data_dir {データセットのパス} \
        --result_dir {出力先のフォルダのパス} /

examples関連

benchmarks/mcmc.sh

3DGS-MCMCの再現ができるパラメータの設定がされたシェルスクリプト。

basic.shと比較すると以下の点が異なる

  • 学習スクリプトの第一引数をmcmcに設定
  • CAP_MAXの値に1000000を適用

mcmc.sh

CUDA_VISIBLE_DEVICES=0 python $EXAMPLES_DIR/simple_trainer.py mcmc --eval_steps -1 --disable_viewer --data_factor $DATA_FACTOR \
    --strategy.cap-max $CAP_MAX \
    --render_traj_path $RENDER_TRAJ_PATH \
    --data_dir $SCENE_DIR/$SCENE/ \
    --result_dir $RESULT_DIR/$SCENE/

basic.sh

# train without eval
CUDA_VISIBLE_DEVICES=0 python $EXAMPLES_DIR/simple_trainer.py default --eval_steps -1 --disable_viewer --data_factor $DATA_FACTOR \
    --render_traj_path $RENDER_TRAJ_PATH \
    --data_dir data/360_v2/$SCENE/ \
    --result_dir $RESULT_DIR/$SCENE/

Discussion