Basit Yardımcı Araçlar
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:
- Fonksiyonun nasıl çalıştığına dair daha fazla bilgi için
annotator.auto_annotatereferans bölümüne bak. - Nesne algılama sınırlayıcı kutuları da oluşturmak için
segments2boxesfonksiyonu ile birlikte kullan.
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

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.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",
)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 boxesBu 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.
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.
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 docstringsHer 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ı
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ı
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ı
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 🚀
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)
# >>> 8SSS
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.