alicevision · fabiencastan · Aug 19, 2025 · Aug 18, 2025 · Aug 18, 2025 · Aug 18, 2025
diff --git a/INSTALL.md b/INSTALL.md
@@ -1,53 +1,52 @@
-# Meshroom installation
+# Meshroom Installation
 This guide will help you setup a development environment to launch and contribute to Meshroom.
 
+## Table of Contents
+
+1. [Use prebuilt release](#use-prebuilt-release)
+2. [Installation from source code](#installation-from-source-code)
+    1. [Install minimal dependencies](#install-minimal-dependencies)
+        1. [Python environment](#python-environment)
+        2. [Qt/PySide](#qtpyside)
+    2. [Install dependencies](#install-dependencies)
+        1. [AliceVision](#alicevision)
+        2. [QtAliceVision](#qtalicevision)
+    3. [Install plugins](#install-plugins)
+        1. [mrSegmentation plugin](#mrsegmentation-plugin)
+        2. [MeshroomHub](#meshroomhub)
+    4. [Start Meshroom](#start-meshroom)
+3. [Adding custom nodes, templates and plugins](#adding-custom-nodes-templates-and-plugins)
+    1. [Custom nodes](#custom-nodes)
+    2. [Custom templates](#custom-templates)
+    3. [Custom plugins](#custom-plugins)
+
+
+## Use prebuilt release 
+
+To quickly run Meshroom without setting up a development environment, follow these simple steps:
+
+1. **Download the prebuilt binaries**:
+    * Visit the [Releases](https://github.com/alicevision/meshroom/releases) page.
+    * Download the latest release that is suitable for your operating system.
+2. **Extract the archive**:
+    * On Windows: right-click on the .zip file and select "Extract All", or run `unzip Meshroom-x.y.z.zip` in a terminal.
+    * On Linux: in a terminal, run `tar -xzvf Meshroom.x.y.z.tar.gz`.
+3. **Run Meshroom**: in the extracted folder, double-click on the "Meshroom" executable to launch it.
 
 ## Installation from source code
 
 Get the source code and install runtime requirements:
 ```bash
 git clone --recursive https://github.com/alicevision/Meshroom.git
 cd meshroom
-pip install -r requirements.txt
 ```
 
+### Install minimal dependencies
 
-## Start Meshroom
+To use Meshroom nodal system without any visualization option, you can rely on a minimal set of dependencies.
 
- - __Launch the User Interface__
-
-```bash
-# Windows
-set PYTHONPATH=%CD% && python meshroom/ui
-# Linux/macOS
-PYTHONPATH=$PWD python meshroom/ui
-```
 
-On Ubuntu, you may have conflicts between native drivers and mesa drivers. In that case, you need to force usage of native drivers by adding them to the LD_LIBRARY_PATH:
-`LD_LIBRARY_PATH=/usr/lib/nvidia-340 PYTHONPATH=$PWD python meshroom/ui`
-You may need to adjust the folder `/usr/lib/nvidia-340` with the correct driver version.
-
- - __Launch a 3D reconstruction in command line__
-
-```bash
-# Windows: set PYTHONPATH=%CD% &&
-# Linux/macOS: PYTHONPATH=$PWD
-python bin/meshroom_batch --input INPUT_IMAGES_FOLDER --output OUTPUT_FOLDER
-```
-
-
-## Use prebuilt AliceVision
-
-Download a [Release](https://github.com/alicevision/meshroom/releases) or extract files from a recent AliceVision build on [Dockerhub](https://hub.docker.com/r/alicevision/alicevision).
-
-`LD_LIBRARY_PATH=~/foo/Meshroom-2023.2.0/aliceVision/lib/ PATH=$PATH:~/foo/Meshroom-2023.2.0/aliceVision/bin/ PYTHONPATH=$PWD python3 meshroom/ui`
-
-You may need to checkout the corresponding Meshroom version/tag to avoid versions incompatibilities.
-
-
-## Install Requirements
-
-### Python environment
+#### Python environment
 
 * Windows: Python 3 (>=3.9)
 * Linux: Python 3 (>=3.9)
@@ -63,7 +62,7 @@ pip install -r requirements.txt -r dev_requirements.txt
 > It is recommended to use a [virtual Python environment](https://docs.python.org/3.9/library/venv.html), like `python -m venv meshroom_venv`.
 
 
-### Qt/PySide
+#### Qt/PySide
 
 * PySide >= 6.7
 
@@ -76,11 +75,19 @@ pip install -r requirements.txt -r dev_requirements.txt
 > - On Linux, the .so (here, Rocky9-based) can be directly downloaded [here](https://drive.google.com/uc?export=download&id=1dq7rm_Egc-sQF6j6_E55f60INyxt1ega). It then needs to be placed in `/path/to/pip/install/PySide6/Qt/qml/QtQuick/Scene3D`.
 
 
-### AliceVision
+### Install dependencies
+
+You can install AliceVision to get access to 3D Computer Vision and Machine Learning nodes and pipelines. Additionally, you can install QtAliceVision to get access to Image and 3D data visualization within Meshroom.
 
-Meshroom relies on the [AliceVision](https://github.com/alicevision/AliceVision) framework for visualization of images and 3D data.
-AliceVision's binaries must be in the path while running Meshroom.
-To build AliceVision, follow this [guide](https://github.com/alicevision/AliceVision/blob/develop/INSTALL.md) and add the installation in your PATH (and LD_LIBRARY_PATH on Linux/macOS).
+#### AliceVision
+
+[AliceVision](https://github.com/alicevision/AliceVision)'s binaries must be in the path while running Meshroom.
+
+The easiest way is to download prebuild binaries from the release. You can download a [Release](https://github.com/alicevision/AliceVision/releases) or extract files from a recent AliceVision build on [Dockerhub](https://hub.docker.com/r/alicevision/alicevision).
+
+Alternatively, you can build AliceVision manually from the source code by following this [guide](https://github.com/alicevision/AliceVision/blob/develop/INSTALL.md).
+
+Then add the `bin` and `lib` folders into your `PATH` (and `LD_LIBRARY_PATH` on Linux/macOS) environment variables.
 
 The following environment variable must always be set with the location of AliceVision's install directory:
 ```
@@ -93,27 +100,29 @@ MESHROOM_NODES_PATH={ALICEVISION_ROOT}/share/meshroom
 MESHROOM_PIPELINE_TEMPLATES_PATH={ALICEVISION_ROOT}/share/meshroom
 ```
 
-Meshroom also relies on specific files provided with AliceVision.
-* Sensor database: a text database of sensor width per camera model.
-Provided in AliceVision source tree: {ALICEVISION_REPOSITORY}/src/aliceVision/sensorDB/cameraSensors.db
-* Voctree (optional): for larger datasets (>200 images), greatly improves image matching performances.
-It can be downloaded [here](https://gitlab.com/alicevision/trainedVocabularyTreeData/raw/master/vlfeat_K80L3.SIFT.tree).
-* Sphere detection model (optional): for the automated sphere detection in stereo photometry.
-It can be downloaded [here](https://gitlab.com/alicevision/SphereDetectionModel/-/raw/main/sphereDetection_Mask-RCNN.onnx).
-* Semantic segmentation model (optional): for the semantic segmentation of objects.
-It can be downloaded [here](https://gitlab.com/alicevision/semanticSegmentationModel/-/raw/main/fcn_resnet50.onnx).
-* Color chart detection models (optional): for the detection of color charts.
-It can be downloaded [here](https://gitlab.com/alicevision/ColorchartDetectionModel).
-
-Environment variables need to be set for Meshroom to find those files:
+Meshroom also relies on [specific files provided with AliceVision](https://github.com/alicevision/AliceVision/blob/develop/INSTALL.md#environment-variables-to-set-for-meshroom), set through environment variables.
+If these variables are not set, Meshroom will by default look for them in `{ALICEVISION_ROOT}/share/aliceVision`.
+
+> [!NOTE]
+> You may need to checkout the corresponding Meshroom version/tag to avoid versions incompatibilities.
+
+
+#### QtAliceVision
+
+[QtAliceVision](https://github.com/alicevision/QtAliceVision), an additional Qt plugin, can be built to extend Meshroom UI features.
+
+Note that it is optional but highly recommended.
+
+This plugin uses AliceVision to load and visualize intermediate reconstruction files and OpenImageIO as backend to read images (including RAW/EXR).
+It also adds support for Alembic file loading in Meshroom's 3D viewport, which allows to visualize sparse reconstruction results (point clouds and cameras).
+
 ```
-ALICEVISION_SENSOR_DB=/path/to/database
-ALICEVISION_VOCTREE=/path/to/voctree
-ALICEVISION_SPHERE_DETECTION_MODEL=/path/to/detection/model
-ALICEVISION_SEMANTIC_SEGMENTATION_MODEL=/path/to/segmentation/model
-ALICEVISION_COLORCHARTDETECTION_MODEL_FOLDER=/path/to/ColorChartDetectionModel
+QML2_IMPORT_PATH=/path/to/QtAliceVision/install/qml
+QT_PLUGIN_PATH=/path/to/QtAliceVision/install
 ```
-If these variables are not set, Meshroom will by default look for them in `{ALICEVISION_ROOT}/share/aliceVision`.
+
+
+### Install plugins
 
 #### mrSegmentation plugin
 
@@ -127,18 +136,32 @@ For mrSegmentation nodes to be correctly detected by Meshroom, the following env
 MESHROOM_PLUGINS_PATH=/path/to/mrSegmentation
 ```
 
-### QtAliceVision plugin
+#### MeshroomHub
 
-[QtAliceVision](https://github.com/alicevision/QtAliceVision), an additional Qt plugin, can be built to extend Meshroom UI features.
+You can find many experimental Machine Learning plugins on [MeshroomHub](https://github.com/meshroomHub).
 
-Note that it is optional but highly recommended.
 
-This plugin uses AliceVision to load and visualize intermediate reconstruction files and OpenImageIO as backend to read images (including RAW/EXR).
-It also adds support for Alembic file loading in Meshroom's 3D viewport, which allows to visualize sparse reconstruction results (point clouds and cameras).
+### Start Meshroom
+
+ - __Launch the User Interface__
 
+```bash
+# Windows
+set PYTHONPATH=%CD% && python meshroom/ui
+# Linux/macOS
+PYTHONPATH=$PWD python meshroom/ui
 ```
-QML2_IMPORT_PATH=/path/to/QtAliceVision/install/qml
-QT_PLUGIN_PATH=/path/to/QtAliceVision/install
+
+On Ubuntu, you may have conflicts between native drivers and mesa drivers. In that case, you need to force usage of native drivers by adding them to the LD_LIBRARY_PATH:
+`LD_LIBRARY_PATH=/usr/lib/nvidia-340 PYTHONPATH=$PWD python meshroom/ui`
+You may need to adjust the folder `/usr/lib/nvidia-340` with the correct driver version.
+
+ - __Launch a 3D reconstruction in command line__
+
+```bash
+# Windows: set PYTHONPATH=%CD% &&
+# Linux/macOS: PYTHONPATH=$PWD
+python bin/meshroom_batch --input INPUT_IMAGES_FOLDER --output OUTPUT_FOLDER
 ```
 
 ## Adding custom nodes, templates and plugins