Skip to content

INSTALL.md

Latest commit

 

History

History
224 lines (159 loc) · 9.31 KB

INSTALL.md

File metadata and controls

224 lines (159 loc) · 9.31 KB

Meshroom Installation

This guide will help you setup a development environment to launch and contribute to Meshroom.

Table of Contents

  1. Use prebuilt release
  2. Installation from source code
    1. Install minimal dependencies
      1. Python environment
      2. Qt/PySide
    2. Install dependencies
      1. AliceVision
      2. QtAliceVision
    3. Install plugins
      1. mrSegmentation plugin
      2. MeshroomHub
    4. Start Meshroom
  3. Adding custom nodes, templates and plugins
    1. Custom nodes
    2. Custom templates
    3. 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 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:

git clone --recursive https://github.com/alicevision/Meshroom.git
cd meshroom

Install minimal dependencies

To use Meshroom nodal system without any visualization option, you can rely on a minimal set of dependencies.

Python environment

  • Windows: Python 3 (>=3.9)
  • Linux: Python 3 (>=3.9)

To install all the requirements for runtime, development and packaging, simply run:

pip install -r requirements.txt -r dev_requirements.txt

Note

dev_requirements is only related to testing and packaging. It is not mandatory to run Meshroom.

Note

It is recommended to use a virtual Python environment, like python -m venv meshroom_venv.

Qt/PySide

  • PySide >= 6.7

Warning

For PySide 6.8.0 and over, the following error may occur when leaving Meshroom's homepage: Cannot load /path/to/pip/install/PySide6/qml/QtQuick/Scene3D/qtquickscene3dplugin.dll: specified module cannot be found. This is caused by Qt63DQuickScene3D.dll which seems to be missing from the pip distribution, but can be retrieved from a standard Qt installation. On recent Linux systems such as Ubuntu 25, this can be resolved by installing libqt63dquickscene3d6 using the package manager. Alternatively:

  • On Windows, the DLL for MSVC2022_64 can be directly downloaded here. It then needs to be placed in /path/to/pip/install/PySide6.
  • On Linux, the .so (here, Rocky9-based) can be directly downloaded here. It then needs to be placed in /path/to/pip/install/PySide6/Qt/qml/QtQuick/Scene3D.

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.

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 or extract files from a recent AliceVision build on Dockerhub.

Alternatively, you can build AliceVision manually from the source code by following this guide.

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:

ALICEVISION_ROOT=/path/to/AliceVision/install/directory

AliceVision provides nodes and templates for Meshroom, which need to be declared to Meshroom with the following environment variables:

MESHROOM_NODES_PATH={ALICEVISION_ROOT}/share/meshroom
MESHROOM_PIPELINE_TEMPLATES_PATH={ALICEVISION_ROOT}/share/meshroom

Meshroom also relies on specific files provided with AliceVision, 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, 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).

QML2_IMPORT_PATH=/path/to/QtAliceVision/install/qml
QT_PLUGIN_PATH=/path/to/QtAliceVision/install

Install plugins

mrSegmentation plugin

Some templates provided by AliceVision contain nodes that are not packaged with AliceVision. These nodes are part of the mrSegmentation plugin, which can be found here.

To build and install mrSegmentation, follow this guide.

For mrSegmentation nodes to be correctly detected by Meshroom, the following environment variable should be set:

MESHROOM_PLUGINS_PATH=/path/to/mrSegmentation

MeshroomHub

You can find many experimental Machine Learning plugins on MeshroomHub.

Start Meshroom

  • Launch the User Interface
# 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
# 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

In addition to the nodes and templates provided by Meshroom and AliceVision, custom ones can be created, loaded by, and used in Meshroom.

Custom nodes

Nodes need to be provided to Meshroom as Python modules, using the MESHROOM_NODES_PATH environment variable.

For example, to add a set of three custom nodes (CustomNodeA, CustomNodeB and CustomNodeC) to Meshroom, a Python module containing these nodes must be created:

├── folderA
│   ├── customNodes
│   │   ├── __init__.py
│   │   ├── CustomNodeA.py
│   │   ├── CustomNodeB.py
│   │   └── CustomNodeC.py
├── folderB

Its containing folder must then be added to MESHROOM_NODES_PATH:

  • On Windows: 
    set MESHROOM_NODES_PATH=/path/to/folderA;%MESHROOM_NODES_PATH%
  • On Linux: 
    export MESHROOM_NODES_PATH=/path/to/folderA:$MESHROOM_NODES_PATH

Note

A valid Meshroom node is a Python file that contains a class inheriting meshroom.core.desc.BaseNode. Before loading a node, Meshroom checks whether its description (the content of its class) is valid. If it is not, the node is rejected with an error log describing which part is invalid.

Custom templates

The list of pipelines can also be enriched with custom templates, that are declared to Meshroom with the environment variable MESHROOM_PIPELINE_TEMPLATES_PATH.

For example, if a couple of custom templates are saved in a folder "customTemplates", the variable should be set as follows:

  • On Windows: 
    set MESHROOM_PIPELINE_TEMPLATES_PATH=/path/to/customTemplate;%MESHROOM_PIPELINE_TEMPLATES_PATH%
  • On Linux: 
    export MESHROOM_PIPELINE_TEMPLATES_PATH=/path/to/customTemplates:$MESHROOM_PIPELINE_TEMPLATES_PATH

Tip

A template can be a Meshroom graph of any type, but it is generally expected to be a graph saved in "minimal mode". In "minimal mode", the .mg file only contains, for each node of the graph, the attributes that have non-default values. To save a graph in "minimal mode", use the File > Advanced > Save As Template menu.

Custom plugins

To add and use custom plugins with Meshroom, follow INSTALL_PLUGINS.md.