# HRNet
HRNet is a convolutional network that keeps a high-resolution feature stream through repeated multi-scale fusion, instead of recovering resolution after downsampling. LibreYOLO wraps the official top-down pose variant for inference and validation.
Tasks: Pose. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

HRNet needs no extra beyond the base package.

```bash
pip install libreyolo
```

Its default person detector, a lightweight LibreYOLO9t checkpoint, downloads
automatically the first time HRNet pairs with it.

## Predict

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

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# No person source given: HRNet pairs itself with a lightweight
# LibreYOLO9t detector automatically and logs that choice once.
model = LibreYOLO("LibreHRNetw32-pose.pt")
result = model(SAMPLE_IMAGE, save=True)

print(result.keypoints.xy)
print(result.boxes.xyxy)
```

**CLI**

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

**Person source**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreHRNetw32-pose.pt")

# Skip detection entirely: treat the whole image as one person.
result = model(SAMPLE_IMAGE, cropped=True)

# Or hand HRNet boxes from a detector you already ran.
result = model(SAMPLE_IMAGE, person_boxes=[[34, 12, 220, 400]])

# Or pair it with a specific LibreYOLO detector instead of the
# LibreYOLO9t default.
result = model(SAMPLE_IMAGE, person_detector="rfdetr")
```

HRNet is a top-down pose estimator: it needs a person box before the pose head
can run, so every call resolves one. Left alone, it pairs itself with a
LibreYOLO9t detector the first time and logs that choice. `cropped=True` skips
detection and treats the whole image as one person; `person_boxes` accepts
boxes from a detector you already ran; `person_detector` accepts `"auto"`,
`"rfdetr"`, any LibreYOLO detection model, or a plain callable. `flip_test=True`
runs the model on the horizontally flipped crop as well and averages the two
heatmaps, HRNet's own test-time augmentation; the generic `augment=True` is not
defined here. Multi-image sources run sequentially: HRNet's detector and
variable per-image person count do not support stacked prediction. See
[prediction](/docs/predict) for sources, streaming and result handling.

## Variants

Two sizes, `w32` and `w48`, both predicting the standard COCO-17 keypoint set
from a fixed-resolution person crop; `w48` is the wider of the two backbones.

The upstream model zoo reports pose accuracy for each size with its own person
detector, its own flip-testing setup, and the official COCO evaluation
protocol. LibreYOLO's default pairing uses a different detector, so a
validation run here measures that combination, not the upstream one; matching
the upstream figures needs the same person boxes, detector scores, and flip
setting the original evaluation used.

## Validate

`val()` runs COCO-style keypoint OKS-AP and accepts a YOLO-pose `data.yaml` or a
COCO keypoints JSON plus an images directory. The metrics backend is
faster-coco-eval by default, with `pycocotools` used automatically when
faster-coco-eval is not installed; `faster_coco_eval=False` forces the
`pycocotools` path.

**Python**

```python
from libreyolo import LibreYOLO

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

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

**CLI**

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

Validation drives HRNet's own `predict()` internally, so it uses whatever
person detector the model was built or called with. Construct the model with
an explicit `person_detector=` to keep that source fixed across runs, rather
than letting each call re-resolve the default.

## Export

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

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

HRNet's export contract covers ONNX, TorchScript, OpenVINO and TensorRT only;
any other format raises before the trace starts. Every export is the
fixed-canvas heatmap head alone, batch-one FP32, taking a person crop and
returning raw heatmaps: the affine crop geometry ahead of it and the heatmap
decoding, flip restoration and OKS suppression behind it stay in Python, so a
full image-in, keypoints-out pipeline still needs LibreYOLO on the other end.

**Python**

```python
from libreyolo import LibreYOLO

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

**CLI**

```bash
libreyolo export model=LibreHRNetw32-pose.pt format=onnx
```

**Use the exported file**

```python
import numpy as np
import onnxruntime as ort

# The exported graph is the fixed-canvas heatmap head alone: it takes
# a batch of already-cropped, already-normalized person crops and
# returns raw heatmaps. Person detection, crop geometry, heatmap
# decoding and OKS suppression are not part of this graph; running it
# outside LibreYOLO means reimplementing that decode step yourself.
session = ort.InferenceSession("LibreHRNetw32-pose.onnx")
name = session.get_inputs()[0].name
heatmaps = session.run(
    None, {name: np.zeros((1, 3, 256, 192), dtype=np.float32)}
)[0]
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreHRNetw32-pose.pt` |  | Pose | mit |
| `LibreHRNetw48-pose.pt` |  | Pose | 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: HRNet, Microsoft
- Upstream license: MIT
- Upstream source: https://github.com/leoxiaobin/deep-high-resolution-net.pytorch
- LibreYOLO code: MIT
- Weights: MIT, republished at https://huggingface.co/LibreYOLO
- Interpretation: MIT permits commercial and non-commercial use, modification and redistribution of both the code and the two published checkpoints, with the copyright notice retained. The official repository does not attach a separate license to its model-zoo checkpoints; LibreYOLO's redistribution basis is the MIT license the releasing project implies, the same basis the upstream repository's own files state.

## Citation

```bibtex
@inproceedings{sun2019deep,
  title={Deep High-Resolution Representation Learning for Human Pose Estimation},
  author={Sun, Ke and Xiao, Bin and Liu, Dong and Wang, Jingdong},
  booktitle={CVPR},
  year={2019}
}
```

Copied from https://github.com/leoxiaobin/deep-high-resolution-net.pytorch#citation