SimpleTrack Documentation

To extract data from nuScenes, use the nuscenes_preprocess.sh script. This script supports two extraction modes:

1. 2Hz mode: Extracts only key frames to the specified data_dir_2hz.
2. 20Hz mode: Extracts all data to the specified data_dir_20hz.

Arguments:

• ${raw_data_dir}: The directory containing the raw nuScenes data.
• ${data_dir_2hz}: Target directory for 2Hz (key frame) data.
• ${data_dir_20hz}: Target directory for 20Hz (all data) extraction.

cd preprocessing/nuscenes_data
bash nuscenes_preprocess.sh ${raw_data_dir} ${data_dir_2hz} ${data_dir_20hz}

To decode ground truth information from a Waymo .bin file, use gt_bin_decode.py. Note that you must provide your own .bin file downloaded from the Waymo Open Dataset due to licensing restrictions.

Arguments:

• --data_folder: The target location for the preprocessed data.
• --file_path: The path to the ground truth .bin file.

Processed ground truth is stored in ${data_folder}/detection/gt/dets/.

cd preprocessing/waymo_data
python gt_bin_decode.py --data_folder ${data_dir} --file_path ${bin_path}

To perform inference only on key frames (2Hz), use tools/main_nuscenes.py. Results are saved in ${nuscenes_result_dir}/SimpleTrack2Hz/summary, organized into subfolders by object type.

Note: It is critical to use the provided configuration files (e.g., configs/nu_configs/giou.yaml) for correct results.

python tools/main_nuscenes.py \
    --name SimpleTrack2Hz \
    --det_name ${det_name} \
    --config_path configs/nu_configs/giou.yaml \
    --result_folder ${nuscenes_result_dir} \
    --data_folder ${nuscenes2hz_data_dir} \
    --process ${proc_num}

For detailed instructions on running inference on specific datasets, refer to the following documentation files:

• Waymo Open Dataset: See docs/waymo.md.
• nuScenes: See docs/nuScenes.md.

Important: You must strictly follow the configuration file paths and instructions provided in those specific documents to ensure reproducible results.

To convert the internal .npz tracking results into the official nuScenes .json format, you must run a two-step process: first create the results, then merge the object types. The final .json files will be located in the results subfolder of your specified result directory.

# For 2Hz (Key Frames) settings
python tools/nuscenes_result_creation.py \
    --name SimpleTrack2Hz \
    --result_folder ${nuscenes_result_dir} \
    --data_folder ${nuscenes2hz_data_dir}

python tools/nuscenes_type_merge.py \
    --name SimpleTrack2Hz \
    --result_folder ${nuscenes_result_dir}

# For 10Hz settings
python tools/nuscenes_result_creation_10hz.py \
    --name SimpleTrack10Hz \
    --result_folder ${nuscenes_result_dir} \
    --data_folder ${nuscenes20hz_data_dir}

python tools/nuscenes_type_merge.py \
    --name SimpleTrack10Hz \
    --result_folder ${nuscenes_result_dir}

Before running inference, you must preprocess the nuScenes dataset. Follow the instructions in the Data Preprocessing Documentations to generate the required directories. After successful preprocessing, you should have two specific directories:

• nuscenes2hz_data_dir: Contains key-frame data (2Hz).
• nuscenes20hz_data_dir: Contains all-frame data (10Hz/20Hz settings).

SimpleTrack behaviors are specified using a single .yaml configuration file. These files are typically located in the ./configs/ directory. You can define data preprocessing, association metrics, motion models, and association stages within this file to control the tracker's behavior.

# Example structure of a SimpleTrack config
running:
  score_threshold: 0.7
  asso: giou
redundancy:
  mode: mm
data_loader:
  nms: true

To use the official Waymo Open Dataset evaluation tools, convert the SimpleTrack .npz results into the official .bin format using tools/waymo_pred_bin.py.

After execution, the converted files will be located in ${waymo_result_dir}/SimpleTrack/bin/ as follows:

• prd.bin: All objects combined.
• vehicle/pred.bin: Vehicles only.
• pedestrian/pred.bin: Pedestrians only.
• cyclist/pred.bin: Cyclists only.

python tools/waymo_pred_bin.py \
    --name SimpleTrack \
    --result_folder ${waymo_result_dir} \
    --data_folder ${waymo_data_dir}

To perform inference using the 10Hz settings proposed in the paper, use tools/main_nuscenes_10hz.py. Results are saved in ${nuscenes_result_dir}/SimpleTrack20Hz/summary.

In experiments, a --process value of 150 is recommended, matching the number of sequences in the nuScenes validation set.

python tools/main_nuscenes_10hz.py \
    --name SimpleTrack10Hz \
    --det_name ${det_name} \
    --config_path configs/nu_configs/giou.yaml \
    --result_folder ${nuscenes_result_dir} \
    --data_folder ${nuscenes20hz_data_dir} \
    --process ${proc_num}