> This is the documentation for LibreYOLO 1.5.0. Current version: https://www.libreyolo.com/docs/models/pidnet

# PIDNet
A three-branch semantic segmentation network that adds a dedicated boundary branch to a proportional-integral-derivative-inspired design, aimed at real-time inference. LibreYOLO ships it for semantic segmentation only.
Tasks: semantic. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

PIDNet 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. The
`-sem` filename suffix is required for this family.

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibrePIDNets-sem.pt")
result = model(SAMPLE_IMAGE, save=True)

mask = result.semantic_mask
print(mask.data.shape)   # (H, W) class ids
print(mask.classes)      # sorted class ids present in the image
```

**CLI**

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

Semantic segmentation returns one class id per pixel, not boxes, so
`result.semantic_mask` carries a `(H, W)` array on `.data` and the list of
class ids present in the image on `.classes`. `conf`, `iou` and `max_det` are
accepted for API parity but have no effect: the model assigns a class to every
pixel by argmax, with no confidence threshold or NMS step. See
[prediction](/docs/v1.5.0/predict) for sources, streaming and result handling.

## Variants

Three sizes, all at a fixed 1024 px input. The published checkpoints are
conversions of the official PIDNet Cityscapes weights, 19 classes.

LibreYOLO does not train PIDNet: `train()` raises `NotImplementedError` for
this family, which the [support tier](/docs/v1.5.0/models) above marks as inference
only.

## Validate

`val()` returns `metrics/mIoU` and `metrics/pixel_accuracy`, measured against
any dataset in the format you trained on.

**Python**

```python
from libreyolo import LibreYOLO

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

print(metrics["metrics/mIoU"])
print(metrics["metrics/pixel_accuracy"])
```

**CLI**

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

## Export

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

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

An exported artifact loads back through `LibreYOLO()` on its file suffix, so a
`.onnx` or `.engine` file behaves like a checkpoint and returns the same
`Results`. [Export](/docs/v1.5.0/export) lists the arguments every format accepts.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibrePIDNets-sem.pt")
model.export(format="onnx")
model.export(format="tensorrt", half=True)
```

**CLI**

```bash
libreyolo export model=LibrePIDNets-sem.pt format=onnx
libreyolo export model=LibrePIDNets-sem.pt format=tensorrt half=True
```

**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("LibrePIDNets-sem.onnx")
result = model(SAMPLE_IMAGE)

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

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibrePIDNets-sem.pt` | 1024 | semantic | mit |
| `LibrePIDNetm-sem.pt` | 1024 | semantic | mit |
| `LibrePIDNetl-sem.pt` | 1024 | semantic | mit |

## 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: PIDNet, Jiacong Xu
- Upstream license: MIT
- Upstream source: https://github.com/XuJiacong/PIDNet
- LibreYOLO code: MIT
- Weights: MIT, republished at https://huggingface.co/LibreYOLO
- Interpretation: MIT is a permissive license, so this code and these weights can be used in commercial and closed-source products. It asks only that you keep the copyright and license notice with any copy you redistribute. LibreYOLO's checkpoints are conversions of the official PIDNet Cityscapes weights, which upstream licenses as MIT. The Cityscapes dataset itself carries separate research-oriented terms and is not redistributed by LibreYOLO.

## Citation

```bibtex
@misc{xu2022pidnet,
      title={PIDNet: A Real-time Semantic Segmentation Network Inspired from PID Controller}, 
      author={Jiacong Xu and Zixiang Xiong and Shankar P. Bhattacharyya},
      year={2022},
      eprint={2206.02066},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}
```

Copied from https://github.com/XuJiacong/PIDNet#bibtex-citation


## PIDNet architecture

- s: [SVG](/diagrams/models/pidnet/s-semantic.svg), [interactive diagram](/diagrams/models/pidnet/s-semantic.html)
- m: [SVG](/diagrams/models/pidnet/m-semantic.svg), [interactive diagram](/diagrams/models/pidnet/m-semantic.html)
- l: [SVG](/diagrams/models/pidnet/l-semantic.svg), [interactive diagram](/diagrams/models/pidnet/l-semantic.html)
- Shared S/M topology: [SVG](/diagrams/models/pidnet/sm-family.svg), [interactive diagram](/diagrams/models/pidnet/sm-family.html)