シンプルなユーティリティ

パースペクティブ・コード

について ultralytics パッケージには、あなたのワークフローをサポートし、強化し、高速化する無数のユーティリティが付属している。利用可能なものは他にもたくさんあるが、ここではほとんどの開発者にとって有用なものをいくつか紹介しよう。また、プログラミングを学ぶ際の参考にもなります。

見るんだ： Ultralytics ユーティリティ｜オートアノテーション、エクスプローラAPI、データセット変換

データ

YOLO データエクスプローラー

YOLO エクスプローラーが追加された。 8.1.0 アニバーサリー・アップデートは、データセットをより深く理解するための強力なツールです。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

この機能がどのように働くかを理解するには、リファレンスページをご覧ください。

ユーティリティ

画像圧縮

アスペクト比と画質を保持したまま、1つの画像ファイルを縮小して圧縮します。入力画像が最大寸法より小さい場合、リサイズされません。

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

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

各関数のdocstringを参照するか、または 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
著者RizwanMunawar（1）、glenn-jocher（3）、Burhan-Q（2）