# Mask R-CNN
Mask R-CNN adds a per-region mask branch to Faster R-CNN, predicting a segmentation mask alongside each box it detects. LibreYOLO ports the torchvision implementation for detection and instance segmentation.
Tasks: Detection, Instance segmentation. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

Mask R-CNN needs no optional extra. Everything it imports is in the base
install.

```bash
pip install libreyolo
```

## Predict

Weights download from Hugging Face on first use and are cached locally.

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreMaskRCNNr50.pt")
result = model(SAMPLE_IMAGE, save=True)

print(result.masks.data.shape)
for box in result.boxes:
    print(box.cls, box.conf, box.xyxy)
```

**CLI**

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

**Boxes only**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# task="detect" skips the mask head and returns boxes from the same
# checkpoint, with no masks in the result.
model = LibreYOLO("LibreMaskRCNNr50.pt", task="detect")
result = model(SAMPLE_IMAGE)

print(result.boxes.xyxy)
```

The returned `Results` object is the one every family returns, so swapping in
a different detector is a one line change. Loading the checkpoint with no
`task` argument returns instance masks, since segmentation is this family's
default task; `result.masks` then carries them alongside the boxes.
Passing `task="detect"` loads the same weights without the mask head and
returns boxes only. `conf` and `iou` set the confidence and NMS thresholds;
Mask R-CNN keeps its upstream NMS step, unlike a query-based detector. See
[prediction](/docs/predict) for sources, streaming and result handling.

## Variants

One backbone: ResNet-50 with a feature pyramid, using torchvision's v2
Mask R-CNN builder. The published checkpoint carries a BSD-3-Clause license
and serves both tasks in this family, so there is no size to choose between.

## Validate

`val()` returns a dictionary of `metrics/` keys. Against this checkpoint's
default segmentation task, the plain `metrics/mAP50-95` key holds the mask
score, and the same run reports boxes under the `(B)` suffix so both are
available from one pass.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreMaskRCNNr50.pt")
metrics = model.val(data="my-dataset.yaml")

print(metrics["metrics/mAP50-95"])      # masks
print(metrics["metrics/mAP50-95(B)"])   # boxes
```

**CLI**

```bash
libreyolo val model=LibreMaskRCNNr50.pt data=my-dataset.yaml
```

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Detection | yes |  |  |  |  |  |  |  |  |  |  |  |
| Instance segmentation | yes |  |  |  |  |  |  |  |  |  |  |  |

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

Mask R-CNN exports to ONNX only, at batch size 1. The exported graph keeps the
upstream resize and mask-paste steps inside it, so LibreYOLO forces
`dynamic=True` regardless of what is passed, to keep the graph valid for
sources that are not square. An exported `.onnx` file loads back through
`LibreYOLO()` on its file suffix and returns the same `Results`.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreMaskRCNNr50.pt")
model.export(format="onnx", imgsz=800)
```

**CLI**

```bash
libreyolo export model=LibreMaskRCNNr50.pt format=onnx imgsz=800
```

**Use the exported file**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# The factory routes on the file suffix, so an exported artifact loads
# like any checkpoint and returns the same Results object.
model = LibreYOLO("LibreMaskRCNNr50.onnx")
result = model(SAMPLE_IMAGE)

print(result.masks.data.shape)
```

## Checkpoints

Every published weight file for this family. The one checkpoint below is
listed under detect, but the same file loads for segmentation too: pass no
`task` argument and it returns masks by default.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreMaskRCNNr50.pt` | 800 | Detection | bsd-3-clause |

## 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: Mask R-CNN, PyTorch
- Upstream license: BSD-3-Clause
- Upstream source: https://github.com/pytorch/vision
- LibreYOLO code: BSD-3-Clause
- Weights: BSD-3-Clause, republished at https://huggingface.co/LibreYOLO
- Interpretation: BSD-3-Clause is a permissive license, so this code can be used in commercial and closed-source products with no obligation on your own application code. It asks only that you keep the copyright notice and disclaimer with any copy you redistribute, and it carries no patent grant. The published checkpoint used for parity testing is not distributed in the LibreYOLO source tree: torchvision's own documentation notes that a pretrained model's terms may depend on its training data, so the Hugging Face mirror ships the BSD text on that implied basis and repeats the caveat rather than issuing an explicit checkpoint-specific grant.

Mask R-CNN is built as a subclass of LibreYOLO's Faster R-CNN wrapper: it
shares the same torchvision source and BSD-3-Clause license, and adds the
mask predictor and mask RoI head from the same ported commit.


## Mask R-CNN architecture

- Mask R-CNN R50 segmentation: [SVG](/diagrams/models/mask-rcnn/r50-segment.svg), [interactive diagram](/diagrams/models/mask-rcnn/r50-segment.html)
- Mask R-CNN R50 detection: [SVG](/diagrams/models/mask-rcnn/r50-detect.svg), [interactive diagram](/diagrams/models/mask-rcnn/r50-detect.html)