Einfache Dienstprogramme
Das ultralytics Paket bietet eine Vielzahl von Dienstprogrammen zur Unterstützung, Verbesserung und Beschleunigung deiner Arbeitsabläufe. Obwohl noch viele weitere verfügbar sind, hebt dieser Leitfaden einige der nützlichsten für Entwickler hervor und dient als praktische Referenz für die Programmierung mit Ultralytics-Tools.
Watch: Ultralytics Utilities | Auto Annotation, Explorer API and Dataset Conversion
Daten
Automatische Etikettierung / Annotationen
Dataset-Annotation ist ein ressourcenintensiver und zeitaufwändiger Prozess. Wenn du ein trainiertes Ultralytics YOLO Objekterkennungsmodell mit einer angemessenen Datenmenge hast, kannst du es mit SAM verwenden, um zusätzliche Daten automatisch im Segmentierungsformat zu annotieren.
from ultralytics.data.annotator import auto_annotate
auto_annotate(
data="path/to/new/data",
det_model="yolo26n.pt",
sam_model="mobile_sam.pt",
device="cuda",
output_dir="path/to/save_labels",
)Diese Funktion gibt keinen Wert zurück. Weitere Details findest du hier:
- Siehe den Referenzabschnitt für
annotator.auto_annotatefür weitere Einblicke in die Funktionsweise dieser Funktion. - Verwende sie in Kombination mit der Funktion
segments2boxes, um auch Begrenzungsrahmen für die Objekterkennung zu generieren.
Datensatz-Annotationen visualisieren
Diese Funktion visualisiert YOLO-Annotationen auf einem Bild vor dem Training und hilft dabei, falsche Annotationen zu identifizieren und zu korrigieren, die zu fehlerhaften Erkennungsergebnissen führen könnten. Sie zeichnet Begrenzungsrahmen, beschriftet Objekte mit Klassennamen und passt die Textfarbe basierend auf der Helligkeit des Hintergrunds an, um die Lesbarkeit zu verbessern.
from ultralytics.data.utils import visualize_image_annotations
label_map = { # Define the label map with all annotated class labels.
0: "person",
1: "car",
}
# Visualize
visualize_image_annotations(
"path/to/image.jpg", # Input image path.
"path/to/annotations.txt", # Annotation file path for the image.
label_map,
)Segmentierungsmasken in das YOLO-Format konvertieren

Verwende dies, um einen Datensatz von Segmentierungsmaskenbildern in das Ultralytics YOLO Segmentierungsformat zu konvertieren. Diese Funktion nimmt das Verzeichnis mit den Maskenbildern im Binärformat entgegen und konvertiert sie in das YOLO-Segmentierungsformat.
Die konvertierten Masken werden im angegebenen Ausgabeordner gespeichert.
from ultralytics.data.converter import convert_segment_masks_to_yolo_seg
# The classes here is the total classes in the dataset.
# for COCO dataset we have 80 classes.
convert_segment_masks_to_yolo_seg(masks_dir="path/to/masks_dir", output_dir="path/to/output_dir", classes=80)COCO in das YOLO-Format konvertieren
Verwende dies, um COCO JSON-Annotationen in das YOLO-Format zu konvertieren. Für Datensätze zur Objekterkennung (Begrenzungsrahmen) setze sowohl use_segments als auch use_keypoints auf False.
from ultralytics.data.converter import convert_coco
convert_coco(
"coco/annotations/",
use_segments=False,
use_keypoints=False,
cls91to80=True,
)Für weitere Informationen über die convert_coco-Funktion besuche die Referenzseite.
Begrenzungsrahmen-Abmessungen abrufen
import cv2
from ultralytics import YOLO
from ultralytics.utils.plotting import Annotator
model = YOLO("yolo26n.pt") # Load pretrain or fine-tune model
# Process the image
source = cv2.imread("path/to/image.jpg")
results = model(source)
# Extract results
annotator = Annotator(source, example=model.names)
for box in results[0].boxes.xyxy.cpu():
width, height, area = annotator.get_bbox_dimension(box)
print(f"Bounding Box Width {width.item()}, Height {height.item()}, Area {area.item()}")Begrenzungsrahmen in Segmente konvertieren
Mit vorhandenen x y w h Begrenzungsrahmendaten kannst du mit der Funktion yolo_bbox2segment in Segmente konvertieren. Organisiere die Dateien für Bilder und Annotationen wie folgt:
data
|__ images
├─ 001.jpg
├─ 002.jpg
├─ ..
└─ NNN.jpg
|__ labels
├─ 001.txt
├─ 002.txt
├─ ..
└─ NNN.txtfrom ultralytics.data.converter import yolo_bbox2segment
yolo_bbox2segment(
im_dir="path/to/images",
save_dir=None, # saved to "labels-segment" in images directory
sam_model="sam_b.pt",
)Besuche die Referenzseite zu yolo_bbox2segment für weitere Informationen zu dieser Funktion.
Segmente in Begrenzungsrahmen konvertieren
Wenn du einen Datensatz hast, der das Segmentierungs-Datensatzformat verwendet, kannst du diese mit dieser Funktion einfach in aufrechte (oder horizontale) Begrenzungsrahmen (x y w h Format) konvertieren.
import numpy as np
from ultralytics.utils.ops import segments2boxes
segments = np.array(
[
[805, 392, 797, 400, ..., 808, 714, 808, 392],
[115, 398, 113, 400, ..., 150, 400, 149, 298],
[267, 412, 265, 413, ..., 300, 413, 299, 412],
]
)
segments2boxes([s.reshape(-1, 2) for s in segments])
# >>> array([[ 741.66, 631.12, 133.31, 479.25],
# [ 146.81, 649.69, 185.62, 502.88],
# [ 281.81, 636.19, 118.12, 448.88]],
# dtype=float32) # xywh bounding boxesUm zu verstehen, wie diese Funktion funktioniert, besuche die Referenzseite.
Dienstprogramme
Bildkomprimierung
Komprimiere eine einzelne Bilddatei auf eine reduzierte Größe, während das Seitenverhältnis und die Qualität erhalten bleiben. Wenn das Eingabebild kleiner als die maximale Dimension ist, wird es nicht in der Größe verändert.
from pathlib import Path
from ultralytics.data.utils import compress_one_image
for f in Path("path/to/dataset").rglob("*.jpg"):
compress_one_image(f)Datensatz automatisch aufteilen
Teile einen Datensatz automatisch in train-/val-/test-Splits auf und speichere die resultierenden Splits in autosplit_*.txt-Dateien. Diese Funktion verwendet Zufallsstichproben, die ausgeschlossen sind, wenn du das fraction-Argument für das Training verwendest.
from ultralytics.data.split import autosplit
autosplit(
path="path/to/images",
weights=(0.9, 0.1, 0.0), # (train, validation, test) fractional splits
annotated_only=False, # split only images with annotation file when True
)Siehe die Referenzseite für weitere Details zu dieser Funktion.
Segment-Polygon in Binärmaske
Konvertiere ein einzelnes Polygon (als Liste) in eine Binärmaske der angegebenen Bildgröße. Das Polygon sollte in der Form [N, 2] vorliegen, wobei N die Anzahl der (x, y)-Punkte ist, die die Polygonkontur definieren.
N muss immer gerade sein.
import numpy as np
from ultralytics.data.utils import polygon2mask
imgsz = (1080, 810)
polygon = np.array([805, 392, 797, 400, ..., 808, 714, 808, 392]) # (238, 2)
mask = polygon2mask(
imgsz, # tuple
[polygon], # input as list
color=255, # 8-bit binary
downsample_ratio=1,
)Begrenzungsrahmen
Begrenzungsrahmen (horizontal) Instanzen
Um Begrenzungsrahmendaten zu verwalten, hilft die Klasse Bboxes dabei, zwischen Box-Koordinatenformaten zu konvertieren, Box-Dimensionen zu skalieren, Flächen zu berechnen, Offsets einzubeziehen und mehr.
import numpy as np
from ultralytics.utils.instance import Bboxes
boxes = Bboxes(
bboxes=np.array(
[
[22.878, 231.27, 804.98, 756.83],
[48.552, 398.56, 245.35, 902.71],
[669.47, 392.19, 809.72, 877.04],
[221.52, 405.8, 344.98, 857.54],
[0, 550.53, 63.01, 873.44],
[0.0584, 254.46, 32.561, 324.87],
]
),
format="xyxy",
)
boxes.areas()
# >>> array([ 4.1104e+05, 99216, 68000, 55772, 20347, 2288.5])
boxes.convert("xywh")
print(boxes.bboxes)
# >>> array(
# [[ 413.93, 494.05, 782.1, 525.56],
# [ 146.95, 650.63, 196.8, 504.15],
# [ 739.6, 634.62, 140.25, 484.85],
# [ 283.25, 631.67, 123.46, 451.74],
# [ 31.505, 711.99, 63.01, 322.91],
# [ 16.31, 289.67, 32.503, 70.41]]
# )Siehe den Referenzabschnitt zu Bboxes für weitere Attribute und Methoden.
Viele der folgenden Funktionen (und mehr) können über die Klasse Bboxes aufgerufen werden, aber wenn du lieber direkt mit den Funktionen arbeitest, siehe die nächsten Unterabschnitte, wie man sie unabhängig importiert.
Boxen skalieren
Beim Vergrößern oder Verkleinern eines Bildes kannst du die entsprechenden Begrenzungsrahmenkoordinaten mit ultralytics.utils.ops.scale_boxes entsprechend skalieren.
import cv2 as cv
import numpy as np
from ultralytics.utils.ops import scale_boxes
image = cv.imread("ultralytics/assets/bus.jpg")
h, w, c = image.shape
resized = cv.resize(image, None, (), fx=1.2, fy=1.2)
new_h, new_w, _ = resized.shape
xyxy_boxes = np.array(
[
[22.878, 231.27, 804.98, 756.83],
[48.552, 398.56, 245.35, 902.71],
[669.47, 392.19, 809.72, 877.04],
[221.52, 405.8, 344.98, 857.54],
[0, 550.53, 63.01, 873.44],
[0.0584, 254.46, 32.561, 324.87],
]
)
new_boxes = scale_boxes(
img1_shape=(h, w), # original image dimensions
boxes=xyxy_boxes, # boxes from original image
img0_shape=(new_h, new_w), # resized image dimensions (scale to)
ratio_pad=None,
padding=False,
xywh=False,
)
print(new_boxes)
# >>> array(
# [[ 27.454, 277.52, 965.98, 908.2],
# [ 58.262, 478.27, 294.42, 1083.3],
# [ 803.36, 470.63, 971.66, 1052.4],
# [ 265.82, 486.96, 413.98, 1029],
# [ 0, 660.64, 75.612, 1048.1],
# [ 0.0701, 305.35, 39.073, 389.84]]
# )Konvertierungen von Begrenzungsrahmenformaten
XYXY → XYWH
Konvertiere Begrenzungsrahmenkoordinaten vom (x1, y1, x2, y2) Format in das (x, y, Breite, Höhe) Format, wobei (x1, y1) die obere linke Ecke und (x2, y2) die untere rechte Ecke ist.
import numpy as np
from ultralytics.utils.ops import xyxy2xywh
xyxy_boxes = np.array(
[
[22.878, 231.27, 804.98, 756.83],
[48.552, 398.56, 245.35, 902.71],
[669.47, 392.19, 809.72, 877.04],
[221.52, 405.8, 344.98, 857.54],
[0, 550.53, 63.01, 873.44],
[0.0584, 254.46, 32.561, 324.87],
]
)
xywh = xyxy2xywh(xyxy_boxes)
print(xywh)
# >>> array(
# [[ 413.93, 494.05, 782.1, 525.56],
# [ 146.95, 650.63, 196.8, 504.15],
# [ 739.6, 634.62, 140.25, 484.85],
# [ 283.25, 631.67, 123.46, 451.74],
# [ 31.505, 711.99, 63.01, 322.91],
# [ 16.31, 289.67, 32.503, 70.41]]
# )Alle Begrenzungsrahmen-Konvertierungen
from ultralytics.utils.ops import (
ltwh2xywh,
ltwh2xyxy,
xywh2ltwh, # xywh → top-left corner, w, h
xywh2xyxy,
xywhn2xyxy, # normalized → pixel
xyxy2ltwh, # xyxy → top-left corner, w, h
xyxy2xywhn, # pixel → normalized
)
for func in (ltwh2xywh, ltwh2xyxy, xywh2ltwh, xywh2xyxy, xywhn2xyxy, xyxy2ltwh, xyxy2xywhn):
print(help(func)) # print function docstringsSee the docstring for each function or visit the ultralytics.utils.ops reference page to read more.
Plotten
Annotierungs-Dienstprogramme
Ultralytics enthält eine Annotator-Klasse für die Annotation verschiedener Datentypen. Sie ist am besten geeignet für Objekterkennungs-Begrenzungsrahmen, Pose-Keypoints und orientierte Begrenzungsrahmen.
Box-Annotation
import cv2 as cv
import numpy as np
from ultralytics.utils.plotting import Annotator, colors
names = {
0: "person",
5: "bus",
11: "stop sign",
}
image = cv.imread("ultralytics/assets/bus.jpg")
ann = Annotator(
image,
line_width=None, # default auto-size
font_size=None, # default auto-size
font="Arial.ttf", # must be ImageFont compatible
pil=False, # use PIL, otherwise uses OpenCV
)
xyxy_boxes = np.array(
[
[5, 22.878, 231.27, 804.98, 756.83], # class-idx x1 y1 x2 y2
[0, 48.552, 398.56, 245.35, 902.71],
[0, 669.47, 392.19, 809.72, 877.04],
[0, 221.52, 405.8, 344.98, 857.54],
[0, 0, 550.53, 63.01, 873.44],
[11, 0.0584, 254.46, 32.561, 324.87],
]
)
for nb, box in enumerate(xyxy_boxes):
c_idx, *box = box
label = f"{str(nb).zfill(2)}:{names.get(int(c_idx))}"
ann.box_label(box, label, color=colors(c_idx, bgr=True))
image_with_bboxes = ann.result()Namen können aus model.names verwendet werden, wenn du mit Erkennungsergebnissen arbeitest. Siehe auch die Annotator-Referenzseite für weitere Einblicke.
Ultralytics Sweep-Annotation
import cv2
import numpy as np
from ultralytics import YOLO
from ultralytics.solutions.solutions import SolutionAnnotator
from ultralytics.utils.plotting import colors
# User defined video path and model file
cap = cv2.VideoCapture("path/to/video.mp4")
model = YOLO(model="yolo26s-seg.pt") # Model file, e.g., yolo26s.pt or yolo26m-seg.pt
if not cap.isOpened():
print("Error: Could not open video.")
exit()
# Initialize the video writer object.
w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))
video_writer = cv2.VideoWriter("ultralytics.avi", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
masks = None # Initialize variable to store masks data
f = 0 # Initialize frame count variable for enabling mouse event.
line_x = w # Store width of line.
dragging = False # Initialize bool variable for line dragging.
classes = model.names # Store model classes names for plotting.
window_name = "Ultralytics Sweep Annotator"
def drag_line(event, x, _, flags, param):
"""Mouse callback function to enable dragging a vertical sweep line across the video frame."""
global line_x, dragging
if event == cv2.EVENT_LBUTTONDOWN or (flags & cv2.EVENT_FLAG_LBUTTON):
line_x = max(0, min(x, w))
dragging = True
while cap.isOpened(): # Loop over the video capture object.
ret, im0 = cap.read()
if not ret:
break
f = f + 1 # Increment frame count.
count = 0 # Re-initialize count variable on every frame for precise counts.
results = model.track(im0, persist=True)[0]
if f == 1:
cv2.namedWindow(window_name)
cv2.setMouseCallback(window_name, drag_line)
annotator = SolutionAnnotator(im0)
if results.boxes.is_track:
if results.masks is not None:
masks = [np.array(m, dtype=np.int32) for m in results.masks.xy]
boxes = results.boxes.xyxy.tolist()
track_ids = results.boxes.id.int().cpu().tolist()
clss = results.boxes.cls.cpu().tolist()
for mask, box, cls, t_id in zip(masks or [None] * len(boxes), boxes, clss, track_ids):
color = colors(t_id, True) # Assign different color to each tracked object.
label = f"{classes[cls]}:{t_id}"
if mask is not None and mask.size > 0:
if box[0] > line_x:
count += 1
cv2.polylines(im0, [mask], True, color, 2)
x, y = mask.min(axis=0)
(w_m, _), _ = cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1)
cv2.rectangle(im0, (x, y - 20), (x + w_m, y), color, -1)
cv2.putText(im0, label, (x, y - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
else:
if box[0] > line_x:
count += 1
annotator.box_label(box=box, color=color, label=label)
# Generate draggable sweep line
annotator.sweep_annotator(line_x=line_x, line_y=h, label=f"COUNT:{count}")
cv2.imshow(window_name, im0)
video_writer.write(im0)
if cv2.waitKey(1) & 0xFF == ord("q"):
break
# Release the resources
cap.release()
video_writer.release()
cv2.destroyAllWindows()Weitere Details zur sweep_annotator-Methode findest du in unserem Referenzabschnitt hier.
Adaptive Label-Annotation
Ab Ultralytics v8.3.167 wurden circle_label und text_label durch eine einheitliche adaptive_label-Funktion ersetzt. Du kannst nun den Annotierungstyp mit dem shape-Argument angeben:
- Rechteck:
annotator.adaptive_label(box, label=names[int(cls)], color=colors(cls, True), shape="rect") - Kreis:
annotator.adaptive_label(box, label=names[int(cls)], color=colors(cls, True), shape="circle")
Watch: In-Depth Guide to Text & Circle Annotations with Python Live Demos | Ultralytics Annotations 🚀
import cv2
from ultralytics import YOLO
from ultralytics.solutions.solutions import SolutionAnnotator
from ultralytics.utils.plotting import colors
model = YOLO("yolo26s.pt")
names = model.names
cap = cv2.VideoCapture("path/to/video.mp4")
w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))
writer = cv2.VideoWriter("Ultralytics circle annotation.avi", cv2.VideoWriter_fourcc(*"MJPG"), fps, (w, h))
while True:
ret, im0 = cap.read()
if not ret:
break
annotator = SolutionAnnotator(im0)
results = model.predict(im0)[0]
boxes = results.boxes.xyxy.cpu()
clss = results.boxes.cls.cpu().tolist()
for box, cls in zip(boxes, clss):
annotator.adaptive_label(box, label=names[int(cls)], color=colors(cls, True), shape="circle")
writer.write(im0)
cv2.imshow("Ultralytics circle annotation", im0)
if cv2.waitKey(1) & 0xFF == ord("q"):
break
writer.release()
cap.release()
cv2.destroyAllWindows()Siehe die SolutionAnnotator-Referenzseite für weitere Einblicke.
Verschiedenes
Code-Profiling
Überprüfe die Dauer der Code-Ausführung/Verarbeitung, entweder mit with oder als Decorator.
from ultralytics.utils.ops import Profile
with Profile(device="cuda:0") as dt:
pass # operation to measure
print(dt)
# >>> "Elapsed time is 9.5367431640625e-07 s"Von Ultralytics unterstützte Formate
Musst du die unterstützten Bild- oder Videoformate in Ultralytics programmgesteuert verwenden? Verwende bei Bedarf diese Konstanten:
from ultralytics.data.utils import IMG_FORMATS, VID_FORMATS
print(IMG_FORMATS)
# {'avif', 'bmp', 'dng', 'heic', 'heif', 'jp2', 'jpeg', 'jpeg2000', 'jpg', 'mpo', 'png', 'tif', 'tiff', 'webp'}
print(VID_FORMATS)
# {'asf', 'avi', 'gif', 'm4v', 'mkv', 'mov', 'mp4', 'mpeg', 'mpg', 'ts', 'wmv', 'webm'}Teilbar machen
Berechne die nächste ganze Zahl zu x, die ohne Rest durch y teilbar ist.
from ultralytics.utils.ops import make_divisible
make_divisible(7, 3)
# >>> 9
make_divisible(7, 2)
# >>> 8FAQ
Welche Dienstprogramme sind im Ultralytics-Paket enthalten, um Machine-Learning-Workflows zu verbessern?
Das Ultralytics-Paket enthält Dienstprogramme, die darauf ausgelegt sind, Machine-Learning-Workflows zu rationalisieren und zu optimieren. Wichtige Dienstprogramme sind Auto-Annotation für die Etikettierung von Datensätzen, das Konvertieren von COCO in das YOLO-Format mit convert_coco, das Komprimieren von Bildern und die automatische Datensatz-Aufteilung. Diese Tools reduzieren den manuellen Aufwand, stellen Konsistenz sicher und verbessern die Effizienz der Datenverarbeitung.
Wie kann ich Ultralytics verwenden, um meinen Datensatz automatisch zu annotieren?
Wenn du ein vortrainiertes Ultralytics YOLO-Objekterkennungsmodell hast, kannst du es mit dem SAM-Modell verwenden, um deinen Datensatz automatisch im Segmentierungsformat zu annotieren. Hier ist ein Beispiel:
from ultralytics.data.annotator import auto_annotate
auto_annotate(
data="path/to/new/data",
det_model="yolo26n.pt",
sam_model="mobile_sam.pt",
device="cuda",
output_dir="path/to/save_labels",
)Weitere Details findest du im auto_annotate-Referenzabschnitt oder nutze die Ultralytics Platform als gehostete No-Code-Alternative mit klickbasierter Maskierung via SAM 2.1 oder SAM 3 oder Vorhersagen von vortrainierten und feinabgestimmten YOLO-Modellen für Detect-, Segment- und OBB-Aufgaben.
Wie konvertiere ich COCO-Datensatz-Annotationen in das YOLO-Format in Ultralytics?
Um COCO JSON-Annotationen für die Objekterkennung in das YOLO-Format zu konvertieren, kannst du das convert_coco-Dienstprogramm verwenden. Hier ist ein Beispiel-Code-Snippet:
from ultralytics.data.converter import convert_coco
convert_coco(
"coco/annotations/",
use_segments=False,
use_keypoints=False,
cls91to80=True,
)Für weitere Informationen besuche die convert_coco-Referenzseite.
Wie kann ich die Zusammensetzung und Verteilung meines Datensatzes analysieren?
Ultralytics Platform bietet automatische Datensatz-Analysen: Der Charts-Tab zeigt die Split-Verteilung, die Anzahl der Top-Klassen, Histogramme der Bilddimensionen und 2D-Heatmaps der Annotationspositionen, was dir hilft, Ungleichgewichte und Ausreißer vor dem Training zu erkennen.
Wie kann ich Begrenzungsrahmen in Segmente in Ultralytics konvertieren?
Um vorhandene Begrenzungsrahmendaten (im x y w h Format) in Segmente zu konvertieren, kannst du die Funktion yolo_bbox2segment verwenden. Stelle sicher, dass deine Dateien mit separaten Verzeichnissen für Bilder und Labels organisiert sind.
from ultralytics.data.converter import yolo_bbox2segment
yolo_bbox2segment(
im_dir="path/to/images",
save_dir=None, # saved to "labels-segment" in the images directory
sam_model="sam_b.pt",
)Für weitere Informationen besuche die yolo_bbox2segment-Referenzseite.