--- title: 씬 및 입력 다루기 slug: api-guide/ko/pf_-tO1WYuOke6zXNcpe7 docTags: createdAt: 2024-12-17T10:38:14.000Z --- :::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`를 반환하며, 이는 나중에 씬으로 작업할 때 사용할 수 있습니다. 이 시점에 모든 파일이 Kognic 플랫폼에 업로드되었으며 씬의 사전 처리가 시작됩니다. 사전 처리가 완료되면 씬이 생성된 것으로 간주합니다. 씬의 다양한 상태에 대한 자세한 내용은 [씬 상태](./#-) 섹션을 참고하세요. 실험할 때는 `dryrun` 파라미터를 사용하는 것이 유용한 경우가 많습니다. 이는 씬 형식을 검증하지만 실제로 생성하지는 않습니다. ### 씬 상태 씬이 업로드되면, 플랫폼에서 사용 가능해지기 전에 사전 처리될 수 있습니다. 이 과정 동안 씬의 status 속성을 사용하여 진행 상황을 추적할 수 있습니다. | 상태 | 설명 | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | indexed | 씬이 클라우드 리소스와 함께 생성되어 검증되었지만 아직 데이터가 사용자의 클라우드를 벗어나지 않았습니다. 누군가 UI나 API를 통해 사용 가능하게 만들거나 요청 입력(request input)을 생성하는 데 사용할 때까지 이 상태로 유지됩니다. | | 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` 파라미터를 생략하면 프로젝트의 가장 최근의 열린(open) 배치가 사용됩니다. 이후 같은 씬을 재사용하여 다른 프로젝트와 배치에 대한 입력을 생성할 수 있습니다. ## 직접 입력 생성하기 위에서 설명한 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` 파라미터를 생략하면 프로젝트의 가장 최근의 열린(open) 배치가 사용됩니다. 이 과정을 돕기 위한 래퍼 함수 `create_inputs`도 제공하고 있습니다. 자세한 내용은 [한 번의 호출로 여러 개의 입력 생성하기](./#------)를 참고하세요. ## 씬 목록 조회하기 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\:ScnZ9HNtKPw7pvGOaKag1) 참고) | | status | 씬 상태([씬 상태](./#-) 참고) | | 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에서 새로 추가되었습니다. ::: 업스트림에서 생성된 입력과 관련된 문제가 발견되면 이를 삭제할 수 있습니다. 이는 문제가 씬이 아니라 입력 자체와 관련된 경우 유용할 수 있습니다. 한 가지 예로, 라이다-카메라 씬에 대해 두 개의 입력이 있고 하나는 2D/3D로 어노테이션하고 싶고 다른 하나는 2D로만 어노테이션하고 싶은 경우가 있습니다. 문제가 잘못된 캘리브레이션이라면 2D 입력은 계속 사용할 수 있지만 2D/3D 입력은 삭제해야 합니다. 입력을 삭제하면 해당 입력에 대해 어노테이션이 생성되지 않으며 해당 입력의 완료된 어노테이션도 제거됩니다. 이 작업은 되돌릴 수 없으므로 주의해서 사용하세요. ```python input_uuid = "9c08f7a3-3216-4bd6-a41a-1dda6f66f53e" client.input.delete_input(input_uuid) ``` ## 한 번의 호출로 여러 개의 입력 생성하기 :::hint{type="info"} ### 참고 이 기능은 버전 1.1.9에서 새로 추가되었습니다. ::: 입력 생성 프로세스는 비동기이므로, 계속 진행하기 전에 입력이 생성되기를 기다리는 것이 유용한 경우가 있습니다. 이를 위해 여러 개의 씬과 입력을 생성하고, 생성(또는 실패)되기를 기다렸다가 결과를 반환(yield)하는 래퍼 함수 `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를 반환하며, 이를 다음 단계에 즉시 사용할 수 있습니다. 오류에 대해 즉각적인 피드백이 필요하다면 각 단계마다 기다리고 싶을 수도 있지만, 새로 도입된 비동기 처리 방식은 이제 Kognic 플랫폼의 Data Orchestration을 통해 나중에 조회할 수 있는 오류를 누적합니다.