Skip to content

README.md

Latest commit

 

History

History
168 lines (112 loc) · 5.47 KB

README.md

File metadata and controls

168 lines (112 loc) · 5.47 KB

mrUniMSPS

Meshroom Plugin for Uni-MS-PS

Integrate Uni-MS-PS multi-view photometric stereo normal estimation directly into your Meshroom photogrammetry pipeline.

Uni-MS-PS

What is Uni-MS-PS?

Uni-MS-PS is a unified multi-view and single-view photometric stereo method for surface normal estimation. Given multiple images of a scene captured from the same viewpoint under varying illumination, it estimates per-pixel surface normals. It supports both calibrated (known light directions) and uncalibrated modes.

Requirements

  • Python 3.10+
  • CUDA 12.x + NVIDIA GPU
  • Meshroom 2025+ (develop branch)

Quick Start

Prerequisite: a working Meshroom installation.

1. Clone the plugin

cd /path/to/your/plugins
git clone https://github.com/meshroomHub/mrUniMSPS.git
cd mrUniMSPS

2. Set up the virtual environment

Meshroom looks for a folder named venv at the plugin root.

python3 -m venv venv
source venv/bin/activate

pip install --upgrade pip
pip install torch torchvision
pip install -r requirements.txt

deactivate

This installs Uni-MS-PS and all its dependencies automatically via pip.

3. Download pretrained weights

bash download_weights.sh

This downloads the uncalibrated model weights (~303 MB) from Google Drive into weights/:

weights/
└── model_uncalibrated.pth

The plugin auto-detects this directory. No config.json needed.

Note: if the download fails (Google Drive quota), install gdown (pip install gdown) and re-run the script.

4. Register the plugin in Meshroom

export MESHROOM_PLUGINS_PATH=/path/to/your/plugins/mrUniMSPS:$MESHROOM_PLUGINS_PATH

Launch Meshroom: the UniMSPS node appears under Photometric Stereo.

Node Parameters

Inputs

Parameter Label Description
inputSfm Input SfMData SfMData JSON file with multi-lighting views grouped by poseId (required)
maskFolder Mask Folder Folder with mask PNGs named by poseId or viewId
downscale Downscale Factor Integer downscale factor for input images (1-8, default: 1)
nbImages Number of Images Number of lighting images per pose (-1 = all)
useGpu Use GPU Use GPU for inference (default: true)

Outputs

Parameter Description
outputFolder Folder containing normal map PNGs
outputSfmDataNormal SfMData file referencing normal maps

Advanced: Developer Setup

If you prefer to work from a local Uni-MS-PS clone instead of pip install:

  1. Clone the repo: git clone -b meshroom https://github.com/meshroomHubWarehouse/Uni-MS-PS.git
  2. Edit meshroom/config.json: 
    [
    {"key": "UNI_MS_PS_PATH", "type": "path", "value": "/path/to/Uni-MS-PS"}
]
  3. Place weights in the weights/ directory of the Uni-MS-PS clone.

The node tries pip imports first, then falls back to the config path.

Plugin Structure

mrUniMSPS/
├── meshroom/
│   ├── config.json                # Plugin configuration (optional for dev)
│   └── UniMSPS/
│       ├── __init__.py
│       └── UniMSPS.py             # Meshroom node definition
├── weights/                       # Downloaded model weights
│   └── model_uncalibrated.pth
├── venv/                          # Python virtual environment
├── download_weights.sh            # Weight download script
├── requirements.txt               # Python dependencies (pip install from git)
└── README.md

For more details on how Meshroom plugins work, see:

Acknowledgements

This work is supported by DOPAMIn (Diffusion Open de Photogrammetrie par AliceVision/Meshroom pour l'Industrie), selected in the 2024 cohort of the OPEN programme run by CNRS Innovation. OPEN supports the valorization of open-source scientific software by providing dedicated developer resources, governance expertise, and industry partnership support.

Lead researcher: Jean-Denis Durou, IRIT (INP-Toulouse)

Related Projects

Project Description
Uni-MS-PS Unified multi-view and single-view photometric stereo
mrSDMUniPS Meshroom plugin for SDM-UniPS photometric stereo
mrOpenRNb Meshroom plugin for neural surface reconstruction from normals

License

This project is licensed under the Mozilla Public License 2.0.