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. Kullanılabilir daha pek çok araç olsa da bu kılavuz, Ultralytics araçlarıyla programlama için pratik bir başvuru kaynağı olarak geliştiricilere en yararlı olanlardan bazılarını öne çıkarır.
İzle: Ultralytics Araçları | Otomatik Etiketleme, Explorer API ve Veri Kümesi Dönüştürme
Veri#
Otomatik Etiketleme / Açıklama Ekleme#
Veri kümesi açıklaması ekleme, kaynak yoğun ve zaman alan bir süreçtir. Makul miktarda veriyle eğitilmiş bir Ultralytics YOLO nesne algılama modelin varsa, bölütleme biçiminde ek verileri otomatik olarak açıklamak için modeli SAM ile kullanabilirsin.
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 işlev herhangi bir değer döndürmez. Daha fazla bilgi için:
- İşlevin nasıl çalıştığı hakkında daha fazla bilgi edinmek için
annotator.auto_annotatebaşvuru bölümüne bak. - Nesne algılama sınırlayıcı kutularını da oluşturmak için bunu
segments2boxesişlevi ile birlikte kullan.
Veri Kümesi Açıklamalarını Görselleştir#
Bu işlev, eğitimden önce bir görüntü üzerindeki YOLO açıklamalarını görselleştirerek hatalı algılama sonuçlarına yol açabilecek yanlış açıklamaları belirlemeye ve düzeltmeye yardımcı olur. Sınırlayıcı kutular çizer, nesneleri sınıf adlarıyla etiketler ve daha iyi okunabilirlik için metin rengini arka planın parlaklığına göre ayarlar.
from ultralytics.data.utils import visualize_image_annotations
label_map = { # Tüm açıklama eklenmiş sınıf etiketleriyle etiket eşlemesini tanımla.
0: "person",
1: "car",
}
# Visualize
visualize_image_annotations(
"path/to/image.jpg", # Giriş görüntüsünün yolu.
"path/to/annotations.txt", # Görüntüye ait açıklama dosyasının yolu.
label_map,
)Bölütleme Maskelerini YOLO Biçimine Dönüştür#

Bölütleme maskesi görüntülerinden oluşan bir veri kümesini Ultralytics YOLO bölütleme biçimine dönüştürmek için bunu kullan. Bu işlev, ikili biçimli maske görüntülerini içeren dizini alır ve bunları YOLO bölütleme biçimine dönüştürür.
Dönüştürülen maskeler belirtilen çıktı dizinine kaydedilir.
from ultralytics.data.converter import convert_segment_masks_to_yolo_seg
# `classes`, veri kümesindeki toplam sınıf sayısıdır.
# COCO veri kümesinde 80 sınıf bulunur.
convert_segment_masks_to_yolo_seg(masks_dir="path/to/masks_dir", output_dir="path/to/output_dir", classes=80)COCO'yu YOLO Biçimine Dönüştür#
COCO JSON açıklamalarını YOLO biçimine dönüştürmek için bunu kullan. Nesne algılama (sınırlayıcı kutu) veri kümelerinde hem use_segments hem de use_keypoints değerini False olarak ayarla.
from ultralytics.data.converter import convert_coco
convert_coco(
"coco/annotations/",
use_segments=False,
use_keypoints=False,
cls91to80=True,
)convert_coco işlevi hakkında daha fazla bilgi için başvuru 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 işlevini kullanarak segmentlere dönüştür. Görüntü ve açıklama dosyalarını ş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, # görüntüler dizininin yanındaki "labels-segment" konumuna kaydedildi
sam_model="sam_b.pt",
)İşlev hakkında daha fazla bilgi için yolo_bbox2segment başvuru sayfasını ziyaret et.
Segmentleri Sınırlayıcı Kutulara Dönüştür#
Bölütleme veri kümesi biçimini kullanan bir veri kümen varsa, bu işlevle bunları kolayca dik (veya yatay) sınırlayıcı kutulara (x y w h biçimi) dönüştürebilirsin.
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 sınırlayıcı kutularıBu işlevin nasıl çalıştığını anlamak için başvuru sayfasını ziyaret et.
Yardımcı Araçlar#
Görüntü Sıkıştırma#
En-boy oranını ve kaliteyi koruyarak tek bir görüntü dosyasını daha küçük 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 yardımcı araç kalıcı bölüm dosyaları oluşturur; fraction eğitim argümanı ise bir çalıştırma için tekrarlanabilir bir alt küme seçer.
from ultralytics.data.split import autosplit
autosplit(
path="path/to/images",
weights=(0.9, 0.1, 0.0), # (eğitim, doğrulama, test) oranlı bölümler
annotated_only=False, # True olduğunda yalnızca açıklama dosyası olan görüntüleri böl
)Bu işlevle ilgili daha fazla ayrıntı için Başvuru sayfasına bak.
Segment Poligonunu İkili Maskeye Dönüştür#
Tek bir poligonu (liste olarak) belirtilen görüntü boyutunda ikili maskeye dönüştür. Poligon, poligonun dış çizgisini tanımlayan x, y değerlerini sırayla içeren, N koordinatlarından oluşan düz bir 1D dizi olmalıdır.
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]) # (N,) düz x, y koordinatları
mask = polygon2mask(
imgsz, # tuple
[polygon], # liste olarak giriş
color=255, # 8 bit ikili
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 biçimleri arasında dönüşüm yapmaya, kutu boyutlarını ölçeklendirmeye, alanları hesaplamaya, ofset eklemeye 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 özellik ve yöntem için Bboxes başvuru bölümüne bak.
Aşağıdaki işlevlerin (ve daha fazlasının) çoğuna Bboxes sınıfı üzerinden erişebilirsin; ancak işlevleri doğrudan kullanmayı tercih ediyorsan, bunları ayrı ayrı 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, karşılık gelen sınırlayıcı kutu koordinatlarını eşleşecek şekilde ultralytics.utils.ops.scale_boxes kullanarak ö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), # orijinal görüntü boyutları
boxes=xyxy_boxes, # orijinal görüntüdeki kutular
img0_shape=(new_h, new_w), # yeniden boyutlandırılan görüntünün boyutları (ölçeklenecek boyutlar)
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 Biçimi Dönüşümleri#
XYXY → XYWH#
Sınırlayıcı kutu koordinatlarını (x1, y1, x2, y2) biçiminden (x, y, genişlik, yükseklik) biçimine dönüştür. Burada (x1, y1) sol üst köşe, (x2, y2) ise 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 → sol üst köşe, w, h
xywh2xyxy,
xywhn2xyxy, # normalize → piksel
xyxy2ltwh, # xyxy → sol üst köşe, w, h
xyxy2xywhn, # piksel → normalize
)
for func in (ltwh2xywh, ltwh2xyxy, xywh2ltwh, xywh2xyxy, xywhn2xyxy, xyxy2ltwh, xyxy2xywhn):
print(help(func)) # işlev açıklama dizelerini yazdırDaha fazla bilgi edinmek için her işlevin dokümantasyon dizgesine bak veya ultralytics.utils.ops başvuru sayfasını ziyaret et.
Çizim#
Açıklama ekleme yardımcı araçları#
Ultralytics, çeşitli veri türlerine açıklama eklemek için bir Annotator sınıfı içerir. Bu sınıf en iyi nesne algılama sınırlayıcı kutuları, poz anahtar noktaları ve yönlendirilmiş sınırlayıcı kutularla 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()Algılama sonuçlarıyla çalışırken adları model.names üzerinden kullanabilirsin. Daha fazla bilgi için Annotator Başvuru Sayfasına da bak.
Ultralytics Süpürme Açıklaması#
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()sweep_annotator yöntemiyle ilgili daha fazla ayrıntıyı başvuru bölümümüzde burada bulabilirsin.
Uyarlanabilir Etiket Açıklaması#
SolutionAnnotator.adaptive_label, şekli shape argümanıyla seçilen bir etiket çizer (bu argüman, eski circle_label ve text_label yöntemlerinin yerini alır):
- 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")
İzle: Python ile Metin ve Daire Açıklamaları İçin Ayrıntılı Kılavuz ve Canlı Demolar | Ultralytics Açıklamaları 🚀
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()Daha fazla bilgi için SolutionAnnotator Referans Sayfası sayfasına bak.
Çeşitli#
Kod Profilleme#
Kodun çalışmasının veya işlenmesinin ne kadar sürdüğünü with kullanarak ya da bir dekoratör olarak kontrol et.
from ultralytics.utils.ops import Profile
with Profile(device="cuda:0") as dt:
pass # ölçülecek işlem
print(dt)
# >>> "Elapsed time is 9.5367431640625e-07 s"Ultralytics Tarafından Desteklenen Biçimler#
Ultralytics'te görsel veya video biçimlerini programatik olarak kullanman mı gerekiyor? Gerekirse bu sabitleri kullan:
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'}Bölünebilir Yap#
y değerine tam bölünebilen ve x değerinden büyük veya bu değere eşit olan en küçük tam sayıyı hesapla.
from ultralytics.utils.ops import make_divisible
make_divisible(7, 3)
# >>> 9
make_divisible(7, 2)
# >>> 8Sık Sorulan Sorular#
Ultralytics paketi, makine öğrenimi iş akışlarını kolaylaştırmak ve optimize etmek için tasarlanmış yardımcı programlar içerir. Öne çıkan yardımcı programlar arasında veri kümelerini etiketlemeye yönelik otomatik açıklama ekleme, COCO biçimini convert_coco ile YOLO biçimine dönüştürme, görselleri sıkıştırma ve veri kümelerini otomatik olarak bölme yer alır. Bu araçlar, manuel iş yükünü azaltır, tutarlılığı sağlar ve veri işleme verimliliğini artırır.
Önceden eğitilmiş bir Ultralytics YOLO nesne algılama modelin varsa, veri kümene segmentasyon biçiminde otomatik olarak açıklama eklemek için modeli SAM modeliyle kullanabilirsin. Ö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", )Daha fazla ayrıntı için auto_annotate başvuru bölümüne bak veya tıklamayla maskeleme olanağı sunan SAM 2.1, SAM 3 ya da SAM 3.1 üzerinden barındırılan, kod gerektirmeyen bir alternatif olarak Ultralytics Platform kullan; ayrıca algılama, segmentasyon ve OBB görevlerinde önceden eğitilmiş ve ince ayar yapılmış YOLO modellerinden tahminler alabilirsin.
Nesne algılama için COCO JSON açıklamalarını YOLO biçimine dönüştürmek üzere
convert_cocoyardımcı programını kullanabilirsin. Örnek bir kod parçacığı:from ultralytics.data.converter import convert_coco convert_coco( "coco/annotations/", use_segments=False, use_keypoints=False, cls91to80=True, )Daha fazla bilgi için convert_coco başvuru sayfasını ziyaret et.
Ultralytics Platform otomatik veri kümesi analizleri sunar:
Chartssekmesi, bölümlerin dağılımını, en yüksek sınıf sayılarını, görsel boyutlarının histogramlarını ve açıklama konumlarının 2D ısı haritalarını göstererek eğitimden önce dengesizlikleri ve aykırı değerleri fark etmene yardımcı olur.Mevcut sınırlayıcı kutu verilerini (
x y w hbiçiminde) segmentlere dönüştürmek içinyolo_bbox2segmentişlevini kullanabilirsin. Dosyalarını görseller ve etiketler için ayrı dizinlerde düzenlediğinden emin ol.from ultralytics.data.converter import yolo_bbox2segment yolo_bbox2segment( im_dir="path/to/images", save_dir=None, # görüntüler dizininin yanındaki "labels-segment" konumuna kaydedildi sam_model="sam_b.pt", )Daha fazla bilgi için yolo_bbox2segment başvuru sayfasını ziyaret et.