hp_tracking

Pure Python release of the hierarchical planner for long-horizon multi-target tracking under target motion uncertainty.

The release keeps the MCTS task planner, shifting-spiral coverage planner, Kalman-filter belief update, and optional visualization / validation tools. ROS packaging files and old experiment artifacts are intentionally removed.

Usage

Run all commands from the repository :

cd hp_tracking/

1. Generate cases

Generate release-format YAML cases before running new experiments.

hetero samples each target independently. homo uses one shared motion-noise and prior-covariance setting for all targets in a case.

Generate 1-target coverage cases:

python case_config/generate_cases.py \
  --profile hetero \
  --num-targets 1 \
  --num-cases 100 \
  --output-dir case_config/generated_cases/1_targets_hetero

Generate 6-target tracking cases:

python case_config/generate_cases.py \
  --profile hetero \
  --num-targets 6 \
  --num-cases 100 \
  --output-dir case_config/generated_cases/6_targets_hetero

2. Run a single coverage test

Run one coverage-estimator / spiral-path validation case:

python scripts/cov_test_run.py \
  --case-path case_config/generated_cases/1_targets_hetero/test_case_0.yaml \
  --pre-dep-time 30 \
  --num-sim-runs 1000

Show the propagated belief, spiral path, and estimator-vs-simulation CDF plots:

python scripts/cov_test_run.py \
  --case-path case_config/generated_cases/1_targets_hetero/test_case_0.yaml \
  --pre-dep-time 30 \
  --num-sim-runs 1000 \
  --debug-vis

3. Run batched coverage / spiral-path tests

Run multiple 1-target cases across several pre-departure times:

python scripts/cov_test_batch.py \
  --case-dir case_config/generated_cases/1_targets_hetero \
  --pre-dep-times 0 30 60 90 \
  --num-sim-runs 1000 \
  --start-index 0 \
  --end-index 99 \
  --output-dir results/coverage

4. Run a single multi-target tracking case

Run one pure-MCTS multi-target tracking case:

python scripts/auto_full_run_demo_vis.py \
  --case-path case_config/generated_cases/6_targets_hetero/test_case_0.yaml \
  --run-index 0 \
  --exploration-c 600

Enable step-by-step plotting during the run:

python scripts/auto_full_run_demo_vis.py \
  --case-path case_config/generated_cases/6_targets_hetero/test_case_0.yaml \
  --run-index 0 \
  --exploration-c 600 \
  --debug-vis

5. Save a recording and render it

Save a frame recording during a multi-target run:

python scripts/auto_full_run_demo_vis.py \
  --case-path case_config/generated_cases/6_targets_hetero/test_case_0.yaml \
  --run-index 0 \
  --exploration-c 600 \
  --save-recording

If --recording-path is not provided, recordings are written to:

results/recordings/mcts_<run_index>.pkl

Render a saved recording to MP4:

python scripts/render_recording.py \
  --recording-path results/recordings/mcts_0.pkl \
  --output-path results/recordings/mcts_0.mp4

Render a saved recording to GIF:

python scripts/render_recording.py \
  --recording-path results/recordings/mcts_0.pkl \
  --output-path results/recordings/mcts_0.gif

Open an interactive preview instead of saving media:

python scripts/render_recording.py \
  --recording-path results/recordings/mcts_0.pkl

6. Run batched multi-target tracking

Run a sequential MCTS batch:

python scripts/mcts_batch_run.py \
  --case-dir case_config/generated_cases/6_targets_hetero \
  --num-targets 6 \
  --exploration-c 600 \
  --start-index 0 \
  --end-index 99 \
  --output-csv results/mcts/mcts_results_6_targets_hetero.csv

7. Run a local parallel batch

Run the same MCTS batch locally with multiple workers:

python scripts/mcts_batch_run_parallel.py \
  --case-dir case_config/generated_cases/6_targets_hetero \
  --num-targets 6 \
  --exploration-c 600 \
  --num-workers 8 \
  --start-index 0 \
  --end-index 99 \
  --output-csv results/mcts/mcts_results_parallel_6_targets_hetero.csv

Optional CPU pinning:

python scripts/mcts_batch_run_parallel.py \
  --case-dir case_config/generated_cases/6_targets_hetero \
  --num-targets 6 \
  --exploration-c 600 \
  --num-workers 8 \
  --start-index 0 \
  --end-index 99 \
  --cpu-ids 0,1,2,3,4,5,6,7

Output directories under results/ are created only when needed.