nuScenes 데이터가 BEVFormer 모델 입력이 되기까지의 데이터 형식, 변환 과정, info pkl의 역할 정리 및 BEVFormer 학습용 커스텀 데이터셋을 수집하기 위한 센서 구성, 데이터 형식, 폴더 구조, 변환 방법 가이드

관련 문서


nuScenes → BEVFormer 입력 변환

개요

  • BEVFormer의 센서 입력은 카메라 이미지 6장이며, 여기에 카메라 캘리브레이션(lidar2img), 자차 움직임 정보(can_bus), **이전 프레임 BEV(prev_bev)**가 함께 들어간다.
  • LiDAR·Radar의 point cloud는 입력으로 사용하지 않는다. LiDAR는 좌표계 기준과 GT 필터링(num_lidar_pts)에만 쓰인다. (단, ego_pose는 LiDAR 기반 localization 결과이다.)
  • nuScenes 원본은 학습 전에 한 번 info pkl로 변환되고, 학습·추론 때마다 Dataset과 pipeline이 pkl과 이미지 파일을 읽어 모델 입력 텐서를 만든다.

전체 흐름

[1] nuScenes 원본 데이터
    v1.0-*/ JSON 테이블 + samples/CAM_*/*.jpg + can_bus/*.json
        │  tools/create_data.py  (오프라인, 1회 실행)
        │  테이블 join, 센서 간 변환 사전 계산, GT 좌표·클래스 변환, CAN bus 시각 맞춤
        ▼
[2] info pkl : nuscenes_infos_temporal_{train,val}.pkl
    sample 1개 = info dict 1개 (이미지 경로 + 변환 행렬 + can_bus + GT)
        │  CustomNuScenesDataset.get_data_info()  (매 iteration)
        │  lidar2img 계산, can_bus 위치·yaw 채우기, GT box 객체 생성
        ▼
[3] input_dict (numpy 배열 + 파일 경로)
        │  pipeline  (매 iteration)
        │  이미지 로드 → (증강) → 정규화 → 리사이즈 → 패딩 → 텐서 변환 → 수집
        ▼
[4] 모델 입력
    img        : Tensor [B, (queue), 6, 3, 480, 800]
    img_metas  : lidar2img, can_bus, scene_token, img_shape, ...
    GT (학습)   : gt_bboxes_3d, gt_labels_3d
        ▼
BEVFormer → 3D box (LiDAR 좌표) → results_nusc.json (Global 좌표)

1. 사용하는 nuScenes 원본 데이터

범주원본 위치형식BEVFormer에서의 용도
카메라 이미지samples/CAM_*/jpg, 1600×900모델 입력 (6장)
카메라 캘리브레이션calibrated_sensor.jsontranslation, rotation (quaternion), 내부 파라미터 3×3lidar2img 계산
LiDAR 캘리브레이션calibrated_sensor.json (LIDAR_TOP)translation, rotation기준 좌표계(LiDAR) 정의
자차 poseego_pose.jsontranslation, rotation센서 간 시간 차 보상, can_bus 위치·yaw, 결과의 Global 변환
CAN buscan_bus/scene-XXXX_pose.json50Hz 메시지 (accel, rotation_rate, vel)can_bus 7~15번 값
시간·scene 정보sample.json, scene.jsontimestamp, prev / next, scene token시간 순서, prev_bev 초기화
3D Boxsample_annotation.json, instance.json, category.jsonGlobal 좌표 box, 클래스학습 GT, 평가 GT
LiDAR / Radar point cloudsamples/LIDAR_TOP/, samples/RADAR_*/pcd.bin, pcd사용하지 않음 (경로만 pkl에 기록)

2. info pkl 생성 (tools/create_data.py)

PYTHONPATH=. python tools/create_data.py nuscenes --root-path ./data/nuscenes \
    --out-dir ./data/nuscenes --extra-tag nuscenes --version v1.0-mini --canbus ./data
>> nuscenes_infos_temporal_{train,val}.pkl

pkl의 역할

  • 원본은 13개 테이블이 token으로 연결된 관계형 구조라, sample 하나의 입력을 만들려면 여러 테이블을 따라가며 join과 좌표 변환을 해야 한다.
  • 이 작업을 학습 전에 한 번만 수행해서, sample 단위의 평평한 dict 목록으로 저장한 것이 info pkl이다.
  • 학습·추론 중에는 devkit(NuScenes 객체) 없이 pkl과 이미지 파일만 읽는다. devkit은 평가 단계에서만 사용한다.
  • 모델 코드는 pkl 구조만 알면 되므로, pkl은 데이터셋과 모델 사이의 인터페이스 역할을 한다. 커스텀 데이터도 같은 구조의 pkl을 만들면 그대로 사용할 수 있다.

create_data.py가 하는 변환

변환입력 (원본)출력 (pkl 키)
scene 단위 train / val 분할nuscenes/utils/splits.py의 scene 목록train, val pkl 파일
테이블 joinsample → sample_data → calibrated_sensor, ego_pose카메라별 경로·캘리브레이션·pose (cams)
카메라 → LiDAR 변환 계산 (시간 차 보상 포함)카메라와 LiDAR 각각의 calibrated_sensor, ego_posesensor2lidar_rotation, sensor2lidar_translation
GT 좌표 변환Global 좌표 boxLiDAR 좌표 gt_boxes (yaw’ 변환 포함)
클래스 이름 매핑23개 category10개 Detection 클래스 gt_names
속도 계산같은 instance의 앞뒤 annotationLiDAR 좌표 gt_velocity
유효 GT 표시num_lidar_pts + num_radar_ptsvalid_flag
CAN bus 시각 맞춤pose 메시지 (50Hz)sample 시각 직전 메시지 → can_bus (18,)
시간 순서 정보sample의 prev / nextprev, next, frame_idx, scene_token, timestamp
  • 함께 생성되는 *_mono3d.coco.json (카메라별 2D/3D annotation)은 BEVFormer v1에서 사용하지 않는다.

pkl 구조

  • {'infos': [info, ...], 'metadata': {'version': 'v1.0-mini'}} 형태이며, mini 기준 train 323개 / val 81개 info가 있다.
키형식내용
tokenstrsample token
scene_tokenstrscene 구분 (시간 정보 초기화 기준)
prev, nextstr앞뒤 keyframe token (scene 시작/끝이면 '')
frame_idxintscene 내 프레임 번호 (0부터)
timestampintLiDAR keyframe 시각 [μs]
lidar_pathstrLIDAR_TOP .pcd.bin 경로 (BEVFormer는 읽지 않음)
lidar2ego_translation / rotationlistLiDAR → Ego
ego2global_translation / rotationlistEgo → Global (LiDAR 시각)
can_busndarray (18,)자차 상태 (아래 참고)
camsdict카메라 6개 정보 (아래 참고)
sweepslist이전 LiDAR sweep 최대 10개 (BEVFormer는 미사용)
gt_boxesndarray (N, 7)LiDAR 좌표 [x, y, z, w, l, h, yaw']
gt_namesndarray (N,)10개 Detection 클래스 이름 (그 외 클래스는 원본 이름 유지)
gt_velocityndarray (N, 2)LiDAR 좌표 기준 속도 [vx, vy]
num_lidar_pts, num_radar_ptsndarray (N,)box 안의 point 개수
valid_flagndarray (N,)num_lidar_pts + num_radar_pts > 0
  • cams[채널] 구조 (채널 순서: CAM_FRONT, CAM_FRONT_RIGHT, CAM_FRONT_LEFT, CAM_BACK, CAM_BACK_LEFT, CAM_BACK_RIGHT)
키내용
data_path이미지 경로
sample_data_token, timestamp카메라 sample_data 정보 (촬영 시각)
sensor2ego_translation / rotation카메라 → Ego
ego2global_translation / rotationEgo → Global (카메라 시각)
sensor2lidar_rotation (3×3), sensor2lidar_translation (3,)카메라 → LiDAR (시간 차 보상 포함, 위 변환 체인으로 계산)
cam_intrinsic (3×3)내부 파라미터

3. Dataset: pkl → input_dict (get_data_info)

  • projects/mmdet3d_plugin/datasets/nuscenes_dataset.py
  • Dataset은 pkl을 불러올 때 info를 timestamp 순으로 정렬한 뒤, index로 info 하나를 꺼내 아래 값을 만든다.

① lidar2img (카메라 6개 × 4×4)

  • BEV 격자의 3D 기준점을 각 카메라 이미지로 투영하는 데 사용된다. (Spatial Cross-Attention)

② can_bus (18차원)

인덱스내용출처
0:3자차 위치 (Global) [m]ego2global_translation으로 덮어씀
3:7자차 회전 (quaternion)ego2global_rotation으로 덮어씀
7:10가속도 accelCAN bus pose 메시지
10:13각속도 rotation_rateCAN bus pose 메시지
13:16속도 velCAN bus pose 메시지
16자차 yaw [rad] (0 ~ 2π)ego pose quaternion에서 계산
17자차 yaw [deg] (0 ~ 360)ego pose quaternion에서 계산
  • 위치와 yaw는 CAN bus가 아니라 nuScenes ego_pose(LiDAR 맵 매칭 localization) 값을 사용한다.
  • 시간 정보로 쓸 때 [0:3]과 [17]은 **이전 프레임과의 차이(Δ위치, Δyaw)**로 바뀐다. 이 값으로 이전 BEV feature를 현재 위치에 맞게 회전·이동한다.
    • scene의 첫 프레임이면 0으로 설정하고 prev_bev_exists = False가 된다.
  • 전체 18차원은 can_bus_mlp를 거쳐 BEV query에 더해진다.

③ GT (학습 시)

  • valid_flag가 True인 box만 사용한다. (use_valid_flag=True)
  • pkl의 7차원 box에 gt_velocity를 붙이고, 중심을 기하 중심에서 바닥 중심으로 바꿔 LiDARInstance3DBoxes 9차원 [x, y, z_bottom, w, l, h, yaw', vx, vy]로 만든다.

4. pipeline: input_dict → 텐서 (tiny 기준)

순서단계처리결과 (카메라 1장 기준)
1LoadMultiViewImageFromFilesjpg 6장을 읽어 float32로 변환 (BGR 순서)ndarray (900, 1600, 3) × 6
2PhotoMetricDistortionMultiViewImage밝기, 대비, 채도, 색조 무작위 변경 (학습만)크기 동일
3LoadAnnotations3D, ObjectRangeFilter, ObjectNameFilterGT 로드, x·y ±51.2m 밖과 10개 클래스 외 box 제거 (학습만)gt_bboxes_3d, gt_labels_3d
4NormalizeMultiviewImageImageNet mean/std 정규화, BGR → RGB(900, 1600, 3)
5RandomScaleImageMultiViewImage0.5배 리사이즈. lidar2img에도 같은 scale 행렬을 곱함(450, 800, 3)
6PadMultiViewImage32의 배수가 되도록 아래쪽을 0으로 패딩(480, 800, 3)
7DefaultFormatBundle3DHWC → CHW, 6장을 쌓아 Tensor로 변환[6, 3, 480, 800]
8CustomCollect3D모델에 넘길 키(img, GT)만 남기고 메타 정보는 img_metas로 묶음img + img_metas
  • 추론 시에는 2, 3단계가 없고, 4~8단계가 MultiScaleFlipAug3D 안에서 실행된다. (flip, 다중 스케일은 사용하지 않음)
  • small은 0.8배 리사이즈, base는 리사이즈 없이 원본 크기를 쓰며, 둘 다 caffe 방식 정규화(BGR mean만 빼고 std = 1)를 사용한다.

5. 최종 모델 입력

키형태내용
imgTensor [B, queue, 6, 3, 480, 800] (학습), [1, 6, 3, 480, 800] (추론)정규화된 카메라 이미지
img_metasdict (학습은 프레임 번호별 dict)lidar2img (6 × 4×4), can_bus (18,), scene_token, prev_bev_exists, img_shape, pad_shape 등
gt_bboxes_3dLiDARInstance3DBoxes (N, 9)현재 프레임 GT box (학습만)
gt_labels_3dTensor (N,)클래스 번호 0~9 (학습만)
  • 학습: queue_length개 프레임을 각각 pipeline에 통과시킨 뒤 union2one()으로 하나의 sample로 묶는다.
    • 이때 can_bus 위치·yaw를 프레임 간 차이로 바꾸고 prev_bev_exists를 정한다.
    • GT는 마지막(현재) 프레임 것만 사용한다.
  • 추론: 프레임 1개만 넣고, can_bus 차이 계산은 모델 내부(prev_frame_info)에서 수행한다.
  • 출력: 모델은 LiDAR 좌표 box를 출력하고, format_results()가 pkl의 lidar2ego, ego2global로 Global 좌표로 바꿔 results_nusc.json에 저장한다. ((Dataset) nuScenes Dataset의 “결과 제출 형식” 참고)

학습 / 추론 시 구성

항목학습추론
한 번에 넣는 프레임현재 + 과거 프레임 (queue)현재 프레임 1개
과거 프레임 선택직전 queue_length(tiny: 3)개 중 무작위로 queue_length − 1개 + 현재-
이전 BEV과거 프레임으로 no_grad 상태에서 BEV를 만들어 사용모델 내부 prev_frame_info에 저장된 직전 BEV 사용
scene 경계queue 안에서 scene이 바뀌면 prev_bev_exists = Falsescene_token이 바뀌면 이전 BEV 초기화
이미지 증강PhotoMetricDistortionMultiViewImage없음
입력 텐서 (tiny)img: [B, 3, 6, 3, 480, 800]img: [1, 6, 3, 480, 800]
데이터 순서무작위 셔플 가능 (queue가 시간 정보 담당)scene 내 시간 순서, batch 1 필수

참고 사항

  • 커스텀 데이터 준비 방법은 아래 커스텀 데이터셋 준비 가이드 참고.
  • _get_can_bus_info()는 sample 시각 직전의 pose 메시지에서 위치·회전을 읽지만, accel / rotation_rate / vel은 코드상 루프를 빠져나온 **직후 메시지(약 20ms 뒤)**에서 읽는다. 영향은 작지만 커스텀 데이터 변환 시 참고한다.

커스텀 데이터셋 준비 가이드

  • 목표: 직접 수집한 데이터를 위 info pkl과 같은 구조로 만들어 BEVFormer를 학습한다. Dataset·pipeline·모델 코드는 pkl만 읽으므로, pkl 구조를 맞추면 학습 코드는 config 수정만으로 사용할 수 있다.
  • 표기
    • [필수] : 코드가 요구하는 조건. 지키지 않으면 오류가 나거나 결과가 틀린다.
    • [권장] : nuScenes 조건과 맞추거나 데이터 품질을 위한 사항. pretrained 모델을 이어서 학습할 때 특히 중요하다.

준비 순서

1. 센서 구성·장착   카메라 6대 + Localization(GNSS/INS 등) + (LiDAR, IMU/차량 CAN)
2. 캘리브레이션     카메라 내부 파라미터, 각 센서 → Ego 외부 파라미터
3. 주행·수집        scene(연속 주행 구간) 단위 녹화, 모든 데이터에 같은 시계의 timestamp
4. keyframe 선택    약 2Hz 간격으로 기준 시각 + 카메라 6장 묶기
5. 3D Box 라벨링    keyframe마다 Global 좌표 box, scene 안에서 instance ID 유지
6. info pkl 변환    아래 변환 코드로 train / val pkl 생성
7. config 수정·검증 경로, 클래스, 범위 수정 → GT 투영 시각화로 확인 → 학습

1. 준비해야 할 데이터

데이터필수 여부형식BEVFormer에서 쓰이는 곳
카메라 이미지필수jpg / png, 왜곡 보정 완료, 모든 카메라 같은 해상도모델 입력 img
카메라 내부 파라미터필수3×3 행렬 (왜곡 보정 후 이미지 기준)lidar2img
센서 외부 파라미터필수센서 → Ego, translation [m] + quaternion (w, x, y, z)lidar2img, 좌표 변환
Ego pose필수시각별 Ego → Global, translation [m] + quaternioncan_bus 위치·yaw (이전 BEV 정렬), 카메라 시간 차 보상, GT 좌표 변환
timestamp필수모든 센서 공통 시계, 절대 시각 [μs] 정수정렬, 과거 프레임(queue) 구성
scene 구분필수연속 주행 구간 이름scene_token (이전 BEV 초기화 기준)
3D Box학습 시 필수중심, 크기 (w, l, h), 회전, 클래스, instance IDgt_bboxes_3d, gt_labels_3d
Box 속도권장instance ID로 계산 (없으면 0)회귀 대상 vx, vy
IMU / 차량 CAN선택가속도, 각속도, 속도 (Ego 좌표)can_bus[7:16] (없으면 0)
LiDAR point cloud선택 (라벨링에 사실상 필요).bin 등3D Box 라벨링, valid_flag, 캘리브레이션 검증 (모델 입력 아님)

2. 센서 구성

카메라

항목조건이유
카메라 개수[권장] 6대config 기본값 num_cams=6. 카메라별 학습 임베딩 cams_embeds 크기가 카메라 수에 고정되어, 수가 다르면 config 수정 후 해당 가중치를 새로 학습해야 한다.
배치[권장] 360° 전체를 덮고, 인접 카메라 시야가 조금씩 겹치게어느 카메라에도 안 보이는 영역은 BEV feature가 비어 검출할 수 없다.
카메라 순서[필수] 모든 sample에서 같은 순서cams_embeds가 카메라 index 순서대로 더해진다.
해상도[필수] 모든 카메라 같은 해상도point_sampling()이 **첫 번째 카메라의 img_shape**로 6장의 투영 좌표를 정규화한다. (encoder.py)
렌즈 왜곡[필수] 왜곡을 보정한 이미지로 저장투영에 만 쓰는 핀홀 모델이며, 왜곡 계수를 입력받지 않는다.
동기화[권장] 하드웨어 트리거로 동시 촬영시간 차가 있으면 카메라별 timestamp와 그 시각의 ego pose로 보상한다. (nuScenes 방식, 아래 변환 코드에 포함)
프레임률[권장] 수집은 10Hz 이상, keyframe은 약 2Hz로 선택nuScenes 학습 조건(0.5초 간격 과거 프레임)과 맞춘다.
장착[권장] 높이 약 1.5m, 수평 방향nuScenes 카메라 조건(높이 약 1.5m, 수평 FOV 약 65°, 후방 약 90°)과 비슷할수록 pretrained 모델을 이어서 학습하기 유리하다.

Localization (Ego pose) [필수]

  • 방법: RTK-GNSS/INS, LiDAR SLAM 또는 맵 매칭. (nuScenes: LiDAR 맵 매칭, 논문 기준 오차 10cm 이내)
  • Global 좌표계: 고정된 미터 단위 직교 좌표계, z 위. (예: 수집 시작점 기준 local ENU, UTM에서 원점 오프셋을 뺀 값)
    • 위도·경도를 그대로 쓰면 안 된다. Δ위치를 미터로 계산해 BEV 격자를 이동시키기 때문이다.
  • 주기: 카메라 촬영 시각마다 pose가 필요하므로 50Hz 이상으로 기록하고 시각에 맞춰 보간한다.
  • 사용처: 프레임 간 Δ위치·Δyaw로 이전 BEV를 이동·회전한다. pose 오차는 이전 BEV와 현재 BEV의 정렬 오차가 된다.

IMU / 차량 CAN [선택]

  • 값: 가속도 accel [m/s²], 각속도 rotation_rate [rad/s], 속도 vel [m/s], 모두 Ego 좌표계 3축. (nuScenes CAN bus pose 메시지와 같은 정의)
  • 없으면 can_bus[7:16]을 0으로 둔다. 학습은 되지만 nuScenes pretrained 모델과 입력 분포가 달라지므로, 가능하면 기록한다.

LiDAR [선택, 라벨링용 권장]

  • 모델 입력은 아니지만, 카메라만으로는 거리·크기가 정확한 3D Box를 라벨링하기 어렵다.
  • 용도: 3D Box 라벨링, box 안 점 개수(num_lidar_pts) → valid_flag, 카메라 캘리브레이션 검증
  • LiDAR가 없어도 기준 좌표계는 있어야 하므로, 아래처럼 가상 센서로 정의한다.

3. 좌표계 규칙

좌표계축원점역할
Global고정, z 위, [m]지도 또는 수집 시작점ego pose, GT 라벨링
Egox 전방, y 좌측, z 위차량 기준점 (nuScenes: 후륜 축 중심)모든 센서 외부 파라미터의 기준
기준 (LIDAR_TOP)[권장] x 우측, y 전방, z 위LiDAR 위치 또는 가상 점BEV 격자와 예측 box의 좌표계
Camerax 우측, y 아래, z 광축 (OpenCV)카메라 광학 중심이미지 투영
  • 기준 좌표계
    • BEV 격자 범위 point_cloud_range = [-51.2, -51.2, -5.0, 51.2, 51.2, 3.0]와 모델이 출력하는 box가 이 좌표계 기준이다.
    • nuScenes LiDAR는 Ego 원점 기준 (0.94, 0, 1.84)m, yaw −90°에 있다. 같은 위치·방향으로 두면 point_cloud_range를 그대로 쓸 수 있다.
    • 원점 높이를 다르게 두면 z 범위(−5 ~ 3m)도 그만큼 옮겨야 한다.
    • LiDAR가 없으면 calib 파일에 위 값으로 가상 LIDAR_TOP을 정의한다. (rotation [0.7071, 0, 0, -0.7071])
  • 변환 표기: 외부 파라미터 “센서 → Ego”는 를 뜻하고, quaternion 순서는 (w, x, y, z) 이다.
  • Box 표기: 크기는 [w, l, h] (폭, 길이, 높이), heading은 길이(l) 방향, yaw는 해당 좌표계 x축에서 반시계 방향 +이다. (nuScenes와 같음)

4. 캘리브레이션

항목방법확인 방법
카메라 내부 파라미터체커보드 촬영 → OpenCV calibrateCamera (, 왜곡 계수)재투영 오차
왜곡 보정저장 전 undistort, 보정 후의 새 를 기록 (getOptimalNewCameraMatrix)직선이 곧게 보이는지
LiDAR → Ego장착 위치 측정 (차량 도면, 지면 기준)지면 점의 z 높이
카메라 → EgoLiDAR-카메라 캘리브레이션 결과에 LiDAR → Ego를 곱함LiDAR 점을 이미지에 투영해 물체 경계와 맞는지
GNSS/INS → Ego장착 위치 측정직진·회전 주행 시 pose 궤적
  • 장착이 바뀌면 calib 파일을 새로 만들고, scene마다 사용한 calib ID를 기록한다. (nuScenes도 차량별로 calibrated_sensor가 다르다.)

5. 원본 데이터 폴더 구조

  • 아래는 수집·라벨링 결과를 저장하는 원본 구조의 예시이며, 6단계에서 info pkl로 변환한다.
data/custom/                                # 데이터셋 루트 (BEVFormer 저장소 기준 경로)
├── calib/
│   └── rig_01.json                         # 센서 리그 1개의 캘리브레이션 (센서별 외부·내부 파라미터)
├── scenes/
│   └── scene_0001/                         # 연속 주행 구간 1개 (예: 20 ~ 60초)
│       ├── scene.json                      # scene 이름, 사용한 calib ID, 날짜, 장소, 설명
│       ├── camera/
│       │   ├── CAM_FRONT/
│       │   │   └── 1700000000012345.jpg    # 파일명 = 촬영 시각 [μs], 왜곡 보정 완료
│       │   ├── CAM_FRONT_RIGHT/
│       │   ├── CAM_FRONT_LEFT/
│       │   ├── CAM_BACK/
│       │   ├── CAM_BACK_LEFT/
│       │   └── CAM_BACK_RIGHT/
│       ├── lidar/                          # (선택) 라벨링·검증용
│       │   └── 1700000000050000.bin
│       ├── ego_pose.csv                    # Ego → Global pose (50Hz 이상)
│       ├── can_bus.csv                     # (선택) 가속도, 각속도, 속도
│       ├── keyframes.json                  # keyframe 목록: 기준 시각 + 카메라 6장 파일
│       └── annotations.json                # keyframe별 3D Box (Global 좌표)
├── splits.json                             # train / val scene 목록
├── custom_infos_temporal_train.pkl         # 변환 결과 (6단계)
└── custom_infos_temporal_val.pkl
파일역할nuScenes 대응
calib/*.json센서별 외부·내부 파라미터sensor, calibrated_sensor
scene.jsonscene 메타데이터scene, log
camera/, lidar/센서 원본 데이터samples/, sweeps/
ego_pose.csv시각별 자차 poseego_pose
can_bus.csv자차 상태can_bus/*_pose.json
keyframes.jsonkeyframe과 센서 파일 묶음sample, sample_data
annotations.json3D Box GTsample_annotation, instance, category
splits.jsontrain / val 분할nuscenes/utils/splits.py
  • train / val은 scene 단위로 나눈다. 같은 scene의 프레임은 서로 거의 같아서, 프레임 단위로 나누면 검증 성능이 실제보다 높게 나온다.

6. 파일 형식

calib/rig_01.json (값은 nuScenes scene-0061 예시)

{
  "id": "rig_01",
  "sensors": {
    "LIDAR_TOP": {"translation": [0.9437, 0.0, 1.8402], "rotation": [0.7078, -0.0065, 0.0106, -0.7063]},
    "CAM_FRONT": {
      "translation": [1.7008, 0.0159, 1.511],
      "rotation": [0.4998, -0.503, 0.4998, -0.4974],
      "intrinsic": [[1266.4, 0.0, 816.3], [0.0, 1266.4, 491.5], [0.0, 0.0, 1.0]],
      "width": 1600, "height": 900
    }
  }
}
  • translation, rotation: 센서 → Ego. 카메라 6대 모두 같은 형식으로 적는다.

scene.json

{"name": "scene_0001", "calib": "rig_01", "date": "2026-11-13", "location": "city_a", "description": "도심 교차로, 주간, 맑음"}

ego_pose.csv, can_bus.csv

timestamp,x,y,z,qw,qx,qy,qz
1700000000000000,12.531,-3.204,0.0,0.9998,0.0,0.0,0.0199
timestamp,ax,ay,az,wx,wy,wz,vx,vy,vz
1700000000000000,0.12,-0.03,9.81,0.0,0.0,0.015,8.42,0.01,0.0
  • ego_pose.csv: Ego → Global. can_bus.csv: Ego 좌표계 값이다. nuScenes 가속도는 중력 성분을 포함한다. (scene-0061 평균 ≈ 9.78) 같은 기준으로 맞추는 것이 좋다.

keyframes.json

[
  {
    "token": "scene_0001_000",
    "timestamp": 1700000000050000,
    "lidar": "lidar/1700000000050000.bin",
    "cams": {
      "CAM_FRONT": {"file": "camera/CAM_FRONT/1700000000012345.jpg", "timestamp": 1700000000012345},
      "CAM_FRONT_RIGHT": {"file": "camera/CAM_FRONT_RIGHT/1700000000020611.jpg", "timestamp": 1700000000020611}
    }
  }
]
  • token: 전체 데이터셋에서 고유한 문자열
  • timestamp: keyframe 기준 시각 (LiDAR가 있으면 LiDAR 시각, 없으면 카메라 시각 평균). GT box는 이 시각 기준으로 라벨링한다.
  • cams: 6대 모두 기록하며, 각 카메라의 실제 촬영 시각을 함께 적는다.

annotations.json (keyframe token별 box 목록)

{
  "scene_0001_000": [
    {
      "instance_id": "scene_0001_car_0012",
      "category": "car",
      "center": [25.1, -4.3, 0.85],
      "size": [1.9, 4.6, 1.7],
      "rotation": [0.9659, 0.0, 0.0, 0.2588],
      "num_lidar_pts": 132
    }
  ]
}
키규칙
instance_id같은 객체는 scene 안에서 같은 ID (속도 계산, 추적에 사용)
category학습 클래스 이름 (config의 class_names와 같은 문자열)
centerGlobal 좌표, box 기하 중심 (높이의 가운데) [m]
size[w, l, h] [m]
rotationGlobal 좌표 quaternion (w, x, y, z). yaw만 있으면
num_lidar_ptsbox 안 LiDAR 점 개수. 0이면 학습에서 제외. LiDAR가 없으면 생략 (모두 유효로 처리)
  • 라벨링 범위: 기준 좌표계 x, y ±51.2m 안의 모든 대상 클래스 객체. 범위 밖 box는 pipeline에서 제거된다.
  • 일부만 라벨링하면 라벨이 없는 객체가 오검출(FP)로 학습되므로, 범위 안 객체는 빠짐없이 라벨링한다.

7. info pkl 변환

[필수] 규칙

  • timestamp는 절대 시각으로 적는다. Dataset이 전체 info를 timestamp로 정렬하므로, scene마다 0부터 시작하면 여러 scene의 프레임이 섞여 queue와 이전 BEV가 엉킨다.
  • data_path는 학습을 실행하는 위치(BEVFormer 저장소 루트) 기준 상대 경로 또는 절대 경로로 적는다. LoadMultiViewImageFromFiles가 이 경로를 그대로 연다.
  • lidar_path, sweeps, prev, next, frame_idx 키는 BEVFormer가 사용하지 않아도 get_data_info()가 읽으므로 반드시 있어야 한다. (LiDAR가 없으면 '', [])
  • can_bus는 ndarray (18,) 이어야 한다. [0:7]과 [16:18]은 Dataset이 ego pose로 덮어쓴다.

변환 코드 (tools/custom_converter.py 예시)

"""커스텀 원본 데이터 → BEVFormer info pkl (create_data.py 결과와 같은 구조)"""
import json, os, pickle
import numpy as np
from pyquaternion import Quaternion
from nuscenes.utils.data_classes import Box
 
ROOT = 'data/custom'   # BEVFormer 저장소 루트 기준
CAMS = ['CAM_FRONT', 'CAM_FRONT_RIGHT', 'CAM_FRONT_LEFT',
        'CAM_BACK', 'CAM_BACK_LEFT', 'CAM_BACK_RIGHT']   # 모든 sample에서 같은 순서
 
 
def T(t, q):
    """translation + quaternion(w, x, y, z) → 4×4 변환 행렬"""
    M = np.eye(4)
    M[:3, :3] = Quaternion(q).rotation_matrix
    M[:3, 3] = t
    return M
 
 
def load_csv(path):
    a = np.loadtxt(path, delimiter=',', skiprows=1, ndmin=2)
    return a[np.argsort(a[:, 0])]
 
 
def pose_at(poses, ts):
    """ego_pose.csv를 시각 ts로 보간 (위치: 선형, 회전: slerp) → Ego → Global 4×4"""
    i = int(np.clip(np.searchsorted(poses[:, 0], ts), 1, len(poses) - 1))
    p0, p1 = poses[i - 1], poses[i]
    r = float(np.clip((ts - p0[0]) / (p1[0] - p0[0]), 0.0, 1.0))
    q = Quaternion.slerp(Quaternion(p0[4:8]), Quaternion(p1[4:8]), r)
    return T(p0[1:4] + r * (p1[1:4] - p0[1:4]), q.elements)
 
 
def can_at(can, ts):
    """ts 직전 CAN 메시지 → can_bus (18,)"""
    v = np.zeros(18)
    if can is not None:
        i = max(int(np.searchsorted(can[:, 0], ts, side='right')) - 1, 0)
        v[7:16] = can[i, 1:10]   # accel(3), rotation_rate(3), vel(3)
    return v
 
 
def velocities(annos, kf_ts):
    """같은 instance의 앞뒤 keyframe 중심 차이 / 시간 차 → Global (vx, vy). 계산할 수 없으면 NaN"""
    tracks = {}
    for tok, boxes in annos.items():
        for a in boxes:
            tracks.setdefault(a['instance_id'], []).append((kf_ts[tok], tok, np.array(a['center'])))
    vel = {}
    for iid, tr in tracks.items():
        tr.sort(key=lambda x: x[0])
        for k, (_, tok, _) in enumerate(tr):
            t0, _, c0 = tr[max(k - 1, 0)]
            t1, _, c1 = tr[min(k + 1, len(tr) - 1)]
            dt = (t1 - t0) / 1e6
            vel[(tok, iid)] = (c1 - c0)[:2] / dt if 0 < dt <= 3.0 else np.array([np.nan, np.nan])
    return vel
 
 
def convert(scene_names, out_path):
    infos = []
    for name in scene_names:
        sd = f'{ROOT}/scenes/{name}'
        scene = json.load(open(f'{sd}/scene.json'))
        calib = json.load(open(f"{ROOT}/calib/{scene['calib']}.json"))['sensors']
        kfs = sorted(json.load(open(f'{sd}/keyframes.json')), key=lambda k: k['timestamp'])
        annos = json.load(open(f'{sd}/annotations.json'))
        poses = load_csv(f'{sd}/ego_pose.csv')
        can = load_csv(f'{sd}/can_bus.csv') if os.path.exists(f'{sd}/can_bus.csv') else None
        vel = velocities(annos, {k['token']: k['timestamp'] for k in kfs})
        ref = calib['LIDAR_TOP']                       # 기준 좌표계 (실제 또는 가상 LiDAR)
        l2e = T(ref['translation'], ref['rotation'])   # 기준 → Ego
 
        for i, kf in enumerate(kfs):
            e2g = pose_at(poses, kf['timestamp'])     # keyframe 시각의 Ego → Global
            info = dict(
                token=kf['token'], scene_token=name, frame_idx=i,
                prev=kfs[i - 1]['token'] if i > 0 else '',
                next=kfs[i + 1]['token'] if i + 1 < len(kfs) else '',
                timestamp=int(kf['timestamp']),
                lidar_path=f"{sd}/{kf['lidar']}" if kf.get('lidar') else '', sweeps=[],
                lidar2ego_translation=list(ref['translation']),
                lidar2ego_rotation=list(ref['rotation']),
                ego2global_translation=list(e2g[:3, 3]),
                ego2global_rotation=list(Quaternion(matrix=e2g[:3, :3]).elements),
                can_bus=can_at(can, kf['timestamp']), cams={})
 
            # 카메라: Camera → Ego(촬영 시각) → Global → Ego(keyframe 시각) → 기준 좌표계
            for ch in CAMS:
                c, cam = calib[ch], kf['cams'][ch]
                e2g_c = pose_at(poses, cam['timestamp'])
                c2l = np.linalg.inv(l2e) @ np.linalg.inv(e2g) @ e2g_c @ T(c['translation'], c['rotation'])
                info['cams'][ch] = dict(
                    data_path=f"{sd}/{cam['file']}", type=ch, timestamp=int(cam['timestamp']),
                    sample_data_token=f"{kf['token']}_{ch}",
                    sensor2ego_translation=list(c['translation']),
                    sensor2ego_rotation=list(c['rotation']),
                    ego2global_translation=list(e2g_c[:3, 3]),
                    ego2global_rotation=list(Quaternion(matrix=e2g_c[:3, :3]).elements),
                    sensor2lidar_rotation=c2l[:3, :3], sensor2lidar_translation=c2l[:3, 3],
                    cam_intrinsic=np.array(c['intrinsic'], dtype=np.float64))
 
            # GT: Global → Ego(keyframe 시각) → 기준 좌표계
            boxes, names, vels, npts = [], [], [], []
            for a in annos.get(kf['token'], []):
                v = vel[(kf['token'], a['instance_id'])]
                b = Box(a['center'], a['size'], Quaternion(a['rotation']), velocity=(v[0], v[1], 0.0))
                b.translate(-e2g[:3, 3]); b.rotate(Quaternion(matrix=e2g[:3, :3]).inverse)
                b.translate(-l2e[:3, 3]); b.rotate(Quaternion(matrix=l2e[:3, :3]).inverse)
                yaw = b.orientation.yaw_pitch_roll[0]
                boxes.append([*b.center, *b.wlh, -yaw - np.pi / 2])   # mmdet3d 0.17 yaw 규칙
                vels.append(b.velocity[:2])
                names.append(a['category'])
                npts.append(a.get('num_lidar_pts', -1))           # -1: 점 개수 정보 없음
            n, npts = len(boxes), np.array(npts, dtype=np.int64)
            info.update(
                gt_boxes=np.array(boxes, dtype=np.float64).reshape(n, 7),
                gt_names=np.array(names, dtype='<U32'),
                gt_velocity=np.array(vels, dtype=np.float64).reshape(n, 2),
                num_lidar_pts=npts, num_radar_pts=np.zeros(n, dtype=np.int64),
                valid_flag=npts != 0)
            infos.append(info)
 
    with open(out_path, 'wb') as f:
        pickle.dump(dict(infos=infos, metadata=dict(version='custom')), f)
    print(out_path, len(infos))
 
 
if __name__ == '__main__':
    splits = json.load(open(f'{ROOT}/splits.json'))   # {"train": [...], "val": [...]}
    convert(splits['train'], f'{ROOT}/custom_infos_temporal_train.pkl')
    convert(splits['val'], f'{ROOT}/custom_infos_temporal_val.pkl')
  • 카메라 → 기준 좌표계 변환, GT box·속도 변환 수식은 nuScenes mini val 20개 sample에서 create_data.py 결과와 같은 값(오차 이하)이 나오는 것을 확인했다.
  • 파일 읽기, 보간, 속도 계산 부분은 실제 커스텀 데이터로 실행해 보지 않은 예시 코드이다.
  • 속도는 nuScenes box_velocity()처럼 앞뒤 keyframe 중심 차이로 구하며, 이웃 프레임이 없으면 NaN이고 Dataset이 0으로 바꾼다.

8. config 수정

  • projects/configs/bevformer/bevformer_tiny.py를 복사해 bevformer_tiny_custom.py로 만든 뒤 아래 항목을 고친다.
항목위치수정 내용
data_root, ann_filedata.train / val / testdata/custom/, custom_infos_temporal_{train,val}.pkl
class_names파일 상단커스텀 클래스 목록 (annotations.json의 category와 같은 문자열)
num_classespts_bbox_head, bbox_coder (2곳)클래스 개수
point_cloud_range파일 상단인식 범위. 기준 좌표계 원점 높이를 바꿨다면 z 범위도 수정 (post_center_range도 함께)
bev_h_, bev_w_파일 상단BEV 격자 수. 범위 ÷ 격자 수 = 격자 크기 (tiny: 102.4m ÷ 50 = 2.048m)
RandomScaleImageMultiViewImagetrain / test pipeline이미지 해상도에 맞춰 축소 비율 조정 (tiny: 1600×900 → 0.5배)
num_camstransformer, SpatialCrossAttention (2곳)카메라가 6대가 아닐 때 추가 (기본값 6)
queue_length파일 상단학습 시 사용할 과거 프레임 수
code_weightspts_bbox_head속도 GT가 없으면 마지막 2개(vx, vy)를 0으로 설정 (기본 [1,1,1,1,1,1,1,1,0.2,0.2])
load_from파일 하단nuScenes pretrained를 이어서 학습할 때 지정. 클래스 수가 다르면 분류 층 shape이 맞지 않아 그 층은 새로 학습된다.
  • 평가: --eval bbox는 nuScenes devkit으로 원본 테이블(v1.0-*)을 다시 읽고, 결과 변환(_format_bbox)도 nuScenes 클래스 이름을 기준으로 한다.
    • 따라서 커스텀 데이터는 학습만 위 pkl로 가능하고, 평가는 결과 box(기준 좌표계)와 GT를 비교하는 별도 평가 코드가 필요하다.
    • nuScenes 형식 테이블까지 만들면 devkit 평가를 쓸 수 있지만, 버전 이름(eval_set_map)과 클래스 설정을 함께 수정해야 한다.

9. 검증 체크리스트

  • 이미지 6장의 해상도가 모두 같고, 카메라 순서가 모든 sample에서 같다.
  • pkl 한 sample의 GT box 꼭짓점을 lidar2img로 6장 이미지에 투영했을 때 객체와 겹친다. ((BEVFormer) BEVFormer 환경구축 및 추론 테스트의 시각화 코드 활용)
  • 정렬된 info에서 같은 scene의 프레임이 연속으로 이어지고, scene끼리 timestamp가 겹치지 않는다.
  • 연속 keyframe 간 ego 이동 거리가 차량 속도 × 시간 간격과 비슷하고, yaw가 끊기지 않는다.
  • gt_names가 class_names에 포함되고, gt_boxes의 x, y가 대부분 ±51.2m 안에 있다.
  • 적은 수의 scene으로 짧게 학습했을 때 loss가 줄어든다. (데이터·config 오류 확인용)

참고