FaCT-GS: Fast and Scalable CT Reconstruction with Gaussian Splatting

1. real_dataset and synthetic_dataset are direct copies from the r2_gaussian project, used in the main performance analysis. Details on the dataset preparation can be found here for the synthetic dataset, and here for the real one.
2. coral_dataset contains multiple resolutions of the same coral scan, used in the scaling study.
3. init_dataset contains scan pairs used in the warmstart vs coldstart initialization study.
4. warmstart_dataset contains lung CT scan pairs used in the warmstart impact study in supplementary material.
5. teaser_figure holds scans used in generating the main teaser figure of the paper.

(overwrite with category.parameter=new_value)

Model:

• num_gaussians - Number of Gaussians the optimization is initialized with
• data_source_path - Path to the source data folder used during optimization
• model_path - Directory where checkpoints, evaluation dumps and exported point clouds are saved
• init_mode - How Gaussians are initialized:
  • gradient - gaussian locations sampled based on a probability distribution from a gradient of an FDK-reconstructed volume
  • intensity - above, but using intensities directly and not their gradients
  • precomputed/prior - only applicable for reconstruction (see below)
• density_thresh - Minimum voxel density used to discard background voxels during initialization
• density_rescale - Empirical scaling applied to the sampled densities to compensate for multi-Gaussian occlusion
• scale_min / scale_max - Lower and upper scale bounds expressed as a fraction of the target volume, converted to world units at runtime
• eval - When False only the training cameras are loaded from meta_data.json

Optimization:

• steps - Number of optimization steps to run. One step equals one rasterization/voxelization pass with backward propagation. In CT recon, an iteration consists of processing all available projections. For volume fitting, since there is only one volume used, step==iteration
• position_lr_init/final/max_steps - Learning rate schedule for Gaussian centers; *_max_steps is expressed as a fraction of steps
• density_lr_init/final/max_steps - Learning rate schedule for Gaussian densities/opacity
• scaling_lr_init/final/max_steps - Learning rate schedule for per-axis scales
• rotation_lr_init/final/max_steps - Learning rate schedule for spherical harmonics rotations
• lambda_dssim - Weight of the DSSIM loss component (set to 0 to disable)
• lambda_tv - Weight of the 3D total-variation regularizer
• ssim3d_early_stop / ssim3d_early_stop_threshold - Optional early-stopping guard. When enabled, training exits as soon as the reported 3D SSIM reaches or exceeds the provided threshold. Useful for time-to-SSIM studies (defaults to disabled).
• training_time_limit_seconds - Optional wall-clock limit (seconds). When >0, stops training once the accumulated training time crosses the threshold.
• densify_gaussians - Enables/disables periodic Gaussian densification and pruning
• density_min_threshold - Minimum density allowed during pruning; Gaussians below the threshold get removed
• densification_interval/densify_from_step/densify_until_step_percent - Controls when densification starts, how often it is triggered, and up to what portion of training it remains active
• densify_grad_threshold - Gradient magnitude threshold a Gaussian must exceed to be duplicated during densification
• densify_scale_threshold - Largest acceptable Gaussian scale (in % of the volume size) before it gets split during densification
• max_screen_size / max_scale / max_num_gaussians - Optional guards that clamp 2D footprint, 3D scale, or total Gaussian count; max_num_gaussians is a multiplier of the initial num_gaussians (default 1.1 = 110%)

Evaluation:

• eval_in_training - Run quantitative evaluation in the middle of training
• every_n_steps - Evaluation frequency measured in optimization steps (ignored when eval_in_training=False)
• eval_start - If True, evaluate the initialization before any optimization step
• eval_end - If True, evaluate after the final step (used for leaderboard metrics)
• extra_eval_iter_num - (optional) specific iteration to force an additional evaluation and metric export; useful for catching early progress snapshots such as the 150-iteration dumps used in the paper (eval_default_extra_150). For reconstruction runs, iterations equal full sweeps over the training cameras, while for volume fitting iteration == step.
• visualize_at_eval - When enabled, dumps reconstructed volumes (tiff + preview) at evaluation checkpoints
• visualize_gaussians - Exports Gaussian position/footprint visualizations and error maps for debugging

Profiling:

• profile - Turns PyTorch's profiler on/off
• profile_wait - How many steps to wait before collecting a trace
• profile_active - Number of active steps that are recorded in the trace

Parameters can either be changed directly in the config folder or when invoking the script.

To change a specific parameter, use:

python script.py category.parameter=new_parameter_val

e.g., python train_recon.py optim.steps=10000

To change a whole config preset, use:

python script.py category=new_category_preset

e.g., python train_recon.py eval=eval_silent

For major adjustments, it is recommended to create your own config presets.

Model:

• init_mode:
  • prior - Warm-start the optimization from a volume prior fitted with train_volume. Requires setting prior_path to a valid model (see below)
  • precomputed - Load initialized Gaussians from a precomputed point cloud. Legacy from the separate r2_gaussian init procedure (expects an init_[data_name].npy file in the data folder).
• prior_path - Absolute path to the point_cloud.pickle model file that should be loaded when init_mode=prior

Optimization:

• tv_vol_size - Side length (in voxels) of the cube that is randomly sampled for the 3D TV loss during reconstruction

Model:

• vol_name - Name (without extension) of the ground-truth volume inside the dataset directory that should be fitted, e.g., vol_prior or vol_gt

Optimization:

• quantize - Enables straight-through estimator quantization of Gaussian positions/scales/rotations/densities during training for model-size control. Useful for GS-based compression
• pos_bits / scale_bits / rot_bits / feat_bits - Bit precision allocated to xyz, scale, rotation and density/features when quantize=True (also used by the model size reporter)