Basit Yardımcı Araçlar#
ultralytics paketi, iş akışlarını desteklemek, geliştirmek ve hızlandırmak için çeşitli araçlar sunar. Çok daha fazlası mevcut olsa da bu kılavuz, geliştiriciler için en faydalı olanlardan bazılarını öne çıkararak Ultralytics araçlarıyla programlama yaparken pratik bir referans işlevi görür.
Watch: Ultralytics Utilities | Auto Annotation, Explorer API and Dataset Conversion
Veri#
Otomatik Etiketleme / Açıklamalar#
Veri seti etiketleme, kaynak tüketen ve zaman alıcı bir süreçtir. Makul miktarda veri üzerinde eğitilmiş bir Ultralytics YOLO nesne algılama modeline sahipseniz, ek verileri segmentasyon formatında otomatik olarak etiketlemek için bunu SAM ile birlikte kullanabilirsiniz.
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:
- İşlevin nasıl çalıştığına dair daha fazla bilgi için
annotator.auto_annotatereferans bölümüne bakın. - Nesne algılama sınırlayıcı kutuları da oluşturmak için
segments2boxesişleviyle birlikte kullanın.
Veri Seti Açıklamalarını Görselleştir#
Bu fonksiyon, eğitimden önce bir görüntü üzerindeki YOLO açıklamalarını görselleştirir ve 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 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 = { # 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#

Bir segmentasyon maskesi görüntüleri veri setini Ultralytics YOLO segmentasyon formatına dönüştürmek için bunu kullanın. Bu işlev, ikili formatta 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#
COCO JSON ek açıklamalarını YOLO formatına dönüştürmek için bunu kullanın. Nesne algılama (sınırlayıcı kutu) veri setleri için, hem use_segments hem de use_keypoints değerini False olarak ayarlayın.
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 ek bilgi için referans sayfasını ziyaret edin.
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 verileriyle, yolo_bbox2segment işlevini kullanarak segmentlere dönüştürün. Görüntüler ve ek açıklamalar için dosyaları aşağıdaki gibi düzenleyin:
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",
)İşlevle ilgili daha fazla bilgi için yolo_bbox2segment referans sayfasını ziyaret edin.
Segmentleri Sınırlayıcı Kutulara Dönüştür#
Segmentasyon veri seti formatını kullanan bir veri setiniz varsa, bu işlevle bunları kolayca dik (veya yatay) sınırlayıcı kutulara (x y w h formatı) dönüştürebilirsiniz.
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 bounding boxesBu işlevin nasıl çalıştığını anlamak için referans sayfasını ziyaret edin.
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 azaltılmış bir boyuta sıkıştır. Giriş görüntüsü maksimum boyuttan küçükse, yeniden boyutlandırılmayacaktır.
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)Otomatik Veri Seti Bölme#
Bir veri setini otomatik olarak train/val/test ayrımlarına böl ve elde edilen ayrımları autosplit_*.txt dosyalarına kaydet. Bu işlev, eğitim için fraction argümanı kullanıldığında hariç tutulan rastgele örnekleme 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 işlev hakkında ek ayrıntılar için Referans sayfasına bakın.
Segment-poligonunu İkili Maskeye Dönüştür#
Tek bir poligonu (liste olarak) belirtilen görüntü boyutunda ikili bir maskeye dönüştür. Poligon, poligon konturunu tanımlayan alternatif x, y değerlerini listeleyen 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]) # (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, kaymaları 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ın.
Aşağıdaki işlevlerin birçoğuna (ve daha fazlasına) Bboxes sınıfı aracılığıyla erişilebilir, ancak işlevlerle doğrudan çalışmayı tercih ederseniz, bunları bağımsız olarak nasıl içe aktaracağınızı görmek için sonraki alt bölümlere bakın.
Kutuları Ölçeklendirme#
Bir görüntüyü büyütürken veya küçültürken, eşleşen ilgili sınırlayıcı kutu koordinatlarını ultralytics.utils.ops.scale_boxes kullanarak uygun şekilde ölçeklendirebilirsiniz.
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 docstringsDaha fazlasını okumak için her işlevin docstring'ine bakın veya ultralytics.utils.ops referans sayfasını ziyaret edin.
Çizim#
Açıklama yardımcı araçları#
Ultralytics, çeşitli veri türlerini etiketlemek için bir Annotator sınıfı içerir. En iyi nesne algılama sınırlayıcı kutuları, pozhtar 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()Algılama sonuçlarıyla çalışırken model.names adları kullanılabilir.
Ayrıca ek bilgi için Annotator Başvuru Sayfası sayfasına göz at.
Ultralytics Tarama (Sweep) 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öntemi hakkında ek ayrıntıları buradaki referans bölümümüzde bulabilirsiniz.
Uyarlanabilir Etiket Açıklaması#
Ultralytics v8.3.167 sürümünden başlayarak, circle_label ve text_label birleşik bir adaptive_label işleviyle değiştirilmiştir. Artık shape argümanını kullanarak ek açıklama türünü belirtebilirsiniz:
- 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ın.
Çeşitli#
Kod Profilleme#
with kullanarak veya bir dekoratör olarak kodun çalışması/işlemesi için geçen süreyi kontrol edin.
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'teki desteklenen görüntü veya video formatlarını programatik olarak kullanmanız mı gerekiyor? Gerekirse şu sabitleri kullanın:
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 ile kalansız bölünebilen, x değerinden büyük veya ona eşit en küçük 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 paketinde hangi yardımcı araçlar yer almaktadır?#
Ultralytics paketi, makine öğrenimi iş akışlarını kolaylaştırmak ve optimize etmek için tasarlanmış araçlar içerir. Temel araçlar arasında veri kümelerini etiketlemek için otomatik etiketleme, COCO veri kümesini convert_coco kullanarak YOLO formatına dönüştürme, görüntüleri sıkıştırma ve veri kümesini otomatik bölme yer alır. Bu araçlar manuel çabayı azaltır, tutarlılığı sağlar ve veri işleme verimliliğini artırır.
Veri setimi otomatik etiketlemek için Ultralytics'i nasıl kullanabilirim?#
Önceden eğitilmiş bir Ultralytics YOLO nesne algılama modeliniz varsa, veri setinizi segmentasyon formatında otomatik olarak etiketlemek için bunu SAM modeliyle birlikte kullanabilirsiniz. İş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",
)Daha fazla ayrıntı için auto_annotate reference section bölümüne göz at veya SAM 2.1 ya da SAM 3 aracılığıyla tık tabanlı maskeleme sunan barındırılan, kodsuz bir alternatif olarak Ultralytics Platform platformunu ya da detect, segment ve OBB görevleri için önceden eğitilmiş ve ince ayar yapılmış YOLO modellerinden gelen tahminleri kullan.
Ultralytics'te COCO veri seti açıklamalarını YOLO formatına nasıl dönüştürürüm?#
COCO JSON ek açıklamalarını nesne algılama için YOLO formatına dönüştürmek için convert_coco yardımcı programını kullanabilirsiniz. İşte örnek bir kod parçacığı:
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 edin.
Veri seti kompozisyonumu ve dağılımımı nasıl analiz edebilirim?#
Ultralytics Platform, otomatik veri seti analitiği sağlar: Charts sekmesi; dağılımı, en üst sınıf sayılarını, görüntü boyutu histogramlarını ve ek açıklama konumlarının 2B ısı haritalarını göstererek eğitimden önce dengesizlikleri ve aykırı değerleri fark etmenize yardımcı olur.
Ultralytics'te sınırlayıcı kutuları segmentlere nasıl dönüştürebilirim?#
Mevcut sınırlayıcı kutu verilerini (x y w h formatında) segmentlere dönüştürmek için yolo_bbox2segment işlevini kullanabilirsiniz. Dosyalarınızın görüntüler ve etiketler için ayrı dizinlerle düzenlendiğinden emin olun.
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 edin.