---
title: シーンとインプットの操作
slug: api-guide/ja/BU_cyJiyNYv7pc2G609u_
docTags: 
createdAt: 2024-12-17T10:38:14.190Z
---

:::hint{type="info"}
### 注記

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

:::hint{type="success"}
### Kognicユーザー向け

Kognicのユーザーは、`KognicIOClient`コンストラクタに`client_organization_id`を指定することで、クライアント組織に代わってシーンを作成できます。
:::

## シーンの作成

各シーンリソースには、対応するタイプのシーンを作成するための`create`メソッドがあります。このメソッドは、対応するシーンモデルを引数として受け取ります。例えば、`Cameras`シーンを作成するには以下のようにします：

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

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

### シーンステータス

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

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

## シーンからインプットを作成する

シーンが作成されると、プロジェクトとインプットバッチに関連付けることでインプットを作成できます。以下のプロジェクト構成を例に考えます：

```text
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`にインプットを作成するには以下のようにします：

```python
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`にインプットを作成するには以下のようにします：

```python
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回の呼び出しで複数のインプットを作成する](docId\:Mf7_5GLLQrKg_To-EV3yD)を参照してください。

## シーンの一覧を取得する

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

```python
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`     | シーンのタイプ（[主要コンセプト](docId\:i8t2MeIkKpcu2GLOnI5Yo)を参照）    |
| `status`         | シーンのステータス（[シーンステータス](docId\:Mf7_5GLLQrKg_To-EV3yD)を参照） |
| `created`        | シーンが作成された日時                                            |
| `calibration_id` | シーンに使用されたキャリブレーション（存在する場合）                             |
| `view_link`      | Kognicプラットフォームでシーンを表示するためのURL                          |
| `error_message`  | シーン作成中にエラーが発生した場合はエラーメッセージが含まれ、それ以外の場合は`None`          |

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

インプットは`query_inputs`メソッドを使用してプラットフォームから取得できます。使用方法は以下のとおりです：

```python
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      |

## シーンの無効化

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

```python
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` | シーンが意図せず作成された場合                             |

## インプットを削除する

:::hint{type="info"}
### 注記

この機能はバージョン1.6.0で追加されました。
:::

作成されたインプットに関連する問題が上流で検出された場合、インプットを削除することができます。これは、問題がシーン自体ではなくインプットに関連している場合に役立ちます。例えば、LiDARとカメラのシーンに2つのインプットがある場合、一方は2D/3Dでアノテーションを行い、もう一方は2Dのみでアノテーションを行うとします。問題がキャリブレーションの誤りである場合、2Dインプットはそのまま使用できますが、2D/3Dインプットは削除すべきです。

インプットを削除すると、そのインプットに対するアノテーションは生成されなくなり、完了済みのアノテーションも削除されます。この操作は元に戻すことができないため、慎重に使用してください。

```python
input_uuid = "9c08f7a3-3216-4bd6-a41a-1dda6f66f53e"
client.input.delete_input(input_uuid)
```

## 1回の呼び出しで複数のインプットを作成する

:::hint{type="info"}
### 注記

この機能はバージョン1.1.9で追加されました。
:::

インプットの作成プロセスは非同期であるため、処理を続行する前にインプットの作成を待機することが役立つ場合があります。これを実現するために、複数のシーンとインプットを作成し、作成（または失敗）されるまで待機して結果を返すラッパー関数`create_inputs`を提供しています。この関数は、すべてのインプットがいずれかの方法で完了するか、返す結果が生じるまでブロックします。この関数は`SceneWithPreannotation`（シーンとオプションのプレアノテーションを含む新しいラッパーオブジェクト）のリストと、通常のインプット作成パラメータを受け取ります：

```python
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`にある以下の例を使用して実現できます：

```python
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で確認できます。