> This is the documentation for LibreYOLO 1.6.0. Current version: https://www.libreyolo.com/docs/models/moge-2

# MoGe-2
MoGe-2 is a single-forward monocular geometry model that predicts a dense surface-normal field from one RGB image. LibreYOLO supports it for normal estimation only, through the official ViT-S, ViT-B and ViT-L checkpoints.
Tasks: Surface normals. Install: pip install libreyolo.
Verified against LibreYOLO v1.6.0.

## Install

MoGe-2 needs no optional extra. Everything it imports is in the base install.

```bash
pip install libreyolo
```

## Predict

Weights download automatically on first use. Sizes s and l use LibreYOLO mirrors; b continues to use the upstream checkpoint.

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreMoGe2s-normal.pt")
result = model(SAMPLE_IMAGE, save=True)

normal = result.normal_map
print(normal.array.shape)   # (H, W, 3) float32 unit vectors
```

**CLI**

```bash
libreyolo predict model=LibreMoGe2s-normal.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True
```

MoGe-2 returns a dense field rather than a set of detections, so
`result.boxes` is empty and `conf`, `iou` and `max_det` have no effect.
`result.normal_map` holds the result: an `(H, W, 3)` array of unit vectors
in the OpenCV camera frame, where `+x` is right, `+y` is down, `+z` is into the
scene, and a surface facing the camera reads `(0, 0, -1)`. Predicting a list of
images runs one forward pass per image; this family has no stacked-batch fast
path. See [prediction](/docs/v1.6.0/predict) for sources, streaming and result
handling.

## Variants

Three encoder sizes ship as separate checkpoints: ViT-S, ViT-B and ViT-L, all
at the same input resolution. LibreYOLO's benchmark harness has not measured
this family, so there are no published accuracy numbers to compare them by;
pick a size against your own compute budget.

## Validate

`val()` measures angular error against a paired normal-map dataset: images
beside same-stem 16-bit normal PNGs, with an optional validity mask so padded
and invalid pixels never count. It returns the mean and median angular error
in degrees, plus the percentage of pixels within 11.25, 22.5 and 30 degrees.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreMoGe2s-normal.pt")
metrics = model.val(data="my-dataset.yaml", imgsz=518)

print(metrics["metrics/mean_angular_error"])   # degrees
print(metrics["metrics/median_angular_error"])
print(metrics["metrics/within_11_25"])          # percent of pixels
```

**CLI**

```bash
libreyolo val model=LibreMoGe2s-normal.pt data=my-dataset.yaml imgsz=518
```

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Surface normals | yes | yes | yes | yes | yes |  |  |  | yes |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

Normal export uses a fixed-resolution, batch-1 runtime contract: `dynamic` and
a `batch` other than 1 are rejected, and `imgsz` must be divisible by the ViT
encoder's patch size, which LibreYOLO checks before the run starts. An
exported artifact loads back through `LibreYOLO()` on its file suffix, so a
`.onnx` file behaves like a checkpoint and returns the same `Results`.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreMoGe2s-normal.pt")
model.export(format="onnx", imgsz=518)
model.export(format="tensorrt", imgsz=518, half=True)
```

**CLI**

```bash
libreyolo export model=LibreMoGe2s-normal.pt format=onnx imgsz=518
libreyolo export model=LibreMoGe2s-normal.pt format=tensorrt imgsz=518 half=True
```

**Use the exported file**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreMoGe2s-normal.onnx")
result = model(SAMPLE_IMAGE)

print(result.normal_map.array.shape)
```

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: MoGe-2, Microsoft
- Upstream license: MIT
- Upstream source: https://github.com/microsoft/MoGe
- LibreYOLO code: MIT
- Weights: MIT, republished at https://huggingface.co/LibreYOLO
- Interpretation: The publisher declares MIT for the model and checkpoints. LibreYOLO mirrors s and l; b remains an upstream download. The DINOv2 encoder retains its separate Apache-2.0 attribution.

The s and l checkpoints are mirrored by LibreYOLO; b stays upstream. Downloaded artifacts retain their publisher's license.

## Citation

```bibtex
@inproceedings{wang2025moge,
  title={Moge: Unlocking accurate monocular geometry estimation for open-domain images with optimal training supervision},
  author={Wang, Ruicheng and Xu, Sicheng and Dai, Cassie and Xiang, Jianfeng and Deng, Yu and Tong, Xin and Yang, Jiaolong},
  booktitle={Proceedings of the Computer Vision and Pattern Recognition Conference},
  pages={5261--5271},
  year={2025}
}

@misc{wang2025moge2,
      title={MoGe-2: Accurate Monocular Geometry with Metric Scale and Sharp Details}, 
      author={Ruicheng Wang and Sicheng Xu and Yue Dong and Yu Deng and Jianfeng Xiang and Zelong Lv and Guangzhong Sun and Xin Tong and Jiaolong Yang},
      year={2025},
      eprint={2507.02546},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2507.02546}, 
}
```

Copied from https://github.com/microsoft/MoGe#-citation


## MoGe-2 architecture

- s: [SVG](/diagrams/models/moge-2/s-normal.svg), [interactive diagram](/diagrams/models/moge-2/s-normal.html)
- b: [SVG](/diagrams/models/moge-2/b-normal.svg), [interactive diagram](/diagrams/models/moge-2/b-normal.html)
- l: [SVG](/diagrams/models/moge-2/l-normal.svg), [interactive diagram](/diagrams/models/moge-2/l-normal.html)
- Shared normal-only topology: [SVG](/diagrams/models/moge-2/family.svg), [interactive diagram](/diagrams/models/moge-2/family.html)