Skip to content

Update Readme & Code for MMScan HVG challenge #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Tai-Wang merged 5 commits into from
Jun 13, 2025
Merged

Update Readme & Code for MMScan HVG challenge #112

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cac0355
challenge
rbler1234 Jun 10, 2025
e10a560
challenge
rbler1234 Jun 10, 2025
54bfead
challenge
rbler1234 Jun 10, 2025
836c6c3
challenge
rbler1234 Jun 12, 2025
64e21b7
challenge
rbler1234 Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 46 additions & 205 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<div id="top" align="center">

[![arXiv](https://img.shields.io/badge/arXiv-2312.16170-blue)](https://arxiv.org/abs/2312.16170)
[![](https://img.shields.io/badge/Paper-%F0%9F%93%96-blue)](./assets/2024_NeurIPS_MMScan_Camera_Ready.pdf)
[![](https://img.shields.io/badge/Paper-%F0%9F%93%96-blue)](./assets/2406.09401v2.pdf)
[![](https://img.shields.io/badge/Project-%F0%9F%9A%80-blue)](https://tai-wang.github.io/mmscan)

</div>
Expand All @@ -21,14 +21,21 @@

## 📋 Contents

1. [About](#-about)
2. [Getting Started](#-getting-started)
3. [MMScan API Tutorial](#-mmscan-api-tutorial)
4. [MMScan Benchmark](#-mmscan-benchmark)
5. [TODO List](#-todo-list)
1. [News](#-news)
2. [About](#-about)
3. [Getting Started](#-getting-started)
4. [MMScan Tutorial](#-mmscan-api-tutorial)
5. [MMScan Benchmark](#-mmscan-benchmark)
6. [TODO List](#-todo-list)

## 🏠 About
## 🔥 News

- \[2025-06\] We are co-organizing the CVPR 2025 3D Scene Understanding Challenge. You're warmly invited to participate in the MMScan Hierarchical Visual Grounding track!
The challenge test server is now online [here](https://huggingface.co/spaces/rbler/3d-iou-challenge). We look forward to your strong submissions!

- \[2025-01\] We are delighted to present the official release of [MMScan-devkit](https://github.com/OpenRobotLab/EmbodiedScan/tree/mmscan), which encompasses a suite of data processing utilities, benchmark evaluation tools, and adaptations of some models for the MMScan benchmarks. We invite you to explore these resources and welcome any feedback or questions you may have!

## 🏠 About

<!-- ![Teaser](assets/teaser.jpg) -->

Expand Down Expand Up @@ -59,7 +66,6 @@ existing benchmarks and in-the-wild evaluation.

## 🚀 Getting Started


### Installation

1. Clone Github repo.
Expand Down Expand Up @@ -100,247 +106,82 @@ existing benchmarks and in-the-wild evaluation.

Please refer to the [guide](data_preparation/README.md) here.

## 👓 MMScan API Tutorial

## 👓 MMScan Tutorial

The **MMScan Toolkit** provides comprehensive tools for dataset handling and model evaluation in tasks.

To import the MMScan API, you can use the following commands:

```bash
import mmscan

# (1) The dataset tool
import mmscan.MMScan as MMScan_dataset

# (2) The evaluator tool ('VisualGroundingEvaluator', 'QuestionAnsweringEvaluator', 'GPTEvaluator')
import mmscan.VisualGroundingEvaluator as MMScan_VG_evaluator

import mmscan.QuestionAnsweringEvaluator as MMScan_QA_evaluator

import mmscan.GPTEvaluator as MMScan_GPT_evaluator
```

### MMScan Dataset

The dataset tool in MMScan allows seamless access to data required for various tasks within MMScan.

#### Usage

Initialize the dataset for a specific task with:

```bash
my_dataset = MMScan_dataset(split='train', task="MMScan-QA", ratio=1.0)
# Access a specific sample
print(my_dataset[index])
```

#### Data Access

Each dataset item is a dictionary containing key elements:

(1) 3D Modality

- **"ori_pcds"** (tuple\[tensor\]): Original point cloud data extracted from the .pth file.
- **"pcds"** (np.ndarray): Point cloud data with dimensions [n_points, 6(xyz+rgb)], representing the coordinates and color of each point.
- **"instance_labels"** (np.ndarray): Instance ID assigned to each point in the point cloud.
- **"class_labels"** (np.ndarray): Class IDs assigned to each point in the point cloud.
- **"bboxes"** (dict): Information about bounding boxes within the scan, structured as { object ID:
{
"type": object type (str),
"bbox": 9 DoF box (np.ndarray)
}}

(2) Language Modality

- **"sub_class"**: The category of the sample.
- **"ID"**: The sample's ID.
- **"scan_id"**: The scan's ID.
- *For Visual Grounding task*
- **"target_id"** (list\[int\]): IDs of target objects.
- **"text"** (str): Text used for grounding.
- **"target"** (list\[str\]): Text prompt to specify the target grounding object.
- **"anchors"** (list\[str\]): Types of anchor objects.
- **"anchor_ids"** (list\[int\]): IDs of anchor objects.
- **"tokens_positive"** (dict): Indices of positions where mentioned objects appear in the text.
- *For Qusetion Answering task*
- **"question"** (str): The text of the question.
- **"answers"** (list\[str\]): List of possible answers.
- **"object_ids"** (list\[int\]): Object IDs referenced in the question.
- **"object_names"** (list\[str\]): Types of referenced objects.
- **"input_bboxes_id"** (list\[int\]): IDs of input bounding boxes.
- **"input_bboxes"** (list\[np.ndarray\]): Input 9-DoF bounding boxes.

(3) 2D Modality

- **'img_path'** (str): File path to the RGB image.
- **'depth_img_path'** (str): File path to the depth image.
- **'intrinsic'** (np.ndarray): Intrinsic parameters of the camera for RGB images.
- **'depth_intrinsic'** (np.ndarray): Intrinsic parameters of the camera for depth images.
- **'extrinsic'** (np.ndarray): Extrinsic parameters of the camera.
- **'visible_instance_id'** (list): IDs of visible objects in the image.

### MMScan Evaluator

Our evaluation tool is designed to streamline the assessment of model outputs for the MMScan task, providing essential metrics to gauge model performance effectively.

#### 1. Visual Grounding Evaluator
- #### Usage

For the visual grounding task, our evaluator computes multiple metrics including AP (Average Precision), AR (Average Recall), AP_C, AR_C, and gtop-k:
Initialize the dataset for a specific task with:

- **AP and AR**: These metrics calculate the precision and recall by considering each sample as an individual category.
- **AP_C and AR_C**: These versions categorize samples belonging to the same subclass and calculate them together.
- **gTop-k**: An expanded metric that generalizes the traditional Top-k metric, offering superior flexibility and interpretability compared to traditional ones when oriented towards multi-target grounding.

*Note:* Here, AP corresponds to AP<sub>sample</sub> in the paper, and AP_C corresponds to AP<sub>box</sub> in the paper.
```bash
from mmscan import MMScan

Below is an example of how to utilize the Visual Grounding Evaluator:
# (1) The dataset tool
my_dataset = MMScan(split='train'/'test'/'val', task='MMScan-VG'/'MMScan-QA')
# Access a specific sample
print(my_dataset[index])
```

```python
# Initialize the evaluator with show_results enabled to display results
my_evaluator = MMScan_VG_evaluator(show_results=True)
*Note:* For the test split, we have only made the VG portion publicly available, while the QA portion has not been released.

# Update the evaluator with the model's output
my_evaluator.update(model_output)
- #### Data Access

# Start the evaluation process and retrieve metric results
metric_dict = my_evaluator.start_evaluation()
Each dataset item is a dictionary containing data information from three modalities: language, 2D, and 3D.（[Details](https://rbler1234.gitbook.io/mmscan-devkit-tutorial#data-access)）

# Optional: Retrieve detailed sample-level results
print(my_evaluator.records)

# Optional: Show the table of results
print(my_evaluator.print_result())

# Important: Reset the evaluator after use
my_evaluator.reset()
```

The evaluator expects input data in a specific format, structured as follows:

```python
[
{
"pred_scores" (tensor/ndarray): Confidence scores for each prediction. Shape: (num_pred, 1)

"pred_bboxes"/"gt_bboxes" (tensor/ndarray): List of 9 DoF bounding boxes.
Supports two input formats:
1. 9-dof box format: (num_pred/gt, 9)
2. center, size and rotation matrix:
"center": (num_pred/gt, 3),
"size" : (num_pred/gt, 3),
"rot" : (num_pred/gt, 3, 3)

"subclass": The subclass of each VG sample.
"index": Index of the sample.
}
...
]
```

#### 2. Question Answering Evaluator

The question answering evaluator measures performance using several established metrics:

- **Bleu-X**: Evaluates n-gram overlap between prediction and ground truths.
- **Meteor**: Focuses on precision, recall, and synonymy.
- **CIDEr**: Considers consensus-based agreement.
- **SPICE**: Used for semantic propositional content.
- **SimCSE/SBERT**: Semantic similarity measures using sentence embeddings.
- **EM (Exact Match) and Refine EM**: Compare exact matches between predictions and ground truths.

```python
# Initialize evaluator with pre-trained weights for SIMCSE and SBERT
my_evaluator = MMScan_QA_evaluator(model_config={}, show_results=True)

# Update evaluator with model output
my_evaluator.update(model_output)

# Start evaluation and obtain metrics
metric_dict = my_evaluator.start_evaluation()
### MMScan Evaluator

# Optional: View detailed sample-level results
print(my_evaluator.records)
Our evaluation tool is designed to streamline the assessment of model outputs for the MMScan task, providing essential metrics to gauge model performance effectively. We provide three evaluation tools: `VisualGroundingEvaluator`, `QuestionAnsweringEvaluator`, and `GPTEvaluator`. ([Details](https://rbler1234.gitbook.io/mmscan-devkit-tutorial/evaluator))

# Important: Reset evaluator after completion
my_evaluator.reset()
```
```bash
from mmscan import MMScan

The evaluator requires input data structured as follows:

```python
[
{
"question" (str): The question text,
"pred" (list[str]): The predicted answer, single element list,
"gt" (list[str]): Ground truth answers, containing multiple elements,
"ID": Unique ID for each QA sample,
"index": Index of the sample,
}
...
]
# (2) The evaluator tool ('VisualGroundingEvaluator', 'QuestionAnsweringEvaluator', 'GPTEvaluator')
from mmscan import VisualGroundingEvaluator, QuestionAnsweringEvaluator, GPTEvaluator
```

#### 3. GPT Evaluator

In addition to classical QA metrics, the GPT evaluator offers a more advanced evaluation process.
### MMScan HVG Challenge Submission

```python
# Initialize GPT evaluator with an API key for access
my_evaluator = MMScan_GPT_Evaluator(API_key='XXX')

# Load, evaluate with multiprocessing, and store results in temporary path
metric_dict = my_evaluator.load_and_eval(model_output, num_threads=5, tmp_path='XXX')

# Important: Reset evaluator when finished
my_evaluator.reset()
```

The input structure remains the same as for the question answering evaluator:

```python
[
{
"question" (str): The question text,
"pred" (list[str]): The predicted answer, single element list,
"gt" (list[str]): Ground truth answers, containing multiple elements,
"ID": Unique ID for each QA sample,
"index": Index of the sample,
}
...
]
```
To participate and submit your results in our MMScan Visual Grounding challenge, please refer to the instructions provided on our [test server](https://huggingface.co/spaces/rbler/3d-iou-challenge).
We welcome any feedback — feel free to contact us via [Google email]([email protected]).

## 🏆 MMScan Benchmark

<div align=center>
<img src="assets/mix.png" width=95%>
</div>

### MMScan Visual Grounding Benchmark

| Methods | gTop-1 | gTop-3 | AP<sub>sample</sub> | AP<sub>box</sub> | AR | Release | Download |
|---------|--------|--------|---------------------|------------------|----|-------|----|
| ScanRefer | 4.74 | 9.19 | 9.49 | 2.28 | 47.68 | [code](https://github.com/rbler1234/EmbodiedScan/tree/mmscan-devkit/models/Scanrefer) | [model](https://drive.google.com/file/d/1C0-AJweXEc-cHTe9tLJ3Shgqyd44tXqY/view?usp=drive_link) \| [log](https://drive.google.com/file/d/1ENOS2FE7fkLPWjIf9J76VgiPrn6dGKvi/view?usp=drive_link) |
|---------|----------------|-----------|---------------------|------------------|----|-------|----|
| ScanRefer | 4.74 | 9.19 | 9.49 | 2.28 | 47.68 | [code](./models/Scanrefer/README.md) | [model](https://drive.google.com/file/d/1C0-AJweXEc-cHTe9tLJ3Shgqyd44tXqY/view?usp=drive_link) | [log](https://drive.google.com/file/d/1ENOS2FE7fkLPWjIf9J76VgiPrn6dGKvi/view?usp=drive_link) |
| MVT | 7.94 | 13.07 | 13.67 | 2.50 | 86.86 | - | - |
| BUTD-DETR | 15.24 | 20.68 | 18.58 | 9.27 | 66.62 | - | - |
| ReGround3D | 16.35 | 26.13 | 22.89 | 5.25 | 43.24 | - | - |
| EmbodiedScan | 19.66 | 34.00 | 29.30 | **15.18** | 59.96 | [code](https://github.com/OpenRobotLab/EmbodiedScan/tree/mmscan/models/EmbodiedScan) | [model](https://drive.google.com/file/d/1F6cHY6-JVzAk6xg5s61aTT-vD-eu_4DD/view?usp=drive_link) \| [log](https://drive.google.com/file/d/1Ua_-Z2G3g0CthbeBkrR1a7_sqg_Spd9s/view?usp=drive_link) |
| EmbodiedScan | 19.66 | 34.00 | 29.30 | **15.18** | 59.96 | [code](./models/EmbodiedScan/README.md) | [model](https://drive.google.com/file/d/1F6cHY6-JVzAk6xg5s61aTT-vD-eu_4DD/view?usp=drive_link) | [log](https://drive.google.com/file/d/1Ua_-Z2G3g0CthbeBkrR1a7_sqg_Spd9s/view?usp=drive_link) |
| 3D-VisTA | 25.38 | 35.41 | 33.47 | 6.67 | 87.52 | - | - |
| ViL3DRef | **26.34** | **37.58** | **35.09** | 6.65 | 86.86 | - | - |

### MMScan Question Answering Benchmark

| Methods | Overall | ST-attr | ST-space | OO-attr | OO-space | OR| Advanced | Release | Download |
|---|--------|--------|--------|--------|--------|--------|-------|----|----|
| LL3DA | 45.7 | 39.1 | 58.5 | 43.6 | 55.9 | 37.1 | 24.0| [code](https://github.com/rbler1234/EmbodiedScan/tree/mmscan-devkit/models/LL3DA) | [model](https://drive.google.com/file/d/1mcWNHdfrhdbtySBtmG-QRH1Y1y5U3PDQ/view?usp=drive_link) \| [log](https://drive.google.com/file/d/1VHpcnO0QmAvMa0HuZa83TEjU6AiFrP42/view?usp=drive_link) |
| LEO |54.6 | 48.9 | 62.7 | 50.8 | 64.7 | 50.4 | 45.9 | [code](https://github.com/rbler1234/EmbodiedScan/tree/mmscan-devkit/models/LEO) | [model](https://drive.google.com/drive/folders/1HZ38LwRe-1Q_VxlWy8vqvImFjtQ_b9iA?usp=drive_link)|
| LL3DA | 45.7 | 39.1 | 58.5 | 43.6 | 55.9 | 37.1 | 24.0| [code](./models/LL3DA/README.md) | [model](https://drive.google.com/file/d/1mcWNHdfrhdbtySBtmG-QRH1Y1y5U3PDQ/view?usp=drive_link) | [log](https://drive.google.com/file/d/1VHpcnO0QmAvMa0HuZa83TEjU6AiFrP42/view?usp=drive_link) |
| LEO |54.6 | 48.9 | 62.7 | 50.8 | 64.7 | 50.4 | 45.9 | [code](./models/LEO/README.md) | [model](https://drive.google.com/drive/folders/1HZ38LwRe-1Q_VxlWy8vqvImFjtQ_b9iA?usp=drive_link)|
| LLaVA-3D |**61.6** | 58.5 | 63.5 | 56.8 | 75.6 | 58.0 | 38.5|- | - |

*Note:* These two tables only show the results for main metrics; see the paper for complete results.

We have released the codes of some models under [./models](./models/README.md).
We have released the codes of some models under [./models](./models).

## 📝 TODO List


- \[ \] MMScan annotation and samples for ARKitScenes.
- \[ \] Online evaluation platform for the MMScan benchmark.
- \[ \] Codes of more MMScan Visual Grounding baselines and Question Answering baselines.
- \[ \] Full release and further updates.
Binary file removed assets/2024_NeurIPS_MMScan_Camera_Ready.pdf
View file
Open in desktop
Binary file not shown.
Binary file added assets/2406.09401v2.pdf
View file
Open in desktop
Binary file not shown.
Binary file added assets/LEO.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/LL3DA.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/Scanrefer.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/benchmark.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/circle.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/ex.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/graph.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/mix.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion data_preparation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
### Prepare MMscan info files.
### MMScan Dataset Preparation

Given the licenses of respective raw datasets, we recommend users download the raw data from their official websites and then organize them following the below guide.
Detailed steps are shown as follows.
Expand Down
Loading
Loading