본격적으로 BEVformer 소스코드를 뜯어보기전에, 먼저 MMDetection3D에 대해 알아봅시다.
안그러면 처음 소스코드를 뜯어보았을때
이게뭐지?
모델구조가 어디있지?
내가 뭘보고 있는거지?
그냥 포기할란다..
하는 반응이 나옵니다. 제가 그랬어요
MMDetection3D는 OpenMMLab에서 개발한 오픈소스 3D 객체 탐지 프레임워크로, 2D 객체 탐지 프레임워크인 MMDetection을 확장한 버전입니다. 자율주행, 로보틱스, 컴퓨터 비전 연구를 위해 설계되었으며, 카메라 이미지, 라이다 포인트 클라우드, 레이더 데이터 등 멀티모달 데이터를 처리할 수 있습니다.
또한, 대규모 자율주행 데이터셋(예: nuScenes, Waymo, KITTI)의 포맷(예: 카메라 이미지, 라이다 포인트 클라우드, 어노테이션)을 직접 지원하며, 최신 논문의 3D 탐지 모델(예: PointPillars, CenterPoint, BEVFormer 등)을 재현하고 커스터마이징할 수 있는 유연성을 제공합니다.
예를 들어, BEVFormer는 MMDetection3D의 데이터 로더를 활용해 nuScenes의 샘플을 불러오고, 전처리 파이프라인을 통해 멀티뷰 이미지를 BEV 특징 맵으로 변환합니다. 이후 Transformer 기반의 아키텍처를 통해 시공간적 정보를 통합하며, MMDetection3D의 평가 모듈로 nuScenes의 메트릭(NDS, mAP 등)을 계산해 성능을 검증합니다.
MMDetection3D의 기본 구조
git을 통해 논문에서 제공하는 mmdetection기반의 여러 소스코드를 다운받고, 내부를 살펴보면 아래와 같은, 혹은 여기서 크게 벗어나지않는 구조를 갖는다는 것을 알 수 있습니다.
mmdetection3d
├── mmdet3d
├── projects
├── core
├── tools
├── data
이러한 구조는 MMDetection3D의 설계 철학에 담겨있습니다.
OpenMMLab은 연구자들이 최신 논문을 빠르게 구현할 수 있도록 도구를 제공하고자 했습니다.
이를 위해 그들은 모델을 백본(Backbone), 네크(Neck), 헤드(Head)로 나누어 각 모듈을 '마치 레고처럼' 독립적으로 개발하고 조합할 수 있는 '모듈화'에 집중하여 이를 실현했습니다.
이러한 수혜로 연구자들은 projects라는 디렉토리 내에 그들만의 모델을 구현하고 실험할 수 있는 공간을 갖게 되었습니다. 이 디렉토리는 MMDetection3D의 기본 코드를 수정하지 않고, 이미 구현된 방법들을 이용하여 새로운 아이디어를 프로토타이핑하고 테스트할 수 있는 역할을 합니다.
연구자는 projects 내에서 자신의 모델을 구현한 후, configs에 설정을 정의하고, tools/train.py를 통해 학습을 실행할 수 있습니다. 이는 OpenMMLab의 모듈화 철학 덕분에, 기존 MMDetection3D의 안정적인 기반 위에서 자유롭게 실험할 수 있는 환경을 제공합니다.
예를 들어, BEVFormer 는 projects/mmdet3d_plugin/bevformer에 Transformer 기반 아키텍처를 추가하고, nuScenes 데이터로 최적화하여 논문의 결과를 재현했습니다.
자 그럼 이제 각 디렉토리가 어떤 역할을 하는지, 모델의 학습과 평가, 그리고 추론과정에서 어떻게 참조되어서 동작하게 만드는지 자세히 알아볼까요?
/ mmdet3d
-
역할
mmdet3d는 MMDetection3D 프레임워크의 핵심 모듈을 포함하며, 데이터 처리, 모델 아키텍처, 평가 로직 등 프레임워크의 기본 기능을 정의합니다.
BEVFormer와 같은 외부 프로젝트(projects)가 MMDetection3D의 안정적인 기반 위에서 동작할 수 있도록 지원합니다. 연구자들이 기본 모델(PointPillars, CenterPoint 등)을 구현하거나 확장할 때 주로 참조하는 디렉토리입니다. -
기능
1) 데이터 처리: nuScenes, Waymo, KITTI 같은 대규모 데이터셋을 로드하고 전처리하는 로직을 제공.
2) 모델 아키텍처 정의: 3D 객체 탐지 모델의 백본, 네크, 헤드를 구현하여 학습 가능하게 만듦.
3) 평가 로직 제공: 데이터셋별 메트릭(예: NDS, mAP)을 계산하는 기능을 포함.
4) 확장성 지원: projects와의 통합을 위한 인터페이스를 제공하여 새로운 모델 통합 가능. -
내부구조
*실제구조는 아래보다 더많은 디렉토리가 존재합니다. 큰 개념 위주로 알아보겠습니다.mmdet3d
├── datasets : 데이터셋별 로더와 전처리 로직을 정의.
├── models : 3D 객체 탐지 모델의 아키텍처를 정의.
│ ├── backbones
│ ├── necks
│ ├── heads
│ └── utils
├── core : 학습, 평가, 후처리 로직을 포함.
│ ├── evaluation
│ ├── losses
│ └── post_processing
├── ops : 최적화된 연산(예: CUDA 연산)을 제공.
├── version.py
/ projects
-
역할
외부 프로젝트 통합: BEVFormer등 외부 프로젝트를 MMDetection3D에 통합하기 위한 확장 모듈을 포함. 기본 코드를 수정하지 않고 새로운 모델을 프로토타이핑하는 디렉토리. -
기능
1) 커스텀 모델 구현: Transformer 기반 아키텍처(예: BEVFormer) 추가.
2) 데이터셋 확장: 커스텀 데이터셋 로더, 파이프라인 정의.
3) 설정 관리: 프로젝트 전용 configs 제공. -
내부구조
projects
├── mmdet3d_plugin: 새 모델을 위한 커스텀 모듈을 추가하는 디렉토리
│ ├── {Custom_model}: 사용자가 정의한 커스텀 모델 디렉토리
│ │ ├── models : 새 모델을 위한 백본,넥,헤드
│ │ │ ├── backbones
│ │ │ ├── necks
│ │ │ │ └── {Custom_model_neck}.py
│ │ │ └── heads
│ │ │ │ └── {Custom_model_head}.py
│ │ ├── datasets : 새 모델 데이터 설정과 전처리 파이프라인
│ │ └── utils : 모델 구현에 필요한 유틸리티 함수를 정의하는 디렉토리
├── configs : 모델, 데이터셋, 학습 옵션을 정의하고 관리하는 디렉토리
/ projects / configs
config는 설계한 모델의 전반적인 구조에 대해 살펴볼 수 있는 부분이기에 설명하고 넘어가겠습니다.
-
역할: 새로운 모델, 데이터셋, 학습 옵션을 정의하고 관리하는 설정 파일들과, 모델 설계를 위해 mmdet3d에서 제공하는 기반 모듈들을 포함합니다.
-
기능: 모델의 학습과 테스트 단계에서 이 설정 파일을 참조하여 모델 학습, 평가, 추론을 실행.
-
내부구조
/projects/configs
├── base : 새 모델 설계에 필요한 기반 모듈(예: 백본, 넥, 데이터셋 설정)
│ ├── datasets: 기반 데이터 설정파일 과 전처리 파이프라인
│ ├── models: 모델 아키텍처의 기반 백본,넥,헤드
│ └── schedules : 기반 학습 스케줄(예: 학습률 감소 정책)
├── {Custom_model}: 새로운 모델의 구조와 학습 및 검증 파이프라인을 명시
├── datasets: 새 모델을 위한 기반 데이터 설정과 전처리 파이프라인
*base는 기본 제공 모듈(예: ResNet, nuScenes 데이터셋 설정)을 명시하며 새로운 모델 설계시, 필요한 기반 모듈을 추가하는 공간입니다.
/ core
-
역할: bbox 처리나 평가 메트릭뿐만 아니라, 3D 검출의 핵심 기능(예: 포인트 클라우드 처리, 2D-to-3D 투영, NMS, RoI 추출)과 관련된 모듈을 포함합니다.
-
기능: 모델의 학습에서 손실 계산, 평가에서 NDS 계산, 추론에서 결과 정제에 활용.
-
내부구조
core
├── evaluation : 데이터셋별 평가 메트릭 계산 로직
├── losses : 학습에 필요한 손실 함수
├── optimizer : 최적화 알고리즘.
├── post_processing : 예측 결과 후처리.
/ tools
-
역할: 모델 학습, 테스트, 추론, 데이터 준비, 로그 분석 등을 위한 실행 스크립트를 제공합니다.
-
기능: 모델의 학습(train.py), 추론(test.py) 실행.
-
내부구조
├── train.py : 모델 학습 실행. 설정 파일을 읽어 학습 시작.
├── test.py : 모델 평가 실행. 학습된 모델로 메트릭 계산.
├── create_data.py : 데이터 전처리.
├── analyze_logs.py : 학습 로그 분석 및 시각화
├── visualize.py : 예측 결과 시각화
/ data
-
역할: 실제 데이터셋 파일을 저장하는 디렉토리입니다.
-
기능 : mmdet3d/datasets가 이 데이터를 로드하여 학습, 평가, 추론에 활용.
-
내부구조
data
├── nuscenes : nuScenes 데이터셋
├── waymo : Waymo 데이터셋.
├── kitti : KITTI 데이터셋.
간단하게
프레임워크내에서 모델의 설계와, 학습 및 검증 파이프라인 구축 단계에 대해 정리하자면,
모델에 대한 데이터셋로드, 학습과 검증 파이프라인 및 모델 아키텍쳐에 대한 전체적인 구조는 /projects/configs내에서 확인 가능하며,
새로운 모델에 대한 설계을 원한다면 MMDetection3D에서 제공하는 기반 모듈을 base로 부터 가져올 수 있고, 새로운 구조가 필요하다면 구현한 모듈을 mmdet3d_plugin 디렉토리를 통해 추가함으로써 모델 설계에 이용할 수 있다는 것입니다.
아래는 MMDetection3D 프레임워크내에서 동작하는 데이터처리+로드+학습과정 모식도를 직관적이게 나타내봤습니다.
대규모 데이터셋: nuScenes, Waymo, KITTI ( /data)
↓
데이터 파이프라인: 데이터 준비 단계
├── 데이터 로더
│ ├── 기본: mmdet3d/datasets (예: NuScenesDataset)
│ └── 커스텀: mmdet3d_plugin/datasets
└── 전처리
├── 기본: mmdet3d/datasets
└── 커스텀: mmdet3d_plugin/datasets
↓
모델 아키텍처
├── 백본
│ ├── 기본: mmdet3d/models/backbones
│ └── 커스텀: mmdet3d_plugin/models/backbones
├── 넥
│ ├── 기본: mmdet3d/models/necks
│ └── 커스텀: mmdet3d_plugin/models/necks
└── 탐지 헤드
├── 기본: mmdet3d/models/heads
└── 커스텀: mmdet3d_plugin/models/heads
↓
학습 및 평가
├── 손실 함수
│ ├── 기본: mmdet3d/core/losses
│ └── 커스텀: mmdet3d_plugin/core/losses
└── 평가 메트릭
├── 기본: mmdet3d/core/evaluation
└── 커스텀: mmdet3d_plugin/core/evaluation
↓
출력 ex) 3D 바운딩 박스 및 클래스 예측
├── 기본 후처리: mmdet3d/core/post_processing
├── 커스텀 후처리: mmdet3d_plugin/core/post_processing
└── 테스트 도구: tools/test.py (공통적으로 사용, 커스텀 설정 파일 참조)
