간단한 유틸리티

관점이 있는 코드

그리고 ultralytics 패키지에는 워크플로를 지원, 개선 및 속도를 높일 수 있는 수많은 유틸리티가 포함되어 있습니다. 더 많은 유틸리티가 있지만 여기서는 대부분의 개발자에게 유용한 몇 가지를 소개합니다. 또한 프로그래밍을 배울 때 참고할 수 있는 훌륭한 참고 자료이기도 합니다.

Watch: Ultralytics 유틸리티 > 자동 주석, 탐색기 API 및 데이터 세트 변환

데이터

YOLO 데이터 탐색기

YOLO 탐색기 에 추가되었습니다. 8.1.0 1주년 기념 업데이트로, 데이터 집합을 더 잘 이해하는 데 사용할 수 있는 강력한 도구입니다. YOLO Explorer가 제공하는 주요 기능 중 하나는 텍스트 쿼리를 사용하여 데이터 집합에서 개체 인스턴스를 찾을 수 있는 기능입니다.

자동 라벨링/주석

데이터 세트 어노테이션은 리소스와 시간이 많이 소요되는 프로세스입니다. 적절한 양의 데이터로 학습된 YOLO 개체 감지 모델이 있는 경우, 이를 사용하고 SAM 를 사용하여 추가 데이터(세분화 형식)에 자동 주석을 달 수 있습니다.

from ultralytics.data.annotator import auto_annotate

auto_annotate(#(1)!
    data='path/to/new/data',
    det_model='yolov8n.pt',
    sam_model='mobile_sam.pt',
    device="cuda",
    output_dir="path/to/save_labels",
)

이 함수에서 반환되는 것은 없습니다.
다음에 대한 참조 섹션을 참조하십시오. annotator.auto_annotate 를 참조하여 기능 작동 방식에 대해 자세히 알아보세요.
와 함께 사용 함수 segments2boxes 를 사용하여 객체 감지 경계 상자도 생성할 수 있습니다.

COCO를 YOLO 형식으로 변환

COCO JSON 주석을 적절한 YOLO 형식으로 변환하는 데 사용합니다. 객체 감지(바운딩 박스) 데이터 세트의 경우, use_segments 그리고 use_keypoints 둘 다 False

from ultralytics.data.converter import convert_coco

convert_coco(#(1)!
    '../datasets/coco/annotations/',
    use_segments=False, 
    use_keypoints=False,
    cls91to80=True,
)

이 함수에서 반환되는 것은 없습니다.

에 대한 자세한 내용은 convert_coco 함수입니다, 참조 페이지 방문

바운딩 박스 치수 가져오기

from ultralytics.utils.plotting import Annotator
from ultralytics import YOLO
import cv2

model = YOLO('yolov8n.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("Bounding Box Width {}, Height {}, Area {}".format(
        width.item(), height.item(), area.item()))

바운딩 박스를 세그먼트로 변환하기

기존 x y w h 바운딩 박스 데이터를 사용하여 세그먼트로 변환합니다. yolo_bbox2segment 함수를 사용하세요. 이미지 및 주석용 파일은 다음과 같이 구성해야 합니다:

data
|__ images
    ├─ 001.jpg
    ├─ 002.jpg
    ├─ ..
    └─ NNN.jpg
|__ labels
    ├─ 001.txt
    ├─ 002.txt
    ├─ ..
    └─ NNN.txt

from ultralytics.data.converter import yolo_bbox2segment

yolo_bbox2segment(#(1)!
    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 형식)을 사용하여 이 함수를 사용할 수 있습니다.

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)#(1)!

이 함수에서 반환되는 것은 없습니다.

데이터 세트 자동 분할

데이터 집합을 다음과 같이 자동으로 분할합니다. train/val/test 분할하고 결과 분할을 autosplit_*.txt 파일을 사용할 수 있습니다. 이 함수는 무작위 샘플링을 사용하며, 이는 다음을 사용할 때는 포함되지 않습니다. fraction 교육용 인수.

from ultralytics.data.utils import autosplit

autosplit( #(1)!
    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 클래스는 상자 좌표 서식 변환, 상자 크기 조정, 면적 계산, 오프셋 포함 등의 작업을 도와줍니다!

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")
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,
)

new_boxes#(1)!
>>> 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, 너비, 높이) 형식으로 변환합니다. 여기서 (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)

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 xywh2xyxy
from ultralytics.utils.ops import xywhn2xyxy # normalized → pixel
from ultralytics.utils.ops import xyxy2xywhn # pixel → normalized
from ultralytics.utils.ops import xywh2ltwh  # xywh → top-left corner, w, h
from ultralytics.utils.ops import xyxy2ltwh  # xyxy → top-left corner, w, h
from ultralytics.utils.ops import ltwh2xywh
from ultralytics.utils.ops import ltwh2xyxy

각 기능에 대한 문서 문자열을 참조하거나 ultralytics.utils.ops 참조 페이지 를 클릭하여 각 기능에 대해 자세히 알아보세요.

플로팅

드로잉 주석

Ultralytics 에는 모든 종류의 데이터에 주석을 다는 데 사용할 수 있는 Annotator 클래스가 포함되어 있습니다. 객체 감지 바운딩 박스, 포즈 키 포인트, 방향성 바운딩 박스에 가장 쉽게 사용할 수 있습니다.

수평 바운딩 박스

import cv2 as cv
import numpy as np
from ultralytics.utils.plotting import Annotator, colors

names { #(1)!
     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 언제 탐지 결과 작업

오리엔티드 바운딩 박스(OBB)

import cv2 as cv
import numpy as np
from ultralytics.utils.plotting import Annotator, colors

obb_names = {10: "small vehicle"}
obb_image = cv.imread("datasets/dota8/images/train/P1142__1024__0___824.jpg")
obb_boxes = np.array(
    [[ 0, 635, 560, 919, 719, 1087, 420, 803,  261,], # class-idx x1 y1 x2 y2 x3 y2 x4 y4
     [ 0, 331,  19, 493, 260, 776,   70, 613, -171,],
     [ 9, 869, 161, 886, 147, 851,  101, 833,  115,]
    ]
)
ann = Annotator(
    obb_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
)
for obb in obb_boxes:
    c_idx, *obb = obb
    obb = np.array(obb).reshape(-1, 4, 2).squeeze()
    label = f"{names.get(int(c_idx))}"
    ann.box_label(
        obb,
        label,
        color=colors(c_idx, True),
        rotated=True,
    )

image_with_obb = ann.result()

참조 Annotator 참조 페이지 를 참조하세요.

기타

코드 프로파일링

다음을 사용하여 실행/처리할 코드의 기간을 확인합니다. with 또는 데코레이터로 사용할 수 있습니다.

from ultralytics.utils.ops import Profile

with Profile(device=device) as dt:
    pass  # operation to measure

print(dt)
>>> "Elapsed time is 9.5367431640625e-07 s"

Ultralytics 지원되는 형식

Ultralytics 에서 지원하는 이미지 또는 동영상 형식의 형식을 프로그래밍 방식으로 사용하고 싶거나 사용해야 하나요? 필요한 경우 이 상수를 사용하세요.

from ultralytics.data.utils import IMG_FORMATS
from ultralytics.data.utils import VID_FORMATS

print(IMG_FORMATS)
>>> ('bmp', 'dng', 'jpeg', 'jpg', 'mpo', 'png', 'tif', 'tiff', 'webp', 'pfm')

분할 가능 만들기

다음에 가장 가까운 정수를 계산합니다. x 로 나눌 때 균등하게 나눌 수 있도록 합니다. y.

from ultralytics.utils.ops import make_divisible

make_divisible(7, 3)
>>> 9
make_divisible(7, 2)
>>> 8

생성 2024-02-20, 업데이트 2024-05-08
작성자: 리즈완 무나와르 (1), 글렌 조처 (3), 버한 큐 (2)