أدوات مساعدة بسيطة
توفر حزمة ultralytics مجموعة متنوعة من الأدوات المساعدة لدعم سير عملك وتعزيزه وتسريعه. وعلى الرغم من توفر العديد من الأدوات الأخرى، يسلط هذا الدليل الضوء على أكثرها فائدة للمطورين، ليكون مرجعاً عملياً للبرمجة باستخدام أدوات Ultralytics.
Watch: Ultralytics Utilities | Auto Annotation, Explorer API and Dataset Conversion
البيانات
وضع العلامات / التسميات التوضيحية التلقائية
تعد عملية وضع تسميات توضيحية للبيانات عملية تستهلك الكثير من الوقت والموارد. إذا كان لديك نموذج Ultralytics YOLO للكشف عن الكائنات مدرب على كمية معقولة من البيانات، يمكنك استخدامه مع SAM لوضع تسميات توضيحية تلقائية لبيانات إضافية بتنسيق التجزئة.
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",
)لا ترجع هذه الدالة أي قيمة. لمزيد من التفاصيل:
- راجع القسم المرجعي لـ
annotator.auto_annotateللحصول على مزيد من المعلومات حول كيفية عمل الدالة. - استخدمها بالاشتراك مع الدالة
segments2boxesلإنشاء صناديق إحاطة للكشف عن الكائنات أيضاً.
تصور تسميات البيانات
تعمل هذه الدالة على تصور تسميات YOLO على صورة قبل التدريب، مما يساعد في تحديد وتصحيح أي تسميات خاطئة قد تؤدي إلى نتائج كشف غير صحيحة. تقوم الدالة برسم صناديق الإحاطة، وتسمية الكائنات بأسماء الفئات، وضبط لون النص بناءً على سطوع الخلفية لتحسين قابلية القراءة.
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,
)تحويل أقنعة التجزئة إلى تنسيق YOLO

استخدم هذا لتحويل مجموعة بيانات من صور أقنعة التجزئة إلى تنسيق التجزئة الخاص بـ Ultralytics YOLO. تأخذ هذه الدالة المجلد الذي يحتوي على صور الأقنعة بالتنسيق الثنائي وتحولها إلى تنسيق التجزئة الخاص بـ YOLO.
سيتم حفظ الأقنعة المحولة في مجلد الإخراج المحدد.
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 إلى تنسيق YOLO
استخدم هذا لتحويل تسميات COCO بتنسيق JSON إلى تنسيق YOLO. بالنسبة لمجموعات بيانات الكشف عن الكائنات (صناديق الإحاطة)، اضبط كلاً من use_segments و use_keypoints على False.
from ultralytics.data.converter import convert_coco
convert_coco(
"coco/annotations/",
use_segments=False,
use_keypoints=False,
cls91to80=True,
)لمزيد من المعلومات حول دالة convert_coco، تفضل بزيارة صفحة المرجع.
الحصول على أبعاد صناديق الإحاطة
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()}")تحويل صناديق الإحاطة إلى قطاعات
باستخدام بيانات صناديق الإحاطة x y w h الموجودة، قم بالتحويل إلى قطاعات باستخدام دالة yolo_bbox2segment. نظم ملفات الصور والتسميات كما يلي:
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",
)تفضل بزيارة صفحة مرجع yolo_bbox2segment لمزيد من المعلومات حول الدالة.
تحويل القطاعات إلى صناديق إحاطة
إذا كان لديك مجموعة بيانات تستخدم تنسيق مجموعة بيانات التجزئة، يمكنك بسهولة تحويلها إلى صناديق إحاطة قائمة (أو أفقية) بتنسيق (x y w h) باستخدام هذه الدالة.
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لفهم كيفية عمل هذه الدالة، تفضل بزيارة صفحة المرجع.
الأدوات المساعدة
ضغط الصور
ضغط ملف صورة واحد إلى حجم أصغر مع الحفاظ على نسبة العرض إلى الارتفاع والجودة. إذا كانت الصورة المدخلة أصغر من البعد الأقصى، فلن يتم تغيير حجمها.
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)التقسيم التلقائي لمجموعة البيانات
تقسيم مجموعة البيانات تلقائياً إلى مجموعات train/val/test وحفظ التقسيمات الناتجة في ملفات autosplit_*.txt. تستخدم هذه الدالة أخذ العينات العشوائي، والذي يتم استبعاده عند استخدام وسيطة fraction للتدريب.
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
)راجع صفحة المرجع للحصول على تفاصيل إضافية حول هذه الدالة.
تحويل المضلع المقطعي إلى قناع ثنائي
تحويل مضلع واحد (كقائمة) إلى قناع ثنائي بحجم الصورة المحدد. يجب أن يكون المضلع في شكل [N, 2]، حيث N هو عدد النقاط (x, y) التي تحدد محيط المضلع.
N يجب دائماً أن يكون زوجياً.
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,
)صناديق الإحاطة
حالات صناديق الإحاطة (الأفقية)
لإدارة بيانات صناديق الإحاطة، تساعد فئة Bboxes في التحويل بين تنسيقات إحداثيات الصناديق، وتغيير حجم أبعاد الصناديق، وحساب المساحات، وإدراج الإزاحات، والمزيد.
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]]
# )راجع القسم المرجعي لـ Bboxes لمزيد من السمات والأساليب.
يمكن الوصول إلى العديد من الدوال التالية (وغيرها) باستخدام فئة Bboxes، ولكن إذا كنت تفضل العمل مع الدوال مباشرة، فراجع الأقسام الفرعية التالية لمعرفة كيفية استيرادها بشكل مستقل.
تغيير حجم الصناديق
عند تكبير أو تصغير صورة، يمكنك تغيير حجم إحداثيات صناديق الإحاطة المقابلة بشكل مناسب لتتطابق باستخدام ultralytics.utils.ops.scale_boxes.
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]]
# )تحويلات تنسيق صناديق الإحاطة
XYXY → XYWH
تحويل إحداثيات صناديق الإحاطة من تنسيق (x1, y1, x2, y2) إلى تنسيق (x, y, width, height)، حيث (x1, y1) هي الزاوية العلوية اليسرى و (x2, y2) هي الزاوية السفلية اليمنى.
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]]
# )جميع تحويلات صناديق الإحاطة
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 docstringsSee the docstring for each function or visit the ultralytics.utils.ops reference page to read more.
الرسم
أدوات التسمية التوضيحية
تتضمن Ultralytics فئة Annotator لتسمية أنواع البيانات المختلفة. يُفضل استخدامها مع صناديق إحاطة الكشف عن الكائنات، ونقاط التمركز (Pose Keypoints)، وصناديق الإحاطة الموجهة (OBB).
تسمية الصناديق
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()يمكن استخدام الأسماء من model.names عند العمل مع نتائج الكشف.
راجع أيضاً صفحة المرجع لـ Annotator للحصول على رؤية إضافية.
تسمية المسح من Ultralytics
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 في القسم المرجعي الخاص بنا هنا.
تسمية التسميات التكيفية
بدءاً من Ultralytics v8.3.167، تم استبدال circle_label و text_label بدالة adaptive_label موحدة. يمكنك الآن تحديد نوع التسمية باستخدام وسيطة shape:
- مستطيل:
annotator.adaptive_label(box, label=names[int(cls)], color=colors(cls, True), shape="rect") - دائرة:
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()راجع صفحة المرجع لـ SolutionAnnotator للحصول على رؤية إضافية.
متفرقات
تحليل أداء الكود
تحقق من المدة التي يستغرقها تشغيل/معالجة الكود إما باستخدام with أو كمزخرف (decorator).
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
هل تحتاج إلى استخدام تنسيقات الصور أو الفيديو المدعومة برمجياً في Ultralytics؟ استخدم هذه الثوابت إذا لزم الأمر:
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'}جعل العدد قابلاً للقسمة
احسب أقرب عدد صحيح لـ x يكون قابلاً للقسمة بالتساوي على y.
from ultralytics.utils.ops import make_divisible
make_divisible(7, 3)
# >>> 9
make_divisible(7, 2)
# >>> 8الأسئلة الشائعة
ما هي الأدوات المساعدة المضمنة في حزمة Ultralytics لتعزيز سير عمل تعلم الآلة؟
تتضمن حزمة Ultralytics أدوات مساعدة مصممة لتبسيط وتحسين سير عمل تعلم الآلة. تشمل الأدوات الرئيسية التسمية التلقائية لتسمية مجموعات البيانات، وتحويل COCO إلى تنسيق YOLO باستخدام convert_coco، وضغط الصور، والتقسيم التلقائي لمجموعة البيانات. تعمل هذه الأدوات على تقليل الجهد اليدوي، وضمان الاتساق، وتعزيز كفاءة معالجة البيانات.
كيف يمكنني استخدام Ultralytics للتسمية التلقائية لمجموعة بياناتي؟
إذا كان لديك نموذج Ultralytics YOLO مدرب مسبقاً للكشف عن الكائنات، يمكنك استخدامه مع نموذج SAM لتسمية مجموعة بياناتك تلقائياً بتنسيق التجزئة. إليك مثال:
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",
)لمزيد من التفاصيل، راجع القسم المرجعي لـ auto_annotate، أو استخدم منصة Ultralytics كبديل مستضاف بدون كود مع خاصية التغطية (masking) القائمة على النقرات عبر SAM 2.1 أو SAM 3، أو التوقعات من نماذج YOLO المدربة مسبقاً والمضبوطة بدقة لمهام الكشف والتجزئة و OBB.
كيف أقوم بتحويل تسميات مجموعة بيانات COCO إلى تنسيق YOLO في Ultralytics؟
لتحويل تسميات COCO بتنسيق JSON إلى تنسيق YOLO للكشف عن الكائنات، يمكنك استخدام أداة convert_coco المساعدة. إليك مقتطف كود نموذجي:
from ultralytics.data.converter import convert_coco
convert_coco(
"coco/annotations/",
use_segments=False,
use_keypoints=False,
cls91to80=True,
)لمزيد من المعلومات، تفضل بزيارة صفحة المرجع لـ convert_coco.
كيف يمكنني تحليل تكوين وتوزيع مجموعة بياناتي؟
توفر منصة Ultralytics تحليلات تلقائية لمجموعة البيانات: تعرض علامة التبويب Charts توزيع التقسيم، وأعداد الفئات الأعلى، ورسوم بيانية لأبعاد الصور، وخرائط حرارية ثنائية الأبعاد لمواضع التسميات، مما يساعدك على اكتشاف الاختلالات والقيم المتطرفة قبل التدريب.
كيف يمكنني تحويل صناديق الإحاطة إلى قطاعات في Ultralytics؟
لتحويل بيانات صناديق الإحاطة الموجودة (بتنسيق x y w h) إلى قطاعات، يمكنك استخدام دالة yolo_bbox2segment. تأكد من تنظيم ملفاتك مع مجلدات منفصلة للصور والتسميات.
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",
)لمزيد من المعلومات، تفضل بزيارة صفحة المرجع لـ yolo_bbox2segment.