シーン
この内容はkognic-io>2.5.0のユーザーを対象としています。それより前のバージョンを使用している場合は、概要旧バージョンのドキュメントを参照するか、アップグレードしてください。
シーンとは、Kognicが一定期間（フレーム）にわたるセンサーリソースをまとめてグループ化するための単位です。
シーンモデルはSceneRequestから始まります：
class SceneRequest:
"""A scene request is used to create a scene in the Kognic platform.
Attributes:
workspace_id (str): The ID of the workspace where the scene will be created.
external_id (str): The external ID of the scene.
frames (List[Frame]): A list of frames that make up the scene.
sensor_specification (Optional[SensorSpecification]): Sensor specification let's the user set the order and display names of the sensors.
calibration_id (Optional[Calibration]): Calibration of the scene, required if the scene contains pointclouds.
metadata (Optional[dict]): Metadata for the scene.
imudata_resource (Optional[Resource]): IMU data of the scene, required for aggregation and motion compensation.
should_motion_compensate (Optional[bool]): Whether to motion compensate the scene.
postpone_external_resource_import (Optional[bool]): Whether to postpone the import of external resources. Only available for scenes with external resources.
"""
workspace_id: str
external_id: str
frames: List[Frame]
sensor_specification: Optional[SensorSpecification] = None
calibration_id: Optional[str] = None
metadata: Optional[dict] = None
imudata_resource: Optional[Resource] = None
should_motion_compensate: Optional[bool] = None
postpone_external_resource_import: Optional[bool] = Noneworkspace idは、シーンを作成するワークスペースを指定するために使用します。ワークスペースの詳細についてはこちらこちらを参照してください。
external idを使用すると、Kognicが生成する長いUUIDを参照しなくても、シーンについてやり取りできます。ただし、主キーはUUIDであり、シーンに対して操作を行う際にはUUIDが必要です。
Framesは、シーンで時間を表現するためのものです。各フレームは、センサーデータを伴う1つのタイムスタンプに対応します（IMUデータは通常はるかに高い周波数で記録されるため、これらのセンサーには含まれません）。フレームについては後ほど詳しく説明します。
Sensor specificationsは、センサーの表示方法に関する設定です。ここでは、各センサーの表示順序を設定したり、人が読みやすい表示名を付けたりできます。
Calibrationsは、1つ以上のLiDARリソースを指定する場合に使用します。キャリブレーションは、それを使用するシーンを作成する前に存在している必要があります。キャリブレーションの詳細についてはキャリブレーション概要こちらを参照してください。
Metadataは、シーンに関する追加データを追加できるフラットな辞書です。
IMU dataは、複数LiDARの点群のモーション補償に使用します。IMUのフォーマットについてはサポートされているファイルフォーマットこちらを参照してください。
Should motion compensate flagは、シーンに対してモーション補償を行うかどうかを決定するために使用します。
Postpone external resource importは、Kognicプラットフォームがシーンの処理をすぐに開始し、指定されたクラウドリソースを読み込むかどうかを決定します。そのため、このフラグは外部リソースを使用する場合にのみ有効です。trueに設定すると、シーンはindexedステータスで作成されます。インデックス済みシーンの詳細についてはこちらを参照してください。
フレーム
フレームオブジェクトにはシーンの情報の大部分が含まれており、以下のような構造になっています：
class Frame:
"""A frame is a collection of images and pointcloud at a given timestamp.
Attributes:
frame_id (str): The ID of the frame.
timestamp_ns (int): The timestamp of the frame in nanoseconds.
images (List[ImageResource]): A list of images in the frame.
pointclouds (Optional[List[SensorResource]]): A list of pointclouds in the frame.
ego_vehicle_pose (Optional[EgoVehiclePose]): The pose of the ego vehicle at the time of the frame, required if providing
pointclouds.
metadata (Optional[dict]): Metadata for the frame.
"""
frame_id: str
timestamp_ns: int
images: List[ImageResource]
pointclouds: Optional[List[SensorResource]] = None
ego_vehicle_pose: Optional[EgoVehiclePose] = None
metadata: Optional[dict] = Noneリソース
すべてのリソースは、ベースリソースを拡張したものです。ベースリソースは、データを指定するためのいくつかの方法を提供するために存在します。モデルは以下のとおりです：
class Resource:
external_resource_uri: Optional[str]
local_file: Optional[LocalFile]
class LocalFile:
filename: str
data: Optional[bytes] = None
callback: Optional[Callback] = Noneリソースには、データインテグレーションデータインテグレーションを指すURIであるexternal_resource_uri、またはローカルファイルのいずれかを指定できます。external_resource_uriを機能させるには、リンク先の説明に従ってデータインテグレーションを設定しておく必要があります。ローカルファイルは、ファイル名、バイトストリーム（data）、またはバイトストリームを返すコールバックの3つの方法で指定できます。いずれの場合も、Kognicプラットフォームはファイル名を使用してリソースを識別するため、ファイル名を指定する必要があります。
インデックス済みシーン
必要になるまでデータをKognicにアップロードせずに済むと便利な場合があります。例えば、膨大なデータセットのうち一部だけを確認したいものの、どのシーンを確認する必要があるかがアップロード時点ではわからない場合です。データセット全体をアップロードすると、データがお客様のクラウドからKognicのクラウドへ移動する際に大量のエグレスが発生します。そこで、シーンを定義しておき、必要になったときにだけインポートできるインデックス済みシーンを導入しました。インデックス済みシーンを使用するには、Kognicがお客様のクラウド内のデータにアクセスする方法を定義するデータインテグレーションデータインテグレーションを作成しておく必要があります。これにより、どのリソースがどのフレームに属するか、キャリブレーションがあるかどうかなど、シーンの定義だけを作成できます。Kognicはその定義を保存しますが、リソースをすぐに読み込む必要はありません。Kognicプラットフォームでシーンを使用する必要が生じたら、ボタンのクリックまたはAPI呼び出しによってシーンを利用可能にできます。その時点で、Kognicはお客様のクラウドからリソースを読み込み、処理してKognicのクラウドに保存します。
例
シーンの作成
例についてはシーンの例シーンの例を参照してください。
シーンの一覧を取得する
scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)インデックス済みシーンをインポートする
シーンがindexed状態にある場合、そのシーンをインポート、つまり「利用可能に」できます。kognic-ioにはそのためのメソッドがあります：
client.scene.import_indexed_scene("cca60a67-cb68-4645-8bae-00c6e6415555"シーンを再インデックスする
インデックス済みシーンのデータをKognicに保存しておく必要はなくなったものの、シーン自体は削除したくない場合は、以下を実行してシーンを再インデックス（indexed状態に戻す）できます：
client.scene.reindex_scene("cca60a67-cb68-4645-8bae-00c6e6415555"