slam-runtime
Run and troubleshoot the CUDA-only Gaussian-SLAM pipeline: validate the environment, construct safe run_slam.py invocations, understand tracking/mapping/submaps and outputs, control seeds and W&B, and prepare non-submitting SLURM plans.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- slam-runtime
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Run and troubleshoot the CUDA-only Gaussian-SLAM pipeline: validate the environment, construct safe run_slam.py invocations, understand tracking/mapping/submaps and outputs, control seeds and W&B, and prepare non-submitting SLURM plans.
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/cli-reference.md4.6 KB
- 参考文档references/cluster-reproduction.md3.9 KB
- 参考文档references/troubleshooting.md6.5 KB
- 参考文档references/workflows.md6.0 KB
03 SKILL.md 正文
Gaussian-SLAM runtime
Use this skill when a user wants to execute, configure, reproduce, or recover a
Gaussian-SLAM run from this repository. The entry point is run_slam.py; the
repository's execution path is CUDA-only. Do not offer a CPU fallback for
tracking, mapping, rendering, or evaluation. Dataset acquisition and dataset
file-layout instructions belong to datasets-and-configuration; evaluation
metric internals belong to evaluation-and-mapping.
Input/output contract
Required inputs
- A scene YAML path passed as the positional
config_pathargument. - A config resolving to
dataset_name,data,cam,tracking,mapping,seed, anduse_wandb. A scene config normally inherits a dataset base config and suppliesdata.scene_name,data.input_path, anddata.output_path. - A prepared RGB-D scene and camera metadata accepted by the selected dataset adapter. The dataset's layout is intentionally not specified here; ask the dataset skill for that contract.
- A CUDA-capable PyTorch installation and both compiled extensions:
simple_knn._Candgaussian_rasterizer._C.
Use explicit --input_path and --output_path values for portable runs. The
config loader resolves inherit_from using the path as written, relative to
the process working directory, so launch from the repository root (or use
paths that resolve from the chosen working directory).
Produced artifacts
run_slam.py creates the output directory, saves the effective config.yaml,
then runs tracking/mapping followed by the repository evaluator. Common
artifacts are:
config.yaml: effective merged configuration after CLI overrides;estimated_c2w.ckpt: estimated camera-to-world poses;submaps/000000.ckpt, etc.: checkpoints containing Gaussian parameters and the keyframe IDs belonging to the completed prior submap;mapping_vis/*.jpgand the createdtracking_vis/directory;- evaluator artifacts such as
rendering_metrics.json,reconstruction_metrics.json,ate_aligned.json, PNG summaries, a Replica mesh, and a refined global-map PLY when the corresponding evaluation phase succeeds.
The evaluator catches failures per evaluation phase and prints a traceback, so
an All done.✨ line is not sufficient evidence that every evaluation artifact
exists. Check the expected files and the log. The active final Gaussian model
is not explicitly finalized after the main loop; verify submap completeness
before consuming checkpoints as a final map.
Required preflight
Run these checks before a full scene. They are safe and do not download data, submit jobs, or contact W&B:
nvidia-smi
python - <<'PY'
import torch
print("torch", torch.__version__, "cuda", torch.version.cuda)
assert torch.cuda.is_available(), "Gaussian-SLAM requires CUDA"
print(torch.cuda.get_device_name(0), torch.cuda.get_device_capability(0))
PY
python - <<'PY'
import simple_knn._C
import gaussian_rasterizer._C
print("CUDA extensions import")
PY
python run_slam.py --help
python skills/disco/gaussian-slam/sub-skills/slam-runtime/scripts/check_cli.py \
configs/Replica/room0.yaml
The repository environment specifies Python 3.10, PyTorch 2.1.2 with CUDA
12.1, torchvision 0.16.2, FAISS-GPU, Open3D 0.18.0, and pinned builds of the
two CUDA extensions. Building extensions needs a compatible host compiler; the
README requires exported CC and CXX. A verified inspection environment
passed CUDA allocation and both extension imports on an NVIDIA A100-SXM4-40GB
with compute capability 8.0 (SM80). Treat that as evidence for A100/SM80
compatibility, not as a promise for arbitrary GPUs. Match the PyTorch/CUDA
runtime, host compiler, toolkit, and extension build target to the actual
machine.
GaussianModel imports simple_knn._C.distCUDA2 at module import and uses it
when adding points. src/utils/utils.py imports the custom
gaussian_rasterizer; render settings, tensors, and camera optimization are
also hard-coded to CUDA. Missing either extension, a CPU-only Torch build, or a
visible device mismatch is a prerequisite failure—not something to work around
by changing the device to CPU.
Standard run
From the repository root, start with a small bounded scene/config if one is available, then use the full run:
python run_slam.py configs/<dataset>/<scene>.yaml \
--input_path <scene-input> \
--output_path <run-output>
The process is sequential: it loads and recursively merges YAML inheritance,
updates selected fields from CLI arguments, optionally initializes W&B, seeds
Python/NumPy/PyTorch/CUDA, runs GaussianSLAM.run(), and then constructs an
Evaluator from the saved output config. The first two frames use dataset poses;
subsequent frames go through the configured tracker. Mapping runs on the
configured keyframe cadence and always appends the last frame to the mapping
IDs. Do not infer that --gt_camera changes this flow: the flag is parsed but
is not applied by update_config_with_args; select
tracking.odometry_type: gt in YAML when ground-truth tracking is intended.
For a deterministic, non-W&B smoke invocation, make the output unique and explicit:
DISABLE_WANDB=true python run_slam.py configs/<dataset>/<scene>.yaml \
--input_path <scene-input> \
--output_path <run-output> \
--seed 0
This controls the software RNGs (torch, CUDA, NumPy, Python, and hash seed)
and disables cuDNN benchmarking, but the README explicitly warns that the
Differential Gaussian rasterizer is nondeterministic. Compare runs with a
small tolerance and record GPU, driver, extension build, config, and seed.
CLI and configuration
Read references/cli-reference.md before changing hyperparameters. It records every parser option, its target config field, and source-level caveats (including parsed-but-ineffective options and truthiness checks that ignore zero). Use the checker to catch missing inherited fields and contradictory filter flags before starting a GPU job.
The highest-risk runtime changes are tracking iterations/loss weighting and mapping cadence/iterations. Large new-submap point counts, high-resolution frames, and long optimization schedules increase VRAM and wall time. Lower cadence or iteration counts only for a smoke test; do not call a shortened run paper reproduction.
Tracking, mapping, and submaps
- Tracking.
Tracker.trackrenders the current Gaussian model and optimizes camera rotation/translation using RGB and depth losses.odometry_typeisgt,const_speed, orodometer; the latter uses the configured visual odometer for initialization. Alpha and depth-outlier filters affect the tracking mask. A high initial loss can double tracking iterations; withhelp_camera_initialization, the tracker may retry initialization with an odometer estimate. - Mapping. At mapping frames, the mapper creates a keyframe, seeds 3D
points from RGB-D and the estimated pose, adds non-duplicate points to the
current Gaussian model using
distCUDA2, optimizes the current submap, and writes a visualization. New submaps use edge/gradient seeding; an existing submap uses alpha/depth-error regions. Dataset-specific point-cloud filtering is an implementation detail; do not substitute a missing dataset contract. - Submap boundaries. With
submap_using_motion_heuristic: true, the source starts a new submap when motion from the last submap start exceeds a hard-coded 50-degree rotation or 0.5 translation threshold. Otherwise it usesnew_submap_everyframe IDs and also includes the last frame. At a boundary, the prior model is written as a zero-padded checkpoint, keyframes are reset, and a new model starts at that frame. The loop saves poses at the end but does not perform a separate final active-model checkpoint; inspect the output rather than assuming the last active model is serialized.
W&B and seed controls
Configs default to use_wandb: False. For an offline/local run, prefer that
setting or set DISABLE_WANDB=true; the entry point treats exactly the string
true as a forced disable. If W&B is enabled, run_slam.py calls wandb.init,
logs source code, and uploads tracking/mapping/evaluation records. Credentials
and network access are not required for the default disabled path. If a site
needs W&B, decide explicitly whether online or offline mode is appropriate and
ensure its run directory is writable: the source contains a site-specific
absolute W&B directory that may not exist on another machine, and it is not a
CLI setting. Patch it to a writable path or keep W&B disabled; do not expose
credentials in configs or SLURM scripts.
SLURM
Use references/cluster-reproduction.md or run the safe planner:
python skills/disco/gaussian-slam/sub-skills/slam-runtime/scripts/render_sbatch_plan.py \
--dataset Replica --scene room0 --scene room1 \
--input-root <input-root> --output-root <output-root>
The planner only prints a reviewable batch script; it never runs sbatch,
starts Python SLAM, downloads data, or authenticates W&B. Review the generated
array bounds, config directory, scene names, input/output roots, partition,
GPU request, and environment activation before manually submitting it. The
repository example contains site placeholders, a dataset-directory case
mismatch for ScanNet++, a fixed array example that must be changed per dataset,
and a trailing continuation after --group_name; use the corrected recipe in
the reference instead of copying it verbatim.
Failure recovery
- Preserve the run log and output directory. Do not delete partial submaps or overwrite a prior run while diagnosing it.
- Classify the first failure: environment/extension, config resolution, dataset contract, CUDA/VRAM, W&B, or post-SLAM evaluation.
- Re-run the corresponding preflight or checker. For config failures, use an explicit scene config and absolute/working-directory-correct input/output overrides. For extension failures, rebuild both pinned extensions for the active Torch/CUDA ABI and GPU architecture; never install a CPU substitute.
- For CUDA out-of-memory, reduce the smoke-test frame limit and mapping point sample/iterations, close competing GPU jobs, and use a fresh output path. Treat a successful reduced run as a diagnostic only.
- For W&B errors, disable it with
DISABLE_WANDB=trueand rerun; separately repair writable run-directory/network/auth configuration if online logging is required. - If tracking diverges, inspect the initial-loss message and try the config-supported odometry initialization or a bounded iteration adjustment. Keep the change in the saved config and record it; do not silently switch to ground-truth poses.
- If SLAM completes but evaluation reports a traceback, verify
estimated_c2w.ckptandsubmaps/first, then treat the affected evaluation artifact as missing. Evaluation failures do not prove tracking/mapping failed, andAll done.✨does not prove evaluation succeeded.
See references/troubleshooting.md for symptom, likely cause, safe check, and recovery tables.
Difficult synthetic cases for verification
- Case A — ignored override and portable logging: provide a valid scene
config with
--track_w_color_loss 0.1 --gt_camera,DISABLE_WANDB=true, and a writable output path. The checker/handoff must warn that those two options do not update the config, while the run plan preserves the YAML odometry and W&B-disabled state rather than claiming ground-truth tracking. - Case B — boundary plus GPU failure: use a tiny synthetic RGB-D fixture and
a config with
map_every: 1, a boundary at the last frame, and a deliberately oversizednew_submap_points_numfor the available VRAM. The expected recovery is a preserved partial output, an OOM classification, a reduced diagnostic config in a new output directory, and an explicit check that only completed prior submaps are consumed—not a CPU rerun or an assumed final checkpoint.
Scope and evidence limits
This skill is runtime-focused. It does not define dataset directory layouts, download commands, metric formulas, mesh evaluation semantics, or global-map quality thresholds. No full-scene execution, dataset download, SLURM submission, or W&B network/login test was performed during construction. The environment report proves package/CUDA allocation/extension-import readiness on an SM80 A100 inspection host, not end-to-end scene correctness on every supported dataset or GPU.
Load the focused references progressively:
- references/workflows.md for execution stages and output validation;
- references/cli-reference.md for exact flags;
- references/cluster-reproduction.md for a corrected, non-submitting cluster recipe;
- references/troubleshooting.md for recovery.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.