ClarityTrack

ClarityTrack is the core online multi-object tracking implementation for our Scientific Reports paper. It focuses on confidence-aware association, condition-aware matching, and motion-appearance consistency control. This release does not include post-processing.

Paper

This repository provides the core tracker implementation for the following paper:

ClarityTrack for multi object tracking via hierarchical association and environment specific cost matching

Se-Eun Lee, Hyun-Sung Yang, Se-Hoon Jung, and Chun-Bo Sim

Scientific Reports, 16, Article number 10581, 2026

DOI: 10.1038/s41598-026-45425-0

Overview

ClarityTrack follows the tracking-by-detection paradigm and improves data association using detection confidence, motion cues, and ReID appearance features. Variant A provides an IoU-based baseline, while Variant B enables BCA (Balanced Cascade Association).

BCA balances IoU and ReID costs and performs confidence-based cascade association. CAMW (Condition-Aware Matching with Weights) applies condition-dependent motion and appearance weights, while MACC (Motion-Appearance Consistency Check) adjusts matches according to the agreement between motion and appearance cues.

Repository Structure

ClarityTrack/
├── tracker/                    # Core tracker and execution entry point
├── trackeval/                  # Tracking evaluation code
├── docs/                       # Additional documentation
├── requirements.txt            # Python dependencies
├── LICENSE                     # ClarityTrack license
└── THIRD_PARTY_NOTICES.md      # Third-party licenses and attributions

Installation

Create a Python environment and install the dependencies listed in requirements.txt:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Data Preparation

The tracker supports MOT17, MOT20, and DanceTrack. The datasets are not included in this repository and must be downloaded from their official sources.

With the default --data_dir ../../dataset, the expected layout is:

workspace/
├── ClarityTrack/
│   ├── tracker/
│   └── outputs/
│       ├── 2. det_feat/
│       └── 3. track/
└── dataset/
    ├── MOT17/
    │   ├── train/
    │   └── test/
    ├── MOT20/
    │   ├── train/
    │   └── test/
    └── DanceTrack/
        ├── val/
        └── test/

The tracker does not run a detector or ReID model directly. It consumes precomputed detection and ReID feature pickle files. YOLOX and FastReID may be used as external components to generate these inputs, but their code and models are not included in this repository.

Input Pickle Format

Each pickle file must contain a nested mapping:

{
    sequence_name: {
        frame_id: ndarray,
    }
}

Each row in a frame array must have the following layout:

[x1, y1, x2, y2, score, class_or_metadata, reid_feature...]

The first four values are bounding-box coordinates, index 4 is the detection score, index 5 is reserved for class or metadata, and the remaining values form the ReID feature vector.

Variant B requires detection files produced with both NMS 0.80 and NMS 0.95. The default validation filenames are:

mot17_val_0.80.pickle
mot17_val_0.95.pickle
mot20_val_0.80.pickle
mot20_val_0.95.pickle
dance_val_0.80.pickle
dance_val_0.95.pickle

Place these files under ClarityTrack/outputs/2. det_feat/ when using the default --pickle_dir. Test mode uses the corresponding filenames with val replaced by test.

Variant A uses the NMS 0.80 input and does not require the NMS 0.95 file.

Running

Run the tracker from the tracker/ directory:

cd tracker

Run the IoU baseline with Variant A:

python run.py --dataset MOT17 --mode val --variant A

Run the BCA configuration with Variant B:

python run.py --dataset MOT17 --mode val --variant B

Run the full ClarityTrack configuration with BCA, CAMW, and MACC:

python run.py --dataset MOT17 --mode val --variant B --use_safe_camw --use_macc

The same configurations can be used with the other supported datasets:

python run.py --dataset MOT20 --mode val --variant B --use_safe_camw --use_macc
python run.py --dataset DanceTrack --mode val --variant B --use_safe_camw --use_macc

Custom input, dataset, and output paths can be provided without trailing slashes:

python run.py \
    --dataset MOT17 \
    --mode val \
    --pickle_dir /path/to/det_feat \
    --data_dir /path/to/dataset \
    --output_dir /path/to/results

The main execution options are:

Argument	Choices or default	Description
--variant	B	B for BCA or A for the IoU baseline
--dataset	MOT17	MOT17, MOT20, or DanceTrack
--mode	val	val or test
--pickle_dir	../outputs/2. det_feat/	Detection and ReID pickle directory
--data_dir	../../dataset/	Dataset root directory
--output_dir	../outputs/3. track/	Tracking result directory
--use_safe_camw	disabled	Enable CAMW
--use_macc	disabled	Enable MACC

Evaluation

Validation mode runs the bundled TrackEval evaluation after tracking. Ground-truth annotations and the expected dataset sequence structure must be available under --data_dir. Test mode produces tracking files without running evaluation.

Tracking results are written as one text file per sequence in MOTChallenge format:

frame,id,x,y,width,height,score,-1,-1,-1

The result subdirectory is created under --output_dir using the input pickle name and tracker variant. The camw and macc suffixes are added when the corresponding components are enabled.

Results

Results will be added after verification. Reported results in this repository will correspond to the core tracker setting without post-processing. Full ClarityTrack uses Variant B with CAMW and MACC enabled.

Notes

• This repository provides the core tracker without post-processing.
• AFLink and GBI post-processing are not included.
• The released code focuses on the core ClarityTrack association strategy.

Citation

If you use this code in your research, please cite:

@article{lee2026claritytrack,
  title={ClarityTrack for multi object tracking via hierarchical association and environment specific cost matching},
  author={Lee, Se-Eun and Yang, Hyun-Sung and Jung, Se-Hoon and Sim, Chun-Bo},
  journal={Scientific Reports},
  volume={16},
  pages={10581},
  year={2026},
  doi={10.1038/s41598-026-45425-0}
}

Acknowledgements

This repository uses TrackEval for evaluation and builds on selected tracker implementation components from TrackTrack. MOTChallenge and DanceTrack are used as datasets and benchmarks. See THIRD_PARTY_NOTICES.md for detailed attribution and license notices.

License

ClarityTrack is released under the MIT License. Third-party components remain subject to their original licenses. See LICENSE and THIRD_PARTY_NOTICES.md for details.