# Faster R-CNN
Faster R-CNN detects objects with a region proposal network feeding a two-stage classifier, the architecture that made region proposals part of the same trained network instead of a separate step. LibreYOLO ports the torchvision implementation for detection.
Tasks: Detection. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

Faster 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("LibreFasterRCNNl.pt")
result = model(SAMPLE_IMAGE, save=True)

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

**CLI**

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

The returned `Results` object is the one every family returns, so swapping in
a different detector is a one line change. `conf` and `iou` set the
confidence and NMS thresholds; Faster R-CNN keeps its upstream NMS step,
unlike a query-based detector. See [prediction](/docs/predict) for sources,
streaming and result handling.

## Variants

Four sizes, each a different torchvision configuration rather than a scaled
version of the same one: `n` is MobileNetV3-Large at a 320 px input, `s` is
the same backbone at 800 px, `m` is ResNet-50 with a feature pyramid, and `l`
is the v2 revision, with a deeper region proposal head and a four-convolution
box head in place of `m`'s. `n` and `s` trade accuracy for a lighter
backbone.

## Validate

`val()` returns a dictionary of `metrics/` keys covering precision, recall,
mAP 50 and mAP 50-95, measured against any dataset in the format you trained
on.

**Python**

```python
from libreyolo import LibreYOLO

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

print(metrics["metrics/mAP50-95"])
print(metrics["metrics/mAP50"])
```

**CLI**

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

## Export

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

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

Faster R-CNN exports to ONNX only, at batch size 1. The exported graph keeps
the upstream resize step 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("LibreFasterRCNNl.pt")
model.export(format="onnx", imgsz=800)
```

**CLI**

```bash
libreyolo export model=LibreFasterRCNNl.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("LibreFasterRCNNl.onnx")
result = model(SAMPLE_IMAGE)

print(result.boxes.xyxy)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreFasterRCNNn.pt` | 320 | Detection | bsd-3-clause |
| `LibreFasterRCNNs.pt` | 800 | Detection | bsd-3-clause |
| `LibreFasterRCNNm.pt` | 800 | Detection | bsd-3-clause |
| `LibreFasterRCNNl.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: Faster 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 four published checkpoints used for parity testing are 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 each Hugging Face mirror ships the BSD text on that implied basis and repeats the caveat rather than issuing an explicit checkpoint-specific grant.

## Citation

```bibtex
@inproceedings{renNIPS15fasterrcnn,
    Author = {Shaoqing Ren and Kaiming He and Ross Girshick and Jian Sun},
    Title = {Faster {R-CNN}: Towards Real-Time Object Detection
             with Region Proposal Networks},
    Booktitle = {Advances in Neural Information Processing Systems ({NIPS})},
    Year = {2015}
}
```

Copied from https://github.com/rbgirshick/py-faster-rcnn#citing-faster-r-cnn


## Faster R-CNN architecture

- Faster R-CNN N: [SVG](/diagrams/models/faster-rcnn/n.svg), [interactive diagram](/diagrams/models/faster-rcnn/n.html)
- Faster R-CNN S: [SVG](/diagrams/models/faster-rcnn/s.svg), [interactive diagram](/diagrams/models/faster-rcnn/s.html)
- Faster R-CNN M: [SVG](/diagrams/models/faster-rcnn/m.svg), [interactive diagram](/diagrams/models/faster-rcnn/m.html)
- Faster R-CNN L: [SVG](/diagrams/models/faster-rcnn/l.svg), [interactive diagram](/diagrams/models/faster-rcnn/l.html)
- Faster R-CNN MobileNet N/S family: [SVG](/diagrams/models/faster-rcnn/family-mobile.svg), [interactive diagram](/diagrams/models/faster-rcnn/family-mobile.html)