1. Install Docker

2. Start and enable the Docker service:

   sudo systemctl start docker
   sudo systemctl enable docker

3. Install the NVIDIA Container Toolkit

4. Configure the Docker runtime and restart:

   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker

The full image prebuilds CUDA wheels for nvdiffrast and gsplat, so texture baking and nerfstudio Gaussian splatting methods do not compile CUDA extensions at runtime.

Also available on GitHub Container Registry: ghcr.io/hummat/mini-mesh

To use slim:

docker pull hummat/mini-mesh:slim
MINI_MESH_IMAGE=hummat/mini-mesh:slim docker/run.sh /path/to/input

The wrappers use hummat/mini-mesh:latest unless MINI_MESH_IMAGE is set. To run a locally built image, use MINI_MESH_USE_LOCAL_IMAGE=1.

The pre-built image includes native CUDA code for compute capabilities 7.5, 8.0, 8.6, and 8.9, plus PyTorch-extension PTX for 8.9.

docker/build.sh local  # Build optimized for your GPU

See CONTRIBUTING.md for build variants and options.

RTX 50XX (Blackwell): not a native target in the published image. The PTX fallback may work with a new enough driver, but the reliable path is a custom CUDA/PyTorch stack with native Blackwell support.

Requirements: Python 3.11, CUDA 12.4.1, COLMAP, GLOMAP, uv

This repository includes a local setup helper for the Web UI's local mode. It uses the active CUDA build environment, builds pinned PoseLib/COLMAP/GLOMAP into .local/mini-mesh, and installs the Python/CUDA stack into .venv.

cp .envrc.example .envrc
# edit .envrc for your CUDA/GCC paths and GPU architecture
direnv allow
make build
uv run python webui.py

Manual setup requires:

• Python 3.11 or 3.12 via uv
• CUDA Toolkit 12.4.x in CUDA_HOME
• GCC/G++ 12 for CUDA extension builds
• System C++ headers/libraries for COLMAP/GLOMAP
• CUDA_HOME, CC, CXX, CUDAHOSTCXX, TORCH_CUDA_ARCH_LIST, and MAX_JOBS exported in .envrc or in the shell running make build
• Optional PyTorch-extension PTX fallback via TORCH_CUDA_ARCH_LIST=8.9+PTX

make build installs the local optional stack used by Web UI local mode: nerfstudio, Splatfacto-W, rembg, SAM2, VGGSfM, HLoc, tiny-cuda-nn, nvdiffrast, and gsplat. The CUDA extension sources are pinned to the same refs as the Docker image.

For custom environments, install from the pinned refs used by scripts/build.sh and pyproject.toml instead of upstream HEAD. For example:

# NeRF/splat models
uv pip install git+https://github.com/hummat/nerfstudio.git@55a1f83025bb28cbf792760c9b79f9eb22c3a2e4
uv pip install git+https://github.com/KevinXu02/splatfacto-w.git@119a3bfb3aa03669278e174ff11c4dfdcbcf97d7

# Background masking
uv pip install "rembg[gpu,cli]==2.0.69"
uv pip install git+https://github.com/hummat/sam2.git@98f488a540f87260b8e51146dc3ab15694dd174c

# Advanced SfM (HLoc) - requires manual clone
git clone --recursive https://github.com/cvg/Hierarchical-Localization.git
cd Hierarchical-Localization && git checkout 3bdf494c852f157db57a1cf2039a6c826d52e702
git submodule update --init --recursive && uv pip install -e . && cd ..
uv pip install git+https://github.com/hummat/hloc-cli.git@1b714e1183bbc3cb6f4031ddedcc4bd5190ece29

# Advanced SfM (VGGSfM)
uv pip install git+https://github.com/hummat/vggsfm.git@d597df629a312a662544006ac3bdbc2782b82834

# GPU texture baking (nvdiffrast) - requires CUDA toolkit
uv pip install --no-build-isolation git+https://github.com/NVlabs/nvdiffrast.git@253ac4fcea7de5f396371124af597e6cc957bfae

SDF models (automatic): Extracts mesh → creates texture coordinates → bakes colors onto texture → simplifies geometry

Export method selector (export --method <name>):

• poisson — Reconstructs smooth surface from rendered point cloud (default)
• tsdf — Fuses depth maps into a volume, then extracts mesh
• pointcloud — Export as point cloud (no mesh)
• orbit-frames — Render a spiral RGB image sequence to orbit_frames/ for frame-snapping web/blog viewers
• Gaussian splats are automatic for splatfacto models; splatfacto-w-light bakes its mean appearance embedding by default and uses classic rasterization plus denser splatfacto-style culling/splitting thresholds for portable PLY output. Use export --appearance-mode index --appearance-idx <N> to bake a specific training image appearance.

For NeRF/ngp models, request several exporters by repeating --method or using a comma-separated value, for example export --method poisson,orbit-frames. For SDF and splat models, orbit-frames is additive to the normal export.

• --mask <method> — Background masking: rembg, sam2, true, none
• --min-match-ratio <float> — Fail if fewer than this fraction of images get poses (default: 0.5)
• --crop-factor <top bot left right> — Crop images before processing

TensorBoard (default):

docker/run.sh video.mp4 train --vis tensorboard
tensorboard --logdir /path/to/your/data  # on host

Weights & Biases:

export WANDB_API_KEY=your_api_key  # add to ~/.bashrc
docker/run.sh video.mp4 train --vis wandb

Web Viewer: Automatically configured for nerfstudio's real-time 3D viewer.

1. Run pipeline up to mesh extraction only:

   docker/run.sh /path/to/input video --fps 2 sfm --method glomap process --mask rembg train --model neus-facto --config neus-facto export --mesh-only

2. Edit train/<name>/<model>/run/mesh.ply in Blender (don't change global transform)

3. Run texturing only:

   docker/run.sh /path/to/input export --texture-only
   # Or with edited mesh:
   docker/run.sh /path/to/input export --texture-only --input-mesh-filename mesh_edited.ply

4. (Optional) Optimize for web delivery:

   The exported GLB files are ~10MB due to uncompressed geometry and PNG textures. For web use (e.g., <model-viewer>), compress with gltf-transform:

   npx @gltf-transform/cli optimize mesh.glb mesh_web.glb --compress draco --texture-compress webp

   This typically achieves 90-95% size reduction (10MB → 500KB-1MB) by:

   • Welding vertices: Blender's GLB export duplicates vertices at UV seams; optimize merges them back
   • Draco compression: Quantizes geometry to 14-bit precision + entropy coding
   • WebP textures: Lossy compression, visually identical to PNG at ~10% the size

   The mesh quality is preserved—the bloat comes from export artifacts, not your edits.

# Step 1: Extract mesh only
scripts/run.sh /path/to/input \
  video --fps 2 sfm --method glomap process --mask rembg train --model neus-facto --config neus-facto export --mesh-only

# Step 3: Texture only (after editing mesh)
scripts/export.sh /path/to/data/train/<name>/<model>/run --texture-only
# Or with edited mesh:
scripts/export.sh /path/to/data/train/<name>/<model>/run --texture-only --input-mesh-filename mesh_edited.ply