CorbeauSplat is an all-in-one Gaussian Splatting automation tool designed specifically for macOS Silicon. It streamlines the entire workflow from raw video/images to a fully trained and viewable 3D scene (Gaussian Splat).
Current version: 2.1.0 — see the CHANGELOG for what changed.
This application provides a unified Graphical User Interface (GUI) to orchestrate the following steps:
- Project Management: Automatically organizes your outputs into structured project folders with images, sparse data, and checkpoints. Settings can be saved as named configurations (load / save / delete) and reused from one project to the next.
- Source Preparation: Point the app at a video or a folder of images — the type is detected automatically (mixed folders are flagged). Folders are scanned in the background, so large folders on a NAS or USB drive no longer freeze the window. For a single video, pick an in/out range with an ffmpeg-based preview before extraction. Formats COLMAP cannot read (HEIC, TIFF, BMP, WebP…) are converted to PNG or JPEG for you, or left untouched if you prefer.
- Sparse Reconstruction: Automates COLMAP feature extraction, matching, and mapping. Supports Glomap as a modern alternative mapper.
- Undistortion: Automatically undistorts images for optimal training quality.
- AI Upscaling: Optionally enhances input images before reconstruction using upscayl-ncnn — a fast NCNN-based upscaler with 6 curated models (Real-ESRGAN x4+, 4xLSDIR, 4xNomos8kSC, and more), browsable in a model gallery where each one can be downloaded or deleted. Downloads are verified against pinned checksums; a model already on disk that cannot be verified is flagged in the log.
- Training: Integrates Brush to train Gaussian Splats directly on your Mac, with a coarse progress indicator based on the checkpoints written to disk. Choose where checkpoints go, and optionally keep only the latest.
- Cleaning: Standalone Nettoyage tab to remove artifacts from any
.plyfile — transparent splats, oversized splats, spatial outliers — in single-file or batch mode. Three presets: Light / Medium / Strong. - Format Conversion: SplatTransform tab powered by PlayCanvas
@playcanvas/splat-transformv3.10.0. Converts between PLY, SPZ, SOG, GLB, and CSV. Supports SH band reduction, point count decimation, NaN filtering, isolated-splat ("floaters") removal, and Morton spatial reordering. - Visualization: Includes a built-in tab running SuperSplat for immediate local viewing and editing of your PLY files. The viewer only listens on
127.0.0.1. - ML Sharp (Image/Video to 3D): Uses Apple ML Sharp to generate a 3D model from a single image or a sequence of 3D models directly from a video.
- 4DGS Preparation (Experimental): Prepares 4D Gaussian Splatting datasets (multi-camera video → Nerfstudio format), with optional pre-COLMAP upscaling and COLMAP tuning (camera model, matcher, sequential overlap). No Apple Silicon 4D trainer exists, so the module stops at dataset preparation.
- 360 Extractor (Experimental): Converts equirectangular 360° videos into optimal planar image sets (Cube Map, Ring, etc.) for photogrammetry, with AI operator masking.
Since v2.0, the steps are no longer separate islands: a single Launch button in the Project panel runs the whole chain, driven by the mode selector (Gsplat → COLMAP, Sharp → ML Sharp, 4DGS → dataset preparation). Optional steps are ticked in the Automation block and each one feeds the next:
360 extraction → Upscale → Reconstruction → Brush → Cleaning → Export → Viewer
Every step is reported in the left rail (running / done / error), can be cancelled from the activity bar, and a failed step offers a "Voir le journal" button. The same chain is available from the CLI: pipeline --clean [light|medium|strong] --export FORMAT, with --trim_start / --trim_end for video ranges and --convert png|jpeg|off for image conversion.
It is designed to be "click-and-run", handling dependency checks, process management, and session persistence for you. It also includes built-in full localization support for French, English, German, Italian, Spanish, Arabic, Russian, Chinese, and Japanese.
This program was realized through "vibecoding" with the help of Gemini 3 Pro.
It was originally created to facilitate the technical workflow for a documentary film titled "Le Corbeau". I am not a professional developer; I simply needed to automate a complex process by gathering the tools I use daily: COLMAP, the Brush app, and SuperSplat.
I share this code in all humility. I didn't originally plan to release it, but I thought that perhaps someone, somewhere on this earth, might find it useful.
As this software was built via "vibecoding" (AI-assisted coding), it is provided "as is" with no guarantees.
- macOS (Apple Silicon recommended)
- Python 3.13+ (Recommended for JIT/Performance) or Python 3.11 (Supported)
- Xcode Command Line Tools (Required for compiling custom engines like Glomap or Brush)
- Homebrew (for installing system dependencies like COLMAP and FFmpeg)
- Git
-
Clone this repository:
git clone https://github.com/freddewitt/CorbeauSplat.git cd CorbeauSplat -
Run the launcher:
./"CorbeauSplat.command"The script will automatically detect missing dependencies (Python packages, Brush, SuperSplat, Rust, Node.js, etc.) and attempt to install them for you. Python packages are installed at the exact versions listed in
requirements.lock(falling back to the ranges inrequirements.txtif the lockfile is absent).
The left rail has four groups: Project (always visible), TRAINING, OPTIONS and TOOLS. Missing dependencies are reported when the app starts: essential ones (ffmpeg, COLMAP) in a dialog, feature-specific ones in the log.
- Project panel:
- Select your input (video or folder of images) and an output folder, and name the project (files go to
[Output Folder]/[Project Name]). - Leave the source type on Auto, or force Images / Video. For a video, set the FPS, or use "Sélection vidéo…" to choose an in/out range.
- Choose the conversion format (PNG, JPEG, or off) for images COLMAP cannot read.
- Pick the mode (Gsplat, Sharp, 4DGS), tick the steps to chain in Automation (360 extraction, Upscale before reconstruction, Brush, Cleaning, Export, Viewer), then click Launch.
- Save your settings as a named configuration in Current settings. A configuration covers the seven chain panels only; Viewer, Sharp, 4DGS and SplatTransform settings are not saved in it.
- Select your input (video or folder of images) and an output folder, and name the project (files go to
- TRAINING group:
- Reconstruction: COLMAP options, LightGlue matchers, Glomap as alternative mapper. Has its own Launch button for a standalone run.
- Training (Brush): Auto-Refine resumes from the latest checkpoint; presets (built-in or your own — user presets can be deleted); Nettoyer après / Exporter ensuite post-training options.
- Visualize: load a
.plyand start the local SuperSplat viewer.
- OPTIONS group:
- 360° extraction: install the dedicated environment, then extract images from 360° videos (Ring, Cube Map, Fibonacci) with optional AI operator masking.
- Upscale:
upscayl-binis installed automatically. Pick a model in the gallery (download or delete from its card), then set scale (x1–x4), format and tile size. - Cleaning: single-file or batch
.plycleaning, three presets (Light / Medium / Strong). - Export: PLY → SPZ, GLB, OBJ or XYZ.
- TOOLS group (standalone modules, typed paths, independent of the chain):
- Brush, SuperSplat, ML Sharp, SplatTransform (PLY ↔ SPZ / GLB / CSV with SH reduction, decimation, NaN and floaters filtering, Morton reordering), 4DGS.
- 4DGS (Experimental): check Activate to install Nerfstudio, select a folder of synchronized camera videos, optionally upscale before reconstruction, and launch to get a dataset ready for 4D training.
- ML Sharp (Bonus): select a single image or a video, then predict the 3D model(s).
CorbeauSplat exposes all its features via the command line.
📘 See CLI.md for full command line documentation
This project stands on the shoulders of giants. A huge thank you to the creators of the core technologies used here:
- COLMAP: Structure-from-Motion and Multi-View Stereo. GitHub
- Brush: An efficient Gaussian Splatting trainer for macOS. GitHub
- SuperSplat: An amazing web-based Splat editor by PlayCanvas. GitHub
- 360Extractor: Advanced 360° video extraction tool. GitHub
- Apple ML Sharp: Machine Learning tools for Swift. GitHub
- Nerfstudio: The modular NeRF and Splatting framework (used for 4DGS data prep). GitHub
- upscayl-ncnn: High-performance AI image upscaling using NCNN. Powers the Upscale tab. GitHub
- PlayCanvas splat-transform: Fast PLY ↔ SPZ ↔ GLB conversion CLI by PlayCanvas (MIT). Powers the SplatTransform tab. GitHub
- nianticlabs/spz: Official SPZ encoder/decoder by Niantic Labs (MIT). Powers the SPZ export in ExportEngine. GitHub
- Qt for Python (PySide6): The official Qt bindings for Python (LGPL). Powers the entire desktop GUI. Docs
This project is licensed under the MIT License - see the LICENSE file for details. This is the most permissive open-source license, allowing you to use, modify, and distribute this software freely.