Utilità semplici

Il ultralytics package fornisce una varietà di utility per supportare, migliorare e accelerare i tuoi flussi di lavoro. Sebbene ce ne siano molti altri disponibili, questa guida evidenzia alcuni dei più utili per gli sviluppatori, fungendo da riferimento pratico per la programmazione con gli strumenti Ultralytics.

Guarda: Utility Ultralytics | Auto Annotazione, API Explorer e Conversione del Dataset

Dati

Etichettatura automatica / Annotazioni

L'annotazione del dataset è un processo dispendioso in termini di risorse e tempo. Se hai un modello di rilevamento oggetti Ultralytics YOLO addestrato su una quantità ragionevole di dati, puoi usarlo con SAM per annotare automaticamente dati aggiuntivi in formato di segmentazione.

from ultralytics.data.annotator import auto_annotate

auto_annotate(
    data="path/to/new/data",
    det_model="yolo11n.pt",
    sam_model="mobile_sam.pt",
    device="cuda",
    output_dir="path/to/save_labels",
)

Questa funzione non restituisce alcun valore. Per maggiori dettagli:

• Vedere il file sezione di riferimento per annotator.auto_annotate per maggiori informazioni su come funziona la funzione.
• Usare in combinazione con la funzione segments2boxes anche per generare bounding box di rilevamento oggetti.

Visualizza le annotazioni del set di dati

Questa funzione visualizza le annotazioni YOLO su un'immagine prima del training, aiutando a identificare e correggere eventuali annotazioni errate che potrebbero portare a risultati di rilevamento non corretti. Disegna riquadri di delimitazione, etichetta gli oggetti con i nomi delle classi e regola il colore del testo in base alla luminanza dello sfondo per una migliore leggibilità.

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,
)

Converti le maschere di segmentazione in formato YOLO

Utilizza questo per convertire un dataset di immagini di maschere di segmentazione nel formato di segmentazione Ultralytics YOLO. Questa funzione prende la directory contenente le immagini di maschere in formato binario e le converte nel formato di segmentazione YOLO.

Le maschere convertite verranno salvate nella directory di output specificata.

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)

Converti COCO in formato YOLO

Utilizza questo per convertire COCO annotazioni JSON nel formato YOLO. Per i dataset di object detection (bounding box), imposta entrambi use_segments e use_keypoints a False.

from ultralytics.data.converter import convert_coco

convert_coco(
    "coco/annotations/",
    use_segments=False,
    use_keypoints=False,
    cls91to80=True,
)

Per ulteriori informazioni sulla convert_coco funzione, visita la pagina di riferimento.

Ottieni le dimensioni della Bounding Box

import cv2

from ultralytics import YOLO
from ultralytics.utils.plotting import Annotator

model = YOLO("yolo11n.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()}")

Converti le Bounding Box in segmenti

Con i dati esistenti dei x y w h bounding box, convertili in segmenti usando la yolo_bbox2segment funzione. Organizza i file per immagini e annotazioni come segue:

data
|__ images
    ├─ 001.jpg
    ├─ 002.jpg
    ├─ ..
    └─ NNN.jpg
|__ labels
    ├─ 001.txt
    ├─ 002.txt
    ├─ ..
    └─ NNN.txt

from 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",
)

Visita la pagina di yolo_bbox2segment riferimento per maggiori informazioni sulla funzione.

Converti i segmenti in Bounding Box

Se hai un set di dati che utilizza il formato del set di dati di segmentazione, è possibile convertirli facilmente in bounding box verticali (o orizzontali) (x y w h formato) con questa funzione.

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 boxes

Per capire come funziona questa funzione, visita la pagina di riferimento.

Utilità

Compressione immagini

Comprimi un singolo file immagine a una dimensione ridotta preservandone le proporzioni e la qualità. Se l'immagine di input è più piccola della dimensione massima, non verrà ridimensionata.

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)

Suddivisione automatica del dataset

Divide automaticamente un set di dati in train/val/test split e salva gli split risultanti in autosplit_*.txt files. Questa funzione utilizza il campionamento casuale, che viene escluso quando si utilizza il fraction per l'addestramento.

from ultralytics.data.utils 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
)

Consulta la pagina di riferimento per ulteriori dettagli su questa funzione.

Da segmento-poligono a maschera binaria

Converte un singolo poligono (come elenco) in una maschera binaria della dimensione dell'immagine specificata. Il poligono dovrebbe essere nella forma di [N, 2], dove N è il numero di (x, y) punti che definiscono il contorno del poligono.

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 Box

Istanze di Bounding Box (Orizzontale)

Per gestire i dati dei bounding box, il Bboxes classe aiuta a convertire tra formati di coordinate delle box, a scalare le dimensioni delle box, a calcolare le aree, a includere gli offset e altro ancora.

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]]
# )

Vedere il file Bboxes sezione di riferimento per ulteriori attributi e metodi.

Ridimensionamento delle Box

Quando si ridimensiona un'immagine verso l'alto o verso il basso, è possibile scalare adeguatamente le coordinate corrispondenti del riquadro di delimitazione in modo che corrispondano utilizzando ultralytics.utils.ops.scale_boxes.

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]]
# )

Conversioni del formato Bounding Box

XYXY → XYWH

Converte le coordinate del riquadro di delimitazione dal formato (x1, y1, x2, y2) al formato (x, y, larghezza, altezza), dove (x1, y1) è l'angolo in alto a sinistra e (x2, y2) è l'angolo in basso a destra.

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]]
# )

Tutte le conversioni di Bounding Box

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 docstrings

Consulta la docstring per ogni funzione oppure visita la ultralytics.utils.ops riferimento per saperne di più.

Plotting

Utilità di annotazione

Ultralytics include un Annotator classe per annotare vari tipi di dati. È preferibile utilizzarla con riquadri di delimitazione del rilevamento oggetti, punti chiave della posa, e bounding box orientati.

Annotazione del riquadro

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()

import cv2 as cv
import numpy as np

from ultralytics.utils.plotting import Annotator, colors

obb_names = {10: "small vehicle"}
obb_image = cv.imread("datasets/dota8/images/train/P1142__1024__0___824.jpg")
obb_boxes = np.array(
    [
        [0, 635, 560, 919, 719, 1087, 420, 803, 261],  # class-idx x1 y1 x2 y2 x3 y2 x4 y4
        [0, 331, 19, 493, 260, 776, 70, 613, -171],
        [9, 869, 161, 886, 147, 851, 101, 833, 115],
    ]
)
ann = Annotator(
    obb_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
)
for obb in obb_boxes:
    c_idx, *obb = obb
    obb = np.array(obb).reshape(-1, 4, 2).squeeze()
    label = f"{obb_names.get(int(c_idx))}"
    ann.box_label(
        obb,
        label,
        color=colors(c_idx, True),
    )

image_with_obb = ann.result()

I nomi possono essere utilizzati da model.names quando si lavora con i risultati del rilevamento. Si veda anche Annotator Pagina di riferimento per ulteriori approfondimenti.

Annotazione Sweep di Ultralytics

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="yolo11s-seg.pt")  # Model file i.e. yolo11s.pt or yolo11m-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()

Trova ulteriori dettagli sul sweep_annotator metodo nella nostra sezione di riferimento qui.

Annotazione adattiva delle etichette

Guarda: Guida approfondita alle annotazioni di testo e cerchi con demo live in Python | Annotazioni Ultralytics 🚀

import cv2

from ultralytics import YOLO
from ultralytics.solutions.solutions import SolutionAnnotator
from ultralytics.utils.plotting import colors

model = YOLO("yolo11s.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()

import cv2

from ultralytics import YOLO
from ultralytics.solutions.solutions import SolutionAnnotator
from ultralytics.utils.plotting import colors

model = YOLO("yolo11s.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 text 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="rect")

    writer.write(im0)
    cv2.imshow("Ultralytics text annotation", im0)

    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

writer.release()
cap.release()
cv2.destroyAllWindows()

Vedere il file SolutionAnnotator Pagina di riferimento per ulteriori approfondimenti.

Varie

Profilazione del codice

Verifica la durata dell'esecuzione/elaborazione del codice utilizzando with o come decoratore.

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"

Formati supportati da Ultralytics

Hai bisogno di utilizzare programmaticamente i formati di immagine o video supportati in Ultralytics? Utilizza queste costanti se necessario:

from ultralytics.data.utils import IMG_FORMATS, VID_FORMATS

print(IMG_FORMATS)
# {'tiff', 'pfm', 'bmp', 'mpo', 'dng', 'jpeg', 'png', 'webp', 'tif', 'jpg'}

print(VID_FORMATS)
# {'avi', 'mpg', 'wmv', 'mpeg', 'm4v', 'mov', 'mp4', 'asf', 'mkv', 'ts', 'gif', 'webm'}

Make Divisible

Calcola il numero intero più vicino a x che sia divisibile per y.

from ultralytics.utils.ops import make_divisible

make_divisible(7, 3)
# >>> 9
make_divisible(7, 2)
# >>> 8

FAQ

Quali utility sono incluse nel pacchetto Ultralytics per migliorare i flussi di lavoro di machine learning?

Il pacchetto Ultralytics include utility progettate per semplificare e ottimizzare i flussi di lavoro di machine learning. Le utility principali includono la auto-annotazione per l'etichettatura dei dataset, la conversione da COCO a formato YOLO con convert_coco, la compressione delle immagini e la suddivisione automatica dei dataset. Questi strumenti riducono lo sforzo manuale, garantiscono la coerenza e migliorano l'efficienza dell'elaborazione dei dati.

Come posso usare Ultralytics per etichettare automaticamente il mio set di dati?

Se si dispone di un modello di rilevamento oggetti Ultralytics YOLO pre-addestrato, è possibile utilizzarlo con il modello SAM per annotare automaticamente il set di dati in formato di segmentazione. Ecco un esempio:

from ultralytics.data.annotator import auto_annotate

auto_annotate(
    data="path/to/new/data",
    det_model="yolo11n.pt",
    sam_model="mobile_sam.pt",
    device="cuda",
    output_dir="path/to/save_labels",
)

Per maggiori dettagli, consultare la sezione di riferimento auto_annotate.

Come posso convertire le annotazioni del set di dati COCO in formato YOLO in Ultralytics?

Per convertire le annotazioni COCO JSON in formato YOLO per il rilevamento di oggetti, è possibile utilizzare l'utility convert_coco . Ecco un esempio di codice:

from ultralytics.data.converter import convert_coco

convert_coco(
    "coco/annotations/",
    use_segments=False,
    use_keypoints=False,
    cls91to80=True,
)

Per ulteriori informazioni, visitare la pagina di riferimento convert_coco.

Qual è lo scopo di YOLO Data Explorer nel pacchetto Ultralytics?

Il YOLO Explorer è un potente strumento introdotto nell'aggiornamento 8.1.0 per migliorare la comprensione del set di dati. Consente di utilizzare query di testo per trovare istanze di oggetti nel set di dati, semplificandone l'analisi e la gestione. Questo strumento fornisce preziose informazioni sulla composizione e la distribuzione del set di dati, contribuendo a migliorare l'addestramento e le prestazioni del modello.

Come posso convertire i bounding box in segmenti in Ultralytics?

Per convertire i dati esistenti dei riquadri di delimitazione (nel formato x y w h ) in segmenti, è possibile utilizzare la funzione yolo_bbox2segment . Assicurarsi che i file siano organizzati con directory separate per immagini ed etichette.

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",
)

Per ulteriori informazioni, visitare la pagina di riferimento yolo_bbox2segment.

📅 Creato 1 anno fa ✏️ Aggiornato 1 mese fa

Commenti