docs: update README.

* update av2_mode to data_mode.
* revert back for zod process file
* runner metric is good in last version as it's range_bucket have different meaning.

Author: Kin-Zhang

README.md

@@ -6,6 +6,8 @@ DeltaFlow: An Efficient Multi-frame Scene Flow Estimation Method
 <!-- [![poster](https://img.shields.io/badge/ECCV24|Poster-6495ed?style=flat&logo=Shotcut&logoColor=wihte)](https://hkustconnect-my.sharepoint.com/:b:/g/personal/qzhangcb_connect_ust_hk/EWyWD-tAX4xIma5U7ZQVk9cBVjsFv0Y_jAC2G7xAB-w4cg?e=c3FbMg)  -->
 <!-- [![video](https://img.shields.io/badge/video-YouTube-FF0000?logo=youtube&logoColor=white)](https://youtu.be/fQqx2IES-VI) -->
 
+<img width="1864" height="756" alt="deltaflow_cover" src="https://github.com/user-attachments/assets/a7348910-8073-4703-8c0b-57c613401552" />
+
 **News w. TBD**:
 
 Note (2025/09/18): We got accepted by NeurIPS 2025 and it's **spotlighted**! 🎉🎉🎉 Working on release the code here.
@@ -20,16 +22,18 @@ Note (2025/09/18): We got accepted by NeurIPS 2025 and it's **spotlighted**! 
 
 ## Quick Run
 
+To train the full dataset, please refer to the [OpenSceneFlow](https://github.com/KTH-RPL/OpenSceneFlow?tab=readme-ov-file#1-data-preparation) for raw data download and h5py files preparation.
+
 ### Training
 
-1. Prepare the demo train and val data:
+1. Prepare the **demo** train and val data for a quick run:
 ```bash
 # around 1.3G
 wget https://huggingface.co/kin-zhang/OpenSceneFlow/resolve/main/demo-data-v2.zip
 unzip demo-data-v2.zip -d /home/kin/data/av2/h5py # to your data path
 ```
 
-2. Follow the [OpenSceneFlow](https://github.com/KTH-RPL/OpenSceneFlow/tree/main?tab=readme-ov-file#0-installation) to setup the environment.
+2. Follow the [OpenSceneFlow](https://github.com/KTH-RPL/OpenSceneFlow/tree/main?tab=readme-ov-file#0-installation) to setup the environment or [use docker](https://github.com/KTH-RPL/OpenSceneFlow?tab=readme-ov-file#docker-recommended-for-isolation).
 
 3. Run the training with the following command (modify the data path accordingly):
 ```bash
@@ -49,7 +53,6 @@ Please refer to the [OpenSceneFlow](https://github.com/KTH-RPL/OpenSceneFlow/tre
 While I will update a unified visualization script for OpenSceneFlow to quickly save all window views as images at the same view and same time etc. (Free us from qualitative figure making work!)
 
 
-
 ## Cite & Acknowledgements
 ```
 @article{zhang2025deltaflow,

assets/slurm/2_eval.sh

@@ -12,9 +12,9 @@ cd /proj/berzelius-2023-364/users/x_qinzh/workspace/OpenSceneFlow
 
 
 # ====> leaderboard model
-# $PYTHON eval.py wandb_mode=online dataset_path=/proj/berzelius-2023-364/users/x_qinzh/data/av2/autolabel av2_mode=test \
+# $PYTHON eval.py wandb_mode=online dataset_path=/proj/berzelius-2023-364/users/x_qinzh/data/av2/autolabel data_mode=test \
 #     checkpoint=/proj/berzelius-2023-154/users/x_qinzh/seflow/logs/wandb/seflow-10086990/checkpoints/epoch_19_seflow.ckpt \
 #     save_res=True
 
-$PYTHON eval.py wandb_mode=online dataset_path=/proj/berzelius-2023-364/users/x_qinzh/data/av2/autolabel av2_mode=val \
+$PYTHON eval.py wandb_mode=online dataset_path=/proj/berzelius-2023-364/users/x_qinzh/data/av2/autolabel data_mode=val \
     checkpoint=/proj/berzelius-2023-154/users/x_qinzh/seflow/logs/wandb/seflow-10086990/checkpoints/epoch_19_seflow.ckpt

dataprocess/extract_zod.py

@@ -122,7 +122,11 @@ def process_logs(data_dir: Path, output_dir: Path, nproc: int):
 
 def main(
     dataset_root: str = "/home/kin/DATA_HDD/public_data/zod/drives",
+    output_dir: str ="/home/kin/data/zod/h5py/himo",
+    nproc: int = (multiprocessing.cpu_count() - 1),
+    only_index: bool = False,
 ):
+    output_dir_ = Path(output_dir)
     if only_index:
         create_reading_index(output_dir_)
         return

src/models/__init__.py

@@ -22,7 +22,7 @@
     print(f"Detail error message\033[0m: {e}. Just ignore this warning if code runs without these models.")
 
 # following need install extra package: 
-# * pip install spconv-cu118
+# * pip install spconv-cu117
 try:
     from .deltaflow import DeltaFlow
     from .flow4d import Flow4D

src/runner.py

@@ -267,15 +267,17 @@ def _run_process(cfg, mode):
                     final_metrics.epe_3way[key].extend(val_list)
 
                 for class_idx, class_name in enumerate(metrics_obj.bucketedMatrix.class_names):
-                    for range_idx, range_bucket in enumerate(metrics_obj.bucketedMatrix.range_buckets):
-                        count = metrics_obj.bucketedMatrix.count_storage_matrix[class_idx, range_idx]
+                    # NOTE(Qingwen): for bucketedMatrix range_buckets = speed_buckets
+                    for speed_idx, speed_bucket in enumerate(metrics_obj.bucketedMatrix.range_buckets):
+                        count = metrics_obj.bucketedMatrix.count_storage_matrix[class_idx, speed_idx]
                         if count > 0:
-                            avg_epe = metrics_obj.bucketedMatrix.epe_storage_matrix[class_idx, range_idx]
-                            avg_range = metrics_obj.bucketedMatrix.range_storage_matrix[class_idx, range_idx]
+                            avg_epe = metrics_obj.bucketedMatrix.epe_storage_matrix[class_idx, speed_idx]
+                            avg_speed = metrics_obj.bucketedMatrix.range_storage_matrix[class_idx, speed_idx]
                             final_metrics.bucketedMatrix.accumulate_value(
-                                class_name, range_bucket, avg_epe, avg_range, count
+                                class_name, speed_bucket, avg_epe, avg_speed, count
                             )
                 for class_idx, class_name in enumerate(metrics_obj.distanceMatrix.class_names):
+                    # NOTE(Qingwen): for distanceMatrix range_buckets = distance_buckets
                     for range_idx, range_bucket in enumerate(metrics_obj.distanceMatrix.range_buckets):
                         count = metrics_obj.distanceMatrix.count_storage_matrix[class_idx, range_idx]
                         if count > 0:
@@ -304,7 +306,7 @@ def _spawn_wrapper(rank, world_size, cfg, mode):
     os.environ['RANK'] = str(rank)
     os.environ['WORLD_SIZE'] = str(world_size)
     os.environ['MASTER_ADDR'] = 'localhost'
-    os.environ['MASTER_PORT'] = cfg.get('master_port', '12355')
+    os.environ['MASTER_PORT'] = str(cfg.get('master_port', 12355))
     _run_process(cfg, mode)
 
 def launch_runner(cfg, mode):

src/utils/eval_metric.py

@@ -201,8 +201,8 @@ def get_mean_average_values(self, normalized: bool = True):
         pass
 
 class BucketedSpeedMatrix(BucketResultMatrix):
-    def __init__(self, class_names: List[str], range_buckets: List[Tuple[float, float]]):
-        super().__init__(class_names, range_buckets)
+    def __init__(self, class_names: List[str], speed_buckets: List[Tuple[float, float]]):
+        super().__init__(class_names, speed_buckets)
 
     def get_normalized_error_matrix(self):
         error_matrix = self.epe_storage_matrix.copy()
@@ -266,7 +266,7 @@ def __init__(self):
         speed_splits = np.concatenate([np.linspace(0, 2.0, 51), [np.inf]])
         self.bucketedMatrix = BucketedSpeedMatrix(
             class_names=['BACKGROUND', 'CAR', 'OTHER_VEHICLES', 'PEDESTRIAN', 'WHEELED_VRU'],
-            range_buckets=list(zip(speed_splits, speed_splits[1:]))
+            speed_buckets=list(zip(speed_splits, speed_splits[1:]))
         )
 
         distance_split = [0, 35, 50, 75, 100, np.inf]