ReconStudio

ReconStudio is a reference implementation for turning ordinary camera media into a Gaussian reconstruction, an OpenUSD asset, and a run report through one repeatable API. A user uploads a video or a zip of photographs, starts a batch job, watches the stages over server-sent events, and downloads the resulting .ply, .usdz, and self-contained HTML report.

The point of this repository is the service contract and the outcome. It shows how capture, camera-pose recovery, GPU training, export, inspection, and reporting can behave as one product surface. It is not presented as a hardened multi-tenant platform.

The stage view keeps the reconstruction evidence beside the running process: registered images, model count, sparse points, reprojection error, and the GPU training log are visible without opening a terminal.

Earlier stages expose their own evidence. Here frame selection has kept 225 images and feature extraction is moving through them, while the source and run settings remain visible beside the pipeline.

Completed jobs can be replayed from their recorded events. The experiment ledger stays on the same screen and groups the wider history by Gaussian budget, training iterations, and source scene.

What it produces

Output	Purpose
scene.ply	Portable Gaussian data for browser and dedicated splat viewers
scene.usdz	OpenUSD ParticleField3DGaussianSplat asset for composition
report.html	Settings, timing, metrics, source-frame samples, USD structure, and process log
events.jsonl	Recorded job event stream for audit and replay
job.json	Machine-readable job state, parameters, stage results, and artifact links

The OpenUSD file describes the reconstruction as a Gaussian particle field. It does not invent mesh surfaces, collision geometry, semantic labels, or physics. Those can be added separately when the use case needs them.

The report keeps the evidence close to the artifact: every stage and its timing, the camera-solve and training metrics, a sample of the selected input frames, and the structure found in the exported OpenUSD file.

Sample run

The repository includes a compact sample from a measured playroom run: 225 photographs, a 4 million Gaussian budget, and a 41.5 minute end-to-end runtime on one NVIDIA L40S. It is included to show the outcome and evidence produced by the service, not as a quality promise for other captures or hardware.

The PLY handoff opens in SuperSplat for orbiting and inspection beyond the recorded camera path. Those views make weak coverage and stray Gaussians easier to see than a single favorable frame.

• Open the self-contained run report
• Watch the 58-second pipeline replay
• See the SuperSplat inspection and layering pitfall

The report and replay were sanitized for public sharing. Raw recordings and the large PLY/USDZ outputs are intentionally excluded. The benchmark imagery is not covered by the ReconStudio MIT or CC BY license; see the sample media notes and third-party notices.

Pipeline

video / photographs
        |
        v
frame selection -> COLMAP features and matching -> camera poses
                                                    |
                                                    v
                                          3DGRUT GPU training
                                                    |
                              +---------------------+------------------+
                              |                     |                  |
                           PLY splat             OpenUSD             report

Each stage emits progress, logs, timing, and a small set of useful metrics. The dashboard emphasizes registration rate, reprojection error, feature count, quality metrics, Gaussian count, GPU memory, and artifact size instead of a generic progress percentage.

Quick start without a GPU

Simulation mode exercises the API, dashboard, job lifecycle, report path, and real video ingest/frame selection. COLMAP and Gaussian training are simulated.

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

RECON_FAKE=1 scripts/run_local.sh
# open http://127.0.0.1:8800

Upload a short video or a zip containing JPEG/PNG photographs. Simulation mode does not fabricate a PLY or USDZ; completed real runs can still be replayed.

Run the real pipeline

The real path is deliberately adapter-based. ReconStudio calls a separate 3DGRUT checkout for training/export and a GPU-enabled COLMAP container for pose recovery. It does not redistribute either project.

1. Use a Linux x86-64 machine with an NVIDIA GPU, Docker with NVIDIA Container Toolkit, FFmpeg/ffprobe, and Python 3.11.

2. Install 3DGRUT using its current upstream instructions. USD export depends on usd-core, which upstream installs for Linux x86-64.

3. Install this project into the same Python environment:

   source /opt/3dgrut/.venv/bin/activate
   pip install -e /path/to/reconstudio

4. Copy .env.example to a private environment file or export the relevant values. At minimum, set RECON_GRUT_DIR, RECON_VENV_PY, and RECON_JOBS_DIR.

5. Start the service:

   scripts/run_local.sh

The source project was exercised on Ubuntu 24.04 with one NVIDIA L40S (48 GB), a CUDA 12.8 3DGRUT environment, and the COLMAP image shown in .env.example. That is a tested reference point, not a minimum hardware promise. Capture size, image resolution, Gaussian budget, and upstream versions change both resource use and runtime.

API shape

FastAPI also exposes interactive documentation at /docs.

Method	Endpoint	Purpose
GET	/health	Local readiness without exposing machine paths
GET	/api/stages	Stage descriptions and current execution mode
GET	/api/samples	Pre-staged source labels, with server paths removed
POST	/api/jobs	Create a job from an upload or staged sample
POST	/api/jobs/{id}/start	Start the one-at-a-time local worker
GET	/api/jobs/{id}	Job state, metrics, and artifact links
GET	/api/jobs/{id}/events	Live server-sent event stream
GET	/api/jobs/{id}/replay	Time-compressed replay of recorded real events
GET	/api/jobs/{id}/artifacts/{name}	Download PLY, USDZ, report, or snapshot
GET	/api/jobs/{id}/usd	Inspect the exported USD scene graph
GET	/api/ledger	Aggregate run and same-scene budget-sweep metrics

Example job creation and start:

job_id=$(curl -sS \
  -F 'file=@capture.mp4' \
  -F 'frame_count=250' \
  -F 'max_width=1920' \
  -F 'iterations=30000' \
  -F 'max_gaussians=1000000' \
  http://127.0.0.1:8800/api/jobs | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

curl -sS -X POST "http://127.0.0.1:8800/api/jobs/$job_id/start"
curl -N "http://127.0.0.1:8800/api/jobs/$job_id/events"

Configuration

Variable	Default	Meaning
RECON_HOME	~/recon	Default root for tools and runtime data
RECON_GRUT_DIR	$RECON_HOME/tools/3dgrut	3DGRUT checkout
RECON_VENV_PY	$RECON_GRUT_DIR/.venv/bin/python	Python used for training/export
RECON_COLMAP_IMAGE	See .env.example	GPU-enabled COLMAP container
RECON_JOBS_DIR	$RECON_HOME/app_jobs	Per-job workspaces and artifacts
RECON_SAMPLES_DIR	$RECON_HOME/samples	Curated local videos/image folders
RECON_DATA_DIR	$RECON_HOME/data	Existing COLMAP-style datasets to discover
RECON_HOST	127.0.0.1	Bind address; keep local for this reference app
RECON_PORT	8800	HTTP port
RECON_FAKE	unset	Set to 1 for simulation mode
RECON_MAX_UPLOAD_MB	2048	Maximum compressed upload size
RECON_MAX_ZIP_FILES	5000	Maximum image entries in one archive
RECON_MAX_ZIP_UNCOMPRESSED_MB	4096	Maximum expanded image bytes

Where on-demand GPU scaling fits

The local implementation keeps job state on disk and starts a background thread that owns one GPU. The API contract does not require that execution model. A hosted implementation can keep the endpoints and event schema while replacing the thread with a durable queue and disposable GPU workers:

API/control plane -> job queue -> autoscaled GPU worker -> object storage
       |                                                    |
       +---------------- status and events -----------------+

That service builder still owns authentication, tenant isolation, signed uploads/downloads, quotas, retries, cancellation, observability, cost controls, and retention. See docs/architecture.md for the handoff points.

Limits and responsible use

• One reconstruction runs at a time in this repository.
• The service has no authentication. Keep it on localhost; see SECURITY.md.
• The default camera model assumes one conventional camera. Calibrated rigs, fisheye lenses, and mixed-camera image sets need a different pose adapter.
• Gaussian quality depends on coverage, parallax, sharpness, lighting, and scene behavior. More iterations cannot recover information that was not captured.
• Source media, trained scenes, reports, and large run artifacts are ignored by Git. Confirm dataset rights, consent, privacy, and attribution before sharing any derived output.
• The browser preview loads the MIT-licensed PlayCanvas engine from jsDelivr. The PLY and USDZ downloads remain available if CDN access is blocked.

Development checks

pip install -r requirements-dev.txt
scripts/check_public.sh

The check compiles the Python source, runs the tests, rejects generated scene or video artifacts, and scans for a small set of high-confidence secret and personal-detail patterns. It complements, rather than replaces, a repository history and secret scan before publication. Use the release checklist before creating the first commit or connecting a remote.

Citation and attribution

If ReconStudio helps your own implementation, article, or evaluation, please credit the project as:

Pradeep Kaushik. ReconStudio: a reference API for camera media to Gaussian splat and OpenUSD jobs. Version 0.1.0, 2026.

A machine-readable citation is available in CITATION.cff.

Related writing

• What Kind of Truth Does Your Digital Twin Need?
• From Camera Media to Gaussian Splats: Building ReconStudio
• What I Learned from 24 Gaussian Splat Jobs

License

• Source code and configuration are licensed under the MIT License.
• Original documentation and diagrams are licensed under Creative Commons Attribution 4.0 International.
• Benchmark imagery and the derived artifacts under docs/media/ are not covered by either license, except for the original text in docs/media/README.md.

See LICENSES.md for the exact scope and attribution language. External tools and datasets keep their own terms; see THIRD_PARTY_NOTICES.md.