概要

さまざまな種類のシーン シーンとは、まとめてアノテーションされるべきセンサーデータ（カメラ画像、ライダー点群）のグループを表します。シーンには、センサー間の関係、カメラ解像度、センサー名、データ記録頻度に関する情報が含まれます。 シーンはセンサータイプによって異なります。カメラのみのデータには cameras シーンタイプを使用します。ライダーとカメラを組み合わせたデータには lidarsandcameras タイプを使用します。シーンは単一フレームまたはシーケンスタイプのいずれかです。 シーケンシャルシーンと非シーケンシャルシーン シーケンシャルシーンはフレームの時系列シーケンスを表し、非シーケンシャルシーンは1つのセンサーデータのスナップショットのみを含みます。シーケンシャルの関係はフレームのシーケンスで表現され、各フレームにはセンサーデータ情報と相対タイムスタンプが含まれます。非シーケンシャルシーンにはタイムスタンプ情報は不要です。 シーケンシャルシーンタイプは、タイプ名の末尾に seq が付いていることで識別されます シーンタイプには、 cameras lidarsandcameras camerasseq lidarsandcamerasseq aggregatedlidarsandcamerasseq シーンのフィールド 非シーケンシャルシーンの構造は以下のとおりです。 class scene(basemodel) external id str frame frame sensor specification sensorspecification calibration id optional\[str] # required if using lidar sensors metadata mapping\[str, union\[int, float, str, bool]] = field(default factory=dict) シーケンシャルシーンも同様の構造で表現されますが、単一のフレームの代わりにフレームのリストを含みます。 class sceneseq(basemodel) external id str frames list\[frame] sensor specification sensorspecification calibration id optional\[str] # required if using lidar sensors metadata mapping\[str, union\[int, float, str, bool]] = field(default factory=dict) 外部id シーンは作成時に自動的にuuidが付与され、kognicの主要な識別子として機能します。シーンをより簡単に参照するために、外部idも必要です。 センサー仕様 使用するカメラおよび/またはライダーセンサーに関する情報を含みます。オプションフィールドでは、カメラ画像の順序や、アノテーションアプリに表示される人が読みやすいセンサー名（例：「fc」の代わりに「front camera」）を指定できます。 例として、エゴビークルに3つのカメラセンサー r 、 f 、 l が搭載されているとします。センサー仕様の作成は以下のようになります。 from kognic io model import sensorspecification sensor spec = sensorspecification( sensor to pretty name={ "r" "right camera", "f" "front camera", "l" "left camera" }, sensor order=\["l", "f", "r"] ) sensor order はカメラ画像の順序を設定し、 sensor to pretty name はkognicアノテーションアプリで表示される際のラベルに影響します。 キャリブレーション ライダーとカメラセンサーで構成されるシーンにはキャリブレーションが必要です。キャリブレーションはセンサー間の空間的な関係（位置と回転）およびカメラの内部パラメータを指定します。ただし、ライダーセンサーを含まないシーンにはキャリブレーションは不要です。キャリブレーションはkognicアノテーションアプリによって、カメラ画像が選択された際に点群内の領域を投影するため、また同様に点群内で選択されたオブジェクト（点、キュービoidなど）を画像に投影するために使用されます。キャリブレーションを作成する際、すべてのセンサーはシーンに存在するセンサーと一致している必要があります。一致しない場合、シーンは作成されず、kognic apiからバリデーションエラーが返されます。apiを介したキャリブレーションの作成に関する詳細なドキュメントは、 docid 40ujebw5cst4e4djxsgty に記載されています メタデータ メタデータは metadata フィールドを介してシーンに追加できます。フラットなキーと値のペアで構成されており、ネストされたデータ構造は使用できません。メタデータはシーンに関する追加情報を含めるために使用できます。メタデータはアノテーターには表示されませんが、kognicアノテーションツールの動作を変更できる予約済みキーワードがいくつかあります。予約済みキーワードはpythonクライアントの metadata オブジェクトに記載されています。 フレー frame オブジェクトは、アノテーション対象のバイナリデータ（ jpg、 png、 lasなど）と、そのデータの元となったセンサーを指定します。 frame オブジェクトは全体的な構造は似ていますが、シーンタイプごとに異なることに注意してください（詳細は以下を参照）。 非シーケンシャルフレー 例として、3つのカメラセンサー r 、 f 、 l からの画像で構成されるシーンを作成するとします。対応するバイナリデータはファイル img cam r jpg 、 img cam f jpg 、 img cam l jpg に格納されています。これはシーンタイプ cameras に対応します。 from kognic io model scene resources import image from kognic io model scene cameras import cameras, frame cameras scene = cameras( , frame=frame( images=\[ image("img cam r jpg", sensor name="r"), image("img cam f jpg", sensor name="f"), image("img cam l jpg", sensor name="l"), ] ) ) 同様に、センサーvdl 64からの関連するライダー点群と対応するバイナリファイル scan vdl 64 las がある場合は、代わりにシーンタイプ lidarsandcameras を使用します。 frame クラスは対応するシーンタイプの下からインポートする必要があることに注意してください。 from kognic io model scene resources import image, pointcloud from kognic io model scene lidars and cameras import lidarsandcameras, frame lidars and cameras = lidarsandcameras( , frame=frame( images=\[ image("img cam r jpg", sensor name="r"), image("img cam f jpg", sensor name="f"), image("img cam l jpg", sensor name="l"), ], point clouds=\[ pointcloud("scan vdl 64 las", sensor name="vdl 64") ] ) ) シーケンシャルフレー シーケンシャルシーンは、単一の frame の代わりに frame オブジェクトのリストを受け取ります。また、シーケンシャルシーンに関連する frame オブジェクトには、 frame id 、 relative timestamp 、 metadata の3つの追加パラメータがあります。シーケンシャルの関係はframeのリストの順序によって表現されます。異なるフレーム間の経過時間を表すには、各 frame の relative timestamp パラメータを使用します。相対タイムスタンプはミリ秒単位で表され、frameとシーンの開始時点との相対的な時間を表します。例えば、センサーデータが2hzで収集・集約されているとします。 frame 1 = frame( , relative timestamp=0) frame 2 = frame( , relative timestamp=500) frame 3 = frame( , relative timestamp=1000) frames = \[frame 1, frame 2, frame 3] frame id はフレームのリスト内で各フレームを一意に識別する文字列です。一般的な使用例として、各 frame id に uuid を使用するか、 external id とフレームインデックスを組み合わせる方法があります。例えば、シーンの external id が shanghai 20200101 の場合、 frame id は最初のフレームを shanghai 20200101 0 、2番目のフレームを shanghai 20200101 1 というようにエンコードできます。シーケンシャルフレームではフレームレベルのメタデータを提供することも可能です。フラットなキーと値のペアで構成され、アノテーション作業中にアノテーターには表示されません。例として、2つのセンサーrとlからのカメラ画像を持つ2フレームで構成される camerassequence タイプのシーンを作成するとします。 from kognic io model scene resources import image from kognic io model scene cameras sequence import camerassequence, frame frames = \[ frame( frame id="1", relative timestamp=0, images=\[ image("img l 1 jpg", sensor name='l'), image("img r 1 jpg", sensor name='r') ]), frame( frame id="2", relative timestamp=500, images=\[ image("img l 2 jpg", sensor name='l'), image("img r 2 jpg", sensor name='r') ]) ] cameras sequence = camerassequence(frames=frames, ) 画像と点群のリソース センサーデータを含むすべてのファイルは resource として表現され、 image と pointcloud がその具体的なサブクラスです。 class resource(abc, baseserializer) filename str resource id optional\[str] = none sensor name str file data optional\[filedata] = field(default=none, exclude=true) resource は最終的に、バイナリまたはテキストのセンサーデータを取得する方法を記述するもので、以下のさまざまな方法で実現できます 間接的に：データを含むローカルファイル名を参照する 直接的に：作成時にバイトライクオブジェクトを提供する 遅延的に：後のプロセスでバイトを提供できるコールバック関数を指定する resource には常に filename を指定する必要があります。方法1の場合、これはアップロードするローカルファイルを指す必要があります。方法2および3の場合、 filename パラメータの値は識別子として扱われます。アップロードされるファイルの名前付けに使用されますが、ファイルシステム上のパスと一致している必要はありません。 resource には常に sensor name があり、データが取得されたセンサーを識別します。シーケンシャルシーンでは、各 frame に各センサーの resource が含まれます 上記の方法2および3では、 filedata オブジェクトを resource （imageまたはpointcloud）に付加してデータのソースを指定します。 filedata は data uploadabledata または callback callable\[\[str], uploadabledata] のいずれかと、バイトに含まれるデータの種類を識別する format を指定して作成します。以下にその例を示します。 uploadabledata は生データのサポートされるソース（ bytes 、 binaryio 、 iobase 、およびそれらの bytes のジェネレーターと非同期ジェネレーター）に対する型エイリアスです。 以前のapiクライアントのリリースでは、 gs\ //bucket/path/file などの外部uriからのファイル取り込みのサポートが案内されていました。今後この機能が必要な場合は、kognicにお問い合わせください。 ローカルファイル filename をローカルファイルのパスに設定し、他の方法（直接またはコールバック）でデータを提供しないでください。コンテンツは filename のサフィックスから推定されたコンテンツタイプを使用してアップロードされます image(filename="/path/to/images/img fc png", sensor name="fc") メモリ内データ filename に加えて、 file data 属性を介して filedata オブジェクトを提供します。 filedata オブジェクトは uploadabledata を data 属性として持ちます。この例では生の bytes を使用します。 image( filename="fc frame15", sensor name="fc", file data=filedata(data=b'some png bytes', format=filedata format png) ) コールバックからのデータ filename に加えて、file data属性を介して filedata オブジェクトを提供します。 filedata オブジェクトには uploadabledata を生成する callback 関数を指定します。例： image( filename="fc frame15", sensor name="fc", file data=filedata(callback=get png, format=filedata format png) ) コールバック関数（get png）は以下のシグネチャを持つ単項関数です。 def get png(filename str) > uploadabledata pass コールバック関数は、単一ファイルのアップロード時に resource filename を引数として呼び出されます。コールバックに追加の引数が必要な場合は、以下のように追加の引数をクロージャでラップすることを推奨します def get callback(arg1, arg2, kwargs) def callback(filename) > bytes \# use arg1, arg2, filename and kwargs return callback filedata( callback=get callback("foo", "bar", extra1="baz", extra2="qux"), format=filedata format jpg ) データストリーム 非同期コールバックを使用すると、特にデータがローカルで利用できない場合に、データのアップロードを高速化するのに役立ちます。同期コールバックと同様に、コールバック関数は単一ファイルのアップロード時に resource filename を引数として呼び出されます。非同期コールバックは以下の方法で使用できます。 async def get png(filename str) > uploadabledata pass image( filename="fc frame15", sensor name="fc", file data=filedata(callback=get png, format=filedata format png) ) データストリーム filename に加えて、 file data 属性を介して filedata オブジェクトを提供します。 filedata オブジェクトの callback 属性にはバイトジェネレーターまたは非同期ジェネレーターを指定します。この例では、非同期ジェネレーターを使用してローカルファイルを小さなチャンクで非常にゆっくりとストリーミングします。 async def slow stream(filename str) > asyncgenerator\[bytes, any] with open(filename, "rb") as f while chunk = f read(1024) asyncio sleep(1) yield chunk image( filename="fc frame15", sensor name="fc", file data=filedata(callback=slow stream, format=filedata format png) ) imuデータ 慣性計測装置（imu）データは、lidarの点群を含むシーンに対して提供できます。これは複数ライダー構成でのモーション補償を実行するために使用でき、デフォルトではimuデータが提供された場合にモーション補償が実行されます。アップロード前にすでにモーション補償が実行済みの場合は、 docid\ r7jjwwzw8kl3lux52wdod でモーション補償を無効化できます。 docid unwsc cucoyh mu9josc を参照してください。 シーンのフィーチャーフラグ シーン作成プロセスのオプション部分は、シーンの作成操作を呼び出す際に渡す featureflags で制御できます。詳細は docid\ r7jjwwzw8kl3lux52wdod を参照してください。