RoCo Spring DevKit

Developer kit for the Robust Correspondence Challenge. This devkit is derived from PTLFlow, so checking PTLFlow's documentation may also help you to customize the code in this devkit.

Prerequisites & Requirements

Before installing, ensure your environment meets the following requirements:

• OS: Linux (recommended) or Windows (not tested)
• Python: >= 3.10 and <= 3.13
• Hardware: CUDA-capable GPU (highly recommended for training and inference)

Installation

1. Clone the repository and enter the downloaded directory:

git clone https://github.com/hmorimitsu/roco-spring-devkit.git
cd roco-spring-devkit

2. Setup and activate a virtual environment (optional, but highly recommended):

python -m venv roco
source roco/bin/activate  # On Windows use: roco\Scripts\activate

3. Install the roco_spring_devkit locally. The -e flag installs it in editable mode, meaning any changes you make to the code will apply immediately without reinstalling:

pip install -e .

---

Dataset Preparation

To participate in the competition, you must download the test files for both the Spring and the RobustSpring dataset.

Spring Dataset

Download the Spring dataset from: https://doi.org/10.18419/DARUS-3376

To submit results to the competition, download the core test files:

• test_frame_left.zip: Left camera frames.
• test_frame_right.zip: Right camera frames.
• test_cam_data.zip: Camera intrinsic data.

Download the train files if you wish to finetune your model on the Spring dataset:

• All Categories: Require the images from train_frame_left.zip and train_frame_right.zip.
• Optical Flow: Also download train_flow_BW_left.zip, train_flow_BW_right.zip, train_flow_FW_left.zip, and train_flow_FW_right.zip.
• Stereo: Also download train_disp1_left.zip and train_disp1_right.zip.
• Scene Flow: Download all files listed above, plus train_disp2_BW_left.zip, train_disp2_BW_right.zip, train_disp2_FW_left.zip, train_disp2_FW_right.zip, and train_cam_data.zip.

RobustSpring Dataset

Download the RobustSpring dataset from: https://doi.org/10.18419/DARUS-5047

You must download all 20 .zip files corresponding to the 20 image corruptions.

---

Folder Structure

After unzipping your files, arrange them to match the following folder structures exactly:

Spring Dataset Layout

spring
├── test
│   ├── 0003
│   │   ├── cam_data
│   │   │   └── intrinsics.txt
│   │   ├── frame_left
│   │   │   └── frame_left_XXXX.png
│   │   └── frame_right
│   │       └── frame_right_XXXX.png
│   ├── XXXX
│   └── 0046
└── train
    ├── 0001
    │   ├── cam_data
    │   │   ├── extrinsics.txt
    │   │   ├── focaldistance.txt
    │   │   └── intrinsics.txt
    │   ├── disp1_left
    │   │   └── disp1_left_XXXX.dsp5
    │   ├── [other categories like disp2, flow]

RobustSpring Dataset Layout

robust_spring
├── brightness
│   └── test
│       ├── 0003
│       │   ├── frame_left
│       │   │   └── frame_left_XXXX.png
│       │   └── frame_right
│       │       └── frame_right_XXXX.png
│       └── 0046
└── [other 19 corruption folders structured identically to brightness/]

Configure Dataset Paths

Once local datasets are ready, locate the datasets.yaml file in the root directory of this devkit. Update the entries for spring and robust_spring with the absolute local paths to your respective dataset directories.

---

Participating in the Competition

First, check the official competition website: https://roco-spring.github.io/index.html. Please follow the instructions on the website to register your team and learn about the submission requirements.

The submission will be done via the official Spring Benchmark website. For more details, follow the submission instructions on the Spring website.

The competition tracks are divided into three main categories. Detailed instructions, training scripts, and evaluation pipelines can be found in their respective subdirectories:

• Optical Flow: roco_spring_devkit/optical_flow/README.md
• Scene Flow: roco_spring_devkit/scene_flow/README.md
• Stereo: roco_spring_devkit/stereo/README.md

📤 Submission Format

After running the test script for your chosen track, your final predictions will be saved under outputs/test/<model and checkpoint name>. To submit your results:

1. Download the Spring subsampling tools and uncompress them into your computer. On Linux, make them executable by running chmod +x <category name>_subsampling.
2. Run the respective subsampling to generate the file to be uploaded to the Spring benchmark. For example, to submit optical flow results to the Robust Spring benchmark, run (on Linux):

./flow_robust_subsampling /path/to/roco-spring-devkit/roco_spring_devkit/optical_flow/outputs/test/<model and checkpoint name>/robust-spring

3. If concluded without errors, this will generate a flow_*.hdf5 file.
4. Go to the Spring website and submit this hdf5 file according to the rules.