Skip to content

cli.md

Latest commit

 

History

History
105 lines (80 loc) · 3.23 KB

cli.md

File metadata and controls

105 lines (80 loc) · 3.23 KB

Command Line Interface

SoccerTrack-V2 provides a command-line interface for all major operations. Commands are structured using the pattern:

python -m src.main command=<command-name> [options]

Available Commands

Data Processing

  1. Process Raw Data

    python -m src.main command=process-raw-data match_id=<match_id>

    Process raw match data into standardized formats.

  2. Transform Coordinates

    python -m src.main command=transform-coordinates match_id=<match_id>

    Convert coordinates between different coordinate spaces.

  3. Extract Features

    python -m src.main command=extract-features match_id=<match_id>

    Extract features from processed data.

Ground Truth Creation

  1. Create Ground Truth MOT 
    python -m src.main command=create-ground-truth-mot-from-coordinates \
  coordinates_path=data/interim/pitch_plane_coordinates/<match_id>/<match_id>_pitch_plane_coordinates.csv \
  homography_path=data/interim/homography/<match_id>/<match_id>_homography.npy \
  bbox_models_path=data/interim/<match_id>/<match_id>_bbox_models.joblib \
  output_path=data/interim/<match_id>/<match_id>_ground_truth_mot_dynamic_bboxes.csv
    Create MOT format ground truth files with dynamic bounding boxes.

Visualization

  1. Plot Bounding Boxes 
    python -m src.main command=plot-bboxes-on-video \
  video_path=data/raw/<match_id>/<match_id>_panorama.mp4 \
  detections_path=data/interim/<match_id>/<match_id>_ground_truth_mot_dynamic_bboxes.csv \
  output_path=data/interim/<match_id>/<match_id>_plot_bboxes_on_video.mp4 \
  [show_ids=false]
    Visualize bounding boxes on video frames.

Shell Scripts

The project includes shell scripts for common operations:

  1. Create ground truth end-to-end

    ./scripts/create_ground_truth.sh <match_id> [<match_id> ...]

    Runs the full ground-truth pipeline (video trim → coord conversion → calibration → detection → bbox generation) for one or more matches. See data_processing.md for the per-step scripts.

  2. Download the dataset from Hugging Face

    ./scripts/download.sh --dest ./data --match 117099 --match 117100

    Thin wrapper around huggingface-cli / hf with per-match filtering and revision pinning.

Configuration Options

All commands support configuration overrides:

python -m src.main command=<command-name> [config_path=configs/custom_config.yaml] [param=value]

See Configuration Guide for details on available options.

Common Parameters

  • match_id: Match identifier (e.g., "117093")
  • config_path: Path to configuration file
  • output_path: Path for output files
  • show_ids: Whether to show track IDs in visualizations (default: true)

Error Handling

Commands will:

  1. Validate input parameters
  2. Check file existence
  3. Create output directories if needed
  4. Log progress and errors

Example error handling:

# Missing required parameter
python -m src.main command=process-raw-data
# Error: match_id is required

# Invalid match_id
python -m src.main command=process-raw-data match_id=invalid
# Error: match_id 'invalid' not found in data/raw/