> This is the documentation for LibreYOLO 1.5.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: normal. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.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: LibreYOLO fetches the matching
size directly from the official checkpoints and caches it locally.

**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.5.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 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| normal | 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, distributed by their authors. LibreYOLO does not host or mirror them.
- Interpretation: MIT is a permissive license: the code and the official ViT-S, ViT-B and ViT-L checkpoints can be used in commercial and closed-source products. It asks that you keep the license text and copyright notice with any copy you redistribute, and it places no obligation on your own application code. LibreYOLO downloads these checkpoints directly from the official Hugging Face repositories at a pinned revision rather than copying them into its own organization, and verifies each file against a recorded SHA-256 checksum before use. The DINOv2 encoder MoGe-2 builds on is separately licensed Apache-2.0 by Meta AI; LibreYOLO reuses the DINOv2 implementation already bundled for its Depth Anything V2 family rather than copying it again here.

LibreYOLO does not copy these checkpoints into its own organization.
`LibreYOLO("LibreMoGe2s-normal.pt")` downloads the matching size directly from
the official Hugging Face repositories at a pinned revision, and verifies the
file against a recorded SHA-256 checksum before use.

## 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)