---
title: 씬 예제
slug: api-guide/ko/oKAVBOhx48FpoMcL2qsly
docTags: 
createdAt: 2025-04-16T06:34:02.000Z
---

원시 데이터를 Kognic 플랫폼에 업로드할 때는 **씬**(Scene)의 형태로 업로드해야 합니다.
씬은 이미지, 포인트 클라우드 및 기타 센서 데이터 등 다양한 소스에서 나온 데이터의 집합입니다.

`kognic-io` 2.5.0에서는 센서 데이터로부터 씬 타입을 추론하는 새로운 씬 모델을 출시했습니다. 포인트 클라우드가 없으면 카메라 전용 시퀀스가 생성됩니다.

:::hint{type="warning"}
이 새로운 모델과 관련 API를 통해 생성된 씬은 항상 *시퀀스*이며, 시퀀스가 아닌 입력을 요구하는 요청에는 추가할 수 없습니다. 앞으로 모든 곳에서 시퀀스로 표준화될 것으로 예상되므로, 이 점은 점차 문제가 되지 않을 것입니다.
:::

:::hint{type="info"}
새로운 모델에서는 씬이 집계되었음을 별도로 지정할 필요가 없으며, 첫 프레임에 대용량('fat') 포인트 클라우드를 담고 나머지 프레임에는 아무것도 담지 않는 이른바 "사전 집계된(pre-aggregated)" 씬의 생성은 더 이상 지원하지 않습니다. 자세한 내용은 [집계된 라이다 및 카메라 시퀀스](docId:6ZC0GQFQ9qOd5PM9nG0Ke)를 참고하세요.
:::

이 모델에 대한 더 자세한 정보는 [씬](docId\:JO4WJCAZ4D4U97yCFNQPL)에서 확인할 수 있습니다.

# 로컬 파일에서 씬 생성하기

이 가이드는 소스가 사용자의 컴퓨터에 위치한 씬을 업로드하는 과정을 안내합니다.

## 사전 요구 사항

[빠른 시작](docId\:J6rPQVoRf7BE4nA1DSk2P) 가이드를 성공적으로 완료했고 `kognic-io` 라이브러리가 설치되어 있어야 합니다. 여러 워크스페이스에 접근 권한이 있는 사용자는 [고급 설정](docId\:PN7g44HOAl8gvbqpgAgqF)해야 합니다.

로컬 파일을 사용해 씬을 업로드하려면 다음이 필요합니다.

- kognic-io >= 2.5.1
- 씬에 대한 [캘리브레이션 개요](docId\:wpoiuoy8AgVrpxZX-ORxm)
- kognic이 지원하는 [지원되는 파일 형식](docId\:T9vXKV5ekVJw5RuNg0oB2)으로 된 로컬 데이터

## 예제

:::hint{type="info"}
로컬 파일로 작업할 때는 postpone\_external\_resource\_import를 반드시 false로 설정해야 합니다. kognic은 로컬 파일에 대한 참조를 유지하고 나중에 가져올 수 없기 때문입니다.
:::

:::ExpandableHeading
### 로컬 파일에서 2D 씬 생성하기

```python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene import SceneRequest, Frame, ImageResource

scene = SceneRequest(
  workspace_id="<workspace_id>",
  external_id="my_first_scene_from_external_resources",
  frames=[
    Frame(
      frame_id="1",
      timestamp_ns=1742225789000000000, # Absolute unix timestamp of frame
      images=[
        ImageResource(
          external_resource_uri=None,
          sensor_name="my_camera",
          local_file=LocalFile(filename="<path to your file>")
        )
      ],
    )
  ],
  postpone_external_resource_import=False
)

client = KognicIOClient()
scene_uuid = client.scene.create_scene(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
```
:::

:::ExpandableHeading
### 로컬 파일에서 2D/3D 씬 생성하기

```python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene import SceneRequest, Frame, ImageResource, SensorResource, Resource, EgoVehiclePose

scene = SceneRequest(
  workspace_id="<workspace_id>",
  external_id="my_first_scene_from_external_resources",
  frames=[
    Frame(
      frame_id="1",
      timestamp_ns=1742225790000000000,
      pointclouds=[
        SensorResource(
          external_resource_uri=None,
          sensor_name="my_lidar",
          local_file=LocalFile(filename="<path to your file>")
        )
      ],
      images=[
        ImageResource(
          external_resource_uri=None,
          sensor_name="my_camera",
          start_shutter_timestamp_ns=1742225789000000000,
          end_shutter_timestamp_ns=1742225790000000000,
          local_file=LocalFile(filename="<path to your file>"),
        )
      ],
      ego_vehicle_pose=EgoVehiclePose(
        x=0.0, y=0.0, z=0.0, rotation_x=0.0, rotation_y=0.0, rotation_z=0.0, rotation_w=1.0
      )
    )
  ],
  calibration_id="<calibration_id>",
  imudata_resource=Resource(
      external_resource_uri=None,
      local_file=LocalFile(filename="<path to your file>")
  ),
  sensor_specification=None,
  should_motion_compensate=False,
  postpone_external_resource_import=False
)

client = KognicIOClient()
scene_uuid = client.scene.create_scene(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
```
:::

# 클라우드 리소스에서 씬 생성하기

이 가이드는 소스가 접근 권한이 있는 버킷에 위치한 씬을 업로드하는 과정을 안내합니다.

## 사전 요구 사항

[빠른 시작](docId\:J6rPQVoRf7BE4nA1DSk2P) 가이드를 성공적으로 완료했고 `kognic-io` 라이브러리가 설치되어 있어야 합니다. 여러 워크스페이스에 접근 권한이 있는 사용자는 [고급 설정](docId\:PN7g44HOAl8gvbqpgAgqF)해야 합니다.

클라우드 리소스를 사용해 씬을 업로드하려면 다음이 필요합니다.

- kognic-io >= 2.5.1
- 유효한 [데이터 통합](#)
- 씬에 대한 [캘리브레이션 개요](docId\:wpoiuoy8AgVrpxZX-ORxm)
- kognic이 지원하는 [지원되는 파일 형식](docId\:T9vXKV5ekVJw5RuNg0oB2)으로 버킷에 저장된 데이터

## 개요

각 리소스(이미지, 포인트 클라우드, IMU 데이터)에 `local_file=LocalFile(...)`을 제공하는 대신, `local_file=None`으로 두고 사용 중인 클라우드 플랫폼의 네이티브 형식, 예를 들어 `gs://` 또는 `s3://` URL로 `external_resource_uri`를 제공합니다.

## 예제

이 예제는 IMU 데이터와 자차 포즈를 포함한 완전한 2D+3D 씬을 보여줍니다. IMU, 자차 포즈, 포인트 클라우드를 제거하면 2D 전용 씬으로 축소할 수 있습니다.

가져오기는 `postpone_external_resource_import`를 통해 지연시킬 수 있으며, 이를 통해 이른바 '인덱싱된(Indexed)' 씬이 생성됩니다. (시스템에 존재할 수 있는 것의 인덱스만 유지하고, 씬이 사용되거나 나중에 수동으로 요청될 때까지 데이터를 가져오지 않기 때문에 '인덱싱된'이라고 부릅니다.)

```python
from kognic.io.client import KognicIOClient
from kognic.io.model.scene import SceneRequest, Frame, ImageResource, SensorResource, Resource, EgoVehiclePose

scene = SceneRequest(
  workspace_id="<workspace_id>",
  external_id="my_first_scene_from_external_resources",
  frames=[
    Frame(
      frame_id="1",
      timestamp_ns=1742225790,
      # For 2D-only scenes, omit pointclouds entirely.
      pointclouds=[
        SensorResource(
          external_resource_uri="<uri>",
          sensor_name="my_lidar",
          local_file=None,
        )
      ],
      images=[
        ImageResource(
          external_resource_uri="<uri>",
          sensor_name="my_camera",
          start_shutter_timestamp_ns=1742225789,
          end_shutter_timestamp_ns=1742225790,
          local_file=None,
        )
      ],
      # For 2D-only scenes, omit ego_vehicle_pose entirely.
      ego_vehicle_pose=EgoVehiclePose(
        x=0.0, y=0.0, z=0.0, rotation_x=0.0, rotation_y=0.0, rotation_z=0.0, rotation_w=1.0
      )
    )
  ],
  calibration_id="<calibration_id>",
  # For 2D scenes, omit imudata_resource entirely.
  imudata_resource=Resource(
      external_resource_uri="<uri>",
      local_file=None
  ),
  sensor_specification=None,
  should_motion_compensate=False, # Omit for 2D, optionally set for 3D+2D
  postpone_external_resource_import=False, # Set true if you want to import at a later point in time
)

client = KognicIOClient()
scene_uuid = client.scene.create_scene(scene).scene_uuid
print("Scene uploaded, got uuid:", scene_uuid)
```