nuScenes 데이터가 BEVFormer 모델 입력이 되기까지의 데이터 형식, 변환 과정, info pkl의 역할 정리 및 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×3 lidar2img 계산LiDAR 캘리브레이션 calibrated_sensor.json (LIDAR_TOP)translation, rotation 기준 좌표계(LiDAR) 정의 자차 pose ego_pose.jsontranslation, rotation 센서 간 시간 차 보상, can_bus 위치·yaw, 결과의 Global 변환 CAN bus can_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 Box sample_annotation.json, instance.json, category.jsonGlobal 좌표 box, 클래스 학습 GT, 평가 GT LiDAR / Radar point cloud samples/LIDAR_TOP/, samples/RADAR_*/pcd.bin, pcd 사용하지 않음 (경로만 pkl에 기록)
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 파일 테이블 join sample → sample_data → calibrated_sensor, ego_pose 카메라별 경로·캘리브레이션·pose (cams) 카메라 → LiDAR 변환 계산 (시간 차 보상 포함) 카메라와 LiDAR 각각의 calibrated_sensor, ego_pose sensor2lidar_rotation, sensor2lidar_translationGT 좌표 변환 Global 좌표 box LiDAR 좌표 gt_boxes (yaw’ 변환 포함) 클래스 이름 매핑 23개 category 10개 Detection 클래스 gt_names 속도 계산 같은 instance의 앞뒤 annotation LiDAR 좌표 gt_velocity 유효 GT 표시 num_lidar_pts + num_radar_ptsvalid_flagCAN bus 시각 맞춤 pose 메시지 (50Hz)sample 시각 직전 메시지 → can_bus (18,) 시간 순서 정보 sample의 prev / next prev, 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가 있다.
키 형식 내용 tokenstr sample token scene_tokenstr scene 구분 (시간 정보 초기화 기준) prev, nextstr 앞뒤 keyframe token (scene 시작/끝이면 '') frame_idxint scene 내 프레임 번호 (0부터) timestampint LiDAR keyframe 시각 [μs] lidar_pathstr LIDAR_TOP .pcd.bin 경로 (BEVFormer는 읽지 않음) lidar2ego_translation / rotationlist LiDAR → Ego ego2global_translation / rotationlist Ego → 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)내부 파라미터 K
projects/mmdet3d_plugin/datasets/nuscenes_dataset.py
Dataset은 pkl을 불러올 때 info를 timestamp 순으로 정렬 한 뒤, index로 info 하나를 꺼내 아래 값을 만든다.
① lidar2img (카메라 6개 × 4×4)
T l i d a r c am = ( T c am l i d a r ) − 1 , lidar2img = [ K 0 0 1 ] ⋅ T l i d a r c am
BEV 격자의 3D 기준점을 각 카메라 이미지로 투영하는 데 사용된다. (Spatial Cross-Attention)
② can_bus (18차원)
인덱스 내용 출처 0:3 자차 위치 (Global) [m] ego2global_translation으로 덮어씀 3:7 자차 회전 (quaternion) ego2global_rotation으로 덮어씀 7:10 가속도 accel CAN bus pose 메시지 10:13 각속도 rotation_rate CAN bus pose 메시지 13:16 속도 vel CAN 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]로 만든다.
순서 단계 처리 결과 (카메라 1장 기준) 1 LoadMultiViewImageFromFilesjpg 6장을 읽어 float32로 변환 (BGR 순서) ndarray (900, 1600, 3) × 6 2 PhotoMetricDistortionMultiViewImage밝기, 대비, 채도, 색조 무작위 변경 (학습만 ) 크기 동일 3 LoadAnnotations3D, ObjectRangeFilter, ObjectNameFilterGT 로드, x·y ±51.2m 밖과 10개 클래스 외 box 제거 (학습만 ) gt_bboxes_3d, gt_labels_3d4 NormalizeMultiviewImageImageNet mean/std 정규화, BGR → RGB (900, 1600, 3) 5 RandomScaleImageMultiViewImage0.5배 리사이즈. lidar2img에도 같은 scale 행렬을 곱함 (450, 800, 3) 6 PadMultiViewImage32의 배수가 되도록 아래쪽을 0으로 패딩 (480, 800, 3) 7 DefaultFormatBundle3DHWC → CHW, 6장을 쌓아 Tensor로 변환 [6, 3, 480, 800] 8 CustomCollect3D모델에 넘길 키(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 = False scene_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 행렬 K (왜곡 보정 후 이미지 기준) lidar2img센서 외부 파라미터 필수 센서 → Ego, translation [m] + quaternion (w, x, y, z) lidar2img, 좌표 변환Ego pose 필수 시각별 Ego → Global, translation [m] + quaternion can_bus 위치·yaw (이전 BEV 정렬), 카메라 시간 차 보상, GT 좌표 변환timestamp 필수 모든 센서 공통 시계, 절대 시각 [μs] 정수 정렬, 과거 프레임(queue) 구성 scene 구분 필수 연속 주행 구간 이름 scene_token (이전 BEV 초기화 기준)3D Box 학습 시 필수 중심, 크기 (w, l, h), 회전, 클래스, instance ID gt_bboxes_3d, gt_labels_3dBox 속도 권장 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)렌즈 왜곡 [필수] 왜곡을 보정한 이미지로 저장 투영에 K 만 쓰는 핀홀 모델이며, 왜곡 계수를 입력받지 않는다. 동기화 [권장] 하드웨어 트리거로 동시 촬영 시간 차가 있으면 카메라별 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 라벨링 Ego x 전방, y 좌측, z 위 차량 기준점 (nuScenes: 후륜 축 중심) 모든 센서 외부 파라미터의 기준 기준 (LIDAR_TOP) [권장] x 우측, y 전방, z 위 LiDAR 위치 또는 가상 점 BEV 격자와 예측 box의 좌표계 Camera x 우측, 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”는 p e g o = R p se n sor + t 를 뜻하고, quaternion 순서는 (w, x, y, z) 이다.
Box 표기 : 크기는 [w, l, h] (폭, 길이, 높이), heading은 길이(l) 방향, yaw는 해당 좌표계 x축에서 반시계 방향 +이다. (nuScenes와 같음)
4. 캘리브레이션
항목 방법 확인 방법 카메라 내부 파라미터 체커보드 촬영 → OpenCV calibrateCamera (K , 왜곡 계수) 재투영 오차 왜곡 보정 저장 전 undistort, 보정 후의 새 K 를 기록 (getOptimalNewCameraMatrix) 직선이 곧게 보이는지 LiDAR → Ego 장착 위치 측정 (차량 도면, 지면 기준) 지면 점의 z 높이 카메라 → Ego LiDAR-카메라 캘리브레이션 결과에 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_sensorscene.jsonscene 메타데이터 scene, logcamera/, lidar/센서 원본 데이터 samples/, sweeps/ego_pose.csv시각별 자차 pose ego_posecan_bus.csv자차 상태 can_bus/*_pose.jsonkeyframes.jsonkeyframe과 센서 파일 묶음 sample, sample_dataannotations.json3D Box GT sample_annotation, instance, categorysplits.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 평균 a z ≈ 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만 있으면 ( cos 2 θ , 0 , 0 , sin 2 θ ) 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 결과와 같은 값(오차 1 0 − 12 이하)이 나오는 것을 확인했다.
파일 읽기, 보간, 속도 계산 부분은 실제 커스텀 데이터로 실행해 보지 않은 예시 코드이다.
속도는 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}.pklclass_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. 검증 체크리스트
참고