Skip to content

README.md

Latest commit

 

History

History
169 lines (114 loc) · 5.51 KB

README.md

File metadata and controls

169 lines (114 loc) · 5.51 KB

mrLINOUniPS

Meshroom Plugin for LINO_UniPS

Integrate LINO_UniPS photometric stereo normal estimation directly into your Meshroom photogrammetry pipeline.

LINO_UniPS

What is LINO_UniPS?

LINO_UniPS is a universal photometric stereo method based on a light-invariant normal estimator. It predicts high-quality per-pixel surface normals from multi-lighting images without requiring known light directions. The method leverages diffusion model priors and handles arbitrary numbers of input images with varying illumination conditions.

Requirements

  • Python 3.10+
  • CUDA 12.x + NVIDIA GPU (ampere or newer recommended for bfloat16 support)
  • 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/mrLINOUniPS.git
cd mrLINOUniPS

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 LINO_UniPS and all its dependencies automatically via pip.

3. Download pretrained weights

bash download_weights.sh

This downloads the pretrained model (~338 MB) from HuggingFace into weights/:

weights/
└── lino.pth

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

4. Register the plugin in Meshroom

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

Launch Meshroom: the LINOUniPS 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 LINO_UniPS clone instead of pip install:

  1. Clone the repo: git clone -b meshroom https://github.com/meshroomHubWarehouse/LINO_UniPS.git
  2. Edit meshroom/config.json: 
    [
    {"key": "LINO_UNIPS_PATH", "type": "path", "value": "/path/to/LINO_UniPS"}
]
  3. Place lino.pth in the LINO_UniPS directory or its weights/ subdirectory.

The node searches for weights in this order:

  1. Plugin weights/ directory
  2. LINO_UniPS code directory (from config.json)
  3. Torch hub cache (~/.cache/torch/hub/checkpoints/lino.pth)

Plugin Structure

mrLINOUniPS/
├── meshroom/
│   ├── config.json                # Plugin configuration (optional for dev)
│   └── LINOUniPS/
│       ├── __init__.py
│       └── LINOUniPS.py           # Meshroom node definition
├── weights/                       # Downloaded model weights
│   └── lino.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
LINO_UniPS Light-invariant normal estimator for universal 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.