GIM CLI Interface Reference

Complete reference for all CLI-capable functions and their configurations.

1. Model Download Script
2. Reconstruction (SfM)
3. Hybrid Densification (GIM + Depth)
4. Depth Densification (MoGe Only)
5. MoGe Inference (Standalone)
6. Sparse COLMAP Filtering
7. GIM Densifier
Filtering Presets Reference

1. Model Download Script

Script: download_models.py Command: uv run download_models.py

Parameter	Type	Default	Description
`--model-type`	`"moge" \| "global" \| "all"`	`"moge"`	Which models to download
`--weights-dir`	`str`	`"weights"`	Directory to store models
`--skip-existing`	`bool`	`True`	Skip download if model exists
`--moge-models`	`str`	`"recommended"`	Which MoGe models: 'recommended', 'all', or comma-separated names

Example Usage:

# Download recommended MoGe model only
uv run download_models.py

# Download all MoGe models
uv run download_models.py --moge-models all

# Download specific models
uv run download_models.py --moge-models "moge-2-vitb-normal,moge-2-vits-normal"

# Download global descriptors for retrieval-based reconstruction
uv run download_models.py --model-type global

# Download everything
uv run download_models.py --model-type all

2. Reconstruction (SfM)

Script: scripts/reconstruction/reconstruction.py Command: uv run scripts/reconstruction/reconstruction.py

Primary Configuration

Parameter	Type	Default	Description
`--input-path`	`str`	required	Path to directory containing images/ subdirectory
`--output-path`	`str \| None`	`None`	Output path (auto: {input_path}/{sparse_subdir})

Directory Structure

Parameter	Type	Default	Description
`--images-subdir`	`str`	`"images"`	Subdirectory for images
`--sparse-subdir`	`str`	`"sparse/0"`	Subdirectory for sparse output
`--object-masks-subdir`	`str \| None`	`None`	Subdirectory for object masks
`--weights-dir`	`str`	`"weights"`	Directory containing model weights

Segmentation Settings

Parameter	Type	Default	Description
`--seg-size`	`int`	`1920`	Maximum image dimension for segmentation
`--skip-segmentation`	`bool`	`False`	Skip semantic segmentation
`--segmentation-model`	`str`	`"yolo11m-seg"`	Segmentation model (yolo11s/m/l-seg, yolov8s/m/l-seg)
`--mask-mode`	`"keep" \| "remove"`	`"keep"`	Mask interpretation mode

Pairing Settings

Parameter	Type	Default	Description
`--pairing-method`	`str`	`"exhaustive"`	Image pairing strategy (exhaustive, sequential, retrieval, poses, covisibility)
`--num-matched`	`int`	`20`	Number of images to match per reference
`--descriptors`	`str \| None`	`None`	Path to global descriptors h5 file (for retrieval)
`--reconstruction-path`	`str \| None`	`None`	Path to existing reconstruction (for poses/covisibility)

Execution

Parameter	Type	Default	Description
`--device`	`"auto" \| "cpu" \| "cuda"`	`"auto"`	Device to run on

Example Usage:

# Basic reconstruction with default settings
uv run scripts/reconstruction/reconstruction.py --input-path inputs/bicycle

# Fast mode: skip segmentation, sequential pairing
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/bicycle \
    --skip-segmentation \
    --pairing-method sequential

# Object-centric reconstruction (statue, product)
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/statue \
    --object-masks-subdir object_masks \
    --mask-mode keep

# Dynamic object filtering (remove people, cars)
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/street \
    --object-masks-subdir people_masks \
    --mask-mode remove

# Retrieval-based pairing for large datasets
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/large_scene \
    --pairing-method retrieval \
    --descriptors outputs/large_scene/global-feats.h5

3. Hybrid Densification (GIM + Depth)

Script: scripts/densification/run_hybrid_densification.py Command: uv run scripts/densification/run_hybrid_densification.py

Primary Configuration

Parameter	Type	Default	Description
`--input-path`	`str`	required	Path to COLMAP directory
`--output-path`	`str \| None`	`None`	Output path (auto: {input_path}/sparse/0_hybrid_densified)

Directory Structure

Parameter	Type	Default	Description
`--images-subdir`	`str`	`"images"`	Subdirectory for images
`--sparse-subdir`	`str`	`"sparse/0"`	Subdirectory for sparse reconstruction
`--depth-subdir`	`str \| None`	`None`	Subdirectory for pre-computed depth .npy files
`--normal-subdir`	`str \| None`	`None`	Subdirectory for pre-computed normal .npy files
`--masks-subdir`	`str \| None`	`None`	Subdirectory for pre-computed MoGe mask .png files
`--object-masks-subdir`	`str \| None`	`None`	Subdirectory for object masks

Stage 1: GIM Densifier Settings

Parameter	Type	Default	Description
`--gim-matcher`	`str`	`"gim_dkm"`	Matcher (gim_roma, gim_dkm, gim_loftr, gim_lightglue)
`--gim-num-refs`	`float`	`0.75`	Fraction of images to use as references (0.0-1.0)
`--gim-neighbors-per-ref`	`int`	`6`	Number of neighbor images per reference
`--gim-matches-per-ref`	`int`	`18000`	Number of dense matches to sample per reference
`--gim-strict-filtering`	`bool`	`True`	Enable stricter geometric filtering
`--gim-reproj-threshold`	`float`	`1.0`	Reprojection error threshold (pixels)
`--gim-sampson-threshold`	`float`	`3.0`	Sampson error threshold (px²)
`--skip-gim`	`bool`	`False`	Skip GIM stage

Coverage Computation

Parameter	Type	Default	Description
`--coverage-threshold`	`float`	`0.2`	Only densify pixels with <20% GIM coverage
`--coverage-kernel-size`	`int`	`5`	Kernel size for coverage dilation

Stage 2: Depth Densifier Settings

Parameter	Type	Default	Description
`--moge-checkpoint`	`str`	`"weights/moge/moge-2-vitl-normal/model.pt"`	Path to MoGe model checkpoint
`--pipeline-downsample-factor`	`int`	`1`	Factor to downsample images
`--skip-depth`	`bool`	`False`	Skip depth stage
`--mask-mode`	`"keep" \| "remove"`	`"keep"`	Mask interpretation mode

Point Sampling Strategy

Parameter	Type	Default	Description
`--enable-point-sampler`	`bool`	`True`	Use intelligent point sampler
`--sampler-num-points`	`int`	`25000`	Number of points to sample per image
`--sampler-strategy`	`str`	`"mixed"`	Sampling strategy (random, edges, mixed)
`--sampler-edge-weight`	`float`	`0.7`	Weight for edge-based sampling
`--downsample-density`	`int`	`16`	Grid step for uniform sampling (fallback)

Depth Refiner Settings

Parameter	Type	Default	Description
`--refiner-verbose`	`int`	`0`	Verbosity level (0=quiet, 1=normal, 2=debug)

Correspondence-based Depth Filtering

Parameter	Type	Default	Description
`--filter-correspondence`	`bool`	`True`	Filter refined depths outside MoGe correspondence range
`--correspondence-extrapolation-lower`	`float`	`0.1`	Allow extrapolation below min (10%)
`--correspondence-extrapolation-upper`	`float`	`0.3`	Allow extrapolation above max (30%)
`--min-depth-sanity`	`float`	`0.1`	Absolute minimum depth (meters)
`--max-depth-sanity`	`float`	`500.0`	Absolute maximum depth (meters)

Sparse Depth Bounds Filtering

Parameter	Type	Default	Description
`--filter-sparse-depth-bounds`	`bool`	`True`	Filter points outside sparse COLMAP depth range
`--sparse-depth-margin`	`float`	`0.1`	Safety margin for sparse depth bounds (10%)

Unified Floater Filtering

Parameter	Type	Default	Description
`--filtering-level`	`str`	`"normal"`	Filtering preset (strict, normal, lenient)
`--filter-sparse-points`	`bool`	`True`	Apply floater filtering to sparse points
`--vote-threshold`	`int \| None`	`None`	Number of inconsistent views (None = use preset)
`--depth-threshold`	`float \| None`	`None`	Depth consistency threshold (None = use preset)
`--depth-offset`	`float \| None`	`None`	Additive depth offset in meters (None = use preset)
`--grazing-angle-threshold`	`float`	`0.087`	Grazing angle threshold (cos of angle)
`--enable-parallel`	`bool`	`True`	Enable parallel processing
`--num-threads`	`int`	`4`	Number of threads for filtering

Post-processing

Parameter	Type	Default	Description
`--max-points`	`int`	`-1`	Maximum number of points (-1 = no limit)
`--cleanup-temp`	`bool`	`True`	Remove temporary GIM output directory

Example Usage:

# Full hybrid pipeline with default settings
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle

# Use RoMa matcher with lenient filtering
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --gim-matcher gim_roma \
    --filtering-level lenient

# Fast mode: fewer references, fewer neighbors
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --gim-num-refs 0.3 \
    --gim-neighbors-per-ref 2 \
    --gim-matches-per-ref 5000

# GIM only (skip depth stage)
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --skip-depth

# Depth only (skip GIM stage)
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --skip-gim

# With pre-computed MoGe data
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --depth-subdir moge/depth \
    --normal-subdir moge/normal \
    --masks-subdir moge/masks

# Object-centric densification (statue)
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/statue \
    --object-masks-subdir object_masks \
    --mask-mode keep

# Dynamic object filtering (street scene)
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/street \
    --object-masks-subdir people_masks \
    --mask-mode remove

4. Depth Densification (MoGe Only)

Script: scripts/depth_densification/run_pipeline.py Command: uv run scripts/depth_densification/run_pipeline.py

Primary Configuration

Parameter	Type	Default	Description
`--input-path`	`str`	required	Path to COLMAP directory
`--output-path`	`str \| None`	`None`	Output path (auto: {input_path}/sparse/0_depth_densified)

Directory Structure

Parameter	Type	Default	Description
`--images-subdir`	`str`	`"images"`	Subdirectory for images
`--sparse-subdir`	`str`	`"sparse/0"`	Subdirectory for sparse reconstruction
`--depth-subdir`	`str \| None`	`None`	Subdirectory for pre-computed depth .npy files
`--normal-subdir`	`str \| None`	`None`	Subdirectory for pre-computed normal .npy files
`--masks-subdir`	`str \| None`	`None`	Subdirectory for pre-computed MoGe masks
`--object-masks-subdir`	`str \| None`	`None`	Subdirectory for object masks
`--mask-mode`	`"keep" \| "remove"`	`"keep"`	Mask interpretation mode

MoGe Model

Parameter	Type	Default	Description
`--moge-checkpoint`	`str`	`"weights/moge/moge-2-vitl-normal/model.pt"`	Path to MoGe model checkpoint

Processing Parameters

Parameter	Type	Default	Description
`--pipeline-downsample-factor`	`int`	`2`	Factor to downsample images
`--downsample-density`	`int`	`16`	Controls final point cloud density (1=densest)

Correspondence-based Filtering

Parameter	Type	Default	Description
`--filter-correspondence`	`bool`	`True`	Filter refined depths outside MoGe range
`--correspondence-extrapolation-lower`	`float`	`0.1`	Allow extrapolation below min (10%)
`--correspondence-extrapolation-upper`	`float`	`0.3`	Allow extrapolation above max (30%)
`--min-depth-sanity`	`float`	`0.1`	Absolute minimum depth (meters)
`--max-depth-sanity`	`float`	`500.0`	Absolute maximum depth (meters)

Sparse Depth Bounds Filtering

Parameter	Type	Default	Description
`--filter-sparse-depth-bounds`	`bool`	`True`	Filter points outside sparse depth range
`--sparse-depth-margin`	`float`	`0.3`	Safety margin (30%)

COLMAP Quality Filtering

Parameter	Type	Default	Description
`--filter-colmap-quality`	`bool`	`True`	Filter COLMAP points by error and track length
`--max-reprojection-error`	`float`	`1.0`	Maximum reprojection error (pixels)
`--max-reprojection-error-fallback`	`float`	`2.0`	Fallback max error if strict yields too few points
`--min-track-length`	`int`	`3`	Minimum track length
`--min-quality-correspondences`	`int`	`50`	Minimum correspondences before fallback

Depth Refiner Settings

Parameter	Type	Default	Description
`--refiner-verbose`	`int`	`0`	Verbosity level

Floater Filtering Settings

Parameter	Type	Default	Description
`--filtering-level`	`str`	`"normal"`	Filtering preset (strict, normal, lenient)
`--filter-sparse-points`	`bool`	`True`	Apply filtering to sparse points
`--vote-threshold`	`int \| None`	`None`	Number of inconsistent views (None = preset)
`--depth-threshold`	`float \| None`	`None`	Depth consistency threshold (None = preset)
`--depth-offset`	`float \| None`	`None`	Additive depth offset (None = preset)
`--grazing-angle-threshold`	`float`	`0.087`	Grazing angle threshold
`--enable-parallel`	`bool`	`True`	Enable parallel processing
`--num-threads`	`int`	`4`	Number of threads

Post-processing

Parameter	Type	Default	Description
`--enable-downsampling`	`bool`	`True`	Enable downsampling if too large
`--max-points`	`int`	`3000000`	Maximum points (3M)

Example Usage:

# Basic depth densification
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/bicycle

# Use smaller MoGe model for speed
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/bicycle \
    --moge-checkpoint "weights/moge/moge-2-vitb-normal/model.pt"

# High-quality mode: strict filtering, denser sampling
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/bicycle \
    --filtering-level strict \
    --downsample-density 8 \
    --max-points 5000000

# With pre-computed MoGe data (much faster iteration)
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/bicycle \
    --depth-subdir moge/depth \
    --normal-subdir moge/normal \
    --masks-subdir moge/masks

# Object-centric densification
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/statue \
    --object-masks-subdir object_masks \
    --mask-mode keep

# Indoor scene: conservative extrapolation
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/indoor \
    --correspondence-extrapolation-lower 0.05 \
    --correspondence-extrapolation-upper 0.1 \
    --sparse-depth-margin 0.05

# Outdoor scene: disable sparse bounds
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/outdoor \
    --no-filter-sparse-depth-bounds

5. MoGe Inference (Standalone)

Script: scripts/depth_densification/run_moge_inference.py Command: uv run scripts/depth_densification/run_moge_inference.py

Parameter	Type	Default	Description
`--input-dir`	`str`	required	Directory containing input images
`--output-dir`	`str`	`"outputs/moge_inference"`	Directory to save outputs
`--checkpoint`	`str`	`"weights/moge/moge-2-vitl-normal/model.pt"`	MoGe model checkpoint path
`--separate-dirs`	`bool`	`True`	Save to separate depth/, normal/, masks/ subdirectories
`--num-tokens`	`int \| None`	`None`	Number of base ViT tokens (1200-2500, default: 'most')
`--no-fp16`	`bool`	`False`	Disable mixed precision (FP16) inference
`--image-extensions`	`tuple[str, ...]`	`(".jpg", ".jpeg", ".png", ".JPG", ".JPEG", ".PNG")`	Image file extensions to process

Example Usage:

# Basic inference
uv run scripts/depth_densification/run_moge_inference.py \
    --input-dir inputs/bicycle/images \
    --output-dir inputs/bicycle/moge

# Save to separate directories (depth/, normal/, masks/)
uv run scripts/depth_densification/run_moge_inference.py \
    --input-dir inputs/bicycle/images \
    --output-dir inputs/bicycle/moge \
    --separate-dirs

# Fast mode: smaller model
uv run scripts/depth_densification/run_moge_inference.py \
    --input-dir inputs/bicycle/images \
    --checkpoint "weights/moge/moge-2-vits-normal/model.pt"

# High-quality mode: more tokens
uv run scripts/depth_densification/run_moge_inference.py \
    --input-dir inputs/bicycle/images \
    --num-tokens 2500

6. Sparse COLMAP Filtering

Script: scripts/depth_densification/filter_sparse_colmap.py Command: uv run scripts/depth_densification/filter_sparse_colmap.py

Primary Configuration

Parameter	Type	Default	Description
`--input-path`	`str`	required	Path to COLMAP directory
`--output-path`	`str \| None`	`None`	Output path (auto: {input_path}/sparse/0_filtered)

Directory Structure

Parameter	Type	Default	Description
`--images-subdir`	`str`	`"images"`	Subdirectory for images
`--sparse-subdir`	`str`	`"sparse/0"`	Subdirectory for sparse reconstruction
`--depth-subdir`	`str \| None`	`None`	Subdirectory for pre-computed depth .npy files
`--normal-subdir`	`str \| None`	`None`	Subdirectory for pre-computed normal .npy files

MoGe Model

Parameter	Type	Default	Description
`--moge-checkpoint`	`str`	`"weights/moge/moge-2-vitl-normal/model.pt"`	Path to MoGe model checkpoint

Processing Parameters

Parameter	Type	Default	Description
`--pipeline-downsample-factor`	`int`	`2`	Factor to downsample images

Depth Refiner Settings

Parameter	Type	Default	Description
`--refiner-verbose`	`int`	`0`	Verbosity level

Floater Filtering Settings

Parameter	Type	Default	Description
`--filtering-level`	`str`	`"normal"`	Filtering preset (strict, normal, lenient)
`--vote-threshold`	`int \| None`	`None`	Number of inconsistent views
`--depth-threshold`	`float \| None`	`None`	Depth consistency threshold
`--depth-offset`	`float \| None`	`None`	Additive depth offset
`--grazing-angle-threshold`	`float`	`0.087`	Grazing angle threshold
`--enable-parallel`	`bool`	`True`	Enable parallel processing
`--num-threads`	`int`	`4`	Number of threads

Example Usage:

# Basic sparse filtering
uv run scripts/depth_densification/filter_sparse_colmap.py \
    --input-path inputs/bicycle

# Strict filtering for high-quality cleanup
uv run scripts/depth_densification/filter_sparse_colmap.py \
    --input-path inputs/bicycle \
    --filtering-level strict

# With pre-computed MoGe data
uv run scripts/depth_densification/filter_sparse_colmap.py \
    --input-path inputs/bicycle \
    --depth-subdir moge/depth \
    --normal-subdir moge/normal

# Custom output path
uv run scripts/depth_densification/filter_sparse_colmap.py \
    --input-path inputs/bicycle \
    --output-path outputs/bicycle_clean/sparse/0

7. GIM Densifier

Script: gim_densifier/__main__.py Command: uv run -m gim_densifier or uv run python -m gim_densifier

Primary Configuration

Parameter	Type	Default	Description
`--input-path`	`str`	required	Path to COLMAP directory
`--output-path`	`str \| None`	`None`	Output path (auto: {input_path}/sparse/0_gim_densified)

Directory Structure

Parameter	Type	Default	Description
`--images-subdir`	`str`	`"images"`	Subdirectory for images
`--sparse-subdir`	`str`	`"sparse/0"`	Subdirectory for sparse reconstruction
`--object-masks-subdir`	`str \| None`	`None`	Subdirectory for object masks

Matcher Configuration

Parameter	Type	Default	Description
`--matcher`	`str`	`"gim_roma"`	Matcher to use (gim_roma, gim_dkm, gim_loftr, gim_lightglue)
`--weights-path`	`str \| None`	`None`	Path to matcher weights (auto-detected if None)
`--mask-mode`	`"keep" \| "remove"`	`"keep"`	Mask interpretation mode

Reference Selection

Parameter	Type	Default	Description
`--num-refs`	`float`	`0.75`	Fraction (≤1) or count (>1) of reference views
`--selection-method`	`str`	`"visibility"`	Selection method (visibility, kcenters, sequential)
`--neighbors-per-ref`	`int`	`4`	Number of neighbor images per reference
`--neighbor-method`	`str`	`"covisibility"`	Neighbor selection (covisibility, spatial, spatial_angular)

Matching & Sampling

Parameter	Type	Default	Description
`--matches-per-ref`	`int`	`12000`	Number of dense matches to sample per reference
`--certainty-threshold`	`float`	`0.20`	Minimum certainty for matches
`--coverage-grid-size`	`int`	`24`	Grid divisions for spatial sampling
`--certainty-cap`	`float`	`0.9`	Cap for EDGS-style sampling
`--multinomial-ratio`	`float`	`0.7`	0.0=pure coverage, 0.7=70% confidence/30% coverage, 1.0=pure confidence
`--border-margin`	`int`	`2`	Pixels to exclude from image borders

Geometric Filtering

Parameter	Type	Default	Description
`--reproj-threshold`	`float`	`1.5`	Max reprojection error (pixels)
`--sampson-threshold`	`float`	`5.0`	Max Sampson error (px², 0 to disable)
`--min-parallax-deg`	`float`	`0.5`	Min parallax angle (degrees)
`--max-parallax-deg`	`float`	`120.0`	Max parallax angle (degrees)
`--use-advanced-filtering`	`bool`	`True`	Use advanced geometric filtering
`--max-distance-ratio`	`float`	`0.0`	Max distance from camera as ratio of baseline (0 to disable)

Output Control

Parameter	Type	Default	Description
`--max-points`	`int`	`0`	Point cloud size limit (0 = unlimited)
`--seed`	`int`	`42`	Random seed
`--device`	`str`	`"cuda"`	Device for matching

Threading Control

Parameter	Type	Default	Description
`--use-threading`	`bool`	`True`	Enable GPU-CPU pipelining
`--max-queue-size`	`int`	`3`	Max jobs in flight (memory control)

Example Usage:

# Basic GIM densification with default RoMa matcher
uv run -m gim_densifier --input-path inputs/bicycle

# Use DKM matcher
uv run -m gim_densifier \
    --input-path inputs/bicycle \
    --matcher gim_dkm

# Fast mode: fewer references, fewer neighbors
uv run -m gim_densifier \
    --input-path inputs/bicycle \
    --num-refs 0.3 \
    --neighbors-per-ref 2 \
    --matches-per-ref 5000

# High-quality mode: strict filtering
uv run -m gim_densifier \
    --input-path inputs/bicycle \
    --use-advanced-filtering \
    --reproj-threshold 1.0 \
    --sampson-threshold 3.0

# Object-centric densification (statue)
uv run -m gim_densifier \
    --input-path inputs/statue \
    --object-masks-subdir object_masks \
    --mask-mode keep

# Dynamic object filtering (street scene)
uv run -m gim_densifier \
    --input-path inputs/street \
    --object-masks-subdir people_masks \
    --mask-mode remove

# Spatial neighbor selection (faster than covisibility)
uv run -m gim_densifier \
    --input-path inputs/bicycle \
    --neighbor-method spatial

# Pure coverage sampling (uniform spatial distribution)
uv run -m gim_densifier \
    --input-path inputs/bicycle \
    --multinomial-ratio 0.0

# Pure confidence sampling (focus on high-certainty matches)
uv run -m gim_densifier \
    --input-path inputs/bicycle \
    --multinomial-ratio 1.0

Filtering Presets Reference

All densification scripts support three filtering presets that control how aggressively floaters are removed:

Preset	Vote Threshold	Depth Threshold	Offset	Use Case
strict	4	0.9	0.1m	Maximum quality, removes most floaters
normal	5	0.85	0.1m	Balanced (default for most tasks)
lenient	5	0.85	0.15m	Keep more points, fewer false positives

Parameter Meanings:

Vote Threshold: Number of views where depth is inconsistent before marking as floater
Depth Threshold: Ratio for depth consistency check (projected_depth < threshold × refined_depth - offset)
Offset: Additive depth tolerance in meters

Custom Filtering Example:

# Override preset with custom values
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --vote-threshold 3 \
    --depth-threshold 0.95 \
    --depth-offset 0.05

Design Patterns and Conventions

1. Path Arguments

All scripts follow a consistent path interface:

Flat arguments (no nesting): --param-name not --config.param-name
Auto-generated outputs: --output-path None generates sensible defaults
Subdirectory overrides: --images-subdir, --sparse-subdir, etc.

2. Mask Modes

Dual-purpose masking system:

keep mode: 255 (white) = object to reconstruct, 0 = background to filter (object-centric)
remove mode: 255 (white) = regions to filter (people, cars), 0 = scene to keep (dynamic filtering)

3. Mask Types

MoGe masks: Automatic from model, filter uncertain predictions (always applied first)
Object masks: User-provided (SAM, manual), spatial filtering (keep/remove mode)
Naming convention:
- MoGe masks: stem_mask.png or stem.mask.png
- Object masks: image.ext.png (e.g., DSC_0001.JPG.png)

4. Pre-computed Data

All densification scripts support pre-computed MoGe data for faster iteration:

# Step 1: Pre-compute MoGe (once)
uv run scripts/depth_densification/run_moge_inference.py \
    --input-dir inputs/bicycle/images \
    --output-dir inputs/bicycle/moge \
    --separate-dirs

# Step 2: Use pre-computed data (fast iteration)
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/bicycle \
    --depth-subdir moge/depth \
    --normal-subdir moge/normal \
    --masks-subdir moge/masks

5. Output Path Patterns

Script	Auto-generated Output Path
Reconstruction	`{input_path}/sparse/0`
Hybrid Densification	`{input_path}/sparse/0_hybrid_densified`
Depth Densification	`{input_path}/sparse/0_depth_densified`
GIM Densifier	`{input_path}/sparse/0_gim_densified`
Sparse Filtering	`{input_path}/sparse/0_filtered`

Common Workflows

Complete Pipeline (Reconstruction → Densification)

# 1. Download models
uv run download_models.py

# 2. Run reconstruction
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/bicycle

# 3. Hybrid densification (RECOMMENDED)
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle

Object-Centric Workflow (Statue/Product)

# 1. Create masks (use SAM or manual tools)
# Save as: inputs/statue/object_masks/image.ext.png

# 2. Reconstruction with object masks
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/statue \
    --object-masks-subdir object_masks \
    --mask-mode keep

# 3. Densification with object masks
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/statue \
    --object-masks-subdir object_masks \
    --mask-mode keep

Fast Iteration with Pre-computed MoGe

# 1. Pre-compute MoGe once (5-10 min)
uv run scripts/depth_densification/run_moge_inference.py \
    --input-dir inputs/bicycle/images \
    --output-dir inputs/bicycle/moge \
    --separate-dirs

# 2. Iterate on filtering/sampling (1-2 min each)
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --depth-subdir moge/depth \
    --normal-subdir moge/normal \
    --masks-subdir moge/masks \
    --filtering-level strict

# Try different filtering
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/bicycle \
    --depth-subdir moge/depth \
    --normal-subdir moge/normal \
    --masks-subdir moge/masks \
    --filtering-level lenient

Dynamic Object Filtering (Street Scene)

# 1. Create masks for people/cars (SAM, YOLO, etc.)
# Save as: inputs/street/dynamic_masks/image.ext.png

# 2. Reconstruction with dynamic filtering
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/street \
    --object-masks-subdir dynamic_masks \
    --mask-mode remove

# 3. Densification with dynamic filtering
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/street \
    --object-masks-subdir dynamic_masks \
    --mask-mode remove

Performance Tips

Speed Optimizations

Fast reconstruction: --skip-segmentation --pairing-method sequential
Fast densification: --gim-num-refs 0.3 --gim-neighbors-per-ref 2
Smaller MoGe model: --moge-checkpoint "weights/moge/moge-2-vits-normal/model.pt"
Pre-compute MoGe: Use run_moge_inference.py once, then iterate with --depth-subdir

Quality Optimizations

Strict filtering: --filtering-level strict
Dense sampling: --downsample-density 8 --max-points 5000000
More references: --gim-num-refs 1.0 --gim-neighbors-per-ref 6
Advanced filtering: --gim-strict-filtering --gim-reproj-threshold 1.0

Memory Management

Limit queue size: --max-queue-size 2 (for low VRAM)
Reduce matches: --matches-per-ref 5000
Use smaller matcher: --matcher gim_roma (lowest VRAM)
Downsample more: --pipeline-downsample-factor 4

Troubleshooting

Common Issues

Issue: Out of VRAM during GIM densification

# Solution 1: Reduce references and neighbors
uv run -m gim_densifier \
    --input-path inputs/scene \
    --num-refs 0.3 \
    --neighbors-per-ref 2 \
    --matches-per-ref 5000

# Solution 2: Use RoMa (lowest VRAM)
uv run -m gim_densifier \
    --input-path inputs/scene \
    --matcher gim_roma

Issue: Too many floaters in point cloud

# Solution: Use stricter filtering
uv run scripts/densification/run_hybrid_densification.py \
    --input-path inputs/scene \
    --filtering-level strict

Issue: Missing valid depth regions

# Solution: Use lenient filtering
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/scene \
    --filtering-level lenient \
    --correspondence-extrapolation-upper 0.5

Issue: Depth extrapolation too aggressive

# Solution: Tighten correspondence bounds
uv run scripts/depth_densification/run_pipeline.py \
    --input-path inputs/scene \
    --correspondence-extrapolation-lower 0.05 \
    --correspondence-extrapolation-upper 0.1

Issue: Reconstruction fails on sparse reconstruction

# Solution 1: Check if COLMAP succeeded
ls inputs/scene/sparse/0  # Should contain cameras.bin, images.bin, points3D.bin

# Solution 2: Try different pairing method
uv run scripts/reconstruction/reconstruction.py \
    --input-path inputs/scene \
    --pairing-method sequential

Script Cross-Reference

Task	Primary Script	Alternative Scripts
Sparse Reconstruction	`reconstruction.py`	-
Dense Point Cloud	`run_hybrid_densification.py`	`run_pipeline.py`, `gim_densifier`
Depth-Only Densification	`run_pipeline.py`	`run_hybrid_densification.py --skip-gim`
GIM-Only Densification	`gim_densifier`	`run_hybrid_densification.py --skip-depth`
Depth Estimation	`run_moge_inference.py`	-
Sparse Cleanup	`filter_sparse_colmap.py`	-
Model Download	`download_models.py`	-

Version History

2025-01-09: Initial comprehensive CLI interface documentation
Documented 7 main scripts with 150+ parameters
Added filtering presets, design patterns, and workflow examples

FilesExpand file tree

INTERFACE.md

Latest commit

History

INTERFACE.md

File metadata and controls

GIM CLI Interface Reference

Table of Contents

1. Model Download Script

2. Reconstruction (SfM)

Primary Configuration

Directory Structure

Segmentation Settings

Pairing Settings

Execution

3. Hybrid Densification (GIM + Depth)

Primary Configuration

Directory Structure

Stage 1: GIM Densifier Settings

Coverage Computation

Stage 2: Depth Densifier Settings

Point Sampling Strategy

Depth Refiner Settings

Correspondence-based Depth Filtering

Sparse Depth Bounds Filtering

Unified Floater Filtering

Post-processing

4. Depth Densification (MoGe Only)

Primary Configuration

Directory Structure

MoGe Model

Processing Parameters

Correspondence-based Filtering

Sparse Depth Bounds Filtering

COLMAP Quality Filtering

Depth Refiner Settings

Floater Filtering Settings

Post-processing

5. MoGe Inference (Standalone)

6. Sparse COLMAP Filtering

Primary Configuration

Directory Structure

MoGe Model

Processing Parameters

Depth Refiner Settings

Floater Filtering Settings

7. GIM Densifier

Primary Configuration

Directory Structure

Matcher Configuration

Reference Selection

Matching & Sampling

Geometric Filtering

Output Control

Threading Control

Filtering Presets Reference

Design Patterns and Conventions

1. Path Arguments

2. Mask Modes

3. Mask Types

4. Pre-computed Data

5. Output Path Patterns

Common Workflows

Complete Pipeline (Reconstruction → Densification)

Object-Centric Workflow (Statue/Product)

Fast Iteration with Pre-computed MoGe

Dynamic Object Filtering (Street Scene)

Performance Tips

Speed Optimizations

Quality Optimizations

Memory Management

Troubleshooting

Common Issues

Script Cross-Reference

Version History