Link to this sectionUtilitários Simples#

YOLO model code with 3D perspective visualization

O pacote ultralytics fornece uma variedade de utilitários para apoiar, aprimorar e acelerar seus fluxos de trabalho. Embora existam muitos outros disponíveis, este guia destaca alguns dos mais úteis para desenvolvedores, servindo como uma referência prática para programação com ferramentas Ultralytics.

Watch: Ultralytics Utilities | Auto Annotation, Explorer API and Dataset Conversion

Link to this sectionDados#

Link to this sectionAuto-rotulagem / Anotações#

A anotação de dataset é um processo que consome muitos recursos e tempo. Se você possui um modelo Ultralytics YOLO de detecção de objetos treinado com uma quantidade razoável de dados, você pode usá-lo com o SAM para auto-anotar dados adicionais no formato de segmentação.

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

Esta função não retorna nenhum valor. Para mais detalhes:

Veja a seção de referência para annotator.auto_annotate para mais informações sobre como a função opera.
Use em combinação com a função segments2boxes para gerar também caixas delimitadoras de detecção de objetos.

Link to this sectionVisualizar Anotações de Dataset#

Esta função visualiza as anotações YOLO em uma imagem antes do treinamento, ajudando a identificar e corrigir quaisquer anotações incorretas que poderiam levar a resultados de detecção errados. Ela desenha caixas delimitadoras, rotula objetos com nomes de classes e ajusta a cor do texto com base na luminosidade do fundo para melhor legibilidade.

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

Link to this sectionConverter Máscaras de Segmentação para Formato YOLO#

Máscaras de Segmentação para Formato YOLO

Use isto para converter um dataset de imagens de máscara de segmentação para o formato de segmentação Ultralytics YOLO. Esta função recebe o diretório contendo as imagens de máscara em formato binário e as converte para o formato de segmentação YOLO.

As máscaras convertidas serão salvas no diretório de saída especificado.

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)

Link to this sectionConverter COCO para Formato YOLO#

Use isto para converter anotações JSON do COCO para o formato YOLO. Para datasets de detecção de objetos (caixa delimitadora), defina use_segments e use_keypoints como False.

from ultralytics.data.converter import convert_coco

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

Para informações adicionais sobre a função convert_coco, visite a página de referência.

Link to this sectionObter Dimensões da Caixa Delimitadora#

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

Link to this sectionConverter Caixas Delimitadoras para Segmentos#

Com dados de caixas delimitadoras x y w h existentes, converta para segmentos usando a função yolo_bbox2segment. Organize os arquivos de imagens e anotações da seguinte forma:

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

Visite a página de referência do yolo_bbox2segment para mais informações sobre a função.

Link to this sectionConverter Segmentos para Caixas Delimitadoras#

Se você tem um dataset que usa o formato de dataset de segmentação, você pode converter facilmente estes para caixas delimitadoras verticais (ou horizontais) (formato x y w h) com esta função.

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

Para entender como esta função funciona, visite a página de referência.

Link to this sectionUtilitários#

Link to this sectionCompressão de Imagem#

Comprima um único arquivo de imagem para um tamanho reduzido, preservando sua proporção e qualidade. Se a imagem de entrada for menor que a dimensão máxima, ela não será redimensionada.

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)

Link to this sectionAuto-divisão de Dataset#

Divida automaticamente um dataset em train/val/test e salve as divisões resultantes em arquivos autosplit_*.txt. Esta função usa amostragem aleatória, que é excluída ao usar o argumento fraction para treinamento.

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
)

Veja a página de Referência para detalhes adicionais sobre esta função.

Link to this sectionSegmento-polígono para Máscara Binária#

Converta um único polígono (como uma lista) para uma máscara binária do tamanho de imagem especificado. O polígono deve ser um array 1D plano de N coordenadas listando valores x, y alternados que definem o contorno do polígono.

Aviso

N deve ser sempre par.

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

Link to this sectionCaixas Delimitadoras#

Link to this sectionInstâncias de Caixa Delimitadora (Horizontal)#

Para gerenciar dados de caixas delimitadoras, a classe Bboxes ajuda a converter entre formatos de coordenadas de caixa, escalar dimensões de caixa, calcular áreas, incluir offsets e muito mais.

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

Veja a seção de referência do Bboxes para mais atributos e métodos.

Dica

Muitas das seguintes funções (e mais) podem ser acessadas usando a classe Bboxes, mas se você preferir trabalhar diretamente com as funções, veja as subseções seguintes para saber como importá-las de forma independente.

Link to this sectionEscalando Caixas#

Ao aumentar ou diminuir uma imagem, você pode ajustar adequadamente as coordenadas da caixa delimitadora correspondente usando 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]]
# )

Link to this sectionConversões de Formato de Caixa Delimitadora#

Link to this sectionXYXY → XYWH#

Converta coordenadas de caixa delimitadora do formato (x1, y1, x2, y2) para o formato (x, y, largura, altura), onde (x1, y1) é o canto superior esquerdo e (x2, y2) é o canto inferior direito.

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

Link to this sectionTodas as Conversões de Caixa Delimitadora#

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

See the docstring for each function or visit the ultralytics.utils.ops reference page to read more.

Link to this sectionPlotagem#

Link to this sectionUtilitários de anotação#

O Ultralytics inclui uma classe Annotator para anotar vários tipos de dados. É melhor utilizada com caixas delimitadoras de detecção de objetos, keypoints de pose e caixas delimitadoras orientadas.

Link to this sectionAnotação de Caixa#

Exemplos em Python usando Ultralytics YOLO 🚀

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

Nomes podem ser usados a partir de model.names ao trabalhar com resultados de detecção. Também veja a Página de Referência do Annotator para informações adicionais.

Link to this sectionAnotação de Varredura Ultralytics#

Anotação de Varredura usando Utilitários 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="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()

Encontre detalhes adicionais sobre o método sweep_annotator em nossa seção de referência aqui.

Link to this sectionAnotação de rótulo adaptativo#

Aviso

A partir do Ultralytics v8.3.167, circle_label e text_label foram substituídos por uma função adaptive_label unificada. Agora você pode especificar o tipo de anotação usando o argumento shape:

Retângulo: annotator.adaptive_label(box, label=names[int(cls)], color=colors(cls, True), shape="rect")
Círculo: 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 🚀

Anotação de rótulo adaptativo usando Utilitários Ultralytics

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

Veja a Página de Referência do SolutionAnnotator para informações adicionais.

Link to this sectionDiversos#

Link to this sectionPerfilamento de Código#

Verifique a duração para que o código seja executado/processado usando with ou como um decorador.

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"

Link to this sectionFormatos Suportados pelo Ultralytics#

Precisa usar programaticamente os formatos de imagem ou vídeo suportados no Ultralytics? Use estas constantes se necessário:

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'}

Link to this sectionTornar Divisível#

Calcule o menor número inteiro maior ou igual a x que seja divisível por y.

from ultralytics.utils.ops import make_divisible

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

Link to this sectionFAQ#

Link to this sectionQuais utilitários estão incluídos no pacote Ultralytics para aprimorar os fluxos de trabalho de aprendizado de máquina?#

O pacote Ultralytics inclui utilitários projetados para simplificar e otimizar fluxos de trabalho de aprendizado de máquina. Os principais utilitários incluem auto-anotação para rotular datasets, conversão de COCO para formato YOLO com convert_coco, compressão de imagens e auto-divisão de dataset. Essas ferramentas reduzem o esforço manual, garantem consistência e aprimoram a eficiência do processamento de dados.

Link to this sectionComo posso usar o Ultralytics para auto-rotular meu dataset?#

Se você possui um modelo de detecção de objetos Ultralytics YOLO pré-treinado, você pode usá-lo com o modelo SAM para auto-anotar seu dataset no formato de segmentação. Aqui está um exemplo:

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

Para mais detalhes, verifique a seção de referência do auto_annotate, ou use a Plataforma Ultralytics como uma alternativa hospedada e sem código com mascaramento baseado em cliques via SAM 2.1 ou SAM 3, ou previsões de modelos YOLO pré-treinados e ajustados para tarefas de detecção, segmentação e OBB.

Link to this sectionComo converto anotações de dataset COCO para o formato YOLO no Ultralytics?#

Para converter anotações JSON do COCO para o formato YOLO para detecção de objetos, você pode usar o utilitário convert_coco. Aqui está um exemplo de trecho de código:

from ultralytics.data.converter import convert_coco

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

Para informações adicionais, visite a página de referência do convert_coco.

Link to this sectionComo posso analisar a composição e distribuição do meu dataset?#

A Plataforma Ultralytics fornece análises automáticas de dataset: a aba Charts mostra a distribuição de divisão, contagens de classes principais, histogramas de dimensões de imagem e mapas de calor 2D das posições de anotação, ajudando você a identificar desequilíbrios e valores atípicos antes do treinamento.

Link to this sectionComo posso converter caixas delimitadoras para segmentos no Ultralytics?#

Para converter dados de caixas delimitadoras existentes (no formato x y w h) para segmentos, você pode usar a função yolo_bbox2segment. Certifique-se de que seus arquivos estejam organizados com diretórios separados para imagens e rótulos.

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

Para mais informações, visite a página de referência do yolo_bbox2segment.

Contribuidores

GLglenn-jocher²¹ RIRizwanMunawar¹⁶ RAraimbekovm⁴ AMambitious-octopus² LALaughing-q² BUBurhan-Q² PDpderrenger¹ MGmgcrea¹ LEleonnil¹ IVIvorZhu331¹

Criado 20 de fev. de 2024Atualizado anteontem