--- title: 予測フォーマット slug: api-guide/ja/xHzmWeiENe6M5kh9YQ8mv docTags: createdAt: 2024-12-16T13:47:19.008Z --- 予測にはJSON形式で表現される[OpenLabelフォーマット](https://www.asam.net/standards/detail/openlabel/)を使用します。これは[プレアノテーション](docId\:PsyfyK8rAnHGWTwMoztAv)のアップロードに使用されるフォーマットと同じです。OpenLabelフォーマットの一般的な情報については、[OpenLABEL形式](docId\:TfDIV3dLaaFNDEhaklui-)をご覧ください。 ## サポートされる予測機能 現在の予測アップロードAPIは、以下のジオメトリをサポートしています： | 名前 | OpenLABELフィールド | 説明 | | ----------------- | -------------- | ------------------ | | キューボイド | `cuboid` | 3Dキューボイド | | バウンディングボックス | `bbox` | 2Dバウンディングボックス | | ビットマップ（セグメンテーション） | `image` | 画像用セグメンテーションビットマップ | キューボイドの回転は、エクスポート時（[OpenLABEL形式](docId\:TfDIV3dLaaFNDEhaklui-)）と同じにしてください（詳細は[座標系](docId:3jKwDhQCmVNvBuZboUZMr)を参照）。2Dジオメトリはピクセル座標で表現してください。 このAPIでは、関連する部分（キー）は`frames`、`objects`、`streams`、`ontologies`、および`metadata`です。最後の`metadata`は最も簡単で、`schema_version": "1.0.0"`と記述するだけです（完全なコンテキストについては以下の例を参照）。また、`stream`も簡単で、どのセンサー（カメラ、LiDARなど）があるか、およびその名前を指定します（例：`sensor_name: {"type": "camera"}`や`sensor_name: {"type": "lidar"}`）。こちらも完全なコンテキストについては以下の例を参照してください。 シーケンス全体で時間的に変化する予測のすべての部分（座標や動的プロパティなど）は`frames`に記述されます。シーケンスの各フレームは`frames`内のキーと値のペアで表現されます。キーは`frame_id`で、値は以下のようになります： ```none frame_id: { "frame_properties": { "timestamp": 0, "external_id": "", "streams": {} }, "objects": { ... } } ``` `frame_properties.timestamp`の値（ミリ秒単位、非シーケンスデータの場合は`0`に設定することを推奨）は、各予測フレームを該当するアノテーション済みフレームとマッチングするために使用されるため、アノテーションされたシーンと一致する必要があります。`frame_id`（文字列）は、基となるシーンの記述に使用される`frame_id`に従うことを推奨しますが、不一致の場合は`frame_properties.timestamp`が優先されます。非シーケンスデータの場合、`frame_id`には`"0"`が適切です。`frame_properties.external_id`と`frame_properties.stream`の値は、図のように空のままにすると自動的に解決されます。 `objects`キーには、キーと値のペアが含まれ、各ペアは基本的にそのフレーム内の1つのオブジェクトを表します。`objects`キーは各フレーム内とルートの両方に存在することに注意してください。基本的に同じオブジェクトを記述しますが、時間的に変化する可能性のある情報（座標など、フレーム固有の情報）はフレームに属し、静的な情報（オブジェクトクラスなど）はルートに属します。オブジェクトキー（文字列）は任意ですが、同じオブジェクトを記述する場合は、異なる`objects`内のキーが一致する必要があります。 オブジェクトの詳細な記述方法については、以下の例を参照してください。キューボイドとバウンディングボックスには、フレーム固有の属性`confidence`を指定することで存在信頼度を提供できます。値は0.0から1.0の間の数値である必要があり、空の場合は`1.0`に設定されます。指定する場合は、数値として定義する必要があります。静的な`object_data.type`は、ツール内でクラス名として表示されます。 セグメンテーションビットマップの場合、画像自体はアノテーション対象画像と同じ解像度のグレースケール8ビットPNG画像です（実際の予測がアノテーション画像を部分的にしかカバーしていない場合や解像度が低い場合は、パディングやアップスケーリングが必要です）。画像自体は、base64エンコードされた文字列としてフレームのオブジェクトにペーストすることでOpenLabel内に提供されます。以下の例を参照してください。さらに、各色レベルに対応するクラスを記述する`ontology`も提供する必要があります。8ビットグレースケール画像では、最大256クラスをエンコードできます。セグメンテーション以外の予測では、`ontology`は省略できます。 以下の例の`camera_id`は、アノテーション済みシーンのセンサーIDと一致する必要があります。一方、LiDARセンサーの対応するIDは`@lidar`に設定してください。 ## 予測の例 ### 静的プロパティ`color`を持つ2フレームの2Dバウンディングボックス OpenLabelでは、バウンディングボックスは4つの値のリスト`[x, y, width, height]`として表現されます。`x`と`y`はバウンディングボックスの中心座標です。`width`と`height`はバウンディングボックスの幅と高さです。`x`と`y`の座標は画像の左上隅を基準とします。 ```json { "openlabel": { "frames": { "0": { "frame_properties": { "timestamp": 0, "external_id": "", "streams": {} }, "objects": { "1232b4f4-e3ca-446a-91cb-d8d403703df7": { "object_data": { "bbox": [ { "attributes": { "num": [ { "val": 0.85, "name": "confidence" } ], "text": [ { "name": "stream", "val": "camera_id" } ] }, "name": "any-human-readable-bounding-box-name", "val": [ 1.0, 1.0, 40.0, 30.0 ] } ] } } } }, "1": { "frame_properties": { "timestamp": 50, "external_id": "", "streams": {} }, "objects": { "1232b4f4-e3ca-446a-91cb-d8d403703df7": { "object_data": { "bbox": [ { "attributes": { "num": [ { "val": 0.82, "name": "confidence" } ], "text": [ { "name": "stream", "val": "camera_id" } ] }, "name": "any-human-readable-bounding-box-name", "val": [ 2.0, 3.0, 30.0, 20.0 ] } ] } } } } }, "metadata": { "schema_version": "1.0.0" }, "objects": { "1232b4f4-e3ca-446a-91cb-d8d403703df7": { "name": "any-human-readable-bounding-box-name", "object_data": { "text": [ { "name": "color", "val": "red" } ] }, "type": "PassengerCar" } }, "streams": { "camera_id": { "type": "camera" } } } } ``` ### 静的プロパティ`color`を持つ2フレームの3Dキューボイド キューボイドは10個の値のリスト`[x, y, z, qx, qy, qz, qw, width, length, height]`として表現されます。`x`、`y`、`z`はキューボイドの中心座標です。`x`、`y`、`z`、`width`、`length`、`height`の単位はメートルです。`qx`、`qy`、`qz`、`qw`はキューボイドの回転を表すクォータニオン値です。 座標系とクォータニオンの詳細については、[OpenLABEL形式](docId\:TfDIV3dLaaFNDEhaklui-)をご覧ください。 ```json { "openlabel": { "frames": { "0": { "frame_properties": { "timestamp": 0, "external_id": "", "streams": {} }, "objects": { "1232b4f4-e3ca-446a-91cb-d8d403703df7": { "object_data": { "cuboid": [ { "attributes": { "num": [ { "val": 0.85, "name": "confidence" } ], "text": [ { "name": "stream", "val": "@lidar" } ] }, "name": "any-human-readable-cuboid-name", "val": [ 2.079312801361084, -18.919870376586914, 0.3359137773513794, -0.002808041640852679, 0.022641949116037438, 0.06772797660868829, 0.9974429197838155, 1.767102435869269, 4.099334155319101, 1.3691029802958168 ] } ] } } } }, "1": { "frame_properties": { "timestamp": 50, "external_id": "", "streams": {} }, "objects": { "1232b4f4-e3ca-446a-91cb-d8d403703df7": { "object_data": { "cuboid": [ { "attributes": { "num": [ { "val": 0.87, "name": "confidence" } ], "text": [ { "name": "stream", "val": "@lidar" } ] }, "name": "any-human-readable-cuboid-name", "val": [ 3.123312801361927, -20.285740376586913, 0.0649137773513349, -0.002808041640852679, 0.022641949116037438, 0.06772797660868829, 0.9974429197838155, 1.767102435869269, 4.099334155319101, 1.3691029802958168 ] } ] } } } } }, "metadata": { "schema_version": "1.0.0" }, "objects": { "1232b4f4-e3ca-446a-91cb-d8d403703df7": { "name": "any-human-readable-cuboid-name", "object_data": { "text": [ { "name": "color", "val": "red" } ] }, "type": "PassengerCar" } }, "streams": { "@lidar": { "type": "lidar" } } } } ``` ### 単一フレームのセグメンテーションビットマップ ### Python PILを使用した小さなカラー画像の変換、アップスケーリング、パディング、およびbase64エンコードによる大きなグレースケール画像への変換 このコード例は、解像度300 x 200のマルチカラー予測ビットマップ画像を、解像度1000 x 800のグレースケール画像に変換する方法を示しています。まずグレースケールに変換し、次に予測を600 x 400にリスケーリングし、両側に均等にパディングします。また、OpenLabelで使用できるように、画像をbase64エンコードされた文字列に変換するコードも含まれています。このコードは組み込みのnumpy関数のみを使用しており、パフォーマンスの最適化は行われていません。 ```python import base64 import io import numpy as np from PIL import Image # The original mapping used to produce the images original_mapping = { (0,0,0): "_background", (255,0,0): "class_1", (0,0,255): "class_2", } # The grayscale mapping (this will also be the ontology in the openlabel) grayscale_mapping = { "_background": 0, "class_1": 1, "class_2": 2, } prediction = Image.open("my_original_prediction_file.png") # Let's say this has resolution 300 x 200 def lookup(pixel_color): return grayscale_mapping[original_mapping[tuple(pixel_color)]] # convert to grayscale via numpy array lookup prediciton_numpy = np.array(prediction) grayscale_prediction_numpy = np.vectorize(lookup, signature="(m)->()")(prediciton_numpy) grayscale_prediction = Image.fromarray(grayscale_prediction_numpy.astype(np.uint8)) # upscale to another resolution upscaled_grayscale_prediction = grayscale_prediction.resize((600, 400), resample=Image.Resampling.NEAREST) # padding by first constructing a new background image of target size, and then paste the prediction in the right position padded_grayscale_prediction = Image.new("L", (1000, 800), 0) padded_grayscale_prediction.paste(upscaled_grayscale_prediction, (201, 201)) image_bytes = io.BytesIO() padded_grayscale_prediction.save(image_bytes, format="PNG") prediction_str = base64.b64encode(image_bytes.getvalue()).decode("utf-8") ``` ### セグメンテーションビットマップ用のOpenLabel `prediction_str`と`grayscale_mapping`は、その後OpenLabel内で以下のように使用できます： ```json { "openlabel": { "frames": { "0": { "objects": { "07d469f9-c9ab-44ec-8d09-0c72bdb44dc2": { "object_data": { "image": [ { "name": "a_human_readable_name", "val": prediction_str, "mime_type": "image/png", "encoding": "base64", "attributes": { "text": [ { "val": "camera_id", "name": "stream" } ] } } ] } } }, "frame_properties": { "streams": {}, "timestamp": 0, "external_id": "" }, } }, "objects": { "07d469f9-c9ab-44ec-8d09-0c72bdb44dc2": { "name": "07d469f9-c9ab-44ec-8d09-0c72bdb44dc2", "type": "segmentation_bitmap" } }, "streams": { "camera_id": { "type": "camera" } }, "metadata": { "schema_version": "1.0.0" }, "ontologies": { "0": { "classifications": {str(v): k for k, v in grayscale_mapping.items()}, "uri": "" } } } } ``` シーン内の複数のカメラに対して予測を提供する場合は、画像のリストを拡張できます。 ### `kognic-openlabel`を使用してフォーマットを検証 詳細については[kognic-openlabel](https://pypi.org/project/kognic-openlabel/)を参照してください。