Proximap is an intuitive desktop application built in Python and PySide6 that provides a step-by-step wizard dashboard for 3D photogrammetry reconstruction. It acts as a graphical pipeline coordinator that automates COLMAP (for Structure-from-Motion / camera registration) and OpenMVS (for dense point clouds, meshing, mesh refinement, and texturing) to turn flat images into detailed 3D scenes.
- Drag-and-Drop Loader: Simply drag a folder or selection of image files (
.png,.jpg,.jpeg,.tiff) into the dashboard. - Camera Detection: Autodetects your camera sensor make/model from image EXIF metadata.
- Hardware Profiler: Automatically profiles local system resources (RAM size, discrete GPU availability) and sets fallback limits for low-resource environments.
- Reconstruction Quality Presets: Select from Preview, Medium, High, or Ultra configuration presets to balance speed and fidelity.
- Interactive Embedded 3D Viewer: Interactively view reconstructed stages (Sparse Cloud & Cameras, Dense Cloud, and Textured Mesh) embedded directly inside the GUI application.
- Multi-Format Export: Export final textured 3D models directly as
.obj,.glb, or.ply.
Optimized for Apple Silicon (M1/M2/M3) and compatible with Intel Macs on macOS 11 or later. The macOS package includes the Proximap desktop client plus bundled COLMAP and OpenMVS reconstruction tools.
After downloading, unzip Proximap_Mac_Release.zip, open Proximap.app, and select a folder of overlapping photos to start a reconstruction.
Proximap/
├── main_window.py # PySide6 desktop GUI entry point
├── pipeline_manager.py # Multi-stage photogrammetry pipeline coordinator
├── hardware_profiler.py # Hardware checker (RAM and CUDA detection)
│
├── package_app.ps1 # PowerShell automated build and compilation pipeline
├── installer.nsi # NSIS Setup Wizard installer configuration
├── toolchain_map.json # Config mapping GUI calls to C++ binaries
│
├── LICENSE # GNU GPL v3 Source code license
└── THIRD_PARTY_LICENSES.md # License attributions for OpenMVS, COLMAP, etc.
- Python: Version 3.9 or higher (64-bit recommended).
- GPU (Optional but Recommended): NVIDIA GPU with CUDA drivers installed for GPU-accelerated mesh refinement and densification.
Clone the repository and install dependencies:
git clone https://github.com/BelieveGamesStudios/Proximap.git
cd Proximap
pip install -r requirements.txt(Dependencies: PySide6, numpy, pillow, pyinstaller for packaging)
To run reconstructions, you must download precompiled C++ binaries for COLMAP and OpenMVS and place them in the backend_bin directory (which is ignored by Git to keep the repository lightweight):
- COLMAP: Download the Windows release and extract it to
backend_bin/colmap/. - OpenMVS: Download the Windows binary package and extract it to
backend_bin/openMVS/.
Make sure your directories resemble the following structure:
Proximap/
└── backend_bin/
├── colmap/
│ ├── colmap.exe
│ └── [Required DLLs...]
└── openMVS/
├── DensifyPointCloud.exe
├── Viewer.exe
└── [Required DLLs...]
Launch the dashboard via Python:
python main_window.pyYou can bundle Proximap into a standalone zip file or platform installer.
Follow the macOS ARM64 Packaging Guide and run:
bash package_app.shThe macOS package is written to Proximap_Mac_Release.zip.
- Place your custom logo as
app_icon.pngin the project root. - Run the automated PowerShell script as an Administrator:
powershell -ExecutionPolicy Bypass -File .\package_app.ps1
This script will automatically:
- Convert
app_icon.pnginto a multi-resolution.icoicon using Pillow. - Compile the Python scripts into a single directory layout using PyInstaller and embed the custom icon inside
Proximap.exe. - Strip out large developer libraries and test executables from COLMAP and OpenMVS to save ~450MB of space.
- Compile a Windows wizard installer (
Proximap_Setup.exe) using NSIS (Nullsoft Scriptable Install System) if installed. - Package the finalized distribution into a clean
Proximap_Commercial_Release.zipfolder.
- The Proximap frontend source code is licensed under the GNU General Public License v3 (GPL v3). See the LICENSE file for details.
- Native backend dependencies (OpenMVS, COLMAP, etc.) are subject to their own respective open-source licenses. See THIRD_PARTY_LICENSES.md for full attribution.