Desktop and command-line preprocessing for stitched 360° panoramas and standard videos/images. Generate rectilinear views, filter blur and motion, and export segmentation masks and optional GPS metadata for reconstruction workflows.
360 Extractor Studio — v4.1.0 Pre-release. This public preview is for user feedback and is excluded from Latest; v3.3 remains the latest stable release.
| Platform | Download v4.1.0 | Validation status |
|---|---|---|
| macOS 14.4+ — Apple Silicon (arm64) | macOS ZIP | Developer ID signed, Apple-notarized and stapled. Real extraction, CPU/MPS masks, reports, project persistence, diagnostics and cancellation tested on an existing Mac. Includes the Qt Cocoa accessibility fix. |
| Windows — x64 | Windows ZIP | Experimental, CPU AI only. Draft binary tested on Shadow Windows 11: extraction, reports, model provisioning, project persistence and cancellation. This package does not include CUDA inference. |
Windows limitation: earlier candidates reproduced an intermittent native crash (0xC0000005) during extraction/shutdown. Its exact cause remains unconfirmed, and passing hosted CI and lifecycle stress tests does not prove it is resolved. Report any recurrence through the bug report form, with your settings and available logs.
Start with a short clip and a separate output folder. Clean-machine acceptance and the full Studio interaction matrix remain open; targeted persistence and cancellation checks passed. Read the release notes and SHA-256 fingerprints for the tested scope, prerequisites and remaining limits; validation evidence and macOS notarization evidence are attached to the release.
New in 4.1.0: saved projects, destination mask profiles, alignment diagnostics, controlled 16-to-31 sampling and consumer-report imports. See the binary acceptance record for exact results and limits.
Actual Studio window with a synthetic demonstration panorama. Preview and controls are rendered by the application; the image is not evidence of segmentation or reconstruction accuracy.
Version 4.1.0 includes the project, diagnostic, sampling and consumer-report workflows described above, together with the earlier October corrections. Source installation requires Python 3.11 or later. Qualification results and remaining limits are documented in the release notes above.
- Cube, Ring and Fibonacci layouts, selectable views, FOV, pitch and output resolution.
- Flat media passthrough at native resolution with the same filtering and masking options.
- GUI and Qt-free CLI execution; settings saved separately from each job's configuration.
- YOLO segmentation with class selection, face scope, binary masks or smoothed edges. The Plants group means COCO's potted plant, not arbitrary vegetation.
- A nadir disc on the Cube Down view, independent of AI.
- Blur filtering, optional sharpening and motion-based selection. AI skipping currently rejects individual views.
- GPS from supported CAMM/GPMF records and GPX/SRT sidecars; explicit telemetry status and time provenance. GPS9, IMU orientation and automatic horizon leveling are not supported.
- COLMAP calibration and a portable runner that applies a virtual rig and separate masks. Reconstruction quality and compatibility with target software still require real dataset validation.
Input 360 media must already be stitched. Accepting .insv does not imply native double-fisheye stitching. Pixel handling currently targets 8-bit SDR; HDR, ICC and alpha workflows are not qualified.
Clone the repository and select the v4.1.0 tag to test the published preview's application source. main may contain different changes. The macOS download also includes a Qt 6.12.0 Cocoa dependency backport, applied after CI; installing the source or wheel alone does not apply that native fix. Run the commands below from the selected checkout’s root.
git clone --branch v4.1.0 https://github.com/nicolasdiolez/360Extractor.git
cd 360ExtractorUse a supported Python interpreter with its own environment. Current development sources require Python 3.11 or later. The local correction tests use Python 3.13; CI targets Python 3.11. Wider Python compatibility is not yet qualified.
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ".[dev]" -c constraints/security-minimums.txt
python check_env.py --mode allThe example selects Python 3.13 explicitly. On Windows, select an installed Python 3.11 or 3.13 interpreter, create the environment with python -m venv .venv and activate .venv\Scripts\Activate.ps1 in PowerShell instead. Install FFmpeg/ffprobe for embedded GPS and verify with python check_env.py --telemetry. The interactive setup_cuda.py helper operates only inside a virtual environment; its --index-url must be selected from the official PyTorch installer for the target driver. A hashed macOS arm64/Python 3.13 lock is available in constraints/macos-arm64-py313.lock. Windows/CUDA locks and clean-machine binary qualification remain work in progress.
Standard model weights use ~/.cache/360-extractor/models (override with EXTRACTOR360_MODEL_DIR). A model absent from the cache may be downloaded on first use. Provision the cache before offline use. Custom .pt files can execute code and require --trust-custom-model or trust_custom_model: true from an explicitly trusted source.
AI selects an available accelerator automatically. If GPU inference is unavailable or unreliable on your machine, set EXTRACTOR360_DEVICE=cpu before launching (export EXTRACTOR360_DEVICE=cpu in a macOS/Linux terminal, or $env:EXTRACTOR360_DEVICE="cpu" in PowerShell). Use auto to restore automatic selection. The Windows 4.1.0 download is CPU-only. CPU and Apple MPS inference were exercised on the final Mac archive; other GPU profiles remain unqualified.
# Studio (.360proj save/open in the Project menu)
python -m extractor360
# Stitched panorama or video, six cube views
360extractor --input panorama.mp4 --output out --layout cube --interval 1 --resolution 2048
# Standard media
360extractor --input video.mp4 --output out --flat
# AI and a nadir disc on the Down face
360extractor --input panorama.mp4 --output out --layout cube --ai-mask --ai-mask-cameras Down --nadir-mask
# COLMAP preparation
360extractor --input panorama.mp4 --output out --layout cube --export-colmapEvery run creates a new source-specific folder: panorama_processed, panorama_processed_001, and so on. Existing datasets are never silently replaced or resumed. Recursive scans exclude generated folders. manifest.json starts as running, then records completed, failed or cancelled with confirmed write counts. A process kill or power loss can leave partial state; no automatic recovery is implemented. images.jsonl associates confirmed images and masks with their camera and frame.
Development sources also provide --mask-profile realityscan|colmap|postshot|custom. Named profiles select mask filenames and polarity together; Postshot targets Remove Occluders, with white ignored regions. Use a separate export for COLMAP, which requires black ignored regions. These file contracts do not certify reconstruction quality in each application. See profiles and disk estimates.
Free space is checked on the destination volume before output creation and before each capture, retaining a 256 MiB reserve. This protects the next write batch; it does not guarantee that the full run, model downloads or reconstruction will fit. The comparison protocol defines how future selection and export changes will be measured.
Run python reconstruct.py from an exported colmap/ folder to prepare a new workspace and invoke COLMAP. It requires a COLMAP build with native rig_configurator support. This pipeline follows the COLMAP rig workflow. Short real-media sparse reconstructions are recorded in the COLMAP validation. Later RealityScan/Postshot pilots from development sources succeeded on Cour but remained fragmented or failed on the difficult windows; complete-scene geometry and general compatibility remain unqualified.
Development sources can also import RealityScan/Postshot reports to inspect retained or rejected views, capture/direction coverage and mask warnings. Imports are saved in projects and do not launch reconstruction.
Feather means smoothing of a binary segmentation mask, not native model probabilities. The segmentation output uses the original image dimensions through Ultralytics' retina mask option. Precision on real operators, partial limbs, posters and tripod scenes remains to be measured.
Studio's development sources can save and reopen projects, retaining media references, per-job settings and the last recorded results. Missing/changed sources remain visible for relocation. Reopening does not resume extraction; running again creates a fresh output folder.
GPS sidecars are aligned to video start by assumption. Camera heading is omitted without orientation evidence. Unknown or relative altitude is not written as sea-level altitude; only set gps_altitude_reference: "orthometric" after confirming the source reference. Inspect telemetry status and provenance in the manifest before relying on geotags.
QT_QPA_PLATFORM=offscreen python -m pytest -q
python -m ruff check .
python scripts/check_release.pyIn PowerShell, set $env:QT_QPA_PLATFORM="offscreen" and run python -m pytest -q separately. See release preparation for versioning, draft builds and binary acceptance.
- Settings reference
- CLI reference
- Acceptance protocol for Studio, CLI and release binaries
- Current roadmap
- Actual architecture
- Audit and implementation plan
- Contributing and changelog
Author: Nicolas Diolez. Licensed under AGPL-3.0. The distribution also requires an inventory of the licenses of its bundled components.