EasySplat turns video, photos, or both into a 3D Gaussian splat on an Apple Silicon Mac. Processing stays on the Mac. The result is a conventional PLY file.
The first stable release is v0.2.0 for macOS 15 and later.
When EasySplat-0.2.0.dmg is present on GitHub Releases, open it and drag EasySplat to Applications. Until that signed asset is published, use the source build; do not download an EasySplat binary from another source.
The release workflow publishes the GitHub build only after Developer ID signing, notarization, stapling, and Gatekeeper verification pass. Initial setup needs internet access because EasySplat downloads only the signed toolchain components required by the selected job. Successfully cached components can be reused offline. Each component is bound to a signed manifest and verified before installation.
- Select New Splat.
- Choose a video or a folder of photos.
- Leave Options collapsed for the normal path.
- Select Create Splat.
EasySplat prepares the input, reconstructs the cameras and scene, trains the splat with native Metal code, validates the result, and opens it in the built-in viewer.
One job runs at a time. You can stop safely and resume from the last durable stage. Training resumes only when a complete optimizer checkpoint was written and validated.
Defaults are Automatic capture, Balanced detail, and Automatic for every other choice.
| Option | Use it when |
|---|---|
| Capture Path | Choose Around a subject for an object orbit, Through a space for an interior or property walkthrough, or Across a large area for a long exterior or drone route. |
| Detail | Fast favors turnaround and memory use. Balanced is the normal choice. High Detail uses a larger frame and training budget when the Mac can support it. |
| Camera Source | Choose Mixed cameras or lenses when the capture combines devices, zoom settings, or lenses. |
| Lens | Choose Fisheye for footage that is genuinely fisheye. Ordinary phone, mirrorless, and drone cameras should normally stay Automatic. |
| Input Order | Use Continuous sequence only for one verified continuous route. Use Unordered for a photo set with no meaningful sequence. |
| Resource Use | Conserve Memory lowers proactive budgets. Maximum Performance uses larger budgets within the Mac's memory tier. |
| Photo Use | Use all valid photos keeps a curated photo set when it fits the resolved frame budget. Unreadable files and exact duplicates are still rejected. |
- Move steadily and keep neighboring views overlapping.
- Walk a property as connected rooms, not isolated clips.
- Circle an object at a consistent distance and include high and low angles.
- Close large exterior or drone loops when possible.
- Avoid motion blur, abrupt exposure changes, and long stretches with no texture.
- Mirrors, windows, water, foliage, moving people, and moving vehicles are hard cases. EasySplat treats motion as an outlier; it does not reconstruct dynamic 4D scenes.
If the overlap graph is disconnected, EasySplat stops and explains the capture problem. It does not combine unrelated spaces into a fake coordinate frame.
- macOS 15 or later
- Apple Silicon only
- 8 GB: Fast with Conserve Memory, selected automatically, for small objects or rooms
- 16 GB: Fast and Balanced
- 24 GB or more: Fast, Balanced, and High Detail, with room for larger captures
Memory budgets are proactive. EasySplat does not deliberately run out of memory to discover a limit.
- EasySplat reconstructs static scenes. Moving people, vehicles, foliage, water, reflections, and changing light can leave gaps or artifacts.
- PLY is the only public export format in
0.2.0. - Only one reconstruction runs at a time.
- The app opens projects written by the current project format. It leaves incompatible older project bundles untouched and omits them from the library.
EasySplat has no cloud processing, analytics, telemetry, advertising SDK, or crash SDK. Source media, notes, projects, checkpoints, and outputs remain local unless you explicitly export or share a result.
Diagnostics exclude source images and notes by default. They remove project identity and scrub local paths and URL credentials before preview, copy, or save.
Projects live under:
~/Documents/EasySplat Projects/
Stable paths inside a project are:
SfM/colmap/sparse/0
SfM/geometry_manifest.json
Training/training_manifest.json
Output/splat.ply
Output/splat_receipt.json
Separate from project.json, Output/splat_receipt.json is the authority for newly published result bytes: Output/splat.ply is usable when both files validate as one published pair. The sole compatibility exception is a fully validated, successfully completed legacy project created before receipts; it may open only its current result. A bare PLY never authorizes a previous result after a failed or interrupted retrain. Publication preserves the current validated pair, installs the new PLY first, and commits by installing its receipt last. Pipeline startup reconciles any interrupted publication before beginning new work.
Retraining leaves the validated pair in place until a replacement pair commits. If the new attempt fails, the project remains Failed while View Previous Result opens the receipt-bound result. Its reconstruction, run-plan, training, and timing facts come from the receipt; the project title, notes, and viewer preferences remain current. Viewer, export, and share resolve the same authority every time, so a stale summary or bare PLY cannot unlock a result.
Export keeps the save-panel grant for the complete operation and reconciles the exact selected file after publication. A destination race is reported as a conflict and EasySplat does not overwrite ambiguous bytes. Share uses a validated temporary snapshot; dismissing the picker deletes that snapshot immediately, while a selected service retains it only until AppKit reports success or failure.
Stored artifact paths are project-relative and resolved through the safe project-path resolver.
- The app will not open: confirm that you downloaded the DMG from the official GitHub release, then download a fresh copy. Do not bypass a Gatekeeper warning for an unverified copy.
- Setup failed: try again. A failed tool download does not create a bogus project and preserves the selected input.
- The scene will not reconstruct: capture more overlap, remove unrelated clips, or choose the correct Capture Path, Lens, and Input Order.
- Memory pressure: choose Fast and Conserve Memory, then reduce capture length if needed.
- A result will not export: EasySplat exports only a validated finished PLY.
- A retrain failed: use View Previous Result when shown. EasySplat keeps the last validated splat available until a replacement finishes.
Use Copy Diagnostics or Save Diagnostics… from a failed project when asking for help. Report reproducible bugs through GitHub Issues. Report security problems privately as described in SECURITY.md.
Requirements:
- macOS 15+
- Apple Silicon
- Xcode 26.6 (build 17F113), selected as the active developer directory
- the Xcode Metal toolchain
- Homebrew
cmake,ninja,ripgrep, andzstd
From the repository root, prepare the release-equivalent build tools and run the development app with the allowed repository-local toolchain path:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -downloadComponent MetalToolchain
brew install cmake ninja ripgrep zstd
./scripts/run.sh --toolchain-root "$PWD/Toolchains/dev/2.0.0"Useful variants:
./scripts/run.sh --fast --toolchain-root "$PWD/Toolchains/dev/2.0.0"
./scripts/run.sh --rebuild --toolchain-root "$PWD/Toolchains/dev/2.0.0"--fast requires an existing valid core component and performs no build or download. --rebuild rebuilds the complete local capability set.
The only supported development overrides are the local toolchain root, candidate route, stop-after stage, skip-training, and benchmark run seed. Product policy lives in typed run options and resolved plans, not backend-specific environment variables.
input
→ preflight and topology policy
→ bounded COLMAP feature matching and camera reconstruction
→ canonical COLMAP model
→ native msplat Metal training
→ validated Output/splat.ply + Output/splat_receipt.json pair
COLMAP is the automatic geometry route in 0.2.0. It is not a user-facing backend choice. A single-batch DA3 initializer remains available only to the typed benchmark override until it clears the full quality corpus. MetalSplatter is the native result viewer.
The release toolchain is split into signed capabilities:
macos-arm64-coregeometry-da3-basegeometry-da3-small
Normal runs install only the capabilities they need. The automatic route uses native COLMAP from the core component and does not download DA3 or its Python runtime. The optional Base component carries the DA3 runtime; constrained DA3 runs select the Small weights before execution.
See ONBOARDING.md for maintainer architecture and CONTRIBUTING.md for change rules.
./scripts/test.sh
swift test --package-path Tools/ManifestTool
./scripts/test_python_tools.sh
./scripts/ci/check_repo_health.sh
./scripts/ci/check_workflows.sh
./scripts/ci/test_release_scripts.sh
find scripts -type f -name '*.sh' -print0 | xargs -0 -n1 bash -n
./scripts/benchmark/run_suite.sh --profile release
shellcheck $(git ls-files 'scripts/*.sh' 'scripts/**/*.sh')
actionlint
gitleaks git --redactThe full release benchmark needs the external 26-scene corpus described by scripts/benchmark/corpus.json; large media is intentionally not stored in Git.
Native trainer changes also run ./scripts/ci/test_msplat_native_build.sh. The Release App workflow generates the pinned synthetic fixture under the hosted runner's temporary root, then reuses those exact bytes for packaged-app, remote-only, bundled-offline, and cached-only verification. It does not accept a repository variable or external fixture path. scripts/release/release_fixture_manifest.json binds the MIT generator, camera construction, per-image hashes and sizes, and aggregate closure digest.
On the exact 48 GiB M4 Max reference host, run the additional product-performance gate:
./scripts/ci/run_release_reliability_product_gate.shThe release-reliability product gate runs optimized XCTest entry points against real 10,000-entry folder and ZIP fixtures plus a 139.6 MiB PLY validation and export. Its host-bound baseline enforces at most 1.25 times baseline operation wall time and whole-process peak RSS plus 64 MiB. The gate separately proves the two-second cooperative-cancellation and one-second passive-share-cleanup budgets, uses one fresh receipt per workload, and verifies the fixture and test binary identities before and after every run. It intentionally fails closed on any other host rather than pretending its numbers are comparable.
Fixture reproducibility proves input integrity only. The integrated geometry-conditioning gate rejects weak camera support, collapsed trajectories, inadequate parallax, and degenerate point distributions before training. Packaged release verification also requires the exact generated corpus to pass signed-core reconstruction for at least 11 of 12 views plus native msplat training on macOS 15 and macOS 26.
Stable release packaging is performed only by the protected workflows. build_dmg.sh --production intentionally rejects a live source checkout.
The release order is fixed: merge the reviewed release commit, make the repository public, manually dispatch CodeQL, create the immutable version tag, then run Release App.
The toolchain is released first. From protected main, create toolchain-v2.0.0, run Toolchain Producer, obtain the schema-v2 payload and receipt from the external sign-only authority, run Release Benchmark Evidence, then run Toolchain Publication. Independently reverify the exact draft release ID, source ref, artifact IDs, sizes, and digests before publishing that draft.
After the signed toolchain is live, create v0.2.0 at the same protected main commit and run Release App. It builds an identity-free prepared product, hands only authenticated bytes to the isolated signing environment, verifies the final closure, and leaves an owned stable draft. Independently reverify that draft before publishing it. The required sign-only authority workflow and EasySplat's release workflows must not publish automatically.
Before either tag is created, the reviewed commit must be merged, both repositories' main branches must be protected, exposed credentials must be rotated, and the owner must explicitly approve publication. Make EasySplat public only with that approval, then run all four CodeQL jobs on the exact protected-main commit. See ONBOARDING.md for the operator sequence, required environments, and runner roles. ./scripts/run.sh remains the development entry point.
Release App verifies hardened-runtime and nested-code signatures, notarization receipts, stapling, Gatekeeper assessment, a quarantined install, the DMG, checksums, SBOM, licenses, and provenance. It can resume only its exact repository/tag/commit-owned draft and rejects different or foreign assets. Final publication remains a separate human action.
TestFlight uses the separate Release TestFlight workflow. It builds one source-bound, App Store-signed arm64 package, verifies its package/signature/entitlement evidence, uploads that exact package once, and does not treat upload acceptance as success. The submission must reach App Store Connect's terminal READY_TO_TEST state with no processing errors. Release approval then requires exact-build dogfood records from both a fresh container and the affected internal container; the records are bound to the source commit, package, build, submission artifact, and processing receipt.
EasySplat is released under the MIT License. Redistributed source, runtime, and model components keep their own licenses; see NOTICE.md and each release's license bundle and SPDX SBOM.