씬 및 입력 다루기
참고
씬 모달리티에 대한 자세한 정보는 Scene Types 섹션을 확인하세요.
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를 반환하며, 이는 나중에 씬으로 작업할 때 사용할 수 있습니다. 이 시점에 모든 파일이 Kognic 플랫폼에 업로드되었으며 씬이 사전 처리를 시작합니다. 사전 처리가 완료되면 씬이 생성되었다고 말합니다. 씬의 다양한 상태에 대한 자세한 내용은 씬 상태 섹션을 참고하세요.
실험할 때는 dryrun 파라미터를 사용하는 것이 유용한 경우가 많습니다. 이는 씬 형식을 검증하지만 실제로 생성하지는 않습니다.
씬 상태
씬이 업로드되면, 플랫폼에서 사용 가능해지기 전에 사전 처리될 수 있습니다. 이 과정 동안 씬의 status 속성을 사용하여 진행 상황을 추적할 수 있습니다.
Status | Description |
|---|---|
indexed | 씬이 클라우드 리소스와 함께 생성되어 검증되었지만 아직 데이터가 사용자의 클라우드를 벗어나지 않았습니다. 누군가 UI나 API를 통해 사용 가능하게 만들거나 Request Input을 생성하는 데 사용할 때까지 이 상태로 유지됩니다. |
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에 있는 모든 request에 대해 씬으로 입력을 생성합니다. 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
)이렇게 하면 씬 생성 프로세스가 트리거되고, 씬이 생성되면 주어진 배치의 모든 request에 입력이 생성됩니다. batch 파라미터를 생략하면 프로젝트의 가장 최신 오픈 배치가 사용됩니다. 이 과정을 돕기 위한 래퍼 함수 create_inputs도 제공하고 있습니다. 자세한 내용은 한 번의 호출로 여러 개의 입력 생성하기를 참고하세요.
씬 목록 조회하기
Kognic 플랫폼에 업로드된 씬 목록을 조회하는 것이 유용할 수 있습니다. 한 가지 예로 씬 생성 중 상태를 확인하는 경우가 있습니다. 씬은 다음과 같은 방법으로 조회할 수 있습니다.
scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)응답
응답은 다음 속성을 포함하는 Scene 객체의 목록입니다.
입력 목록 조회하기
query_inputs 메서드를 사용하여 플랫폼에서 입력을 조회할 수 있으며, 다음과 같이 사용할 수 있습니다.
scene_uuids = ["cca60a67-cb68-4645-8bae-00c6e6415555", "cc8776d0-f537-4094-8b11-8c2111741e2f"]
client.scene.get_scenes_by_uuids(scene_uuids=scene_uuids)입력을 조회하기 위한 추가 필터 파라미터는 아래에 나열되어 있습니다.
Parameter | Description |
|---|---|
project | 필터링할 프로젝트 식별자 |
batch | 입력을 반환할 프로젝트 내 배치 |
scene_uuids | 지정된 uuid와 일치하는 씬을 사용하는 입력을 반환 |
external_ids | 지정된 external_ids와 일치하는 씬을 사용하는 입력을 반환 |
응답
응답은 다음 속성을 포함하는 Input 객체의 목록입니다.
Property | Description |
|---|---|
uuid | Kognic 플랫폼 내에서 입력을 식별하는 데 사용되는 ID |
scene_uuid | 입력이 사용하는 씬을 식별하는 데 사용되는 ID |
request_uid | 입력이 속한 request를 식별하는 데 사용되는 ID |
view_link | Kognic 플랫폼에서 입력을 확인할 수 있는 url |
씬 무효화하기
업스트림에서 씬과 관련된 문제가 발견되면 씬을 무효화할 수 있습니다. 이는 개발 중이거나 데이터에 문제가 발견된 경우에 유용할 수 있습니다. 씬을 무효화하면 request에서 제거되며, 이는 해당 씬을 사용하는 모든 입력이 삭제됨을 의미합니다. 결과적으로 무효화된 씬은 어노테이션을 생성하지 않으며 해당 씬의 완료된 어노테이션도 제거됩니다. 이 작업은 되돌릴 수 없으므로 주의해서 사용하세요.
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)씬을 무효화할 때 다음과 같은 사유를 사용할 수 있습니다.
Reason | Description |
|---|---|
bad-content | 씬이 로드되지 않거나, 유효하지 않은 캘리브레이션 등 잘못된 메타데이터를 가지고 있음 |
duplicate | 동일한 씬이 여러 번 생성된 경우 |
incorrectly-created | 씬이 의도치 않게 생성된 경우 |
입력 삭제하기
참고
이 기능은 버전 1.6.0에서 새로 추가되었습니다.
업스트림에서 생성된 입력과 관련된 문제가 발견되면 이를 삭제할 수 있습니다. 이는 문제가 씬이 아니라 입력 자체와 관련된 경우 유용할 수 있습니다. 한 가지 예로, 라이다-카메라 씬에 대해 두 개의 입력이 있고 하나는 2D/3D로 어노테이션하고 싶고 다른 하나는 2D로만 어노테이션하고 싶은 경우가 있습니다. 문제가 잘못된 캘리브레이션이라면 2D 입력은 계속 사용할 수 있지만 2D/3D 입력은 삭제해야 합니다.
입력을 삭제하면 해당 입력에 대해 어노테이션이 생성되지 않으며 해당 입력의 완료된 어노테이션도 제거됩니다. 이 작업은 되돌릴 수 없으므로 주의해서 사용하세요.
input_uuid = "9c08f7a3-3216-4bd6-a41a-1dda6f66f53e"
client.input.delete_input(input_uuid)한 번의 호출로 여러 개의 입력 생성하기
참고
이 기능은 버전 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년 중반부터는 사전 어노테이션 및 request 입력 생성 단계로 넘어가기 전에 씬 생성이 완전히 완료되기를 기다릴 필요가 없어졌습니다. 이제 씬 및 사전 어노테이션 생성 작업은 UUID를 반환하며, 이를 다음 단계에 즉시 사용할 수 있습니다. 오류에 대해 즉각적인 피드백이 필요하다면 각 단계마다 기다리고 싶을 수도 있지만, 새로 도입된 비동기 처리 방식은 이제 Kognic 플랫폼의 Data Orchestration을 통해 나중에 조회할 수 있는 오류를 누적합니다.