ML 데이터셋과 내보내기

SEAM Studio는 뷰어로 끝나지 않습니다 — 시뮬레이션한 모든 것을 파일로 꺼낼 수 있습니다: ML 모델 학습용 NumPy .npz 그라운드트루스 데이터셋, AODT 뷰어 호환 RFData 번들, 보이는 그대로(WYSIWYG)의 뷰포트 캡처, 차트별 CSV/PNG/SVG 내보내기까지. 이 가이드에서 각 내보내기 경로를 하나씩 살펴봅니다.

여기 나오는 모든 기능은 Mock 백엔드만으로도 동작합니다 — Sionna RT가 설치되어 있지 않아도 데이터셋 생성과 모든 내보내기가 끝까지 실행됩니다(값은 mock 솔버가 만들지만, 파이프라인 테스트에는 충분합니다).

1. ML dataset 패널

데이터셋 생성기는 ML dataset 패널에 있습니다(헤더에는 ML DATASET으로 표시됩니다). 두 가지 방법으로 열 수 있습니다:

• Results 모드 — 오른쪽의 도킹 가능한 카드 중 하나입니다.
• 어느 모드에서든 툴바의 Panels ▾ 메뉴 — ML dataset 행을 클릭하면 뷰포트 위에 플로팅되고, ◧ / ◨ 버튼으로 좌/우 사이드바에 도킹할 수도 있습니다. 플로팅한 패널은 모드를 바꿔도 그대로 유지됩니다.

데이터셋 생성 단계별 안내

1. Name — 데이터셋 표시 이름입니다(아래 목록에도 나타납니다).
2. Sampling mode — UE 위치를 고르는 방식:
   • random — 영역 안 균일 랜덤 위치,
   • grid — 영역 위 정규 격자(Grid spacing 필드가 추가됩니다, 단위 m),
   • trajectory — 직선 start→end 구간 위의 점들.
3. Actor flight path — 씬 액터(웨이포인트를 가진 차량·보행자·UAV)의 저작된 궤적을 따라 샘플링하는 옵션입니다. 여기서 액터를 고르면 아래의 영역 / start-end 를 덮어씁니다; — none — 으로 두면 샘플링 모드 자체의 기하를 사용합니다. 궤적이 있는 액터가 없으면 패널이 알려 주니 먼저 Visual 모드에서 지정하세요. 필드 아래 힌트에 우선순위가 그대로 나옵니다: waypoints > actor flight path > start/end (or region).
4. dt (s) — 백엔드가 이동 샘플에 붙이는 속도/도플러 라벨의 유한차분(finite-difference) 시간 간격입니다.
5. Num samples — 풀 UE 위치 수(1–20000). CFR points — 위치당 주파수 응답 표본 수(2–4096). Height (m) — UE 샘플링 높이.
6. 영역을 설정합니다(random / grid 모드):
   • ⌖ Pick region in viewport — 버튼이 Click 2 corners… (Esc) 로 바뀌면, 씬 표면에서 영역의 마주 보는 두 모서리를 클릭하세요. XY 필드가 채워집니다(Esc 취소).
   • Fit to scene — 영역과 높이를 씬 전체를 덮도록 설정합니다(프로젝트를 열 때 패널이 실제 씬 경계로 자동 시드되므로, 엉뚱한 값에서 시작하는 일은 드뭅니다).
   • Region min / Region max — XY 모서리를 숫자로 직접 입력.
   • 힌트 줄을 눈여겨보세요. 예: "Scene spans [-40.0, -40.0]…[40.0, 40.0] m — samples outside it get zero paths." 기하 밖을 샘플링하는 것이 쓸모없는 데이터셋이 나오는 1순위 원인입니다.

   trajectory 모드에서는 대신 ⌖ Pick path in viewport 버튼과 Start / End XYZ 필드가 나타납니다.

7. Seed — 랜덤 샘플링을 재현 가능하게 만듭니다. 논문에는 함께 기록하세요.
8. Include paths — 각 샘플의 전체 레이 경로(정점 + 상호작용)를 paths.jsonl 로 추가 덤프합니다. 용량이 크므로 기본은 꺼져 있습니다.
9. Follow terrain — 각 샘플의 높이를 그 아래 표면에 스냅한 뒤 높이 오프셋을 더합니다. 경사 실외 씬에서 쓰고, 실내에서는 끄세요(지붕에 스냅됩니다).
10. Generate dataset 을 누릅니다. 솔버가 위치들을 도는 동안 버튼에 Generating… 이 표시됩니다.

데이터셋 목록

생성이 끝난 데이터셋은 버튼 아래 표에 한 행씩 나타납니다:

• name / # / created / size — 이름, 샘플 수, 생성 시각, 파일 크기.
• files — npz(dataset.npz, 배열 본체)와 json(metadata.json, 설정 에코 + 좌표/단위 규약) 다운로드 링크.
• 이름 옆의 ⚠ N zero-path 플래그는 N개 샘플에서 경로가 하나도 안 나왔다는 뜻입니다(UE가 씬 밖이거나 완전히 가려짐) — 영역을 다시 확인하세요.
• × 버튼으로 데이터셋을 삭제합니다. 한 번 누르면 ✓? 로 바뀌고, 다시 눌러야 확정됩니다(몇 초 뒤 자동 해제).

디스크에서는 프로젝트 폴더의 export/datasets/<dataset_id>/ 아래에 쌓입니다.

라벨에는 무엇이 들어 있나

.npz 에는 샘플별 위치, 복소 CFR, 경로별 CIR 이득·지연, LOS 플래그, RSS, 분산 지표가 들어 있습니다 — 정확한 배열 스키마, AODT 필드 매핑, 바로 실행할 수 있는 학습 예제(examples/ml/train_channel_estimator.py)는 ML 그라운드트루스 데이터셋 문서에 정리되어 있습니다.

2. RFData 내보내기 (AODT 뷰어 번들)

결과를 외부 AODT 스타일 뷰어나 자체 파이프라인에 넘기려면 툴바의 Actions ▾ → Export RFData 를 사용하세요. 프로젝트 폴더 안 export/rfdata/ 에 번들이 기록됩니다:

scenario_meta.json과 devices.json의 주파수는 프로젝트의 첫 번째 저장 구성이 아니라, 저장된 결과를 실제로 푼 구성(가장 최근 paths 결과의 구성 스냅샷)을 따릅니다. API(POST /api/projects/{project_id}/export/rfdata)에서는 config_id나 인라인 config로 바꿀 수 있습니다.

내보내기가 끝나면 Results 에 닫을 수 있는 행이 나타납니다 — "Exported RFData to export/rfdata" — 파일별 다운로드 링크가 붙어 있어 프로젝트 폴더를 뒤질 필요가 없습니다.

AODT 결과 스키마 내보내기

위 번들은 뷰어 계약입니다. NVIDIA AODT 자체 결과 스키마에 맞춰 만들어진 도구에 넘기려면, 해당 테이블들을 Parquet 으로 쓰는 두 번째 내보내기를 사용하세요. UI 에서는 Actions ▾ → AODT export (parquet) 입니다(소스와, 필요하면 결과 id 를 고릅니다. 비우면 가장 최근 결과). API 로는 다음과 같습니다:

POST /api/projects/{project_id}/export/aodt
     {"source": "paths", "result_id": null, "fft_size": 64,
      "subcarrier_spacing_hz": 30000}

export/aodt/ 안에 AODT 테이블별로 <table>.parquet 하나씩 기록됩니다: ues, scatterers, rus, dus, panels, patterns, time_info, cfrs, cirs, raypaths — 컬럼 이름과 타입은 AODT 문서 그대로입니다. source: "paths" 는 저장된 paths 결과에서 스냅숏 하나(time_idx 0)를 쓰고, source: "playback" 은 저장된 playback 팩의 프레임마다 time_idx 를 하나씩 써서 time_info·raypaths·cirs·cfrs 가 주행 구간 전체를 덮고 UE 의 route_* 컬럼에 프레임 위치가 담깁니다. source: "sensing" 은 저장된 센싱 결과를 스냅숏 하나로 씁니다(sensing.ko.md). 반송파 주파수, 대역폭(따라서 cfrs의 톤 격자)과 패널 간격은 내보내는 결과를 푼 구성을 따르며, 요청에 config_id를 주면 그 구성으로 바뀝니다.

AODT 테이블 중 telemetry 와 ran_config 는 쓰지 않습니다. 둘 다 RAN 시뮬레이션 산출물(스케줄러/PHY KPI, gNB 설정)이라 레이 트레이싱 파이프라인이 만들어내지 않으며, 빈 파일을 쓰면 SEAM 이 제공하지 않는 범위를 제공하는 것처럼 보이게 됩니다.

테이블과 함께 id_map.json 이 기록됩니다 — Parquet 행이 담을 수 없는 문자열 ↔ 정수 id 매핑입니다: 디바이스 id → ru_id/ue_id, prim id → prim_ids 인덱스, 액터 id → scatterer ID, 디바이스 → panel 인덱스.

테이블을 쓰기 전에 알아둘 제약:

• normals 는 전부 0 입니다 — SEAM 은 상호작용 지점과 그 prim 만 기록하고 표면 법선은 기록하지 않습니다. object_ids 는 prim_ids 와 같습니다(별도 USD object 테이블이 없습니다). 예외는 센싱 타깃 꼭짓점으로, object id 가 1 000 000 + 액터 id 정렬 순서에서의 위치입니다(id_map.json 의 sensing_targets).
• ru_ant_el/ue_ant_el 는 (0, 0[, 0]) 이고 ampl_* 리스트는 항목이 하나입니다: 경로 솔버는 링크 단위 계수를 풀지, 소자 단위 계수를 풀지 않습니다.
• patterns 는 등방성 자리표시자 한 행입니다.
• 진폭(그리고 cirs/cfrs)은 수신 전력이 아니라 채널 계수입니다 — |a| = 10^(path_gain_dB/20), 위상은 경로의 반송파 위상. cir_delay 는 AODT 스키마대로 초(second) 단위입니다.
• raypaths 의 points 는 폴리라인 전체(TX, 모든 상호작용, RX)이고, interaction_types/normals/prim_ids/object_ids/vegetation_depths 도 점마다 한 항목씩 같은 길이입니다. interaction_types 는 "emission", 상호작용마다 토큰 하나, "reception" 순서이며 AODT 문서에 있는 토큰 (reflection, diffraction, diffuse, transmission)만 씁니다. SEAM 의 scattering 과 센싱 에코는 diffuse 로 기록됩니다. 양 끝점의 prim/object id 는 −1 입니다.
• 상호작용 지점을 전부 타입으로 표시할 수 없는 경로(상호작용 기록이 없고 경로 타입이 mixed 처럼 단일 메커니즘이 아닌 경우)는 경고와 함께 raypaths 에서 빠집니다. 그 탭은 cirs/cfrs 에는 그대로 들어갑니다.

이 내보내기는 pyarrow 가 필요합니다(pip install "seam-studio[parquet]", 즉 parquet extra. backend[dev,parquet] 로 설치한 소스 체크아웃에는 들어 있습니다). 없으면 엔드포인트가 그 명령을 담아 409 를, 요청한 source 종류의 결과가 프로젝트에 없으면 404 를 돌려줍니다. 기록된 raypaths.parquet 는 SEAM 자체 AODT 임포터(POST /results/import-aodt, 또는 SEAM 이 돌아가는 기기의 폴더 경로를 주는 Actions ▾ → AODT import (parquet))로 다시 읽어들일 수 있고, 임포터는 내부 지점마다 상호작용을 하나씩 되살립니다(diffuse 는 scattering 으로).

3. 채널 데이터셋(.npz) — AODT/HYRAY 링크별 레이아웃

1절의 ML 데이터셋은 위치별 데이터셋(CFR, 집계 KPI)입니다. NVIDIA AODT / HYRAY 참조 파일이 쓰는 레이아웃 그대로, 즉 링크별 다중경로를 UE 한 행 × TRP 한 열 × 경로 한 항목으로 받고 싶다면 툴바에서 Actions ▾ → Channel dataset (.npz) 를 쓰세요. export/channel_npz/channel_dataset.npz 와 metadata.json 사이드카를 씁니다.

UE 격자는 자동으로 정해집니다. 프로젝트에 저장된 trajectory 결과가 있으면 그중 최신 것(UE 행이 많음), 없으면 씬의 수신기 디바이스 — 즉 POST /import/devices 로 임포트한 UE 목록이 들어가는 바로 그 자리입니다. 어느 격자를 썼는지와 링크 수는 알림과 Results 의 닫을 수 있는 행에 모두 표시됩니다. UE 하나당 paths 솔브 한 번을 돌리므로 진행률 카드에 진행 상황이 뜨고, 취소도 됩니다.

npz 에는 13개 정규 키만 들어갑니다.

T 는 송신기 수, U 는 UE 위치 수, P 는 max_paths(기본 500)입니다. 링크마다 경로 축은 |진폭| 기준 강한 순으로 정렬해 P 까지 0으로 패딩합니다. 솔버가 경로를 하나도 못 찾은 링크는 전부 0인 채로 is_nlos = True 가 됩니다.

배열을 쓰기 전에 알아야 할 규약:

• sorted_dataset_ampl 은 선형 복소 채널 진폭 10^((path_gain_db + normalization_db)/20) · e^{j·phase_rad} 이며 수신 전력이 아닙니다. normalization_db 기본값은 0.0(SEAM 자체 물리 이득) 이고, 연구실의 AODT 파일은 고정 −5.06 dB 오프셋을 함께 담고 있으므로 수치까지 맞추려면 normalization_db: -5.06 을 넘기세요.
• sorted_dataset_azimuth / _elevation 은 송신 TX 의 로컬 어레이 좌표계 에서 본 출발(departure) 각이며 단위는 라디안입니다. 방위각은 atan2(y_local, x_local) 로 (−π, π], 앙각은 천정각 arccos(z_local) 로 [0, π] 범위입니다. 로컬 좌표계는 해당 TX 디바이스 자신의 orientation_deg([yaw, pitch, roll] 도)에서 R = Rz(yaw)·Ry(pitch)·Rx(roll) 로 만듭니다 — SEAM 이 Sionna Transmitter 에 넘기는 orientation 으로 sionna-rt 가 세우는 바로 그 행렬이라, 데이터셋의 각도와 솔버의 어레이 조향이 같은 좌표계를 씁니다.
• sorted_dataset_toa 는 절대 전파 지연이며 단위는 초입니다.
• dataset_TRP_ori_angle 은 TX 별 [yaw_deg, pitch_deg] 이며 단위는 도 입니다(참조 파일과 동일 — 방향 쌍만 도 단위이고 경로별 각도 배열은 라디안).

스크립트로 돌릴 수 있게 HTTP 로도 전부 열려 있습니다.

POST /api/projects/{project_id}/export/channel-npz
     {"ue_source": "explicit",
      "ue_positions": [[25, 5, 1.5], [40, -12, 1.5]],
      "tx_ids": null,          // null = 씬 순서대로 모든 tx 디바이스
      "max_paths": 500,
      "normalization_db": 0.0,
      "ue_ids": null, "time_idx": null, "batch": 0}

ue_source 는 "explicit"(ue_positions 목록), "devices"(모든 rx 디바이스, id 순), "trajectory"(저장된 trajectory 결과의 샘플별 위치 — ue_result_id 로 지정하거나 null 이면 최신) 중 하나입니다. ue_ids / time_idx 는 선택적 패스스루 열이고(기본값 arange(U), zeros(U)), 주는 경우 길이가 정확히 U 여야 합니다. 한 번의 내보내기는 UE 5000개로 제한됩니다.

이 내보내기는 씬을 건드리지 않습니다. UE 마다 메모리 상 사본에서 임시 프로브 수신기 하나만 두고 풀며, 결과 세트도 저장하지 않습니다 — export/channel_npz/ 와 export_channel_npz 프로버넌스 이벤트 한 건만 남습니다.

솔버 자체도 내보내기가 유지하는 경로 수에서 멈추게 하려면 Paths 솔버 패널의 Max paths / TX 필드(max_num_paths_per_src)와 함께 쓰세요.

4. 뷰포트 캡처 — Snapshot 과 Render

뷰포트 우측 하단 버튼 묶음의 아이콘 버튼 두 개가 씬 이미지를 저장합니다:

• Snapshot(카메라 아이콘) — 보이는 그대로(WYSIWYG) 저장합니다: 현재 카메라 포즈, 레이, 마커, 라디오맵 오버레이를 캔버스 전체 해상도의 PNG로 내보냅니다. 툴팁은 "Save this exact view as a PNG (what you see, full resolution — paper-ready)" 입니다. 논문·슬라이드 그림에는 이 버튼을 쓰세요.
• Render(필름 아이콘) — Mitsuba 를 통한 오프라인 물리 기반 경로추적 렌더입니다. 더 느리고, 의도적으로 화면 뷰와 다릅니다 — 레이나 오버레이 없이 셰이딩된 씬만 렌더합니다.

디바이스/액터 시점의 실시간 1인칭 뷰인 POV 인셋에도 자체 카메라 버튼이 있어, POV 프레임을 전체 해상도 PNG로 저장할 수 있습니다.

5. 대시보드의 CSV·그림 내보내기

• Metrics dashboard 패널의 모든 차트(그리고 다른 논문 스타일 차트들)는 헤더에 PNG / SVG / CSV 버튼이 있는 프레임 안에 있습니다 — 3× 비트맵, 벡터, 또는 원 데이터 CSV. 그림은 보이는 그대로(흰 배경, Times New Roman) 내보내집니다.
• 대시보드 헤더의 Export all (CSV) 버튼은 KPI 표 전체를 metric,value,unit 행으로 다운로드합니다.
• Results 의 경로 테이블에는 Export filtered CSV (N) 이 있습니다 — 현재 필터된 경로 집합을 그대로, 경로당 한 행(type, power, delay, 상호작용 재질 포함)으로 내보냅니다.

관련 문서

• ML 그라운드트루스 데이터셋 — .npz 스키마, zero-path 경고, AODT 필드 매핑, 학습 예제 스크립트.
• 시작하기 — 설치, 첫 프로젝트, 모드 탭.
• 시뮬레이션 가이드 — 경로, 라디오맵, 그리고 데이터셋이 물려받는 솔버 설정.
• 씬·프로젝트 포맷 — 프로젝트 폴더 안 파일들의 위치.
• Sionna 버전 — 재현성을 위해 metadata.json 에 기록되는 engine.
• 15분 튜토리얼 — 데이터셋 생성을 포함한 첫 세션 전체 흐름.
• 레이더 센싱 — 센싱 데이터셋 내보내기(§10)와 AODT 내보내기의 sensing 소스.
• 재생 대시보드 — GT 대 DT 재생 팩, AODT 내보내기의 playback 소스.