シーンとインプットの操作
さまざまなシーンモダリティの詳細については、==!シーンタイプ!==セクションを参照してください。
Kognicユーザーとして、KognicIOClientコンストラクタにclient_organization_idを指定することで、クライアント組織に代わってシーンを作成できます。
シーンの作成
各シーンリソースには、対応するタイプのシーンを作成するためのcreateメソッドがあります。対応するシーンモデルを入力として受け取ります。例えば、Camerasシーンを作成するには以下のようにします。
from kognic.io.model.scene.cameras import Cameras
scene = Cameras(...)
created_scene = client.cameras.create(cameras_scene)
scene_uuid = created_scene.uuidご覧のとおり、createメソッドは関連するscene_uuidを返します。このscene_uuidは後でシーンの操作に使用できます。この時点ですべてのファイルがKognic Platformにアップロードされ、シーンの前処理が開始されます。前処理が完了すると、シーンが作成されたとみなされます。さまざまなシーンステータスの詳細については、シーンステータスセクションを参照してください。
実験中はdryrunパラメータを使用すると便利です。これにより、シーンのフォーマットを検証しますが、シーンは作成されません。
シーンステータス
シーンがアップロードされると、プラットフォームで利用可能になる前に前処理が行われる場合があります。このプロセス中、シーンのstatusプロパティを使用して進捗状況を追跡できます。
Status | 説明 |
|---|---|
indexed | シーンはクラウドリソースで作成・検証済みですが、クラウドからデータは送出されていません。UIまたはAPIで利用可能にするまでこの状態が維持されます。 |
pending | シーンは検証済みですが、サーバーは関連リソースのアップロードを待機しています。 |
processing | 関連データがアップロードされ、Kognic Platformによって処理中です。ファイルフォーマットの変換が行われる場合があります。 |
created | シーンが作成され、プラットフォームで利用可能です。 |
failed | シーンの変換に失敗しました。詳細は関連するエラーメッセージを参照してください。 |
invalidated | シーンがロードされなかったため無効化されました。 |
invalidated | 複数回アップロードされたため無効化されました。 |
invalidated | シーンが正しく作成されなかったため無効化されました |
シーンからインプットを作成する
シーンが作成されると、プロジェクトとインプットバッチに関連付けることでインプットを作成できます。以下のプロジェクト設定を例に考えます。
organization # root for projects and scenes
└── projects
├── project-a
├── batch-1 - completed
├── batch-2 - open
├── request-1
├── input 9c08f7a3-3216-4bd6-a41a-1dda6f66f53e – using scene 0edb
├── input ddf548e3-9806-433c-afb5-fb951a721462 - using scene 37d9
└── ...
└── request-2
└── batch-3 - pending
└── project-b
├── batch-1
└── ...
└── scenes
├── scene 0edb8f59-a8ea-4c9b-aebb-a3caaa6f2ba3
├── scene 37d9dda4-3a29-4fcb-8a71-6bf16d5a9c36
└── ...create_from_sceneメソッドはシーンからインプットを作成するために使用します。このメソッドはシーンのUUIDと、プロジェクト、バッチ、アノテーションタイプなどのアノテーション情報を入力として受け取ります。例えば、project-aとbatch-2にインプットを作成するには以下のようにします。
client.cameras.create_from_scene(
scene_uuid="0edb8f59-a8ea-4c9b-aebb-a3caaa6f2ba3",
project="project-a", # Important: this is the external id and not the title
batch="batch-2" # Important: this is the external id and not the title
)上記のコードは、プロジェクトproject-aのバッチbatch-2内のすべてのリクエストに対して、シーンのインプットを作成します。batchパラメータが省略された場合、そのプロジェクトの最新のオープンバッチが使用されます。同じシーンを後で他のプロジェクトやバッチのインプット作成に再利用することもできます。
インプットを直接作成する
上記の2ステップのプロセスの代わりに、インプットを直接作成すると便利な場合がよくあります。これを行うには、対応するシーンタイプのcreateメソッドにアノテーション情報を直接渡すだけです。例えば、project-aとbatch-2にインプットを作成するには以下のようにします。
client.cameras_sequence.create(
...,
project="project-a", # Important: this is the external id and not the title
batch="batch-2" # Important: this is the external id and not the title
)これによりシーン作成プロセスが開始され、シーンが作成されると、指定されたバッチ内のすべてのリクエストに入力が作成されます。batchパラメータが省略 された場合、プロジェクトの最新のオープンバッチが使用されます。このプロセスを支援するラッパー関数create_inputsも提供しています。参照してください 。
これによりシーン作成プロセスがトリガーされ、シーンが作成されると、指定されたバッチ内のすべてのリクエストにインプットが作成されます。batchパラメータが省略された場合、そのプロジェクトの最新のオープンバッチが使用されます。このプロセスを補助するラッパー関数create_inputsも提供しています。詳細は1回の呼び出しで複数のインプットを作成するを参照してください。
シーンの一覧を取得する
この機能はバージョン1.6.0で追加されました。
Kognic Platformにアップロードされたシーンの一覧を取得することが役立つ場合があります。例えば、シーン作成中にステータスを確認する際などに使用します。シーンは以下の方法で取得できます。
scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)レスポンス
レスポンスは以下のプロパティを含むSceneオブジェクトのリストです。
インプットの一覧を取得する
この機能はバージョン1.7.0で追加されました。
インプットはquery_inputsメソッドを使用してプラットフォームから取得できます。使用方法は以下のとおりです。
scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)入力のクエリに使用できる追加のフィルタパラメータを以下に示します。
パラメータ | 説明 |
|---|---|
project | フィルタするプロジェクト識別子 |
batch | どのバッチの入力を返すかを指定するプロジェクト内のバッチ |
scene_uuids | 指定されたUUIDに一致するシーンを使用する入力を返す |
external_ids | 指定されたexternal_idsに一致するシーンを使用する入力を返す |
レスポンス
レスポンスは、以下のプロパティを含むInputオブジェクトのリストです
プロパティ | 説明 |
|---|---|
uuid | Kognicプラットフォーム内で入力を識別するために使用されるID |
scene_uuid | 入力が使用しているシーンを識別するために使用されるID |
request_uid | 入力が属するリクエストを識別するために使用されるID |
view_link | Kognicプラットフォームで入力を表示するためのURL |
シーンの無効化
注意
この機能はバージョン1.6.0で追加されました
作成されたシーンに関する上流の問題が検出された場合、シーンを無効化できます。これは、開発中やデータに問題が検出された場合に便利です。シーンを無効化すると、リクエストから削除され、そのシーンを使用するすべての入力が削除されます。さらに、無効化されたシーンはアノテーションを生成せず、そのシーンの完了済みアノテーションも削除されます。この操作は元に戻すことができないため、慎重に使用してください。
from kognic.io.model.scene.invalidated_reason import SceneInvalidatedReason
scene_uuids = ["0edb8f59-a8ea-4c9b-aebb-a3caaa6f2ba3", "37d9dda4-3a29-4fcb-8a71-6bf16d5a9c36"]
reason = SceneInvalidatedReason.BAD_CONTENT
client.scene.invalidate_scenes(scene_uuids, reason)インプットの取得に使用できる追加のフィルターパラメータを以下に示します。
理由 | 説明 |
|---|---|
bad-content | シーンがロードされないか、無効なキャリブレーションなどの誤ったメタデータが含まれている |
duplicate | 同じシーンが複数回作成された場合 |
incorrectly-created | シーンが意図せず作成された場合 |
インプットを削除する
この機能はバージョン1.6.0で追加されました。
作成されたインプットに関連する問題が上流で検出された場合、インプットを削除することができます。これは、問題がシーン自体ではなくインプットに関連している場合に役立ちます。例えば、ライダーとカメラのシーンに2つのインプットがある場合、一方は2D/3Dでアノテーションを行い、もう一方は2Dのみでアノテーションを行うとします。問題がキャリブレーションの誤りである場合、2Dインプットはそのまま使用できますが、2D/3Dインプットは削除する必要があります。
インプットを削除すると、そのインプットに対するアノテーションは生成されなくなり、完了済みのアノテーションも削除されます。この操作は元に戻すことができないため、慎重に使用してください。
input_uuid = "9c08f7a3-3216-4bd6-a41a-1dda6f66f53e"
client.input.delete_input(input_uuid)1回の呼び出しで複数のインプットを作成する
この機能はバージョン1.1.9で追加されました。
インプットの作成プロセスは非同期であるため、処理を続行する前にインプットの作成を待機することが役立つ場合があります。これを実現するために、複数のシーンとインプットを作成し、作成（または失敗）されるまで待機して結果を返すラッパー関数create_inputsを提供しています。この関数は、すべてのインプットがいずれかの方法で完了するか、返す結果が生じるまでブロックします。この関数はSceneWithPreannotation（シーンとオプションのプレアノテーションを含む新しいラッパーオブジェクト）のリストと、通常のインプット作成パラメータを受け取ります。
from kognic.io.tools.input_creation import create_inputs, SceneWithPreAnnotation, InputCreationStatus
from kognic.io.model.scene import LidarsAndCamerasSequence
from kognic.openlabel.models import OpenLabelAnnotation
scenes_with_pre_annotations: List[SceneWithPreAnnotation] = [
SceneWithPreAnnotation(
scene=LidarsAndCamerasSequence(...),
preannotation=OpenLabelAnnotation(...) # Optional
),
...
]
for input_result in create_inputs(client, scenes_with_pre_annotations, "project-identifier", batch="batch-identifier"):
# Do something with the result
if input_result.status == InputCreationStatus.CREATED:
print(f"Input {input_result.external_id} was created, got uuid {input_result.input_uuid}")
elif input_result.status == InputCreationStatus.FAILED:
print(f"Input {input_result.external_id} failed to be created at stage {input_result.error.stage} with error {input_result.error.message}")
else:
print(f"Input {input_result.external_id} is in status {input_result.status}")この関数はwait_timeoutとsleep_timeパラメータも受け付けることに注意してください。これらは待機動作を制御するために使用できます。wait_timeoutパラメータはインプットの作成/失敗を待機する最大時間を指定し、sleep_timeは各チェック間のスリープ時間を指定します。単位は秒です。インプットの作成にかかる時間はサイズと作成するインプットの数によって異なるため、wait_timeoutは適切に設定する必要があります。デフォルト値は30分で、すべてのシーンジョブがコミットされた時点から計測されます。
シーン作成の完了を待機する
処理を続行する前にシーンの作成完了を待機することが役立つ場合があります。これはutils.pyの以下の例を使用して実現できます。
import time
from kognic.io.client import KognicIOClient
from kognic.io.model import SceneStatus
def wait_for_scene_job(client: KognicIOClient, scene_uuid: str, timeout=20) -> SceneStatus:
start_time = time.time()
while (time.time() - start_time) < timeout:
response = client.scene.get_scenes_by_uuids(scene_uuids=[scene_uuid])
scene = response[0]
if scene.status in [SceneStatus.Created, SceneStatus.Failed]:
return scene.status
time.sleep(1)
raise Exception(f"Job was not finished: {scene_uuid}")