Einfache Hilfsprogramme#
Das Paket ultralytics bietet eine Vielzahl von Hilfsprogrammen 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-Werkzeugen.
Watch: Ultralytics Utilities | Auto Annotation, Explorer API and Dataset Conversion
Daten#
Automatische Etikettierung / Annotationen#
Die Dataset annotation ist ein ressourcenintensiver und zeitaufwändiger Prozess. Wenn du ein trainiertes Ultralytics YOLO object detection-Modell mit einer angemessenen Datenmenge hast, kannst du es zusammen 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:
- Weitere Einblicke in die Funktionsweise der Funktion findest du im Referenzabschnitt für
annotator.auto_annotate. - Verwende sie in Kombination mit der Funktion
segments2boxes, um auch Bounding-Boxes für die Objekterkennung zu generieren.
Dataset-Annotationen visualisieren#
Diese Funktion visualisiert YOLO-Annotationen auf einem Bild vor dem Training, was dabei hilft, fehlerhafte Annotationen zu identifizieren und zu korrigieren, die zu falschen Erkennungsergebnissen führen könnten. Sie zeichnet Begrenzungsrahmen, beschriftet Objekte mit Klassennamen und passt die Textfarbe basierend auf der Luminanz des Hintergrunds für eine bessere Lesbarkeit an.
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 Segmentierungsmasken-Bildern 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 Ausgabeverzeichnis 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. Setze für Datensätze zur Objekterkennung (Bounding-Box) 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,
)Weitere Informationen zur Funktion convert_coco findest du auf der Referenzseite.
Bounding-Box-Dimensionen 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()}")Bounding Boxes in Segmente konvertieren#
Konvertiere vorhandene Bounding-Box-Daten von x y w h mithilfe der Funktion yolo_bbox2segment in Segmente. 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 bezüglich der Funktion.
Segmente in Bounding Boxes konvertieren#
Wenn du einen Datensatz hast, der das Segmentierungsdatensatzformat verwendet, kannst du diesen mit dieser Funktion ganz einfach in aufrechte (oder horizontale) Bounding-Boxes (x y w h-Format) konvertieren.
import numpy as np
from ultralytics.utils.ops import segments2boxes
segments = np.array(
[
[805, 392, 797, 400, 812, 402, 808, 714, 808, 392],
[115, 398, 113, 400, 150, 410, 150, 400, 149, 298],
[267, 412, 265, 413, 300, 420, 300, 413, 299, 412],
],
dtype=np.float32,
)
segments2boxes([s.reshape(-1, 2) for s in segments])
# >>> array([[804.5, 553. , 15. , 322. ],
# [131.5, 354. , 37. , 112. ],
# [282.5, 416. , 35. , 8. ]],
# dtype=float32) # xywh bounding boxesUm zu verstehen, wie diese Funktion funktioniert, besuche die Referenzseite.
Hilfsprogramme#
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)Dataset automatisch aufteilen#
Teile einen Datensatz automatisch in train/val/test-Splits auf und speichere die resultierenden Splits in autosplit_*.txt-Dateien. Dieses Hilfsprogramm erstellt persistente Split-Dateien; das fraction-Trainingsargument wählt stattdessen eine reproduzierbare Teilmenge für einen Durchlauf aus.
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
)Weitere Details zu dieser Funktion findest du auf der Referenzseite.
Segment-Polygon zu binärer Maske#
Konvertiere ein einzelnes Polygon (als Liste) in eine binäre Maske der angegebenen Bildgröße. Das Polygon sollte ein flaches 1D-Array von N-Koordinaten sein, das abwechselnde x, y-Werte auflistet, 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,
)Bounding Boxes#
Bounding Box (horizontal) Instanzen#
Zur Verwaltung von Bounding-Box-Daten hilft die Klasse Bboxes dabei, zwischen Box-Koordinatenformaten zu konvertieren, Box-Dimensionen zu skalieren, Flächen zu berechnen, Offsets einzubeziehen und vieles 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]]
# )Weitere Attribute und Methoden findest du im Referenzabschnitt zu Bboxes.
Auf viele der folgenden (und weitere) Funktionen kann über die Bboxes-Klasse zugegriffen werden. Wenn du jedoch lieber direkt mit den Funktionen arbeiten möchtest, erfährst du in den nächsten Unterabschnitten, wie du sie unabhängig importieren kannst.
Boxen skalieren#
Wenn du ein Bild vergrößerst oder verkleinerst, kannst du die entsprechenden Bounding-Box-Koordinaten mithilfe von ultralytics.utils.ops.scale_boxes entsprechend anpassen.
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]]
# )Bounding-Box-Formatkonvertierungen#
XYXY → XYWH#
Konvertiere Bounding-Box-Koordinaten 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 Bounding-Box-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 docstringsLies den Docstring jeder Funktion oder besuche die Referenzseite für ultralytics.utils.ops, um mehr zu erfahren.
Plotten#
Annotation-Hilfsprogramme#
Ultralytics enthält eine Annotator-Klasse zur Annotation verschiedener Datentypen. Sie wird am besten mit Bounding-Boxes für die Objekterkennung, Pose-Keypoints und orientierten Bounding-Boxes verwendet.
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 von model.names verwendet werden, wenn mit Erkennungsergebnissen gearbeitet wird.
Siehe auch die Annotator-Referenzseite für weitere Einblicke.
Ultralytics Sweep-Annotation#
import sys
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.")
sys.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 Methode sweep_annotator findest du hier in unserem Referenzabschnitt.
Adaptive Label-Annotation#
Ab Ultralytics v8.3.167 wurden circle_label und text_label durch eine einheitliche adaptive_label-Funktion ersetzt. Du kannst den Annotationstyp nun über das Argument shape 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()Weitere Einblicke findest du auf der SolutionAnnotator-Referenzseite.
Verschiedenes#
Code-Profiling#
Überprüfe die Ausführungs- oder Verarbeitungszeit von Code 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#
Möchtest 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', '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 kleinste ganze Zahl größer oder gleich 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#
Das Ultralytics-Paket enthält Hilfsprogramme zur Rationalisierung und Optimierung von Machine-Learning-Arbeitsabläufen. Zu den wichtigsten Hilfsprogrammen gehören die auto-annotation zum Beschriften von Datensätzen, das Konvertieren von COCO in das YOLO-Format mit convert_coco, das Komprimieren von Bildern und die automatische Datensatzaufteilung. Diese Werkzeuge reduzieren den manuellen Aufwand, gewährleisten Konsistenz und verbessern die Effizienz der Datenverarbeitung.
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 Referenzabschnitt zu auto_annotate, oder nutze die Ultralytics Platform als gehostete No-Code-Alternative mit klickbasiertem Maskieren über SAM 2.1 oder SAM 3 bzw. Vorhersagen von vortrainierten und feinabgestimmten YOLO-Modellen für Detect-, Segment- und OBB-Aufgaben.
Um COCO-JSON-Annotationen für die Objekterkennung in das YOLO-Format zu konvertieren, kannst du das Hilfsprogramm
convert_cocoverwenden. Hier ist ein Beispiel-Codeausschnitt:from ultralytics.data.converter import convert_coco convert_coco( "coco/annotations/", use_segments=False, use_keypoints=False, cls91to80=True, )Weitere Informationen findest du auf der Referenzseite zu convert_coco.
Die Ultralytics Platform bietet automatische Datensatzanalysen: Die Registerkarte
Chartszeigt die Split-Verteilung, die Anzahl der Top-Klassen, Histogramme der Bildabmessungen und 2D-Heatmaps der Annotationspositionen, damit du Ungleichgewichte und Ausreißer vor dem Training erkennen kannst.Um bestehende Bounding-Box-Daten (im
x y w h-Format) in Segmente zu konvertieren, kannst du die Funktionyolo_bbox2segmentverwenden. 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", )Weitere Informationen findest du auf der Referenzseite zu yolo_bbox2segment.