# Falcon Perception
Falcon Perception is an early-fusion transformer by the Technology Innovation Institute (TII) that reads an image and a natural-language query and returns every matching instance. LibreYOLO vendors its inference network for open-vocabulary detection on both sizes and instance segmentation on 600m.
Tasks: Detection, Instance segmentation. Install: pip install "libreyolo[vlm]".
Verified against LibreYOLO v1.8.0.

## Install

Falcon Perception belongs to LibreYOLO's VLM tier and needs the `vlm` extra.

```bash
pip install "libreyolo[vlm]"
```

## Predict

Weights download on first use from TII's own repositories,
`tiiuae/Falcon-Perception` (600m) and `tiiuae/Falcon-Perception-300M`, pinned
to a revision. The network is vendored in LibreYOLO; no remote code runs.

**Python**

```python
from libreyolo import LibreVLM, SAMPLE_IMAGE

# Each vocabulary entry is one query; instances get that entry's class id.
model = LibreVLM("falcon-perception", names=["building", "person"])
result = model.predict(SAMPLE_IMAGE, save=True)

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

**Segment**

```python
from libreyolo import LibreVLM, SAMPLE_IMAGE

model = LibreVLM("falcon-perception", names=["the titanium building"])
result = model.set_task("segment").predict(SAMPLE_IMAGE)

print(result.boxes.xyxy)
print(result.masks.data.shape)          # one mask per instance
```

**300m**

```python
from libreyolo import LibreVLM, SAMPLE_IMAGE

# The smaller size has no mask head: detect only.
model = LibreVLM("falcon-perception-300m", names=["building"])
result = model.predict(SAMPLE_IMAGE)
```

The family loads through `LibreVLM()`, or the `LibreFalconPerception` class.
`names=` (or `set_classes()`) is required. Each vocabulary entry is one text
query and one generation, so cost grows with the number of entries, and every
instance found for an entry gets that entry's class id. A query can be a class
name or a phrase such as `"the dog on the left"`.

For each instance the model emits a box centre, a box extent and a mask query.
`detect` returns `Results.boxes`; `segment` (600m only) also returns
`Results.masks`, made by dotting the mask query with AnyUp-upsampled image
features. Confidence is a constant 1.0 and there is no NMS: upstream's
coordinate de-duplication runs inside decoding (`coord_dedup_threshold`,
default 0.01). The generation budget is 2048 new tokens per query
(`max_new_tokens`).

## Variants

| Name | Size | Tasks |
| --- | --- | --- |
| `falcon-perception`, `falcon-perception-600m` | 600m (default) | detect, segment |
| `falcon-perception-300m` | 300m | detect |

Both run at 1024 px. When only MPS is available the family runs on CPU,
because its RoPE tables are complex64, which MPS does not implement. On CPU in
fp32 the port matches the upstream engine bit for bit: logits and hidden
states on every forward pass, and the generated tokens, box floats and mask
bytes.

## Export

Inference only: `train()`, `val()`, `export()` and `chat()` raise.

## 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: Falcon Perception, Technology Innovation Institute (TII)
- Upstream license: Apache-2.0
- Upstream source: https://github.com/tiiuae/Falcon-Perception
- LibreYOLO code: Apache-2.0
- Weights: Apache-2.0, distributed by their authors. LibreYOLO does not host or mirror them.
- Interpretation: Apache-2.0 is a permissive license, so the Falcon Perception code and weights can be used in commercial and closed-source products. Redistributing them means keeping the license text and TII's NOTICE, which asks public-facing work to retain it and cite the project, and the license grants a patent license. LibreYOLO vendors the inference network, preprocessing and generation loop from tiiuae/Falcon-Perception at commit c457916c9974efbacfa91f0f6ecc2c49c6543e56 under Apache-2.0 (libreyolo/models/falcon_perception/NOTICE); the adapter around it is MIT. One exception: the AnyUp feature upsampler that upstream flattened into its code, used only by the 600m segment task, is by the AnyUp authors under CC BY 4.0, which permits commercial use but requires attribution. Weights are not redistributed: they download at runtime from tiiuae/Falcon-Perception (600m, revision a3e21ada0abd533393776ffab8908a728f775509) and tiiuae/Falcon-Perception-300M (300m, detect only, revision 36993684b3ba5945b22d01e705f8ff2e048bf0b0), both declared Apache-2.0 and not gated.

Falcon Perception is Apache-2.0, code and weights, by the
[Technology Innovation Institute](https://github.com/tiiuae/Falcon-Perception).
Commercial use is allowed; TII's NOTICE asks public-facing work to retain it
and cite the project. The AnyUp feature upsampler, used only by the 600m
segment task, is by the AnyUp authors under CC BY 4.0, which permits
commercial use with attribution. LibreYOLO does not redistribute the weights.

## Citation

```bibtex
@article{bevli2026falcon,
  title   = {Falcon Perception},
  author  = {Bevli, Aviraj and Chaybouti, Sofian and Dahou, Yasser and Hacid, Hakim and Huynh, Ngoc Dung and Le Khac, Phuc H. and Narayan, Sanath and Para, Wamiq Reyaz and Singh, Ankit},
  journal = {arXiv preprint arXiv:2603.27365},
  year    = {2026},
  url     = {https://arxiv.org/abs/2603.27365}
}
```

Copied from https://github.com/tiiuae/Falcon-Perception#citation
