Resultsの型

Resultsオブジェクト

1つのResultsが1枚の画像を表します。単一画像のソースは1つ、リストのソースまたは ディレクトリはリストを返し、stream=Trueはそれらを生成するジェネレーターを返します。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) print(result.orig_shape, result.path)print(result.boxes.xyxy)print(result.boxes.conf)print(result.names[int(result.boxes.cls[0])])

ペイロードスロット

モデルが生成しない限り、各スロットはNoneです。ファミリーが埋めるスロットは、そのタスクに よって決まります。

result.normalsはresult.normal_mapの読み書き可能な別名です。

複数のスロットを同時に設定できます。セグメンテーションモデルはboxesとmasksの両方を 埋めます。視線モデルは顔のボックスをboxesに、角度をgazeに格納します。メッシュモデルは 人物ボックスをboxesに格納し、それと行を対応させてmeshesを埋めます。

Boxes

1枚の画像に対する検出ボックス。

with_id(id)とwith_orig_shape(orig_shape)は、該当フィールドを置き換えた新しいBoxesを 返します。

Masks

1枚の画像に対するインスタンスマスク。dataはマスクテンソルです。xyはインスタンスごとの 輪郭をピクセル単位で返し、xynは正規化して返します。

Keypoints

boxesと行が対応する姿勢キーポイント。xyはキーポイントごとの座標ペア、xynは正規化済み ペアです。データに第3チャンネルがあればconfはその値、なければNoneです。has_visibleは ブール配列で、conf > 0の位置がtrueになり、信頼度チャンネルがない場合はすべてtrueです。

Points

1枚の画像に対する点の位置特定。dataの形状は(N, 4)で、各行はx, y, class, confidenceです。 座標は絶対ピクセルです。xy、cls、confが各列を分け、xynが座標を正規化します。

Probs

分類スコア。top1は最上位のインデックス、top5は上位5件のインデックス、top1confと top5confはそれぞれのスコアです。

OBB

回転ボックス。dataは行ごとに7個または8個の値を保持します：xywhr、オプションの トラックID、信頼度、クラスの順です。

Gaze

顔ごとのラジアン単位の視線角度で、形状は(N, 2)、boxesの顔ボックスと行が対応します。 L2CSの規約に従い、列0はピッチ、列1はヨーです。正のヨーは被写体から見て左へ視線を回転させ、 正のピッチは下へ回転させます。pitch_degとyaw_degは度へ変換し、direction_3dは単位方向 ベクトルを返します。

SemanticMask

元画像のキャンバス上にある、整数クラスIDの密なセマンティックマップで、形状は(H, W)です。 255は無視する値であり、クラスとして数えられることはありません （SemanticMask.IGNORE_INDEX）。classesは存在するクラスIDを一覧化し、 class_mask(class_id)は1つのクラスに対するブールマスクを返します。

PanopticSegmentation

すべてのピクセルに重複しないセグメントをちょうど1つ割り当て、stuff領域とthingインスタンスを 統合します。dataは(H, W)の整数セグメントIDマップです。セグメントID0はラベルなしを 表します（PanopticSegmentation.IGNORE_INDEX）。segments_infoはセグメントごとに1つの dictを持つリストで、それぞれ少なくとも{"id": int, "category_id": int}を含みます。 ここでidはマップ内の値に一致し、category_idはnamesのインデックスです。 segment_idsは存在するIDを一覧化し、segment_mask(segment_id)は1つのセグメントの ブールマスクを返します。

thingとstuffの区別はセグメントではなくカテゴリーのプロパティです。ペイロードはそれを "isthing": boolとして各セグメントへ非正規化する場合があり、その場合、値はカテゴリー レベルのマップと一致する必要があります。

DepthMap

元画像のキャンバス上にある、浮動小数点数の密な相対逆深度マップで、形状は(H, W)です。 値が大きいほどカメラに近いことを意味します。値は相対値であり、メートル単位の実測値では ありません。min、max、meanは有限値に対して計算され、normalized()はマップを [0, 1]に再スケーリングします。

DepthMap(data, orig_shape=None, encoding="inverse_depth")は、encoding="depth"とencoding="log_depth"も受け付けます。バリデーターは整合の前にこれを解釈します。相対深度の値に実距離の尺度が保証されるわけではありません。

NormalMap

元画像のキャンバス上にある、float32の密な表面法線フィールドです。形状は(H, W, 3)で、 OpenCVのカメラ座標系を使います：+xは右、+yは下、+zはシーンの奥です。法線はカメラを 向くため、正面に平行な面は(0, 0, -1)です。すべてのピクセルは単位ベクトルです。 assert_normalized(atol=1e-4)はこの不変条件を確認します。

EdgeMap

元画像のキャンバス上にある、float32の密なエッジ確率マップで、形状は(H, W)です。0は 非エッジ、1はエッジです。しきい値を呼び出し元が選べるよう、連続値マップが保持されます。 binary(threshold=0.5)がしきい値を適用し、arrayはnumpyビューを返します。

RestoredImage

復元されたRGB画像で、形式は(H, W, 3)のuint8です。超解像では、キャンバスは入力の Results.restore_scale倍になります。arrayはnumpyビューを返し、save(path)は画像を 書き出します。

Matte

元画像のキャンバス上にある、[0, 1]範囲のfloat32によるソフト不透明度マットで、形状は (H, W)です。1は完全な前景、0は完全な背景です。ソフトマットは0.5でしきい値処理した 強制的な背景除去マスクを包含し、バイナリマスクでは失われるアンチエイリアス処理済みの境界を 保持します。arrayはnumpyビューを返します。

マットの結果では、Results.cutout(image=None)が第4チャンネルをマットとするRGBAの (H, W, 4) uint8配列を返し、Results.save(path, image=None)がその切り抜きを透明背景の PNGとして書き出します。どちらもimageが指定されていればそこからRGBを取得し、それ以外は Results.pathから再読み込みします。

OCRRegions

位置が特定されたテキストと転記。dataは元画像のピクセル単位による(N, 4, 2)の浮動小数点 ポリゴンで、左上、右上、右下、左下の順です。領域は上から下、次に左から右という読み順で 並びます。textsはN個の転記のリストです。confは領域ごとの認識スコア、det_confは 検出スコアで、どちらも形状は(N,)です。

検出四角形は実際のポリゴンであるため、Results.boxesには格納されません。xyxyは軸平行の 外接矩形を返します。

Embeddings

embedタスクのL2正規化済みベクトルで、形状は常に(N, D)です。画像全体の結果は1行を持ち、 ボックスはありません。領域の埋め込みベクトルはboxesと行が対応します。各行は正規化されて いるため、コサイン類似度はドット積になります。

Identities

embeddingsと行が対応する、名前付きギャラリーとの一致結果。Galleryをembed推論に渡すと 生成されます。nameはリストで、一致のしきい値を下回る項目はNoneです。しきい値を下回る 最も近い名前が推測されることはありません。scoreは一致スコアの配列で、dataは名前と スコアをペアにします。

Meshes

boxesの人物ボックスと行が対応する、パラメトリックな人体メッシュ。すべて元画像のカメラ 座標系にあります。translはメートル単位の実測値で、+zはカメラから遠ざかる方向です。 verticesとjoints3dは実測値で、すでにtranslを含みます。joints2dはネットワークが 入力した切り抜きではなく、元画像のキャンバス上のピクセル単位です。ワールド座標系や重力 座標系を持つフィールドはありません。

パラメータの配置は人体モデルごとに異なるため、形状についてハードコードされているものは ありません。body_modelがパラメータ化方式を示し、num_vertices、num_joints、 num_betas、has_verticesの数値はテンソルから読み取られます。paramsはパラメータの dictを返し、save_obj(path, index=0)は1つのメッシュを書き出します。フィールドは global_orient、body_pose、betas、transl、vertices、faces、joints3d、 joints2d、conf、focal_length、extrasです。

body_model="mhr"の場合、回転は軸角ではなくラジアン単位のオイラー角です。body_poseは 関節ごとの3要素ではなく、関節ごとの平坦なパラメータベクトルで、betasは人物識別用の ブレンドシェイプ係数です。骨格スケール、手の姿勢、顔の表情はextrasに格納されます。

変換と選択

すべてのペイロードはto(*args, **kwargs)、cpu()、cuda()、numpy()を持ちます。 Resultsでいずれかを呼び出すと、格納済みのすべてのスロットへ一度に適用されます。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) # すべてのペイロードをまとめて移動result = result.cpu().numpy() # 行を通常のdictで取得し、次にJSONへ変換print(result.summary()[:1])print(result.to_json())

result[idx]は、行が対応するペイロード全体から行を選択します。len(result)は検出数で、 ボックスがなければ点の数です。result.update(...)は指定したスロットを置き換えたコピーを 返します。すべてのスロットに加えて、track_idとrestore_scaleを受け入れます。

summaryとto_json

summary(normalize=False, decimals=5, embeddings=False)は通常のdictのリストを返します。 どのスロットが設定されているかに応じて、検出、セグメント、点、または領域ごとに1行です。 to_json(**kwargs)は引数をsummaryへ渡し、JSON文字列を返します。

plot()はすべてのタスクのペイロードを描画します。画像への重ね合わせはデフォルトでBGR配列を返し、pil=TrueでPILを要求できます。深度マップ、法線マップ、エッジマップ、アルベドマップ、3D直方体、アクションチャンクは、デフォルトでPIL画像を返し、pil=Falseで配列を返します。

Boxes3D

Boxes3D(data, orig_shape=None, intrinsics=None)は(N, 14)の行を保持します。内容は中心xyz、寸法wlh、クォータニオンwxyz、順位付けスコア、クラスID、2D信頼度、3D信頼度です。座標はカメラ座標系のメートル単位で、xは右、yは下、zは前方です。世界座標系を意味しません。3x3の内部パラメータは元のキャンバスを基準とします。行はResults.boxesと対応します。

AlbedoMap

AlbedoMap(data, orig_shape=None)は線形RGBを保持します。表示用の変換ではsRGBを生成し、アルベドの定量的な検証では元の線形値を使います。

Actions

Actions(data, orig_shape=None, names=None, fps=None, instruction=None)は、float32のアクションチャンク(T, D)を表します。firstは最初の行を返し、スライスでタイムステップを選択します。値はポリシーのデータセットの単位を維持します。namesはアクションの各次元、fpsは制御レート、instructionは条件付けのテキストを表します。

GeneratedImage

GeneratedImage(data, orig_shape=None, *, prompt=None, seed=None, params=None)は、合成された1枚の画像を(H, W, 3)のuint8 RGBとして保持します。arrayはnumpyビューを、imageはPIL.Imageを返します。promptは画像を生成したテキスト、seedは同じモデルと設定でその画像を再現する整数です。paramsは呼び出しの残りの内容、つまりmodel、imgsz、有効なすべてのファミリー設定を記録します。save(path)は画像を書き出し、PNGの場合はto_dict()（形状、プロンプト、シード、params）もJSONとしてlibreyoloテキストチャンクに格納します。

生成結果では、Results.boxesとResults.pathはNone、orig_shapeは画像自身の(H, W)、len(result)は1です。Results.save(path)は画像を書き出し、plot()はそれをPIL画像として返し、summary()はペイロードの記録を含む1行を返します。

Gaussians

Gaussians(xyz, scales, rotations, opacities, sh, *, camera=None, seed=None, params=None, input_image=None)は、生成された1つの3Dオブジェクトを、オブジェクト自身の座標系でのガウシアンスプラットとして保持します：z軸が上で、立方体[-0.5, 0.5]^3の中心に配置されます。各行が1つのガウシアンです。

len(gaussians)はNで、gaussians[gaussians.opacities > 0.1]は選択した行を保持する新しいGaussiansを返します。save(path)は拡張子に応じて書き出します。.plyは標準の3D Gaussian Splattingレイアウトで、対数スケールとロジットの不透明度を使い、スプラットビューアーが想定するとおりy軸が上になるよう回転し、シード、カメラ、paramsをJSONとして保持するcomment libreyoloヘッダー行を含みます。高次の色（K > 1）を持つペイロードは、.plyではNotImplementedErrorを送出します。.splatはガウシアンあたり32バイトのコンパクトなWeb形式です。render(size=512, background=(0, 0, 0))は、ガウシアンのラスタライズではなく簡易確認用として、推定された入力ビューからの点レンダリングをPIL.Imageで返します。

生成された3D結果では、Results.boxesはNoneです。path、orig_shape、orig_imgはソース画像を表し、len(result)は1です。Results.save(path)はオブジェクトを書き出し、plot()はその点レンダリングを返し、summary()はペイロードの記録を含む1行を返します。