Loading...
Searching...
No Matches
reusex::gsplat::TrainOptions Struct Reference
Optimizer / schedule parameters for the 3DGS training loop. More...
#include <train.hpp>
Collaboration diagram for reusex::gsplat::TrainOptions:
Public Attributes | |
| int | iterations = 2000 |
| float | lr_means = 1.6e-4f |
| scaled by scene extent (see above) | |
| float | lr_scales = 5e-3f |
| on log-scales | |
| float | lr_quats = 1e-3f |
| on raw (unnormalised) quaternions | |
| float | lr_opacities = 5e-2f |
| on logit-opacity | |
| float | lr_sh_dc = 2.5e-3f |
| on the degree-0 SH coefficients | |
| float | lr_sh_rest = 2.5e-3f / 20.0f |
| Learning rate for SH degrees 1..GaussianInitOptions::sh_degree — the view-*dependent* colour. | |
| int | sh_degree_interval = 1000 |
| Iterations between unlocking one more SH band (reference 3DGS's oneUpSHdegree). | |
| float | lambda_dssim = 0.2f |
| Weight of the D-SSIM term: loss = (1-l)*L1 + l*(1 - SSIM). | |
| bool | prune_enabled = true |
| Periodically drop Gaussians whose opacity has collapsed. | |
| int | prune_interval = 500 |
| iterations between prune passes | |
| int | prune_start = 500 |
| first iteration eligible for pruning | |
| float | prune_opacity = 0.005f |
| alpha below which a Gaussian is dropped | |
| float | prune_max_scale = 10.0f |
| drop Gaussians larger than this [m] | |
| MCMCOptions | mcmc |
| MCMC density control. | |
| int | holdout_every = 8 |
| Held-out split: every holdout_every-th view (indices 0, N, 2N, …) is excluded from training and used only for evaluation. | |
| int | eval_interval = 1000 |
| Iterations between held-out evaluation passes. | |
| int | eval_max_views = 32 |
| Upper bound on the views used per evaluation pass, per side. | |
| unsigned | seed = 42 |
| Seeds the per-iteration view draw, which makes the training schedule reproducible. | |
| int | log_interval = 100 |
| iterations between progress log lines | |
| std::vector< int > | render_iterations |
| Dump a rendered PNG of render_view_index at each of these iterations (0 = the untrained seed). | |
| std::filesystem::path | render_dir |
| std::size_t | render_view_index = 0 |
| const std::atomic_bool * | cancel_token = nullptr |
| Cooperative cancellation, owned by the caller and polled once per iteration. | |
| int | checkpoint_every = 0 |
| Write an intermediate .ply every N iterations (0 = off, the default). | |
| int | checkpoint_keep = 3 |
| How many checkpoint files to keep; older ones are deleted as new ones land. | |
| std::filesystem::path | checkpoint_dir |
| Directory for checkpoint .ply files. | |
Detailed Description
Optimizer / schedule parameters for the 3DGS training loop.
Learning rates follow the reference 3DGS implementation. lr_means is additionally scaled by the scene extent inside the trainer, because a position learning rate in metres is only meaningful relative to how large the scene is.
Member Data Documentation
◆ cancel_token
| const std::atomic_bool* reusex::gsplat::TrainOptions::cancel_token = nullptr |
Cooperative cancellation, owned by the caller and polled once per iteration.
When it flips, the loop stops at the end of the current iteration, runs a final evaluation, and returns a complete TrainResult — the run is cut short, not thrown away. May be null.
A raw pointer rather than a pipeline type on purpose: reusex_gsplat is a Layer-3 peer and cannot see reusex_pipeline (STANDARDS §1), so the contract is the narrowest thing both layers can name.
◆ checkpoint_dir
| std::filesystem::path reusex::gsplat::TrainOptions::checkpoint_dir |
Directory for checkpoint .ply files.
When empty, they go next to GsplatStageOptions::out_ply.
◆ checkpoint_every
| int reusex::gsplat::TrainOptions::checkpoint_every = 0 |
◆ checkpoint_keep
| int reusex::gsplat::TrainOptions::checkpoint_keep = 3 |
◆ eval_interval
| int reusex::gsplat::TrainOptions::eval_interval = 1000 |
Iterations between held-out evaluation passes.
Separate from log_interval because an evaluation renders many views and the training log line renders none.
◆ eval_max_views
| int reusex::gsplat::TrainOptions::eval_max_views = 32 |
◆ holdout_every
| int reusex::gsplat::TrainOptions::holdout_every = 8 |
Held-out split: every holdout_every-th view (indices 0, N, 2N, …) is excluded from training and used only for evaluation.
0 trains on every view and reports no held-out number.
The split is a pure function of the view count — it does not consume the RNG — so it is identical across runs and across the prune-only/MCMC comparison (STANDARDS §6).
◆ iterations
◆ lambda_dssim
| float reusex::gsplat::TrainOptions::lambda_dssim = 0.2f |
◆ log_interval
| int reusex::gsplat::TrainOptions::log_interval = 100 |
◆ lr_means
| float reusex::gsplat::TrainOptions::lr_means = 1.6e-4f |
◆ lr_opacities
| float reusex::gsplat::TrainOptions::lr_opacities = 5e-2f |
◆ lr_quats
| float reusex::gsplat::TrainOptions::lr_quats = 1e-3f |
◆ lr_scales
| float reusex::gsplat::TrainOptions::lr_scales = 5e-3f |
◆ lr_sh_dc
| float reusex::gsplat::TrainOptions::lr_sh_dc = 2.5e-3f |
◆ lr_sh_rest
| float reusex::gsplat::TrainOptions::lr_sh_rest = 2.5e-3f / 20.0f |
Learning rate for SH degrees 1..GaussianInitOptions::sh_degree — the view-*dependent* colour.
The reference 3DGS trains these at a twentieth of the DC rate and the ratio matters more than either absolute value: the higher bands start at zero and are the most expressive parameters in the model, so at the DC rate they race ahead of the geometry and absorb residuals that a Gaussian should have moved to explain. That fits the training views and shows up as a worse held-out number.
Ignored entirely when the model is degree 0, which is the default.
◆ mcmc
| MCMCOptions reusex::gsplat::TrainOptions::mcmc |
◆ prune_enabled
| bool reusex::gsplat::TrainOptions::prune_enabled = true |
Periodically drop Gaussians whose opacity has collapsed.
This is the only density control in this version — see the note on densification in docs/research/gaussian-splatting.md: the world-space rasterizer this trainer uses does not expose the screen-space absgrad that the reference clone/split heuristic keys on. Seeding from a LiDAR cloud supplies the density the reference has to grow.
◆ prune_interval
| int reusex::gsplat::TrainOptions::prune_interval = 500 |
◆ prune_max_scale
| float reusex::gsplat::TrainOptions::prune_max_scale = 10.0f |
◆ prune_opacity
| float reusex::gsplat::TrainOptions::prune_opacity = 0.005f |
◆ prune_start
| int reusex::gsplat::TrainOptions::prune_start = 500 |
◆ render_dir
| std::filesystem::path reusex::gsplat::TrainOptions::render_dir |
◆ render_iterations
| std::vector<int> reusex::gsplat::TrainOptions::render_iterations |
Dump a rendered PNG of render_view_index at each of these iterations (0 = the untrained seed).
Ignored when render_dir is empty.
◆ render_view_index
| std::size_t reusex::gsplat::TrainOptions::render_view_index = 0 |
◆ seed
| unsigned reusex::gsplat::TrainOptions::seed = 42 |
Seeds the per-iteration view draw, which makes the training schedule reproducible.
It does not make a run bit-reproducible, and nothing here can: gsplat's backward kernels accumulate per-Gaussian gradients with atomicAdd, so the summation order is decided by the GPU scheduler. Measured run-to-run spread is ~2.5e-6 relative on the loss after 20 iterations. This is a documented departure from STANDARDS §6 — the alternative is a deterministic-but-far-slower gradient reduction that gsplat does not provide.
◆ sh_degree_interval
| int reusex::gsplat::TrainOptions::sh_degree_interval = 1000 |
Iterations between unlocking one more SH band (reference 3DGS's oneUpSHdegree).
Rendering starts at DC only and reaches the model's full degree at sh_degree_interval * sh_degree; a locked band gets no gradient and stays at its zero initialisation.
Set to 0 to train every band from iteration 0. That is not recommended — see lr_sh_rest for why the higher bands need the DC term to settle first — but it makes the warm-up measurable rather than assumed.
A run shorter than sh_degree_interval * sh_degree never reaches the degree it was asked for; the trainer warns at startup and names the degree the schedule will actually reach rather than letting the run quietly deliver a cheaper model than requested (STANDARDS §5).
The documentation for this struct was generated from the following file:
- libs/reusex/include/gsplat/train.hpp
