Basit Araçlar#
ultralytics paketi, iş akışlarını desteklemek, geliştirmek ve hızlandırmak için çeşitli araçlar sunar. Daha birçok araç mevcut olsa da bu kılavuz, geliştiriciler için en yararlı olanlardan bazılarını vurgulayarak Ultralytics araçlarıyla programlama yapmak için pratik bir başvuru kaynağı görevi görür.
Watch: Ultralytics Utilities | Auto Annotation, Explorer API and Dataset Conversion
Veri#
Otomatik Etiketleme / Açıklama Ekleme#
Veri kümesi açıklaması, kaynak yoğun ve zaman alıcı bir süreçtir. Makul düzeyde veriyle eğitilmiş bir Ultralytics YOLO nesne algılama modeline sahipseniz, bölütleme formatında ek verileri otomatik olarak etiketlemek için bu modeli 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:
- Fonksiyonun nasıl çalıştığı hakkında daha fazla bilgi edinmek için
annotator.auto_annotatereferans bölümüne göz at. - Nesne algılama sınırlayıcı kutuları da oluşturmak için
segments2boxesfonksiyonu ile birlikte kullan.
Veri Kümesi Anotasyonlarını Görselleştirme#
Bu fonksiyon, eğitimden önce bir görüntü üzerindeki YOLO açıklamalarını görselleştirerek yanlış algılama sonuçlarına yol açabilecek hatalı açıklamaların tanımlanmasına ve düzeltilmesine yardımcı olur. Sınır 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,
)Bölütleme Maskelerini YOLO Formatına Dönüştürme#
Bir bölütleme maskesi görüntüsü veri kümesini Ultralytics YOLO bölütleme formatına dönüştürmek için bunu kullan. Bu fonksiyon, ikili format maske görüntülerini içeren dizini alır ve bunları YOLO bölütleme 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 Veri Kümesini YOLO Formatına Dönüştürme#
COCO JSON açıklamalarını YOLO formatına dönüştürmek için bunu kullan. Nesne algılama (sınır kutusu) veri kümeleri için 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 fonksiyonu hakkında ek bilgi için referans sayfasını ziyaret et.
Sınır Kutusu 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ır Kutularını Segmentlere Dönüştür#
Mevcut x y w h sınır kutusu verileriyle, yolo_bbox2segment fonksiyonunu kullanarak segmentlere dönüştür. Görüntüler ve açıklamalar için dosyaları şu şekilde organize et:
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",
)Fonksiyon hakkında daha fazla bilgi için yolo_bbox2segment referans sayfasını ziyaret et.
Segmentleri Sınır Kutularına Dönüştür#
Bölütleme veri kümesi formatını kullanan bir veri kümeniz varsa, bu fonksiyonla bunları kolayca dik (veya yatay) sınır kutularına (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, 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 fonksiyonun nasıl çalıştığını anlamak için referans sayfasını ziyaret et.
Yardımcı Programlar#
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ı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ölme#
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ı program kalıcı bölme dosyaları oluşturur; bunun yerine fraction eğitim argümanı bir çalıştırılabilirlik için yeniden üretilebilir bir alt küme seçer.
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 fonksiyon hakkında ek ayrıntılar için Referans sayfasına göz at.
Segment-Çokgeni İkili Maskeye Dönüştürme#
Tek bir çokgeni (liste olarak) belirtilen görüntü boyutunda ikili bir maskeye dönüştür. Çokgen, çokgen konturunu tanımlayan alternatif x, y değerlerini listeleyen, N koordinatlarından oluşan düz 1 boyutlu bir dizi olmalıdır.
N her zaman çift sayı 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ır Kutuları#
Sınır Kutusu (Yatay) Örnekleri#
Sınır kutusu 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 göz at.
Aşağıdaki fonksiyonların birçoğuna (ve daha fazlasına) Bboxes sınıfı aracılığıyla erişilebilir, ancak fonksiyonlarla doğrudan çalışmayı tercih ediyorsan bunları bağımsız olarak nasıl içe aktaracağını görmek için sonraki alt bölümlere göz at.
Kutuları Ölçeklendirme#
Bir görüntüyü büyütürken veya küçültürken, ultralytics.utils.ops.scale_boxes kullanarak eşleşen sınır kutusu koordinatlarını 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ır Kutusu Formatı Dönüşümleri#
XYXY → XYWH#
Sınır kutusu 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öşeyi ve (x2, y2) sağ alt köşeyi temsil eder.
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ır Kutusu 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 fonksiyonun belge dizesine (docstring) bakın veya ultralytics.utils.ops referans sayfasını ziyaret edin.
Görselleştirme#
Açıklama araçları#
Ultralytics, çeşitli veri türlerine açıklama eklemek için bir Annotator sınıfı içerir. En iyi nesne algılama sınır kutuları, poz eklem noktaları ve yönlendirilmiş sınır 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 içindeki adlar kullanılabilir.
Ayrıca ek bilgi için Annotator Referans Sayfasına göz atın.
Ultralytics Tarama 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 bulabilirsin.
Uyarlanabilir etiket Açıklaması#
SolutionAnnotator.adaptive_label, shape argümanıyla seçilen bir şekle sahip bir etiket çizer (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") - Çember:
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 göz at.
Çeşitli#
Kod Profili Oluşturma#
with kullanarak veya bir dekoratör olarak kodun çalışması/işlenmesi 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 Tarafından Desteklenen Formatlar#
Ultralytics'te desteklenen görüntü veya video formatlarını programatik olarak kullanmanız mı gerekiyor? Gerekirse bu 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 olan en küçük tam sayıyı hesapla.
from ultralytics.utils.ops import make_divisible
make_divisible(7, 3)
# >>> 9
make_divisible(7, 2)
# >>> 8SSS#
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 açıklama, convert_coco ile COCO formatını 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.
Önceden eğitilmiş bir Ultralytics YOLO nesne algılama modeliniz varsa, veri kümenizi bölütleme formatında otomatik olarak açıklamak 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, SAM 3 ya da SAM 3.1 aracılığıyla tık tabanlı maskeleme sunan barındırılan, kodsuz bir alternatif olarak Ultralytics Platform platformunu veya nesne tespiti, bölütleme ve OBB görevleri için önceden eğitilmiş ve ince ayarı yapılmış YOLO modellerinden gelen tahminleri kullan.
Nesne algılama için COCO JSON açıklamalarını YOLO formatına dönüştürmek üzere
convert_cocoyardı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.
Ultralytics Platform otomatik veri kümesi analitiği sağlar:
Chartssekmesi; bölünme dağılımını, en üst 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 etmenize yardımcı olur.Mevcut sınır kutusu verilerini (
x y w hformatında) segmentlere dönüştürmek içinyolo_bbox2segmentfonksiyonunu 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.