Skip to content

Minimum Training and Evaluation Flow

This page gives the shortest practical workflow for taking a prepared dataset through Smurfstudio training, inspecting the resulting 3D Gaussian Splatting model, and running the standard evaluation or multi-model visualization tools.

It is intended as a starting workflow, not a complete description of every available training or evaluation option.

1. Select or Prepare a Training Dataset

Choose the dataset for the run and verify that the required inputs are available.

At minimum, a normal dataset should contain:

  • training images;
  • a transforms.json file containing camera information;
  • valid camera intrinsics and cam2world transforms;
  • and any dataset-specific metadata required by the active dataparser.

Depending on the experiment, the dataset may also include:

  • per-image sun directions;
  • a COLMAP or other point cloud for initialization;
  • a spacecraft mesh for Mesh-Aware training;
  • masks or foreground information;
  • or other experiment-specific metadata.

Before training, verify that:

  1. image paths in transforms.json are correct;
  2. camera poses and intrinsics correspond to the supplied images;
  3. sun directions are present and expressed in the expected frame when required;
  4. point-cloud or mesh paths are valid when those resources are enabled;
  5. the configuration points to the intended dataset rather than a previous experiment.

For a new dataset

If the images still need camera reconstruction, complete the COLMAP/Nerfstudio processing workflow first. See COLMAP Use and the ADRAS-J Reconstruction Example.

2. Customize the Training Configuration

Start from the relevant configuration in splatfacto_train_example.py and create or modify a configuration for the experiment you intend to run.

At minimum, check:

  • dataset/dataparser path;
  • output or experiment naming;
  • total training steps;
  • initialization method;
  • density-control strategy;
  • shadow mapping or shadow splatting settings, if applicable;
  • appearance-field settings;
  • shadow-refinement settings;
  • and any experiment-specific options being tested.

When testing a new change, begin from a known-good configuration and modify as few settings as possible. This makes failures much easier to isolate.

For controlled method comparisons, keep unrelated settings fixed.

3. Run Training and Monitor It in Viser

Launch the selected configuration through the normal Nerfstudio/Smurfstudio ns-train workflow.

During training, monitor both the terminal and Viser.

Terminal

Watch for:

  • current training step;
  • loss values;
  • iterations per second;
  • Gaussian count;
  • refinement, densification, pruning, or opacity-reset operations;
  • warnings or CUDA errors.

Abrupt changes around a known density-control operation are not automatically failures, but large unexplained changes should be investigated.

Viser

Use the live Viser viewer to inspect:

  • whether useful geometry is forming;
  • whether the rendered object remains visible;
  • whether Gaussians are becoming excessively sparse or dense;
  • whether RGB/depth outputs appear reasonable;
  • and, when relevant, whether relighting and shadowing behavior is physically plausible.

Do not wait until the end of a long run to inspect the model. Early visual checks can catch incorrect datasets, broken geometry, opacity collapse, or configuration mistakes before substantial compute time is spent.

If something looks wrong, see Common Failure Modes and Troubleshooting.

4. Locate and Record the Trained Run

After training, identify the output directory for the run.

The most important artifacts are typically:

  • config.yml — records the final training configuration and is normally the entry point used by later viewer/evaluation scripts;
  • checkpoint files such as .ckpt — store trained model parameters;
  • optional Weights & Biases logs and metrics;
  • and any experiment-specific outputs saved by the run.

Keep the config.yml associated with its checkpoint directory. For most post-training scripts, use the path to config.yml rather than manually selecting an individual checkpoint unless the script specifically asks for one.

It is useful to record:

  • experiment name;
  • dataset;
  • important non-default settings;
  • final/selected checkpoint;
  • and a short note describing the purpose of the run.

5. Inspect or Composite the Trained Model

For a more detailed post-training inspection, load the trained run using its config.yml.

For one or more independently trained models, use:

multiple_model_view_example.py

and provide the config.yml path for each model.

This is useful for:

  • further visual inspection after training;
  • applying model transforms;
  • placing independently trained models into a shared scene;
  • checking relative scale, translation, and orientation;
  • and previewing multi-model composition and inter-model shadowing behavior before running a formal evaluation.

Viser Tutorial

6. Run Detailed Evaluation

After confirming that the trained model loads correctly and looks reasonable, run the evaluation scripts appropriate to the experiment.

Note: Both basic_dynamic_relighting_and_shadowing_eval.py and compare_dynamic_relighting_and_shadowing_runs.py are tracked on the 'smurfs2dev' branch in the Smurfstudio repository. They are part of a semi-standalone 'experiments' folder used to create thesis-specific figures and diagnostics, and require maturation before they can be selectively/bulk moved into the main branch.

For dynamic relighting and shadowing, a common starting point is:

basic_dynamic_relighting_shadowing_eval.py

Use this for detailed evaluation of a selected trained model/run, including the relevant render outputs and quantitative comparisons supported by the script.

For comparisons between multiple runs or methods, use:

compare_dynamic_relighting_shadowing_runs.py

This is useful for controlled comparisons such as:

  • baseline versus proposed method;
  • shadow mapping versus shadow splatting;
  • different shadow-refinement settings;
  • different receiver-bias settings;
  • or other experiment variants.

Before comparing runs, verify that they use compatible:

  • datasets/test frames;
  • camera poses;
  • sun directions;
  • evaluation settings;
  • image resolution;
  • and metric definitions.

Depending on the experiment, inspect:

  • RGB renders;
  • shadow/visibility outputs;
  • expected depth;
  • photometric metrics;
  • shadow-specific metrics;
  • 3D geometry metrics;
  • and multi-model renders.

7. Save the Important Outputs

For any run that may be referenced later, retain enough information that another researcher can reproduce or understand it.

At minimum, keep or record:

  • path to config.yml;
  • checkpoint/run directory;
  • important configuration choices;
  • evaluation script or command;
  • representative output images;
  • metrics/results;
  • and a short description of what was being tested.

For method comparisons, save representative renders from identical views and sun directions so the results can be compared side by side.

Workflow Summary

Select / prepare dataset
          ↓
Customize splatfacto_train_example.py
          ↓
Run ns-train
          ↓
Monitor terminal + Viser
          ↓
config.yml + checkpoints
          ↓
     ┌────┴─────────────────────────┐
     ↓                              ↓
Inspect / composite models      Detailed evaluation
multiple_model_view_            basic_dynamic_relighting_
example.py                      shadowing_eval.py
                                      ↓
                                compare_dynamic_relighting_
                                shadowing_runs.py
     └──────────────┬───────────────┘
                    ↓
             Save results / notes

This is the minimum repeatable loop to become comfortable with before moving into more specialized model-development or debugging work.