CO3Dv2：三维中的常见物体（版本2）

本仓库包含一套用于处理三维中的常见物体数据集第2版(CO3Dv2)的工具。

原始数据集已在我们的ICCV'21论文中介绍：三维中的常见物体：大规模的真实世界3D类别重建学习与评估。如需访问原始数据，请切换到本仓库的v1分支。

CO3Dv2的新特性

• 三维中的常见物体挑战赛，可在隐藏的测试服务器上进行透明评估——更多详情请参阅挑战赛README
• 序列数量增加至原来的2倍，帧数增加至原来的4倍
• 图像质量提升——由于更好的视频解码，块状伪影更少
• 分割掩码改进——主前景物体跟踪更加稳定，不会误跳到背景物体上
• 支持下载一个较小的单序列子集，约100个序列，仅包含用于多视角单序列任务评估的序列
• 数据集文件以20 GB为单位分块存储，便于更稳定的下载
• 采用全新、更友好的数据集格式
• 同一序列内的所有图像均裁剪为相同的高度×宽度

下载数据集

本仓库的dataset/links.json文件中包含了所有数据集文件的下载链接。

自动批量下载

我们还提供了一个Python脚本，可一次性下载所有数据集文件。执行以下命令即可开始下载：

python ./co3d/download_dataset.py --download_folder DOWNLOAD_FOLDER

其中DOWNLOAD_FOLDER是用于存放下载数据集文件的本地目标文件夹。请务必在开始下载前创建该文件夹。

大小：数据集的所有压缩文件共占用5.5 TB磁盘空间。

单序列数据集子集

我们还提供一个仅包含多视角单序列任务所选序列的数据集子集，该任务通常在单个图像序列上同时进行训练和评估。要下载此子集，请在download_dataset.py中添加--single_sequence_subset选项：

python ./co3d/download_dataset.py --download_folder DOWNLOAD_FOLDER --single_sequence_subset

大小：单序列子集远小于完整数据集，仅占用8.9 GB磁盘空间。

三维中的常见物体挑战赛

随着数据集v2版本的发布，我们也在EvalAI平台上组织了三维中的常见物体挑战赛。更多信息请访问[挑战赛官网](https://eval.ai/web/challenges/challenge-page/1819/overview)和[挑战赛README](./co3d/challenge/README.md)。

安装

本项目基于Python 3和PyTorch。

1. 安装PyTorch。
2. 安装PyTorch3D。
   • 请注意，必须从源代码构建PyTorch3D才能启用Implicitron模块
3. 安装requirements.txt中的其余依赖项：

pip install visdom tqdm requests h5py 

4. 安装CO3D包本身：pip install -e .

依赖项

• PyTorch
• PyTorch3D（需从源代码构建）
• tqdm
• visdom
• requests
• h5py

需要注意的是，co3d/dataset/data_types.py中的核心数据模型独立于PyTorch/PyTorch3D，可以被其他机器学习框架导入并使用。

开始使用

1. 安装依赖项——请参阅上方的[安装说明]。
2. 在指定根目录CO3DV2_DATASET_ROOT中下载数据集[此处]。
3. 设置环境变量CO3DV2_DATASET_ROOT指向数据集根目录：

   export CO3DV2_DATASET_ROOT="your_dataset_root_folder"
   

4. 运行example_co3d_challenge_submission.py：

   cd examples
   python example_co3d_challenge_submission.py
   

   请注意，example_co3d_challenge_submission.py会针对CO3D挑战赛的所有任务和数据集运行一个简单的基于深度的图像渲染（DBIR）模型的评估。您可以自由扩展该脚本，以提交您自己的CO3D挑战赛参赛作品。

运行测试

单元测试可以通过以下命令执行：

python -m unittest

复现结果

Implicitron是我们开源的框架，用于训练CO3D论文中提出的所有隐式形状学习方法。 更多详情请访问以下链接： https://github.com/facebookresearch/pytorch3d/tree/main/projects/implicitron_trainer

数据集格式

数据集在文件系统中的组织结构如下：

CO3DV2_DATASET_ROOT
    ├── <category_0>
    │   ├── <sequence_name_0>
    │   │   ├── depth_masks
    │   │   ├── depths
    │   │   ├── images
    │   │   ├── masks
    │   │   └── pointcloud.ply
    │   ├── <sequence_name_1>
    │   │   ├── depth_masks
    │   │   ├── depths
    │   │   ├── images
    │   │   ├── masks
    │   │   └── pointcloud.ply
    │   ├── ...
    │   ├── <sequence_name_N>
    │   ├── set_lists
    │       ├── set_lists_<subset_name_0>.json
    │       ├── set_lists_<subset_name_1>.json
    │       ├── ...
    │       ├── set_lists_<subset_name_M>.json
    │   ├── eval_batches
    │   │   ├── eval_batches_<subset_name_0>.json
    │   │   ├── eval_batches_<subset_name_1>.json
    │   │   ├── ...
    │   │   ├── eval_batches_<subset_name_M>.json
    │   ├── frame_annotations.jgz
    │   ├── sequence_annotations.jgz
    ├── <category_1>
    ├── ...
    ├── <category_K>

该数据集包含来自 K 个类别的序列，每个类别下有若干序列文件夹 <category_k>/<sequence_name_i>，其中分别存放了序列的图像、深度图、前景掩码和有效深度掩码，即 images、depths、masks 和 depth_masks。此外，<category_k>/<sequence_name_i>/set_lists/ 目录下存储了 M 个 JSON 文件 set_lists_<subset_name_l>.json，每个文件描述了一个特定的序列子集。

用户可以通过将 self.subset_name 设置为可用的子集名称 <subset_name_l> 来指定加载的数据集子集。

frame_annotations.jgz 和 sequence_annotations.jgz 是压缩的 JSON 文件，分别包含了给定类别中所有帧和序列的列表，以 FrameAnnotation 和 SequenceAnnotation 对象的形式存储。

子集列表

每个 set_lists_<subset_name_l>.json 文件包含以下字典：

{
    "train": [
        (sequence_name: str, frame_number: int, image_path: str),
        ...
    ],
    "val": [
        (sequence_name: str, frame_number: int, image_path: str),
        ...
    ],
    "test": [
        (sequence_name: str, frame_number: int, image_path: str),
        ...
    ],
}

定义了数据集中“train”、“val”和“test”子集中各帧的列表（通过 sequence_name 和 frame_number 标识）。

请注意，frame_number 只能从 frame_annotations.jgz 中获取，并不一定与对应图像文件名中的数字后缀一致（例如，文件 <category_0>/<sequence_name_0>/images/frame00005.jpg 的帧编号可能是 20，而不是 5）。

CO3Dv2 中可用的子集名称

在 CO3DV2 中，默认情况下，每个类别都包含以下子集列表：

"set_lists_fewview_test.json"  # 在“test”序列集上进行少视角任务。
"set_lists_fewview_dev.json"  # 在“dev”序列集上进行少视角任务。
"set_lists_manyview_test.json"  # 在某个类别的“test”序列上进行多视角任务。
"set_lists_manyview_dev_0.json"  # 在某个类别的第 1 个“dev”序列上进行多视角任务。
"set_lists_manyview_dev_1.json"  # 在某个类别的第 2 个“dev”序列上进行多视角任务。

评估批次

每个 eval_batches_<subset_name_l>.json 文件包含以下形式的评估示例列表：

[
    [  # 批次 1
        (sequence_name: str, frame_number: int, image_path: str),
        ...
    ],
    [  # 批次 2
        (sequence_name: str, frame_number: int, image_path: str),
        ...
    ],
]

请注意，评估示例始终来自对应的子集列表 set_lists_<subset_name_l>.json 中的“test”部分。

评估任务是根据已知的其他图像生成每个批次中的第一张图像。因此，每个批次中的第一张图像代表未见的目标帧，仅已知其相机参数；而批次中的其余图像则是已知的源帧，其相机和颜色均已给出。

对于多视角任务，当用户被提供某一序列的多个已知视图并需要生成该序列中未提供的视图时，eval_batches_manyview_<sequence_set>_<sequence_id>.json 文件中的每个评估批次只包含一张目标帧。用户可以从子集列表 set_lists_manyview_<sequence_set>_<sequence_id>.json 中对应的“train”帧列表中获取这些已知视图。

不依赖 PyTorch 的使用方式

co3d/dataset/data_types.py 中的核心数据模型独立于 PyTorch/PyTorch3D，可以导入并在其他机器学习框架中使用。

例如，要加载每个类别的帧和序列标注，可以执行以下代码：

from typing import List
from co3d.dataset.data_types import (
    load_dataclass_jgzip, FrameAnnotation, SequenceAnnotation
)
category_frame_annotations = load_dataclass_jgzip(
    f"{CO3DV2_DATASET_ROOT}/{category_name}/frame_annotations.jgz", List[FrameAnnotation]
)
category_sequence_annotations = load_dataclass_jgzip(
    f"{CO3DV2_DATASET_ROOT}/{category_name}/sequence_annotations.jgz", List[SequenceAnnotation]
)

此外，co3d/challenge 下的所有挑战相关代码也不依赖于 PyTorch。

参考文献

如果您使用我们的数据集，请引用以下文献：

@inproceedings{reizenstein21co3d,
	Author = {Reizenstein, Jeremy and Shapovalov, Roman and Henzler, Philipp and Sbordone, Luca and Labatut, Patrick and Novotny, David},
	Booktitle = {International Conference on Computer Vision},
	Title = {Common Objects in 3D: Large-Scale Learning and Evaluation of Real-life 3D Category Reconstruction},
	Year = {2021},
}

许可证

CO3D 代码库采用 CC BY-NC 4.0 许可证发布。

概览视频

以下是在 CVPR 2021 极端视觉研讨会中展示的数据集介绍：

CO3Dv2 快速上手指南

CO3Dv2 (Common Objects in 3D version 2) 是一个用于真实世界 3D 物体重建的大规模数据集及配套工具库。本指南帮助开发者快速搭建环境并运行基础示例。

环境准备

本项目基于 Python 3 和 PyTorch 构建。

系统要求

• 操作系统: Linux (推荐) 或 macOS
• 磁盘空间:
  • 完整数据集约需 5.5 TB
  • 单序列子集（适合快速测试）约需 8.9 GB
• GPU: 推荐具备 CUDA 支持的 NVIDIA GPU（用于运行深度学习模型）

前置依赖

在开始之前，请确保已安装以下核心依赖：

1. PyTorch: 请访问 PyTorch 官网 根据你的环境安装。

   国内用户建议使用清华或中科大镜像源加速安装。

2. PyTorch3D: 必须从源码编译安装以启用 Implicitron 模块。
   • 安装说明参考：PyTorch3D Installation
3. 其他 Python 库: visdom, tqdm, requests, h5py

安装步骤

请按顺序执行以下命令完成环境配置：

1. 安装剩余依赖包

   pip install visdom tqdm requests h5py
   

   国内用户可使用国内镜像源加速： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple visdom tqdm requests h5py

2. 安装 CO3D 工具包 克隆本仓库后，在项目根目录下执行：

   pip install -e .
   

基本使用

1. 下载数据集

数据集链接存储在 dataset/links.json 中。你可以选择下载完整数据集或较小的单序列子集。

下载单序列子集（推荐用于快速验证，仅需 8.9 GB）：

python ./co3d/download_dataset.py --download_folder YOUR_DATASET_PATH --single_sequence_subset

下载完整数据集（需 5.5 TB）：

python ./co3d/download_dataset.py --download_folder YOUR_DATASET_PATH

请将 YOUR_DATASET_PATH 替换为你本地的目标文件夹路径，并确保该文件夹已创建。

2. 配置环境变量

下载完成后，设置数据集根目录的环境变量：

export CO3DV2_DATASET_ROOT="YOUR_DATASET_PATH"

3. 运行示例代码

进入 examples 目录并运行挑战提交示例脚本。该脚本会在 CO3D Challenge 的所有任务上评估一个简单的基于深度的图像渲染 (DBIR) 模型：

cd examples
python example_co3d_challenge_submission.py

4. 独立加载数据（非 PyTorch 环境）

如果你仅需要读取数据标注而不依赖 PyTorch，可以使用核心数据模型：

from typing import List
from co3d.dataset.data_types import (
    load_dataclass_jgzip, FrameAnnotation, SequenceAnnotation
)

# 替换 category_name 为具体类别，如 'teddybear'
category_frame_annotations = load_dataclass_jgzip(
    f"{CO3DV2_DATASET_ROOT}/{category_name}/frame_annotations.jgz", List[FrameAnnotation]
)
category_sequence_annotations = load_dataclass_jgzip(
    f"{CO3DV2_DATASET_ROOT}/{category_name}/sequence_annotations.jgz", List[SequenceAnnotation]
)