# InternImage-based Baseline for Occupancy Prediction
We improve our baseline with a more powerful image backbone: **InaternImage**, which shows its excellent ability within a series of leaderboards and benchmarks, such as *COCO* and *nuScenes*.
#### 1. Openmmlab packages requirements
```bash
torch==1.12 # recommend
mmcv-full>=1.5.0
mmdet==2.24.0
mmsegmentation==0.24.0
timm
numpy==1.22
```
### 2. Install DCNv3 for InternImage
```bash
cd projects/mmdet3d_plugin/bevformer/backbones/ops_dcnv3
bash make.sh # requires torch>=1.10
```
### 3. Train with InternImage-Small
```bash
./tools/dist_train.sh projects/configs/bevformer/bevformer_intern-s_occ.py 8 # consumes less than 14G memory
```
Notes: InatenImage provides abundant pre-trained model weights that can be used!!!
# CVPR2023 Occupancy Prediction Challenge Information
-[Rules for Occupancy Challenge](#rules-for-occupancy-challenge)
-[Evaluation Metrics](#evaluation-metrics)
-[mIoU](#miou)
-[F Score](#f-score)
-[Data](#data)
-[Basic Information](#basic-information)
-[Download](#download)
-[Hierarchy](#hierarchy)
-[Known Issues](#known-issues)
-[Getting Started](#getting-started)
-[Timeline](#challenge-timeline)
-[Leaderboard](#leaderboard)
-[License](#license)
## Introduction
Understanding the 3D surroundings including the background stuffs and foreground objects is important for autonomous driving. In the traditional 3D object detection task, a foreground object is represented by the 3D bounding box. However, the geometrical shape of the object is complex, which can not be represented by a simple 3D box, and the perception of the background is absent. The goal of this task is to predict the 3D occupancy of the scene. In this task, we provide a large-scale occupancy benchmark based on the nuScenes dataset. The benchmark is a voxelized representation of the 3D space, and the occupancy state and semantics of the voxel in 3D space are jointly estimated in this task. The complexity of this task lies in the dense prediction of 3D space given the surround-view image.
<palign="right">(<ahref="#top">back to top</a>)</p>
## Task Definition
Given images from multiple cameras, the goal is to predict the current occupancy state and semantics of each voxel grid in the scene. The voxel state is predicted to be either free or occupied. If a voxel is occupied, its semantic class needs to be predicted, as well. Besides, we also provide a binary observed/unobserved mask for each frame. An observed voxel is defined as an invisible grid in the current camera observation, which is ignored in the evaluation stage.
### Rules for Occupancy Challenge
* We allow using annotations provided in the nuScenes dataset, and during inference, the input modality of the model should be camera only.
* Other public/private datasets are not allowed in the challenge in any form (except ImageNet or MS-COCO pre-trained image backbone).
* No future frame is allowed during inference.
* In order to check the compliance, we will ask the participants to provide technical reports to the challenge committee and the participant will be asked to provide a public talk about the method after winning the award.
<palign="right">(<ahref="#top">back to top</a>)</p>
## Evaluation Metrics
Leaderboard ranking for this challenge is by the intersection-over-union (mIoU) over all classes.
where $P_a$ is the percentage of predicted voxels that are within a distance threshold to the ground truth voxels, and $P_c$ is the percentage of ground truth voxels that are within a distance threshold to the predicted voxels.
<palign="right">(<ahref="#top">back to top</a>)</p>
## Data
<divid="top"align="center">
<imgsrc="./figs/mask.jpg">
</div>
<divid="top"align="center">
Figure 1. Semantic labels (left), visibility masks in the LiDAR (middle) and the camera (right) view. Grey voxels are unobserved in LiDAR view and white voxels are observed in the accumulative LiDAR view but unobserved in the current camera view.
</div>
### Basic Information
<divalign="center">
| Type | Info |
| :----: | :----: |
| mini | 404 |
| train | 28,130 |
| val | 6,019 |
| test | 6,006 |
| cameras | 6 |
| voxel size | 0.4m |
| range | [-40m, -40m, -1m, 40m, 40m, 5.4m]|
| volume size | [200, 200, 16]|
| #classes | 0 - 17 |
</div>
- The dataset contains 18 classes. The definition of classes from 0 to 16 is the same as the [nuScenes-lidarseg](https://github.com/nutonomy/nuscenes-devkit/blob/fcc41628d41060b3c1a86928751e5a571d2fc2fa/python-sdk/nuscenes/eval/lidarseg/README.md) dataset. The label 17 category represents voxels that are not occupied by anything, which is named as `free`. Voxel semantics for each sample frame is given as `[semantics]` in the labels.npz.
-<strong>How are the labels annotated?</strong> The ground truth labels of occupancy derive from accumulative LiDAR scans with human annotations.
- If a voxel reflects a LiDAR point, then it is assigned as the same semantic label as the LiDAR point;
- If a LiDAR beam passes through a voxel in the air, the voxel is set to be `free`;
- Otherwise, we set the voxel to be unknown, or unobserved. This happens due to the sparsity of the LiDAR or the voxel is occluded, e.g. by a wall. In the dataset, `[mask_lidar]` is a 0-1 binary mask, where 0's represent unobserved voxels. As shown in Fig.1(b), grey voxels are unobserved. Due to the limitation of the visualization tool, we only show unobserved voxels at the same height as the ground.
-<strong>Camera visibility.</strong> Note that the installation positions of LiDAR and cameras are different, therefore, some observed voxels in the LiDAR view are not seen by the cameras. Since we focus on a vision-centric task, we provide a binary voxel mask `[mask_camera]`, indicating whether the voxels are observed or not in the current camera view. As shown in Fig.1(c), white voxels are observed in the accumulative LiDAR view but unobserved in the current camera view.
- Both `[mask_lidar]` and `[mask_camera]` masks are optional for training. Participants do not need to predict the masks. Only `[mask_camera]` is used for evaluation; the unobserved voxels are not involved during calculating the F-score and mIoU.
### Download
The files mentioned below can also be downloaded via <imgsrc="https://user-images.githubusercontent.com/29263416/222076048-21501bac-71df-40fa-8671-2b5f8013d2cd.png"alt="OpenDataLab"width="18"/>[OpenDataLab](https://opendatalab.com/CVPR2023-3D-Occupancy/download).It is recommended to use provided [command line interface](https://opendatalab.com/CVPR2023-3D-Occupancy/cli) for acceleration.
* Mini and trainval data contain three parts -- `imgs`, `gts` and `annotations`. The `imgs` datas have the same hierarchy with the image samples in the original nuScenes dataset.
### Hierarchy
The hierarchy of folder `Occpancy3D-nuScenes-V1.0/` is described below:
-`imgs/` contains images captured by various cameras.
-`gts/` contains the ground truth of each sample. `[scene_name]` specifies a sequence of frames, and `[frame_token]` specifies a single frame in a sequence.
-`annotations.json` contains meta infos of the dataset.
-`labels.npz` contains `[semantics]`, `[mask_lidar]`, and `[mask_camera]` for each frame.
```
annotations {
"train_split": ["scene-0001", ...], <list> -- training dataset split by scene_name
"val_split": list ["scene-0003", ...], <list> -- validation dataset split by scene_name
"scene_infos" { <dict> -- meta infos of the scenes
[scene_name]: { <str> -- name of the scene.
[frame_token]: { <str> -- samples in a scene, ordered by time
"timestamp": <str> -- timestamp (or token), unique by sample
"camera_sensor": { <dict> -- meta infos of the camera sensor
"intrinsic": <float> [3, 3] -- intrinsic camera calibration
"extrinsic":{ <dict> -- extrinsic parameters of the camera
"translation": <float> [3] -- coordinate system origin in meters
"rotation": <float> [4] -- coordinate system orientation as quaternion
}
"ego_pose": { <dict> -- vehicle pose of the camera
"translation": <float> [3] -- coordinate system origin in meters
"rotation": <float> [4] -- coordinate system orientation as quaternion
}
},
...
},
"ego_pose": { <dict> -- vehicle pose
"translation": <float> [3] -- coordinate system origin in meters
"rotation": <float> [4] -- coordinate system orientation as quaternion
},
"gt_path": <str> -- corresponding 3D voxel gt path, *.npz
"next": <str> -- frame_token of the previous keyframe in the scene
"prev": <str> -- frame_token of the next keyframe in the scene
}
]
}
}
}
```
### Known Issues
- Nuscene ([issues-721](https://github.com/nutonomy/nuscenes-devkit/issues/721)) lacks translation in the z-axis, which makes it hard to recover accurate 6d localization and would lead to the misalignment of point clouds while accumulating them over whole scenes. Ground stratification occurs in several data.
<palign="right">(<ahref="#top">back to top</a>)</p>
## Getting Started
We provide a baseline model based on [BEVFormer](https://github.com/fundamentalvision/BEVFormer).
Please refer to [getting_started](docs/getting_started.md) for details.
<palign="right">(<ahref="#top">back to top</a>)</p>
## Challenge Timeline
- Pending - Challenge Period Open.
- Jun 01, 2023 - Challenge Period End.
- Jun 03, 2023 - Finalist Notification.
- Jun 10, 2023 - Technical Report Deadline.
- Jun 12, 2023 - Winner Announcement.
<palign="right">(<ahref="#top">back to top</a>)</p>
## Leaderboard
To be released.
<palign="right">(<ahref="#top">back to top</a>)</p>
## License
Before using the dataset, you should register on the website and agree to the terms of use of the [nuScenes](https://www.nuscenes.org/nuscenes).
All code within this repository is under [Apache License 2.0](./LICENSE).
<palign="right">(<ahref="#top">back to top</a>)</p>
