物体検出

定義

物体検出は、各物体がどこにあり、何であるかを答えます。1枚の画像を入力すると、インスタンスごとに1行を出力します。各行には長方形を表す4つの数値、クラスインデックス、スコアがあります。ピクセル単位の形状、向き、部位は含まれません。この点がインスタンスセグメンテーション、回転ボックス、姿勢推定との違いです。

detectが標準タスクキーであり、デフォルトです。ファイル名にタスク接尾辞がないチェックポイントは検出器として読み込まれます。

predict()はresult.boxesを設定します。.xyxyは元画像のキャンバス上のピクセル単位の角座標、.confはスコア、.clsはresult.namesを参照するクラスインデックスです。.xywh、.xyxyn、.xywhnは同じ行から導出したビューで、トラッカーを接続すると.idに追跡IDが格納されます。Boxesオブジェクトを反復処理すると1行のスライスが得られるため、検出ごとにbox.cls、box.conf、box.xyxyを使用できます。

モデル

以下のファミリーは学習と推論に対応します。YOLOv9、RF-DETR、EdgeCrafter、RT-DETR、D-FINE、DEIM、Dome-DETR、GTR、YOLO-NAS、YOLOX、YOLOv7、RTMDet、PicoDetです。YOLOv9とRF-DETRは2つの主力ファミリーで、新機能は最初にこれらへ追加されます。RF-DETRには専用の追加パッケージpip install "libreyolo[rfdetr]"が必要です。それ以外は基本パッケージで実行できます。

さらに11個のファミリーが推論、検証、エクスポートに対応しますが、train()はNotImplementedErrorを送出します。LW-DETR、DETR、Deformable DETR、DINO-DETR、Faster R-CNN、Mask R-CNN、FCOS、RetinaNet、SSD、CenterNet、EfficientDetです。

Darknet系統のYOLOv1、YOLOv2、YOLOv3、YOLOv4は、固定された展示物として維持されています。推論、検証、エクスポートは機能しますが、学習はできません。

別のグループはチェックポイントではなく実行時にクラスリストを受け取るため、学習時に見たことのない名前も検出できます。Grounding DINO、OWLv2、OMDet-Turbo、OV-DEIMに加え、Vision-LanguageファミリーのFlorence-2、Kosmos-2、Qwen3-VL、SmolVLM2、InternVL3、LFM2-VL、Gemma 4、Moondream、North Micro Vision、LocateAnything、SenseNova-Vision、WeVisOne-VL、LibreMODUSです。これらは固有のファクトリと追加パッケージを通して読み込まれます。正確な呼び出しは各モデルページに記載されています。

PP-YOLOEとTinyFormerも物体検出の学習に対応します。

推論

重みは初回使用時にHugging Faceからダウンロードされ、ローカルにキャッシュされます。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(result.names[int(box.cls)], float(box.conf), box.xyxy)

libreyolo predict model=LibreYOLO9t.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE # ファクトリはチェックポイントに応じて振り分け 全検出器が同じ# Resultsオブジェクトを返すためファミリーの切り替えは1行の変更で済むmodel = LibreYOLO("LibreDFINEn.pt")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy.shape)

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # ライブラリが受け付ける任意のソース ファイル フォルダー URL# Webカメラのインデックス RTSPストリーム .streamsリストfor result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

confは信頼度のしきい値、max_detは行数の上限です。iouはNMSのしきい値なので、NMSを実行するファミリーだけに影響します。RF-DETRとエンドツーエンドYOLOv9ヘッドは固定された予測集合をデコードするため、これを無視します。agnostic_nms=Trueはiouでクラスに依存しない抑制ステップを追加し、これはこの2つにも適用されます。しきい値とフィルタリングを参照してください。入力ソース、ストリーミング、結果の処理については推論を参照してください。

データセット形式

画像ごとに1つの.txtラベルファイルを使用します。画像パス内のimagesをlabelsへ置き換え、拡張子を変更して検索します。

dataset/  data.yaml  images/    train/000001.jpg    val/000101.jpg  labels/    train/000001.txt    val/000101.txt

各行は正確に5つのフィールドで、クラスインデックスの後に、正規化済みの中心座標とサイズを持つボックスを記述します。

<class_id> <cx> <cy> <w> <h>

座標は元画像の幅と高さに対する[0, 1]範囲の浮動小数点数です。wとhは正でなければなりません。ラベルファイルが存在しないか空の場合、その画像に物体がないことを意味します。行に信頼度や追跡IDは含まれません。

YAMLでは分割とクラスを指定します。

path: datasettrain: images/trainval: images/valnames:  0: person  1: bicycle

trainとvalには画像ディレクトリ、画像一覧の.txtファイル、またはそのどちらかのリストを指定できます。ncは任意で、指定した場合はnamesと一致する必要があります。ネイティブのCOCO JSONも使用できます。分割名とJSONファイルのannotationsマッピングを追加すると、分割パスが画像ルートになります。namesがある場合はラベルIDを定義するため、JSONのカテゴリー名と一致しなければなりません。

学習

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # coco128.yamlは初回使用時に128枚のサンプルをダウンロードする# 実際の学習ではdataに独自データセットのYAMLを指定するmodel.train(data="coco128.yaml", epochs=50, imgsz=640, batch=8)

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 imgsz=640 batch=8

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 device=0,1 batch=-1

最初に調整する引数はepochs、imgsz、batch、lr0です。ファミリー間で流用できないのはlr0です。畳み込み検出器が許容する学習率でもTransformer検出器では発散する可能性があるため、別ファミリーの例ではなくモデルページの値を使用してください。ファミリーが引数を完全に無視する場合もあり、各ページにその対象が記載されています。データセット、データ拡張、マルチGPU、ロガーについては学習を参照してください。

classes=で元のデータセットIDから残すものを選択します。single_cls=Trueは残したラベルをクラス0に統合します。対応ファミリーと検証時の設定継承についてはハイパーパラメータを参照してください。

検証

val()は、データセットYAMLのvalで指定した分割に対してCOCO評価で計算したmetrics/キーを持つ辞書を返し、クラスごとの結果を属性として付加します。

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # metrics/キーのdictで、クラスごとの結果を属性として保持metrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"], metrics["metrics/mAP75"])print(metrics["metrics/AR100"])print(metrics.confusion_matrix.class_accuracy())

libreyolo val model=LibreYOLO9t.pt data=coco128.yaml

metrics/mAP50-95はIoUしきい値0.50から0.95までで平均した平均適合率で、主要な数値です。metrics/mAP50とmetrics/mAP75は単一しきい値版です。metrics/mAP_small、metrics/mAP_medium、metrics/mAP_largeは同じ平均を物体面積別に分けます。metrics/AR1、metrics/AR10、metrics/AR100、metrics/AR_small、metrics/AR_medium、metrics/AR_largeは対応する平均再現率です。metrics/AR_max_detとmetrics/max_detには実行時に使った検出上限が記録されます。

このタスクのmetrics/precisionとmetrics/recallは注意して解釈してください。後方互換性のために維持された別名であり、ある運用点の値ではありません。metrics/precisionはmetrics/mAP50-95と同じ値を、metrics/recallはmetrics/AR100と同じ値を保持します。適合率と再現率のペアとして描画すると同じ数値を二重に報告することになります。モデルがマスクも予測する場合でも検出キーを同じように読めるよう、4つのキーはボックスを表す(B)接尾辞付きでも繰り返されます。metrics/mAP50-95(B)、metrics/mAP50(B)、metrics/precision(B)、metrics/recall(B)です。

結果には、backgroundの行と列を持ちmatrix[predicted, true]でインデックスするconfusion_matrixと、box上の信頼度ごとのクラス別の適合率、再現率、F1も含まれます：box.px、box.p_curve、box.r_curve、box.f1_curveで、box.ap_class_indexのクラスごとに1行です。検証と指標で、val(agnostic_nms=True)とあわせて両方を説明しています。

エクスポート

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt")model.export(format="onnx", imgsz=640)

libreyolo export model=LibreYOLO9t.pt format=onnx imgsz=640

from libreyolo import LibreYOLO, SAMPLE_IMAGE # ファクトリはファイルの拡張子に応じて振り分けるためエクスポートした# アーティファクトもチェックポイントと同様に読み込まれ同じResultsオブジェクトを返すmodel = LibreYOLO("LibreYOLO9t.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

エクスポートしたアーティファクトはファイルの拡張子に基づいてLibreYOLO()で再読み込みできるため、.onnxや.engineファイルもチェックポイントと同様に動作し、同じResultsを返します。対応形式はファミリーごとに異なり、各モデルページのマトリックスは手入力ではなく検証済みの集合から生成されます。形式、追加パッケージ、制約についてはエクスポートとデプロイを参照してください。