Here's my concise technical briefing for the Skyfall-GS repository.

The Problem

This repository synthesizes immersive 3D urban scenes from satellite imagery, but the codebase has significant structural and quality issues that impede reliable extension or integration. A senior engineer would find the code difficult to modify safely without introducing regressions.

What This Does

Skyfall-GS is a two-stage framework: Stage 1 reconstructs geometry from COLMAP/satellite data, and Stage 2 iteratively refines appearance via a diffusion model. The entry point is cmmd_pytorch/main.py:62 (main), which reaches 71 functions and orchestrates training and evaluation. The CMMd computation (compute_cmmd at line 33) reaches 6 functions and is the primary analytical path. Core logic lives in scene/gaussian_model.py (39 functions, 2 classes, called from 7 files) and scene/dataset_readers.py (13 functions, file I/O for COLMP loading). train.py (11 functions) handles the training loop, while render_video.py and render_videos.py manage rendering pipelines. align_ges.py extracts reference frames and compares structure, running external commands. The module graph shows render_video as a high-instability hub (Ca=1, Ce=8, instability=0.89), and evaluate_gs_geometry/train as singleton sinks with instability=1—any change to these ripples widely with no alternative paths. gaussian_renderer/__init__.py has broad except clauses that swallow errors indiscriminately.

How It Is Wired

Execution starts at cmmd_pytorch/main.py:62 (main), which calls into train, render, and evaluation paths. The internal call graph has 320 resolved edges; CameraInfo is called from 8 places, render from 7, GaussianModel from 7. scene/gaussian_model.py and scene/dataset_readers.py are the most central files, each called from 3+ other modules. train.py and evaluate_gs_geometry.py are oversized (661 and ~600 lines respectively), creating high cognitive load. cmmd_pytorch/distance.py, embedding.py, io_util.py, and main.py contain 242 duplicated 6-line blocks across 28 files—violating DRY. cmmd_pytorch/io_util.py opens files without a context manager. gaussian_renderer/__init__.py has 4 bare except clauses. train.py has 3 stale TODO/FIXME markers; scene/gaussian_model.py has 7. No test files exist; no CI/CD pipeline is configured. Dependencies are declared in requirements.txt and cmmd_pytorch/requirements.txt without a lockfile, so builds are non-reproducible across environments.

Code Health & Issues

  • [HIGH] No test suite—45 source files, zero test files. Any change ships with no regression signal.
  • [HIGH] No CI/CD pipeline—merges happen without anyone having run the build.
  • [MEDIUM] No Dependabot/Renovate configured; 2 manifests with no automated dependency updates.
  • [MEDIUM] Broad except in gaussian_renderer/__init__.py, scene/dataset_readers.py, align_ges.py swallows errors.
  • [MEDIUM] Deep nesting (max indent 14) in scene/__init__.py, scene/gaussian_model.py, gaussian_renderer/__init__.py.
  • [MEDIUM] 242 duplicated 6-line blocks across cmmd_pytorch/ files.
  • [MEDIUM] Oversized files: train.py (661 lines), evaluate_gs_geometry.py.
  • [MEDIUM] File leaks: cmmd_pytorch/io_util.py opens open(...) without with.
  • [LOW] 7 TODO/FIXME in scene/gaussian_model.py, 3 in train.py.

How To Use It

Setup: Clone with git clone https://github.com/moses-y/Skyfall-GS.git (verbatim). Create a Conda env python=3.10. Install NVIDIA toolkit (conda install cuda-toolkit=12.8 cuda-nvcc=12.8 -c nvidia). Then pip install -r requirements.txt followed by pip install --force-reinstall torch torchvision torchaudio. Install submodules: pip install submodules/diff-gaussian-rasterization-depth, submodules/simple-knn, submodules/fused-ssim.

Configuration: No explicit env vars are documented beyond what the scripts set. The requirements.txt and cmmd_pytorch/requirements.txt declare pins; treat these as the dependency contract.

Running it: The entry point is cmmd_pytorch/main.py. To train, invoke python cmmd_pytorch/main.py with appropriate flags (the CLI is defined in arguments/__init__.py). Scripts in scripts/ (run_nyc.py, run_jax.py, etc.) provide ready-made pipelines for the JAX and NYC datasets. compute_cmmd in main.py is the analytical entry for CMMd evaluation.

Real-World Use

A research team wanting to generate a new city scene would place COLMP-formatted data in data/, run the Stage 1 reconstruction script (scripts/run_nyc.py or run_jax.py), then invoke the IDU training loop via python cmmd_pytorch/main.py --mode idu. The generated Gaussians can be visualized via the fused PLY pipeline (create_fused_ply.py). However, the absence of tests and CI means any pipeline change requires manual regression checks—a non-trivial overhead for a production ML system.

Code Health & Issues

  • [HIGH] No test suite; 45 source files, zero test files. Any change ships with no regression signal.
  • [HIGH] No CI/CD pipeline; 45 source files merge with nobody having run the build.
  • [MEDIUM] No Dependabot/Renovate; 2 manifests, no automated dependency updates.
  • [MEDIUM] Broad except in gaussian_renderer/__init__.py, scene/dataset_readers.py, align_ges.py swallows errors.
  • [MEDIUM] 242 duplicated 6-line blocks across cmmd_pytorch/ files.
  • [MEDIUM] Oversized files: train.py (661 lines), evaluate_gs_geometry.py.
  • [MEDIUM] File leak: cmmd_pytorch/io_util.py opens without with.
  • [LOW] 7 TODO/FIXME in scene/gaussian_model.py, 3 in train.py.

The Bottom Line

The framework functionalizes a novel idea—3D urban scenes from satellite+diffusion—but the codebase is not engineer-friendly. High duplication, oversized files, and zero test/CI infrastructure mean productionizing this requires significant cleanup investment. Use it only if you have bandwidth to refactor the cmmd_pytorch/ and scene/ modules first, or if you need the specific satellite-to-3D pipeline immediately and can tolerate technical debt.