Common Failure Modes and Troubleshooting

This page documents common failure modes that have appeared during Smurfstudio training, COLMAP reconstruction, and dynamic shadowing work. It is intended as a symptom-first debugging reference: start with what you observe, confirm the likely cause, and only then change the implementation or configuration.

Debug one cause at a time

When possible, reproduce the problem with the smallest useful case, compare against a known-good configuration or checkpoint, and change only one variable at a time. Save diagnostic outputs before modifying the implementation so that you can tell whether a change actually fixed the original failure.

Quick Symptom Index

What you see	Start here
Render suddenly becomes black or almost fully transparent	Model Becomes Black or Nearly Transparent
Randomly initialized Gaussians never organize into the spacecraft	Random Initialization Fails to Form Useful Geometry
Gaussian count grows extremely quickly or training runs out of GPU memory	Gaussian Count Grows Uncontrollably
Geometry is reasonable on the illuminated side but poorly formed or missing on the dark backside	Backside Geometry Is Poorly Formed with Single-Sun Training Data
COLMAP finishes, but the camera trajectory is folded, disconnected, or physically implausible	COLMAP Produces an Incorrect or Disconnected Camera Trajectory
Dark speckling or false self-shadowing appears on illuminated surfaces	Shadow Acne Appears on Lit Surfaces
Shadows appear detached from the receiver or caster	Shadows Are Detached or Peter-Panning

Failure or Expected Behavior?

Not every abrupt visual change indicates a bug. Before debugging deeply, determine whether the behavior is unexpected for the active method or training stage.

Observation	Usually a failure?	Notes
Gaussian count changes abruptly during a refinement or pruning step	Not necessarily	Density-control operations intentionally add and remove Gaussians.
Training loss changes slightly around a density-control operation	Not necessarily	A small discontinuity can occur when the Gaussian population changes.
Model becomes nearly fully transparent immediately after an opacity reset	Yes	Inspect the reset value and the configured culling threshold.
Geometry is poor only on the permanently dark side of a single-sun dataset	Often a data/observability limitation	The model receives little photometric evidence for surface structure that remains deeply shadowed.
COLMAP command completes but the reconstructed camera path is physically nonsensical	Yes	A successful command does not guarantee a valid reconstruction.
Small self-shadowing artifacts appear at shallow light angles	Usually	Inspect receiver-depth bias and the light-space depth comparison.
Shadows visibly detach from the receiving surface after increasing bias	Usually	This is a classic sign of excessive receiver bias.

Training and Density Control

Model Becomes Black or Nearly Transparent

What It Looks Like

Typical symptoms include:

The model is initially visible and then abruptly becomes black or almost completely transparent.
Gaussian opacities suddenly collapse to extremely small values.
Training continues numerically, but the rendered object does not visibly recover.
Loss values may still be reported even though the Gaussian population contributes almost nothing to the rendered image.
The failure may happen immediately after an opacity-reset or refinement operation.

Likely Cause

A particularly important failure mode is setting the culling alpha threshold to an extremely small value in an attempt to effectively disable culling.

Depending on the Smurfstudio configuration/version, this parameter may appear as something similar to cull_alpha_thresh or cull_alpha_threshold. If the opacity-reset logic derives its reset opacity from that threshold, an extremely small threshold can also produce an extremely small reset opacity.

For example, a culling threshold near:

1e-6

can result in a reset opacity on the order of:

2e-6

If essentially all Gaussians are reset to this range, their image contribution can become so small that normal optimization does not recover a useful opacity distribution.

Check First

Identify the exact training step where the render becomes black.
Check whether an opacity-reset, densification, or pruning operation occurred at or immediately before that step.
Inspect the configured culling alpha threshold.
Log opacity statistics immediately before and after the suspected reset:
minimum
maximum
mean or median
useful percentiles
If possible, save an opacity histogram before and after the reset.
Confirm whether most or all Gaussians were reset to approximately the same tiny opacity.

Fix

Do not use an arbitrarily tiny culling threshold as a substitute for explicitly disabling culling.

If the goal is to prevent culling:

change or gate the culling behavior directly;
modify the culling schedule explicitly;
or use a configuration option that disables the relevant operation, if one exists.

Keep the opacity-reset behavior and the culling threshold logically separate whenever possible.

After changing the configuration, rerun a short training test that crosses the same opacity-reset/refinement step and verify that:

the rendered model remains visible;
opacity statistics remain in a recoverable range;
and gradients continue to produce meaningful updates after the reset.

Why This Happens

A Gaussian with nearly zero opacity contributes almost nothing to the rendered image. If an entire model is simultaneously pushed into that regime, the photometric learning signal reaching those primitives can become too weak to restore them. The training loop can therefore continue without crashing while the scene remains effectively invisible.

Search the active training configuration and density-control implementation for:

cull_alpha_thresh
cull_alpha_threshold
opacity-reset logic
pruning logic
refinement scheduling

Key lesson

A parameter that controls when Gaussians are culled should not be assumed to be safe as a proxy for turning culling off, especially if the same value is reused by opacity-reset logic.

Random Initialization Fails to Form Useful Geometry

What It Looks Like

Typical symptoms include:

Randomly initialized Gaussians remain broadly distributed through the scene.
A recognizable spacecraft shape never forms, or forms only very slowly.
Large numbers of primitives are removed before they establish useful support.
The reconstructed object is incomplete, diffuse, or surrounded by persistent outlying Gaussians.
Training from a COLMAP or other informed initialization works substantially better than the random-initialization run.

Likely Cause

Pure random initialization gives the model very little useful information about where the object surface is located. At the same time, the normal density-control strategy may begin pruning, duplicating, or otherwise modifying Gaussians before a useful spatial organization has emerged.

The failure is therefore not necessarily that optimization is completely broken. The early optimization problem may simply be too poorly conditioned for the normal training schedule.

Check First

Inspect the Gaussian positions very early in training rather than only looking at RGB renders.
Compare the primitive distribution at:
initialization;
the first few hundred steps;
the first density-control/refinement event;
and the point where the reconstruction stops improving.
Check whether large numbers of Gaussians are culled before they ever project onto the foreground object.
Compare against a known-good point-cloud-initialized run if one is available.
Verify that foreground masks, camera intrinsics, and camera poses are correct before blaming density control.

Fix

Use a short warm-start stage before normal training.

A practical structure is:

Random Gaussian initialization
        ↓
Temporarily emphasize position / foreground attraction
        ↓
Pull projected Gaussians toward the foreground object
        ↓
Use conservative or delayed culling / densification
        ↓
Resume normal optimization and density control

The warm start should be strong enough to organize the Gaussian population, but temporary. Once the primitives are concentrated around the object, normal appearance, geometry, and density-control optimization should resume.

If random initialization is not itself an experimental requirement, prefer an informed initialization such as a valid COLMAP point cloud when available.

Why This Happens

Normal 3DGS optimization assumes that at least some primitives already contribute meaningfully to the training images. With a poorly placed random population, many Gaussians may contribute little or nothing, so both photometric gradients and density-control statistics provide weak guidance.

The warm start changes the early problem from:

learn the entire scene while simultaneously discovering where the object is

into:

first place a useful primitive population near the object, then solve the normal reconstruction problem.

Review:

random Gaussian initialization
foreground-mask generation
projected-distance or foreground-attraction loss
early culling behavior
density-control start time
Mesh-Aware or Support-Aware strategy configuration, if enabled

Gaussian Count Grows Uncontrollably

What It Looks Like

Typical symptoms include:

Gaussian count rises much faster than expected.
Iterations per second steadily decrease.
Viser becomes increasingly slow or unresponsive.
GPU memory usage continually increases.
Training eventually fails with CUDA out-of-memory errors.
Model size grows dramatically without a corresponding improvement in rendered quality.

Likely Cause

The density-control strategy is creating new Gaussians faster than ineffective primitives are being removed.

Possible causes include:

densification/refinement running too aggressively;
pruning criteria being too permissive;
culling thresholds being unintentionally disabled;
custom support/contribution gates protecting too many weak Gaussians;
a refinement schedule that runs for longer than intended;
or a custom density-control strategy being configured differently from the expected baseline.

Check First

Plot Gaussian count as a function of training step.
Mark refinement, densification, reset, and pruning operations on the same plot if possible.
Determine whether growth is:
gradual;
stepwise at known refinement events;
or unexpectedly continuous.
Compare the run against a known-good configuration.
Inspect:
pruning frequency;
opacity thresholds;
contribution/support gates;
refinement start and stop steps;
and any strategy-specific protection rules.
Confirm that the intended density-control strategy is actually active.
If using a custom strategy, compare its Gaussian-count trajectory against the default strategy on the same dataset.

Fix

Fix the underlying imbalance rather than imposing an arbitrary hard Gaussian-count limit first.

Depending on the cause, this may mean:

stopping refinement at the intended step;
restoring effective pruning;
tightening a support/contribution protection condition;
correcting an accidentally disabled culling threshold;
reducing the aggressiveness or frequency of densification;
or reverting temporarily to the default strategy to isolate whether the custom strategy is responsible.

After changing the configuration, compare both Gaussian count and render quality. A lower count alone is not evidence that the problem is fixed.

Why This Happens

3DGS density control intentionally increases model capacity in difficult image regions. If the criteria for creating Gaussians are much easier to satisfy than the criteria for removing them, model size can grow continuously.

This can be especially easy to introduce when adding custom "protect this Gaussian" logic: a gate intended to preserve useful surface primitives can accidentally protect a large population of weak or redundant primitives.

Useful Diagnostics

At minimum, log:

training step;
total Gaussian count;
count added during refinement;
count removed during pruning;
GPU memory usage;
iterations per second.

If modifying Mesh-Aware or Support-Aware logic, also log the number of Gaussians protected by the custom strategy.

Backside Geometry Is Poorly Formed with Single-Sun Training Data

What It Looks Like

Typical symptoms include:

the illuminated side of the spacecraft reconstructs reasonably well while the opposite side is incomplete, diffuse, or poorly shaped;
Gaussians on the non-illuminated side are sparse, misplaced, oversized, or otherwise less surface-consistent;
RGB renders from familiar training-side views may still look acceptable even though the recovered 3D shape is poor;
geometry quality degrades most strongly in regions that remain deeply shadowed across nearly all training images;
rotating the trained model in Viser reveals that the dark backside is much less coherent than the illuminated side.

Likely Cause

This is often a data-coverage and observability limitation rather than an implementation bug.

With a single harsh illumination direction, one side of the spacecraft can remain deeply shadowed across most or all of the training set. Even if cameras observe that side geometrically, the pixels may contain very little texture, contrast, or illumination variation for the optimizer to use when locating the surface.

For 3DGS, this can make it difficult to distinguish between several different Gaussian arrangements that all render as nearly black. The optimizer therefore receives much stronger geometric guidance from the illuminated side than from the persistently dark side.

The problem can be especially pronounced for space imagery because:

illumination is highly directional;
cast and self-shadows can be very dark;
large spacecraft surfaces may have little texture;
and the background may also be close to black.

Check First

Inspect the training images and determine whether the poorly reconstructed region is consistently shadowed across the dataset.
Compare the model from:
illuminated-side viewpoints;
shadow-side viewpoints;
depth or Gaussian-geometry views in Viser.
Confirm that the camera coverage itself is adequate. A dark backside and an unobserved backside are different problems.
Check whether COLMAP or another initialization source contains useful points on the dark side.
Compare against a dataset or run with multiple sun directions, if available.
If possible, evaluate 3D geometry directly rather than judging only from RGB renders.

Fix / Mitigation

The best fix is to provide additional information about the poorly illuminated surface.

Preferred options, when available, include:

train with multiple illumination directions so that surfaces shadowed under one sun angle become illuminated under another;
include additional imagery in which the dark side receives usable illumination;
use a stronger geometric initialization, such as a reliable COLMAP point cloud or mesh-derived initialization;
incorporate depth, mesh, silhouette, or other geometric supervision when available;
evaluate whether an informed density-control strategy helps preserve weakly observed surface primitives.

If the dataset is inherently restricted to one sun direction, treat this as an expected limitation of the available observations. A training-parameter change may improve the result, but it cannot fully recover surface detail that is never meaningfully constrained by the images.

Do not confuse appearance quality with geometry quality

A model can produce plausible dark RGB pixels while still having incorrect 3D geometry on the shadowed side. Inspect Gaussian positions, depth, or a reconstructed surface before concluding that the backside was learned correctly.

Why This Happens

Photometric reconstruction works by adjusting geometry and appearance until rendered training views match the observed images.

On a well-illuminated surface, image gradients, edges, texture, and view-dependent changes provide useful evidence about where the surface should be. On a surface that remains nearly black under every training view, many different geometric configurations can produce nearly the same pixel values.

Well illuminated surface
        ↓
visible texture / edges / shading changes
        ↓
stronger photometric constraint
        ↓
better-constrained geometry

Persistently shadowed surface
        ↓
many pixels ≈ black
        ↓
different geometries can render similarly
        ↓
weakly constrained geometry

Useful Comparison

A particularly useful diagnostic is to train comparable models with:

Single sun direction
        vs.
Multiple sun directions

and inspect the same nominal backside region in:

RGB;
expected depth;
Gaussian geometry;
and, if available, 3D metrics.

If the backside improves when that surface becomes illuminated in at least some training images, the original failure was likely dominated by illumination coverage rather than a general geometry-learning bug.

Review:

number and distribution of training sun directions;
camera coverage of the affected surface;
point-cloud or mesh initialization quality;
expected-depth visualization;
Mesh-Aware / Support-Aware density control;
and any future depth-guided or geometry-supervised training methods.

Dataset Preparation / COLMAP

COLMAP Produces an Incorrect or Disconnected Camera Trajectory

What It Looks Like

Typical symptoms include:

COLMAP completes without an error, but the recovered camera trajectory is physically implausible.
The camera arc folds back across itself.
Multiple disconnected camera groups are reconstructed.
Only a fraction of the source images register.
Duplicate or inconsistent spacecraft geometry appears in the sparse point cloud.
The reconstructed trajectory does not resemble the known or expected image sequence.

Likely Cause

Spacecraft imagery can be particularly difficult for feature-based structure from motion because the target may have:

repeated or symmetric geometry;
low-texture regions;
large dark areas;
highly reflective surfaces;
substantial appearance changes;
and a camera sequence that samples only a limited observation arc.

Incorrect feature correspondences or a weak view graph can therefore produce a mathematically valid but physically incorrect reconstruction.

The choice of matching and mapping strategy also matters. A sequentially captured image set should generally exploit its known ordering rather than treating all images as unrelated.

Check First

Open the sparse reconstruction in COLMAP and inspect the camera trajectory, not only the point cloud.
Check how many source images registered successfully.
Verify that the recovered camera ordering is physically plausible.
Inspect feature matches between representative neighboring frames.
Look specifically for correspondences between visually similar but physically different symmetric spacecraft features.
Confirm whether the dataset is truly sequential.
Check whether the reconstruction forms one connected model.
Compare the result against the workflow in COLMAP Use.
For the ADRAS-J case, compare against ADRAS-J Dataset COLMAP Reconstruction Example.

Fix

For an ordered image sequence, start with a sequential matching strategy and tune the connectivity of the view graph before moving to more expensive all-to-all matching.

Useful actions can include:

increasing sequential matching overlap;
enabling or tuning quadratic-overlap proposals;
checking whether loop detection is useful;
inspecting representative feature correspondences manually;
using exhaustive matching when the dataset is small enough and image ordering is not reliable;
comparing incremental and global mapping;
and reducing matching block size when GPU memory, rather than reconstruction correctness, is the limiting issue.

For ADRAS-J specifically, the incremental mapping workflow produced a more reliable camera trajectory than the earlier global-mapping attempts.

Why This Happens

COLMAP optimizes a reconstruction from feature correspondences; it does not know the true spacecraft geometry or expected camera path. If the feature graph contains incorrect but internally consistent matches, the mapper can converge to a reconstruction that is numerically valid but physically wrong.

Do not use command success as the validation criterion

A COLMAP command completing successfully only means that the solver ran. Always inspect the recovered camera poses and sparse geometry before converting the reconstruction for Nerfstudio/Smurfstudio.

Useful Diagnostics

Save screenshots of:

the full camera trajectory;
the sparse point cloud;
the number of registered images;
and representative feature-match pairs.

When changing matching settings, compare these diagnostics side by side rather than judging only from the final training result.

Relighting and Shadowing

Shadow Acne Appears on Lit Surfaces

What It Looks Like

Typical symptoms include:

dark speckles, bands, or patches appear on surfaces that should be directly illuminated;
the artifact resembles a surface incorrectly shadowing itself;
errors become more visible at shallow or grazing illumination angles;
increasing receiver bias reduces the artifact;
and the problem occurs even when there is no meaningful external occluder.

Likely Cause

The shadowing pipeline compares receiver depth against a light-space shadow representation. Unlike an ideal infinitesimal surface point, a 3D Gaussian has finite, anisotropic spatial extent.

A Gaussian can therefore overlap its own shadow representation in depth. At shallow illumination angles, this effect can become stronger because more of the Gaussian's extent projects along the light direction.

The result is a false conclusion that the receiver lies behind an occluder, producing shadow acne.

Check First

Determine whether the dark artifact lies on a surface that should be directly illuminated.
Check whether the artifact becomes stronger at grazing light angles.
Compare the result with receiver bias disabled, reduced, and increased.
Verify that the artifact is caused by self-shadowing rather than a genuine external occluder.
Inspect the raw physical shadow/visibility output before any learned shadow refinement.
If possible, compare the same view using both shadow mapping and shadow splatting.

Fix

Use an appropriate receiver-depth bias when comparing the receiver against the light-space depth/visibility representation.

In the Smurfstudio shadowing pipeline, receiver bias should account for the finite Gaussian geometry rather than relying only on a single global constant. The goal is to move the receiver comparison far enough to avoid self-intersection without moving it so far that real shadows detach from the surface.

Tune and validate the bias on:

directly illuminated faces;
grazing-light configurations;
sharp shadow boundaries;
and scenes with genuine inter-object occlusion.

See the shadowing discussion in Completed Work for the broader motivation and implementation context.

Why This Happens

The classic shadow-map comparison assumes a clean separation between the stored occluder depth and the receiver depth. A Gaussian splat instead occupies a region of space and has a nonzero extent along the light direction. Without a correction, the receiver can incorrectly fail its own visibility test.

Useful Diagnostic Sweep

A fixed-view bias sweep is particularly useful:

bias = 0
bias = small
bias = nominal
bias = large

Hold the camera, sun direction, model, and all other rendering settings constant. Compare the illuminated surfaces and shadow boundaries across the sweep.

Shadows Are Detached or Peter-Panning

What It Looks Like

Typical symptoms include:

a visible gap appears between an object and the shadow it should cast;
a contact shadow appears to "float" away from the receiving surface;
thin or close-contact shadows disappear;
increasing receiver bias makes the separation worse;
while reducing receiver bias moves the shadow back toward the correct boundary.

Likely Cause

The receiver bias is too large.

Receiver-depth bias is introduced to prevent a surface from incorrectly shadowing itself. However, shifting the receiver too far in the light-space depth comparison can also cause genuine nearby occluders to be ignored.

This produces the classic peter-panning effect: the shadow appears separated from the object or receiving contact region.

Check First

Render the exact same camera and sun configuration with several receiver-bias values.
Confirm that the shadow moves farther away as bias increases.
Check whether reducing bias restores the contact shadow.
Inspect the raw physical visibility result before learned shadow refinement.
Compare regions suffering from peter-panning against regions that previously showed shadow acne.
Verify that a world-scale or normalization change has not unintentionally changed the effective size of the bias.

Fix

Reduce or correct the receiver bias rather than attempting to repair the detached shadow with the refinement network.

The desired bias is the smallest value or per-Gaussian correction that reliably suppresses self-shadowing artifacts while preserving:

contact shadows;
narrow cast shadows;
shadow boundaries;
and inter-object occlusion.

When changing the receiver-bias formulation, test both failure directions:

too little bias  →  shadow acne
appropriate bias →  clean visibility
too much bias    →  peter-panning

A fix should improve the tradeoff rather than merely moving the system from one failure mode to the other.

Why This Happens

Receiver bias deliberately shifts the visibility comparison away from the physical receiver location. If that shift becomes too large, nearby real occluders no longer appear to block the receiver, so the shadow boundary moves away from its physically correct location.

Review:

receiver-depth bias computation;
Gaussian extent along the light direction;
normal/alignment-dependent bias terms, if enabled;
scene-scale normalization;
shadow mapping/splatting depth conventions;
and any learned shadow-refinement stage applied after physical visibility.

Always evaluate acne and peter-panning together

A receiver-bias change should never be judged only by whether shadow acne disappeared. Verify that contact shadows and shadow boundaries remain correctly attached at the same time.

Common Failure Modes and Troubleshooting

Quick Symptom Index

Failure or Expected Behavior?

Training and Density Control

Model Becomes Black or Nearly Transparent

What It Looks Like

Likely Cause

Check First

Fix

Why This Happens

Related Parameters / Areas

Random Initialization Fails to Form Useful Geometry

What It Looks Like

Likely Cause

Check First

Fix

Why This Happens

Related Areas

Gaussian Count Grows Uncontrollably

What It Looks Like

Likely Cause

Check First

Fix

Why This Happens

Useful Diagnostics

Backside Geometry Is Poorly Formed with Single-Sun Training Data

What It Looks Like

Likely Cause

Check First

Fix / Mitigation

Why This Happens

Useful Comparison

Related Areas

Dataset Preparation / COLMAP

COLMAP Produces an Incorrect or Disconnected Camera Trajectory

What It Looks Like

Likely Cause

Check First

Fix

Why This Happens

Useful Diagnostics

Relighting and Shadowing

Shadow Acne Appears on Lit Surfaces

What It Looks Like

Likely Cause

Check First

Fix

Why This Happens

Useful Diagnostic Sweep

Shadows Are Detached or Peter-Panning

What It Looks Like

Likely Cause

Check First

Fix

Why This Happens

Related Areas