Basit Yardımcı Araçlar

YOLO model code with 3D perspective visualization

ultralytics paketi, iş akışlarını desteklemek, geliştirmek ve hızlandırmak için çeşitli yardımcı araçlar sunar. Çok daha fazlası mevcut olsa da, bu kılavuz geliştiriciler için en yararlı olanlardan bazılarını vurgular ve Ultralytics araçlarıyla programlama için pratik bir referans görevi görür.



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

Veri

Otomatik Etiketleme / Açıklamalar

Veri kümesi açıklaması kaynak yoğun ve zaman alıcı bir süreçtir. Makul miktarda veri üzerinde eğitilmiş bir Ultralytics YOLO nesne algılama modelin varsa, bunu SAM ile birlikte kullanarak ek verileri segmentasyon formatında otomatik olarak etiketleyebilirsin.

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

Bu fonksiyon herhangi bir değer döndürmez. Daha fazla ayrıntı için:

Veri Kümesi Açıklamalarını Görselleştir

Bu fonksiyon, eğitimden önce YOLO açıklamalarını bir görüntü üzerinde görselleştirir; böylece hatalı algılama sonuçlarına yol açabilecek yanlış açıklamaların belirlenmesine ve düzeltilmesine yardımcı olur. Sınırlayıcı kutuları çizer, nesneleri sınıf adlarıyla etiketler ve metin rengini daha iyi okunabilirlik için arka planın parlaklığına göre ayarlar.

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

Segmentasyon Maskelerini YOLO Formatına Dönüştür

Segmentasyon Maskeleri YOLO Formatına

Bunu, bir segmentasyon maskesi görüntüleri veri kümesini Ultralytics YOLO segmentasyon formatına dönüştürmek için kullan. Bu fonksiyon, ikili format maske görüntülerini içeren dizini alır ve bunları YOLO segmentasyon formatına dönüştürür.

Dönüştürülen maskeler belirtilen çıktı dizinine kaydedilecektir.

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 Formatını YOLO Formatına Dönüştür

Bunu, COCO JSON açıklamalarını YOLO formatına dönüştürmek için kullan. Nesne algılama (sınırlayıcı kutu) veri kümeleri için hem use_segments hem de use_keypoints değerlerini False olarak ayarla.

from ultralytics.data.converter import convert_coco

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

convert_coco fonksiyonu hakkında ek bilgi için referans sayfasını ziyaret et.

Sınırlayıcı Kutu Boyutlarını Al

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

Sınırlayıcı Kutuları Segmentlere Dönüştür

Mevcut x y w h sınırlayıcı kutu verilerini yolo_bbox2segment fonksiyonunu kullanarak segmentlere dönüştür. Görüntüler ve açıklamalar için dosyaları şu şekilde düzenle:

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

Fonksiyonla ilgili daha fazla bilgi için yolo_bbox2segment referans sayfasını ziyaret et.

Segmentleri Sınırlayıcı Kutulara Dönüştür

Segmentasyon veri kümesi formatını kullanan bir veri kümen varsa, bunları bu fonksiyonla kolayca dik (veya yatay) sınırlayıcı kutulara (x y w h formatı) dönüştürebilirsin.

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

Bu fonksiyonun nasıl çalıştığını anlamak için referans sayfasını ziyaret et.

Yardımcı Araçlar

Görüntü Sıkıştırma

Tek bir görüntü dosyasını, en-boy oranını ve kalitesini korurken küçültülmüş bir boyuta sıkıştır. Giriş görüntüsü maksimum boyuttan küçükse, yeniden boyutlandırılmaz.

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)

Veri Kümesini Otomatik Böl

Bir veri kümesini otomatik olarak train/val/test bölümlerine ayır ve ortaya çıkan bölümleri autosplit_*.txt dosyalarına kaydet. Bu fonksiyon, eğitim için fraction argümanı kullanılırken hariç tutulan rastgele örnekleme yöntemini kullanır.

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
)

Bu fonksiyonla ilgili ek ayrıntılar için Referans sayfasına bak.

Poligondan İkili Maskeye Segmentasyon

Convert a single polygon (as a list) to a binary mask of the specified image size. The polygon should be in the form of [N, 2], where N is the number of (x, y) points defining the polygon contour.

Uyarı

N her zaman çift olmalıdır.

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

Sınırlayıcı Kutular

Sınırlayıcı Kutu (Yatay) Örnekleri

Sınırlayıcı kutu verilerini yönetmek için Bboxes sınıfı, kutu koordinat formatları arasında dönüştürme yapmaya, kutu boyutlarını ölçeklendirmeye, alanları hesaplamaya, ofsetleri dahil etmeye ve daha fazlasına yardımcı olur.

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

Daha fazla öznitelik ve yöntem için Bboxes referans bölümüne bak.

İpucu

Aşağıdaki fonksiyonların çoğuna (ve daha fazlasına) Bboxes sınıfı kullanılarak erişilebilir, ancak fonksiyonlarla doğrudan çalışmayı tercih edersen, bunları bağımsız olarak nasıl içe aktaracağını öğrenmek için sonraki alt bölümlere bak.

Kutuları Ölçeklendirme

Bir görüntüyü büyütürken veya küçültürken, ultralytics.utils.ops.scale_boxes kullanarak ilgili sınırlayıcı kutu koordinatlarını eşleşecek şekilde uygun şekilde ölçeklendirebilirsin.

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

Sınırlayıcı Kutu Format Dönüşümleri

XYXY → XYWH

Sınırlayıcı kutu koordinatlarını (x1, y1, x2, y2) formatından (x, y, genişlik, yükseklik) formatına dönüştür; burada (x1, y1) sol üst köşe ve (x2, y2) sağ alt köşedir.

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

Tüm Sınırlayıcı Kutu Dönüşümleri

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

Her fonksiyonun dokümantasyonuna bak veya daha fazlasını okumak için ultralytics.utils.ops referans sayfasını ziyaret et.

Çizim

Açıklama yardımcı araçları

Ultralytics, çeşitli veri türlerini açıklamak için bir Annotator sınıfı içerir. En iyi şekilde nesne algılama sınırlayıcı kutuları, poz anahtar noktaları ve yönlendirilmiş sınırlayıcı kutular ile kullanılır.

Kutu Açıklaması

Ultralytics YOLO Kullanarak Python Örnekleri 🚀
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()

Names can be used from model.names when working with detection results. Also see the Annotator Reference Page for additional insight.

Ultralytics Tarama Açıklaması

Ultralytics Yardımcı Araçlarını Kullanarak Tarama Açıklaması
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()

sweep_annotator yöntemi hakkında ek ayrıntıları referans bölümümüzde burada bulabilirsin.

Uyarlanabilir etiket Açıklaması

Uyarı

Ultralytics v8.3.167 sürümünden itibaren, circle_label ve text_label yerini birleşik bir adaptive_label fonksiyonuna bırakmıştır. Artık shape argümanını kullanarak açıklama türünü belirleyebilirsin:

  • Dikdörtgen: annotator.adaptive_label(box, label=names[int(cls)], color=colors(cls, True), shape="rect")
  • Daire: 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 🚀
Ultralytics Yardımcı Araçlarını Kullanarak Uyarlanabilir etiket Açıklaması
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()

Ek bilgi için SolutionAnnotator Referans Sayfasına bak.

Çeşitli

Kod Profilleme

Kodun çalışma/işlem süresini with kullanarak veya bir dekoratör olarak kontrol et.

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"

Ultralytics Desteklenen Formatlar

Ultralytics'te desteklenen görüntü veya video formatlarını programlı olarak kullanman mı gerekiyor? Gerekirse şu sabitleri kullan:

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

Bölünebilir Yap

x sayısına en yakın, y sayısına tam bölünebilen tam sayıyı hesapla.

from ultralytics.utils.ops import make_divisible

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

SSS

Makine öğrenimi iş akışlarını geliştirmek için Ultralytics paketine hangi yardımcı araçlar dahildir?

Ultralytics paketi, makine öğrenimi iş akışlarını kolaylaştırmak ve optimize etmek için tasarlanmış yardımcı araçlar içerir. Temel yardımcı araçlar arasında veri kümelerini etiketlemek için otomatik açıklama, COCO verilerini convert_coco ile YOLO formatına dönüştürme, görüntüleri sıkıştırma ve veri kümesini otomatik bölme işlemleri yer alır. Bu araçlar manuel çabayı azaltır, tutarlılığı sağlar ve veri işleme verimliliğini artırır.

Veri kümemi otomatik etiketlemek için Ultralytics'i nasıl kullanabilirim?

Önceden eğitilmiş bir Ultralytics YOLO nesne algılama modelin varsa, veri kümeni segmentasyon formatında otomatik olarak açıklamak için bunu SAM modeliyle birlikte kullanabilirsin. İşte bir örnek:

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

For more details, check the auto_annotate reference section, or use Ultralytics Platform as a hosted, no-code alternative with click-based masking via SAM 2.1 or SAM 3, or predictions from pretrained and fine-tuned YOLO models for detect, segment, and OBB tasks.

Ultralytics'te COCO veri kümesi açıklamalarını YOLO formatına nasıl dönüştürürüm?

COCO JSON açıklamalarını nesne algılama için YOLO formatına dönüştürmek amacıyla convert_coco yardımcı aracını kullanabilirsin. İşte örnek bir kod parçası:

from ultralytics.data.converter import convert_coco

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

Ek bilgi için convert_coco referans sayfasını ziyaret et.

Veri kümesi kompozisyonumu ve dağılımımı nasıl analiz edebilirim?

Ultralytics Platformu, otomatik veri kümesi analitiği sağlar: Charts sekmesi bölüm dağılımını, en iyi sınıf sayılarını, görüntü boyutu histogramlarını ve açıklama konumlarının 2B ısı haritalarını göstererek eğitimden önce dengesizlikleri ve aykırı değerleri tespit etmene yardımcı olur.

Ultralytics'te sınırlayıcı kutuları nasıl segmentlere dönüştürürüm?

Mevcut sınırlayıcı kutu verilerini (x y w h formatında) segmentlere dönüştürmek için yolo_bbox2segment fonksiyonunu kullanabilirsin. Dosyalarının görüntüler ve etiketler için ayrı dizinlerle düzenlendiğinden emin ol.

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

Daha fazla bilgi için yolo_bbox2segment referans sayfasını ziyaret et.

Yorumlar