シーンとインプットの操作

16 分

注記

さまざまなシーンモダリティの詳細については、シーンタイプのセクションを参照してください。

Kognicユーザー向け

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プラットフォームにアップロードされ、シーンの前処理が開始されます。前処理が完了すると、シーンが作成されたとみなされます。さまざまなシーンステータスの詳細については、シーンとインプットの操作シーンステータスセクションを参照してください。

試行錯誤する際は、dryrunパラメータを使用すると便利な場合がよくあります。これにより、シーンのフォーマットを検証しますが、シーンは作成されません。

シーンステータス

シーンがアップロードされると、プラットフォームで利用可能になる前に前処理が行われる場合があります。このプロセス中、シーンのstatusプロパティを使用して進捗状況を追跡できます。

ステータス	説明
indexed	シーンはクラウドリソースで作成・検証済みですが、お客様のクラウドからデータは送出されていません。誰かがUIまたはAPIで利用可能にするか、そのシーンを使用してリクエストインプットを作成するまで、この状態が維持されます。
pending	シーンは検証済みですが、サーバーは関連リソースのアップロードを待機しています。
processing	関連データがアップロードされ、Kognicプラットフォームによって処理中です。ファイルフォーマットの変換が行われる場合があります。
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も提供しています。詳細は1回の呼び出しで複数のインプットを作成するを参照してください。

シーンの一覧を取得する

Kognicプラットフォームにアップロードされたシーンの一覧を取得することが役立つ場合があります。例えば、シーン作成中にステータスを確認する際などに使用します。シーンは以下の方法で取得できます：

scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)

レスポンス

レスポンスは、以下のプロパティを含むSceneオブジェクトのリストです：

プロパティ	説明
uuid	Kognicプラットフォーム内でシーンを識別するために使用されるUUID
external_id	シーン作成時に指定された外部ID
scene_type	シーンのタイプ（主要コンセプト主要コンセプトを参照）
status	シーンのステータス（シーンとインプットの操作シーンステータスを参照）
created	シーンが作成された日時
calibration_id	シーンに使用されたキャリブレーション（存在する場合）
view_link	Kognicプラットフォームでシーンを表示するためのURL
error_message	シーン作成中にエラーが発生した場合はエラーメッセージが含まれ、それ以外の場合はNone

インプットの一覧を取得する

インプットは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

シーンの無効化

作成されたシーンに関する問題が上流で検出された場合、シーンを無効化できます。これは、開発中やデータに問題が検出された場合に便利です。シーンを無効化するとリクエストから削除されます。つまり、そのシーンを使用するすべてのインプットが削除されます。さらに、無効化されたシーンはアノテーションを生成せず、そのシーンの完了済みアノテーションも削除されます。この操作は元に戻すことができないため、慎重に使用してください。

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で追加されました。

作成されたインプットに関連する問題が上流で検出された場合、インプットを削除することができます。これは、問題がシーン自体ではなくインプットに関連している場合に役立ちます。例えば、LiDARとカメラのシーンに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}")

2026年半ばから、プレアノテーションやリクエストインプットの作成に進む前に、シーンの作成が完全に完了するまで待機する必要はなくなりました。現在は、シーンおよびプレアノテーションの作成操作がUUIDを返し、そのUUIDをすぐに次のステップで使用できます。エラーをすぐに確認する必要がある場合は、引き続き各ステップで待機することもできます。ただし、新しい非同期処理ではエラーが蓄積され、後からKognicプラットフォームのData Orchestrationで確認できます。