# EdgeCrafter
A compact vision transformer for dense prediction on edge hardware, published upstream as three sibling models: ECDet, ECPose and ECSeg. LibreYOLO loads all three as one family, with the task carried by the checkpoint.
Tasks: Detection, Pose, Instance segmentation. Install: pip install libreyolo.
Verified against LibreYOLO v1.6.0.

## Install

EdgeCrafter needs no optional extra. Everything it imports is in the base
install.

```bash
pip install libreyolo
```

Adapter fine-tuning with `lora=True` is the exception, and needs the `lora`
extra.

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

## Predict

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

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

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

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

**CLI**

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

**Pose**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# The -pose suffix in the filename selects the keypoint head, so no
# task argument is needed here.
model = LibreYOLO("LibreECs-pose.pt")
result = model(SAMPLE_IMAGE, save=True)

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

**Instance segmentation**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreECs-seg.pt")
result = model(SAMPLE_IMAGE, save=True)

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

The task comes from the filename, so a `-pose` or `-seg` checkpoint selects its
own head and takes no task argument. All three return the `Results` object every
family returns, with `result.keypoints` added for pose and
`result.masks` for segmentation. Pose covers one class, person, with the 17
COCO keypoints, and the count is fixed when the model is built. It has no box
head, so each pose box is the bounding extent of its own keypoints, and the
third keypoint channel is a constant rather than a per-point score.

`conf` and `max_det` filter the query selection; `iou` is accepted for API
parity but has no effect, because all three heads decode a set of queries with no
NMS step. See [prediction](/docs/predict) for sources, streaming and result
handling.

Detection prediction accepts rectangular `imgsz=(height, width)`; training and export retain their own shape constraints.

## Variants

Four sizes. They all run at the same input resolution, so the table separates
them by parameter count and accuracy.

| Checkpoint | Input (px) | mAP 50-95 | Params (M) |
| --- | --- | --- | --- |
| `LibreECl` | 640 | 60.1 | 32.97 |
| `LibreECm` | 640 | 58.4 | 19.43 |
| `LibreECs` | 640 | 54.3 | 9.88 |
| `LibreECx` | 640 | 61.1 | 49.94 |

COCO val2017, 500 images. Published on https://www.visionanalysis.org/

Interactive chart: https://www.visionanalysis.org/embed/scatter?highlight=ec-l%2Cec-m%2Cec-s%2Cec-x&title=EdgeCrafter%20on%20COCO&subtitle=Accuracy%20against%20latency%2C%20every%20benchmarked%20model

Upstream publishes ECDet, ECPose and ECSeg as three separate models rather than
one model with three heads. They share the ECViT backbone and the hybrid encoder
and differ only in the head, so LibreYOLO folds them into a single family and
lets the checkpoint filename carry the task. A size letter therefore means the
same backbone and encoder across all three, and predict, validate and export
take the same arguments whichever one you load.

## Train

All three tasks train through `train()`, which reads the task from the loaded
checkpoint and picks the matching trainer.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreECs.pt")
model.train(
    data="my-dataset.yaml",
    epochs=50,
    imgsz=640,
    batch=8,
    lr0=5e-4,
)
```

**CLI**

```bash
libreyolo train model=LibreECs.pt data=my-dataset.yaml epochs=50 imgsz=640 batch=8 lr0=5e-4
```

**Pose**

```python
from libreyolo import LibreYOLO

# Needs a single-class keypoint dataset whose data.yaml declares
# kpt_shape, and imgsz at the checkpoint's native size.
model = LibreYOLO("LibreECs-pose.pt")
model.train(
    data="my-pose-dataset.yaml",
    epochs=50,
    imgsz=640,
)
```

**Instance segmentation**

```python
from libreyolo import LibreYOLO

# Needs polygon labels, and imgsz at the checkpoint's native size.
model = LibreYOLO("LibreECs-seg.pt")
model.train(
    data="my-dataset.yaml",
    epochs=50,
    imgsz=640,
)
```

**LoRA**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreECs.pt")
model.train(
    data="my-dataset.yaml",
    epochs=50,
    lora=True,
)
```

What has been checked for detection and segmentation: inference parity against
upstream at 1e-5, layer by layer and per size, and that the loss and a single
training step run on synthetic input. What has not, per `train()`'s own
docstring: convergence of a full fine-tune, multi-GPU training, the
stop-augmentation best-reload step, and the Objects365 to COCO class remap. The
pose path follows DETRPose's published recipe, a Hungarian matcher over class,
keypoint L1 and OKS costs with contrastive keypoint denoising, and its
convergence has not been checked end to end either.

Left alone, the trainer runs 74 epochs at `lr0=5e-4` with mixed precision on,
following upstream's recipe: AdamW, a flat cosine schedule, EMA at 0.9999 and
ImageNet-normalized inputs. Pose and segmentation both require `imgsz` at the
checkpoint's native size, because their evaluation anchor grid is built when the
model is constructed; a different value raises before the run starts. Pose also
requires a single-class dataset whose `data.yaml` declares `kpt_shape`, with a
keypoint count matching the head.

`lora=True` applies to detection only; pose and segmentation raise a
`ValueError` on it. On Apple silicon the trainer keeps the run on the GPU and
sends one operation to CPU, the grid-sample backward inside deformable
attention, which PyTorch does not implement in Metal.

See [training](/docs/train) for datasets, augmentation, multi-GPU and loggers.

## Validate

`val()` returns a dictionary keyed by metric name, and prints per-class results
when `verbose` is left on.

**Python**

```python
from libreyolo import LibreYOLO

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

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

**CLI**

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

**Pose**

```python
from libreyolo import LibreYOLO

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

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

**Instance segmentation**

```python
from libreyolo import LibreYOLO

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

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

Pose reports keypoint OKS metrics under `metrics/keypoints_*`. Segmentation
reports masks under the plain `metrics/mAP50-95` key and repeats both views in
one pass, boxes under `(B)` and masks under `(M)`.

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Detection | yes | yes | yes | yes | yes | yes | yes |  |  |  |  | yes |
| Pose | yes | yes | yes | yes | yes | yes |  |  |  |  |  |  |
| Instance segmentation | 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`. Pose and segmentation export at a fixed 640 by 640 input rather than
dynamic shapes, and several detection targets are fixed-canvas too, including
OpenVINO, Paddle, MNN, ExecuTorch and Core AI. [Export](/docs/export) lists the
arguments every format accepts and the extras a few of them add.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreECs.pt")
model.export(format="onnx", imgsz=640)
model.export(format="tensorrt", imgsz=640, half=True)
```

**CLI**

```bash
libreyolo export model=LibreECs.pt format=onnx imgsz=640
libreyolo export model=LibreECs-pose.pt format=onnx imgsz=640
libreyolo export model=LibreECs-seg.pt format=onnx imgsz=640
```

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

print(result.boxes.xyxy)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreECs-pose.pt` | 640 | Pose | apache-2.0 |
| `LibreECm-pose.pt` | 640 | Pose | apache-2.0 |
| `LibreECl-pose.pt` | 640 | Pose | apache-2.0 |
| `LibreECx-pose.pt` | 640 | Pose | apache-2.0 |
| `LibreECs-seg.pt` | 640 | Instance segmentation | apache-2.0 |
| `LibreECm-seg.pt` | 640 | Instance segmentation | apache-2.0 |
| `LibreECl-seg.pt` | 640 | Instance segmentation | apache-2.0 |
| `LibreECx-seg.pt` | 640 | Instance segmentation | apache-2.0 |
| `LibreECs.pt` | 640 | Detection | apache-2.0 |
| `LibreECm.pt` | 640 | Detection | apache-2.0 |
| `LibreECl.pt` | 640 | Detection | apache-2.0 |
| `LibreECx.pt` | 640 | Detection | apache-2.0 |
| `LibreECl-obj2coco.pt` |  | Detection | other |
| `LibreECm-obj2coco.pt` |  | Detection | other |
| `LibreECs-obj2coco.pt` |  | Detection | other |
| `LibreECx-obj2coco.pt` |  | Detection | other |
| `LibreECl-pose-obj2coco.pt` |  | Pose | other |
| `LibreECm-pose-obj2coco.pt` |  | Pose | other |
| `LibreECs-pose-obj2coco.pt` |  | Pose | other |
| `LibreECx-pose-obj2coco.pt` |  | Pose | other |
| `LibreECm-seg-obj2coco.pt` |  | Instance segmentation | other |
| `LibreECs-seg-obj2coco.pt` |  | Instance segmentation | other |
| `LibreECl-seg-obj2coco.pt` |  | Instance segmentation | other |
| `LibreECx-seg-obj2coco.pt` |  | Instance segmentation | other |

The `obj2coco` variants cover detection, segmentation and pose. Their download is opt-in and their upstream terms restrict commercial use. Original COCO checkpoints keep their recorded Apache-2.0 grant.

## 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: EdgeCrafter, Intellindust AI Lab
- Upstream license: Apache-2.0 original COCO weights; restricted obj2coco weights
- Upstream source: https://github.com/Intellindust-AI-Lab/EdgeCrafter
- LibreYOLO code: Apache-2.0
- Weights: Apache-2.0 original COCO weights; restricted obj2coco weights, republished at https://huggingface.co/LibreYOLO
- Interpretation: Original COCO checkpoints retain their recorded Apache-2.0 grant. The obj2coco detection, segmentation and pose variants require explicit opt-in and retain non-commercial upstream terms. The library code license does not replace those weight terms.

## Citation

```bibtex
@article{liu2026edgecrafter,
  title={EdgeCrafter: Compact ViTs for Edge Dense Prediction via Task-Specialized Distillation},
  author={Liu, Longfei and Hou, Yongjie and Li, Yang and Wang, Qirui and Sha, Youyang and Yu, Yongjun and Wang, Yinzhi and Ru, Peizhe and Yu, Xuanlong and Shen, Xi},
  journal={arXiv},
  year={2026}
}
```

Copied from https://github.com/Intellindust-AI-Lab/EdgeCrafter#-citation