1
pip install libreyolo

1
git clone https://github.com/LibreYOLO/libreyolo.git
2
cd libreyolo
3
pip install -e .

1
# ONNX export and inference
2
pip install libreyolo[onnx]
3
# or: pip install onnx onnxsim onnxruntime
4
5
# RT-DETR compatibility extra (currently no extra packages)
6
pip install libreyolo[rtdetr]
7
8
# RF-DETR support
9
pip install libreyolo[rfdetr]
10
# or: pip install transformers
11
12
# TensorRT export and inference (NVIDIA GPU)
13
pip install libreyolo[tensorrt]
14
# Installs TensorRT CUDA 12 Python packages on Linux/Windows.
15
# Host driver/CUDA compatibility still matters.
16
17
# OpenVINO export and inference (Intel CPU/GPU/VPU)
18
pip install libreyolo[openvino]
19
# INT8 export also needs: pip install nncf
20
21
# NCNN export and inference
22
pip install libreyolo[ncnn]
23
# or: pip install pnnx ncnn
24
25
# ByteTrack API compatibility extra
26
pip install libreyolo[tracking]
27
# Tracking dependencies are part of the base install in v1.3.1.
28
29
# CoreML export and inference (macOS only for runtime)
30
pip install libreyolo[coreml]
31
# or: pip install coremltools
32
33
# L2CS gaze optional auto-download helper
34
pip install libreyolo[gaze]
35
36
# Promptable segmentation (LibreSAM: SAM-1, SAM-2, MobileSAM)
37
pip install libreyolo[sam]
38
39
# Open-vocabulary detection (Grounding DINO, OWLv2)
40
pip install libreyolo[openvocab]
41
42
# LibreLabel AI assist (SAM click-to-mask)
43
pip install libreyolo[label]
44
45
# Zero-shot classification (CLIP)
46
pip install libreyolo[clip]
47
48
# Install every optional LibreYOLO extra
49
pip install libreyolo[all]

1
# ONNX environment
2
uv venv .venv-onnx
3
uv pip install --python .venv-onnx/bin/python -e '.[onnx]'
4
5
# RT-DETR environment
6
uv venv .venv-rtdetr
7
uv pip install --python .venv-rtdetr/bin/python -e '.[rtdetr]'
8
9
# Repeat with .[rfdetr], .[openvino], .[ncnn], .[coreml], .[gaze], .[tracking], or .[tensorrt] as needed

1
from libreyolo import LibreYOLO, SAMPLE_IMAGE
2
3
# Use the official checkpoint name and let the factory resolve the details
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
# Run on a single image (SAMPLE_IMAGE ships with the package)
7
result = model(SAMPLE_IMAGE)
8
9
print(f"Found {len(result)} objects")
10
print(result.boxes.xyxy)   # bounding boxes (N, 4)
11
print(result.boxes.conf)   # confidence scores (N,)
12
print(result.boxes.cls)    # class IDs (N,)

1
from libreyolo import LibreYOLO, SAMPLE_IMAGE
2
3
# Same factory, same call shape - just point at an RF-DETR checkpoint
4
model = LibreYOLO("LibreRFDETRs.pt")
5
result = model(SAMPLE_IMAGE)
6
7
print(f"Found {len(result)} objects")
8
print(result.boxes.xyxy)

1
result = model(SAMPLE_IMAGE, save=True)
2
print(result.saved_path)   # e.g. runs/detect/predict/parkour.jpg

1
results = model("images/", save=True, batch=4)
2
for r in results:
3
    print(f"{r.path}: {len(r)} detections")

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")   # detection

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreRFDETRs.pt")           # detect (validated)
4
# model = LibreYOLO("LibreRFDETRs-seg.pt")     # segment (validated)
5
# model = LibreYOLO("LibreRFDETRx-pose.pt")    # pose  (research preview)
6
# model = LibreYOLO("LibreRFDETRn-obb.pt")     # obb   (research preview)

1
from libreyolo import LibreYOLO
2
3
# Default: YOLO9 detection
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
# Flagship transformer: RF-DETR
7
model = LibreYOLO("LibreRFDETRs.pt")
8
model = LibreYOLO("LibreRFDETRs-seg.pt")        # validated segmentation
9
10
# New in v1.3.0
11
model = LibreYOLO("LibreMobileNetV4s-cls.pt")   # classification (Apache, ImageNet-1k)
12
model = LibreYOLO("LibreDINOv2n.pt")            # semantic segmentation
13
model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")  # monocular depth
14
model = LibreYOLO("LibreFOMOs-point.pt")        # point localization (local weights)
15
16
# Exported deployment formats
17
model = LibreYOLO("model.onnx")                 # ONNX Runtime
18
model = LibreYOLO("model.engine")               # TensorRT
19
model = LibreYOLO("model.mlpackage")            # CoreML (macOS)
20
model = LibreYOLO("model_openvino/")            # OpenVINO (directory)
21
model = LibreYOLO("model_ncnn/")                # NCNN (directory)

1
Libre<FAMILY><size>[-<task>].pt

1
explicit task=  →  checkpoint["task"]  →  filename suffix  →  family default

1
from libreyolo import LibreYOLO
2
3
# 1. Filename suffix decides → segment
4
model = LibreYOLO("LibreRFDETRs-seg.pt")
5
6
# 2. Override regardless of filename
7
model = LibreYOLO("custom_weights.pt", task="segment")
8
9
# 3. Detection is implicit
10
model = LibreYOLO("LibreYOLO9c.pt")  # task="detect"

1
# Detection (implicit)
2
LibreYOLO9c.pt
3
LibreRFDETRs.pt
4
LibreRTDETRr50.pt
5
6
# Instance segmentation (-seg)
7
LibreRFDETRs-seg.pt
8
LibreECm-seg.pt
9
10
# Semantic segmentation (-sem)
11
LibreDINOv2n.pt          # semantic is DINOv2's default; -sem optional
12
13
# Pose (-pose)
14
LibreYOLONASn-pose.pt
15
LibreECs-pose.pt
16
LibreRFDETRx-pose.pt     # preview; size x only
17
18
# Oriented boxes (-obb)
19
LibreRFDETRn-obb.pt      # preview
20
21
# Classification (-cls)
22
LibreMobileNetV4s-cls.pt
23
LibreConvNeXtt-cls.pt
24
LibreEfficientNetV2b0-cls.pt
25
LibreDINOv2n-cls.pt      # DINOv2 linear probe
26
27
# Depth (-depth)
28
LibreDepthAnythingV2s-depth.pt
29
30
# Point (-point)
31
LibreFOMOs-point.pt
32
33
# Gaze (-gaze optional; only task for L2CS)
34
LibreL2CSr50.pt

1
result = model("image.jpg")

1
result = model(
2
    "image.jpg",
3
    conf=0.25,            # confidence threshold (default: 0.25)
4
    iou=0.45,             # NMS IoU threshold (default: 0.45)
5
    imgsz=640,            # input size override (default: model's native)
6
    device="auto",        # "auto", "cpu", "mps", "0", "cuda:0", ...
7
    classes=[0, 2, 5],    # filter to specific class IDs (default: all)
8
    max_det=300,          # max detections per image (default: 300)
9
    augment=False,        # test-time augmentation where implemented
10
    save=True,            # save annotated image (default: False)
11
    batch=4,              # directory batch size
12
    stream=False,         # video only: yield frame results instead of a list
13
    vid_stride=1,         # video only: process every N-th frame
14
    show=False,           # video only: display annotated frames
15
    tiling=False,         # large-image tiled detection
16
    overlap_ratio=0.2,    # tile overlap ratio
17
    output_path="out/",   # where to save (default: runs/detect/predict*/)
18
    color_format="auto",  # "auto", "rgb", or "bgr"
19
    output_file_format="png",  # output format: "jpg", "png", "webp"
20
)

1
# File path (string or pathlib.Path)
2
result = model("photo.jpg")
3
result = model(Path("photo.jpg"))
4
5
# URL
6
result = model("https://example.com/image.jpg")
7
result = model("s3://bucket/image.jpg")
8
result = model("gs://bucket/image.jpg")
9
10
# PIL Image
11
from PIL import Image
12
img = Image.open("photo.jpg")
13
result = model(img)
14
15
# NumPy array (HWC or CHW, RGB or BGR, uint8 or float32)
16
import numpy as np
17
arr = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
18
result = model(arr)
19
20
# OpenCV (BGR) - specify color_format
21
import cv2
22
frame = cv2.imread("photo.jpg")
23
result = model(frame, color_format="bgr")
24
25
# PyTorch tensor (CHW or NCHW)
26
import torch
27
tensor = torch.randn(3, 640, 640)
28
result = model(tensor)
29
30
# Raw bytes
31
with open("photo.jpg", "rb") as f:
32
    result = model(f.read())
33
34
# BytesIO
35
from io import BytesIO
36
result = model(BytesIO(open("photo.jpg", "rb").read()))
37
38
# Directory of images
39
results = model("images/", batch=4)

1
result = model("image.jpg")
2
3
# Number of detections
4
len(result)  # e.g., 5
5
6
# Bounding boxes in xyxy format (x1, y1, x2, y2)
7
result.boxes.xyxy        # tensor of shape (N, 4)
8
9
# Bounding boxes in xywh format (center_x, center_y, width, height)
10
result.boxes.xywh        # tensor of shape (N, 4)
11
12
# Confidence scores
13
result.boxes.conf        # tensor of shape (N,)
14
15
# Class IDs
16
result.boxes.cls         # tensor of shape (N,)
17
18
# Combined data: [x1, y1, x2, y2, conf, cls]
19
# Tracking adds a track_id column before conf/cls.
20
result.boxes.data        # shape (N, 6), or (N, 7) when tracked
21
22
# Metadata
23
result.orig_shape        # (height, width) of original image
24
result.path              # source file path (or None)
25
result.names             # {0: "person", 1: "bicycle", ...}
26
27
# Move to CPU / convert to numpy
28
result_cpu = result.cpu()
29
boxes_np = result.boxes.numpy()

1
# Only detect people (class 0) and cars (class 2)
2
result = model("image.jpg", classes=[0, 2])

1
import numpy as np
2
from libreyolo import LibreYOLO
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
frames = [
7
    np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8),
8
    np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8),
9
    np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8),
10
]
11
12
results = model(frames, batch=4)   # list/tuple -> true batched inference
13
for r in results:
14
    print(len(r), r.boxes.xyxy.shape)

1
meta = model.info(detailed=False, verbose=True)
2
# meta -> {"family": ..., "size": ..., "task": ..., "params": ..., "imgsz": ..., "names": {...}, ...}

1
result = model(
2
    "large_aerial_image.jpg",
3
    tiling=True,
4
    overlap_ratio=0.2,   # 20% overlap between tiles (default)
5
    save=True,
6
)
7
8
# Extra metadata on tiled results
9
result.tiled           # True
10
result.num_tiles       # number of tiles used
11
result.saved_path      # output directory when save=True
12
result.tiles_path      # directory containing per-tile crops
13
result.grid_path       # grid visualization image

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
results = model("clip.mp4", save=True)
5
# Saved under runs/detect/predict*/clip.mp4

1
for result in model("long_clip.mp4", stream=True):
2
    print(f"frame {result.frame_idx}: {len(result)} detections")

1
# Process every 2nd frame (halves compute and saved fps)
2
results = model("clip.mp4", vid_stride=2, save=True)

1
# Display annotated frames in an OpenCV window while processing
2
results = model("clip.mp4", show=True)

1
from libreyolo import LibreYOLO
2
from libreyolo.utils.video import VideoSource, VideoWriter
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
6
with VideoSource("clip.mp4", vid_stride=1) as src, \
7
     VideoWriter("out.mp4", fps=src.fps, width=src.width, height=src.height) as out:
8
    for frame_bgr, frame_idx in src:
9
        result = model(frame_bgr, color_format="bgr")
10
        # ... draw, transform, etc.
11
        out.write_frame(frame_bgr)

1
pip install libreyolo[tracking]   # compatibility extra; tracking deps ship in base dev install

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
5
for result in model.track(
6
    "clip.mp4",
7
    track_conf=0.25,
8
    iou=0.45,
9
    save=True,             # writes runs/track/<video_stem>.mp4 by default
10
    vid_stride=1,
11
):
12
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreYOLO, ByteTracker
2
from libreyolo.utils.video import VideoSource
3
4
model = LibreYOLO("LibreYOLO9c.pt")
5
tracker = ByteTracker()
6
7
with VideoSource("clip.mp4") as src:
8
    for frame_bgr, frame_idx in src:
9
        result = model(frame_bgr, color_format="bgr", conf=0.1)
10
        tracked = tracker.update(result)
11
12
        for i in range(len(tracked.boxes)):
13
            track_id = int(tracked.boxes.id[i])
14
            xyxy = tracked.boxes.xyxy[i].tolist()
15
            cls = int(tracked.boxes.cls[i])
16
            print(f"frame {frame_idx} - id {track_id} cls {cls} {xyxy}")

1
from libreyolo import ByteTracker, TrackConfig
2
3
cfg = TrackConfig(
4
    track_high_thresh=0.25,           # first-stage match threshold
5
    track_low_thresh=0.1,             # second-stage (low-conf recovery)
6
    new_track_thresh=0.25,            # minimum conf to start a new track
7
    match_thresh=0.8,                 # IoU cost cutoff (stage 1)
8
    match_thresh_low=0.5,             # IoU cost cutoff (stage 2)
9
    match_thresh_unconfirmed=0.7,     # IoU cost cutoff for unconfirmed tracks
10
    track_buffer=30,                  # frames to keep lost tracks before removal
11
    frame_rate=30,                    # scales track_buffer
12
    fuse_score=True,                  # multiply IoU by detection score
13
    minimum_consecutive_frames=1,     # frames to confirm a new track
14
)
15
tracker = ByteTracker(config=cfg)

1
tracker.reset()   # clears tracked / lost / removed lists and the ID counter

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9c.pt")
4
5
for result in model.track(
6
    "clip.mp4",
7
    tracker="ocsort",      # "bytetrack" (default) or "ocsort"
8
    track_conf=0.25,       # maps to OC-SORT det_thresh
9
    iou=0.45,
10
    save=True,
11
):
12
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreYOLO, OCSortConfig
2
3
cfg = OCSortConfig(
4
    det_thresh=0.25,     # boxes above this drive association and spawn new tracks
5
    max_age=30,          # frames a track survives without an observation
6
    min_hits=3,          # consecutive hits before a track is reported
7
    iou_threshold=0.3,   # minimum IoU for a valid association
8
    delta_t=3,           # frame span used to estimate velocity direction
9
    inertia=0.2,         # weight of the velocity-direction (momentum) term
10
    use_byte=False,      # enable the BYTE low-score recovery pass
11
)
12
13
model = LibreYOLO("LibreYOLO9c.pt")
14
for result in model.track("clip.mp4", tracker_config=cfg, save=True):
15
    print(result.frame_idx, result.track_id)

1
from libreyolo import LibreEnsemble
2
3
# 加权框融合（WBF，默认），只保留两个模型都找到的框
4
ens = LibreEnsemble(["LibreYOLO9s.pt", "LibreRFDETRs.pt"], min_votes=2)
5
6
result = ens("image.jpg", conf=0.25)
7
print(result.boxes.xyxy)
8
print(result.names)     # 统一后的（并集）类别表

1
ens = LibreEnsemble(
2
    ["LibreYOLO9s.pt", "LibreRFDETRs.pt"],
3
    weights=[1.0, 1.4],     # 让融合结果更偏向第二个成员
4
    fusion="wbf",           # "wbf" | "wbf_seeded" | "nms" | 自定义可调用对象
5
    fusion_iou=0.55,        # 用于聚类的 IoU，不是成员的 NMS
6
    min_votes=1,
7
)
8
9
result = ens("image.jpg", conf=[0.25, 0.4])   # 每个成员单独的置信度阈值

1
from libreyolo import LibreYOLO
2
3
# RF-DETR segmentation, the heavily tested segmentation path
4
model = LibreYOLO("LibreRFDETRs-seg.pt")
5
result = model("photo.jpg")
6
7
# EdgeCrafter segmentation is also available but experimental
8
# model = LibreYOLO("LibreECs-seg.pt")
9
10
# Segmentation returns boxes + masks
11
print(result.boxes.xyxy)        # bounding boxes (N, 4)
12
print(result.boxes.cls)         # class IDs (N,)
13
print(result.masks.data.shape)  # (N, H, W) tensor of binary masks

1
# Raw bitmasks
2
result.masks.data        # tensor (N, H, W) - original image resolution
3
4
# Polygon contours (one ndarray of (M, 2) per instance)
5
result.masks.xy          # absolute pixel coords
6
result.masks.xyn         # normalized to [0, 1]
7
8
# Move / convert like Boxes
9
result.masks.cpu()
10
result.masks.numpy()

1
model("photo.jpg", save=True)

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibrePIDNets-sem.pt")   # Cityscapes，19 类
4
result = model.predict("street.jpg")
5
6
sm = result.semantic_mask     # SemanticMask
7
print(sm.data.shape)          # (H, W) 整数类别 id，位于原图尺寸上
8
print(sm.classes)             # 出现过的类别 id，已排除 255（忽略）
9
car = sm.class_mask(13)       # (H, W) 布尔掩码
10
11
result.plot().save("out.png")
12
print(result.boxes, result.masks)   # None None：语义分割没有实例

1
metrics = model.val(data="cityscapes.yaml")
2
print(metrics["metrics/mIoU"])
3
print(metrics["metrics/pixel_accuracy"])

1
dataset/
2
    images/train/*.jpg
3
    masks/train/*.png      # 与图像同名；像素值 = 类别 id

1
from libreyolo import LibreDINOv2
2
3
model = LibreDINOv2(model_path=None, size="s", task="semantic", nb_classes=19)
4
model.train(data="cityscapes.yaml", epochs=100, batch_size=4, lr=1e-4)

1
from libreyolo import LibreSAM
2
3
model = LibreSAM("base")
4
5
# 一次点击
6
r = model.predict("img.jpg", points=[640, 360], labels=[1])
7
print(r.masks.data.shape)   # (1, H, W) 布尔掩码，原图分辨率
8
print(r.boxes.conf)         # SAM 预测的掩码质量，不是检测置信度
9
10
# 框提示
11
r = model.predict("img.jpg", bboxes=[100, 100, 500, 500])

1
model.set_image("img.jpg")                        # 重量级编码器只运行一次
2
a = model.predict(points=[500, 375], labels=[1])  # 廉价：只跑解码器
3
b = model.predict(bboxes=[100, 100, 200, 200])    # 廉价：复用图像嵌入
4
model.reset_image()

1
from libreyolo import LibreOpenVocab
2
3
model = LibreOpenVocab("grounding-dino")
4
model.set_classes(["person", "dog", "skateboard"])   # 持久词表
5
6
result = model.predict("street.jpg", conf=0.25, text_threshold=0.25)
7
print(result.names)     # {0: 'person', 1: 'dog', 2: 'skateboard'}
8
9
result = model.predict("another.jpg")   # 词表仍然有效

1
from libreyolo import LibreYOLO
2
3
# YOLO-NAS pose
4
model = LibreYOLO("LibreYOLONASs-pose.pt")
5
result = model("people.jpg")
6
7
# EdgeCrafter pose
8
# model = LibreYOLO("LibreECs-pose.pt")
9
10
# Per-person bbox + 17 keypoints
11
print(result.boxes.xyxy)          # person boxes (N, 4)
12
print(result.keypoints.xy.shape)  # (N, 17, 2) pixel coordinates

1
# RF-DETR pose preview (size x only)
2
model = LibreYOLO("LibreRFDETRx-pose.pt")
3
result = model("people.jpg")
4
print(result.keypoints.xy.shape)  # (N, 17, 2)

1
result.keypoints.xy        # (N, K, 2) absolute pixel coords
2
result.keypoints.xyn       # (N, K, 2) normalized to [0, 1]
3
result.keypoints.conf      # (N, K) per-keypoint confidence (None if model doesn't emit it)
4
result.keypoints.has_visible  # (N, K) bool - conf > 0
5
6
result.keypoints.cpu()
7
result.keypoints.numpy()

1
model("people.jpg", save=True)  # draws boxes + skeleton

1
pip install libreyolo[gaze]   # optional Google Drive helper for Gaze360 weights

1
from libreyolo import LibreYOLO
2
from libreyolo.models.l2cs.face import resolve_face_detector
3
4
# Gaze head
5
gaze = LibreYOLO("LibreL2CSr50.pt")
6
7
# Wire any LibreYOLO detector trained on faces
8
face = LibreYOLO("path/to/face-detector.pt")
9
gaze.face_detector = resolve_face_detector(face)
10
11
result = gaze("portrait.jpg")
12
print(result.boxes.xyxy)    # face boxes
13
print(result.gaze.data)     # (N, 2) tensor - pitch, yaw in radians