CLI Reference
Every command the trackers CLI exposes, in one table, plus the full flag reference for trackers inspect's four subcommands — the one part of the CLI with no flag table anywhere else in the docs.
What you'll learn:
- Every top-level command and subcommand the CLI exposes
- Where each command's detailed guide and flag table lives
- The full flag reference for
trackers inspect sam/cutie/mask-manager/mcbyte
Install
Get started by installing the package.
inspect subcommands additionally need the mask extra — see Requires the mask extra below. For more options, see the install guide.
Commands
| Command | Purpose | Reference |
|---|---|---|
trackers track |
Run a tracker on a video, webcam, RTSP stream, or image directory. | Track guide |
trackers eval |
Score tracker output against ground truth with CLEAR, HOTA, and Identity metrics. | Evaluate guide |
trackers download |
Download MOT benchmark datasets — MOT17 and SportsMOT. | Download guide |
trackers tune |
Search tracker hyperparameters with Optuna. | Tune guide |
trackers inspect sam |
Run SAM mask generation on a single image and save a visualization. | Below |
trackers inspect cutie |
Seed masks with SAM on the first frame, then propagate them with Cutie across a frame range. | Below |
trackers inspect mask-manager |
Run the real MaskManager orchestration — initialize, propagate, add, remove — in manual or gt mode. |
Below |
trackers inspect mcbyte |
Compare locked-IoU vs. mask-conditioned McByte on one sequence. | Below |
trackers benchmark mcbyte |
Run McByte over complete benchmark test sets and write MOTChallenge-format results. | Benchmark Runner guide |
For a narrative walkthrough of track, eval, download, or tune, see their own guides linked above. For inspect, see the Inspect the Mask Pipeline guide for worked examples — the flag tables below cover the full surface of each subcommand.
Every trackers subcommand accepts --config <file> to load arguments from a YAML file, and hyphens and underscores are interchangeable in flag names (--cmc-downscale and --cmc_downscale are the same option). Boolean flags gain a negated --no_<name> counterpart. A nested option group (e.g. --tracker.mask.*) exposes a .help sub-command — --tracker.mask.help lists that group's fields without printing the rest of --help.
Requires the mask extra
All four inspect subcommands build SAM and Cutie, so install them first:
Without the extra, the command exits with an install hint rather than a traceback. For more options, see the install guide.
Inspect Subcommands
Each tab lists all arguments accepted by that trackers inspect subcommand.
trackers inspect sam
| Argument | Description | Default |
|---|---|---|
--image_path |
Path to the input image. | — |
--box |
Bounding boxes in xyxy format, given as one list: --box='[[x1,y1,x2,y2]]'. Append with --box+=.... |
— |
--output_path |
Path to save the visualization. | outputs/inspect/sam/sam_masks.jpg |
--device |
Device used by SAM, e.g. cpu or cuda. auto resolves to CUDA when available, otherwise CPU. |
auto |
--model_type |
SAM model type. | vit_b |
trackers inspect cutie
| Argument | Description | Default |
|---|---|---|
--image_dir |
Directory containing input frames. | — |
--start_file |
First frame filename, included in the selected frame range. | — |
--end_file |
Last frame filename, included in the selected frame range. | — |
--box |
Bounding boxes on the first selected frame, xyxy, as one list. Append with --box+=.... |
— |
--add_at |
Masks to add via a box on a given frame, each filename:x1,y1,x2,y2. Applied on that frame then propagated to the next, matching McByte timing; each event is treated as a new object. |
none |
--remove_at |
Masks to remove before propagating to the given frame, each filename:manual_mask_id. |
none |
--output_root |
Root directory for timestamped outputs. | outputs/inspect/cutie |
--device |
Device used by SAM and Cutie, e.g. cpu/cuda. auto resolves to CUDA when available, otherwise CPU. |
auto |
--sam_model_type |
SAM model type. | vit_b |
--cutie_model_type |
Cutie model type. | base-mega |
--cutie_config_path |
Optional path to Cutie's Hydra config directory. | none |
--cutie_config_name |
Cutie Hydra config name. | eval_config |
trackers inspect mask-manager — --mode selects manual or gt; passing an option that belongs to the other mode is an error.
| Argument | Description | Default |
|---|---|---|
--image_dir |
Directory holding the frame images. | — |
--mode |
manual (boxes and lifecycle events from the CLI) or gt (replay from a MOT-format ground-truth file). |
— |
--start_file |
Manual mode. Filename of the first frame to process. | none |
--end_file |
Manual mode. Filename of the last frame to process. | none |
--box |
Manual mode. Initial tracklet boxes on the first selected frame, xyxy, as one list. Append with --box+=.... |
none |
--add_at |
Manual mode. New tracklets to add from given frame boxes, each filename:x1,y1,x2,y2. |
none |
--remove_at |
Manual mode. Tracklets to remove before propagating to the given frame, each filename:tracklet_id. |
none |
--gt_file |
GT mode. MOT-format ground-truth file to replay. | none |
--start_frame |
GT mode. First frame number to replay. | none |
--end_frame |
GT mode. Last frame number to replay. | none |
--tracklet_id |
GT mode. Tracklet IDs to replay, e.g. --tracklet_id='[3,7]'. Omit, or pass [all], to replay every tracklet. |
all |
--output_root |
Directory holding run directories, grouped by mode (<output_root>/<mode>/<timestamp>/). |
outputs/inspect/mask-manager |
--device |
Device used by SAM and Cutie, e.g. cuda/cpu. auto resolves to CUDA when available, otherwise CPU. |
auto |
--sam_model_type |
SAM model type. | vit_b |
--cutie_model_type |
Cutie model type. | base-mega |
--cutie_config_path |
Directory holding the Cutie config. Omit to use the config shipped with the installed Cutie package. | none |
--cutie_config_name |
Name of the Cutie config to load. | eval_config |
--mask_creation_bbox_overlap_threshold |
GT mode. Overlap threshold above which mask creation is delayed. | 0.6 |
trackers inspect mcbyte — options are grouped into nested dataclasses: --sequence.*, --cmc.*, --mask.*.
| Argument | Description | Default |
|---|---|---|
--sequence.image_dir |
Directory containing sequence frames. | — |
--sequence.det_file |
Path to the detection file. | — |
--sequence.start_frame |
First frame number to process, inclusive. | — |
--sequence.end_frame |
Last frame number to process, inclusive. | — |
--sequence.det_format |
Detection-file column format: mot_tlwh (frame,id,left,top,width,height,confidence,...) or xyxy (frame,x1,y1,x2,y2,confidence). |
mot_tlwh |
--sequence.frame_rate |
Sequence frame rate used to scale the lost-track buffer. | 30.0 |
--cmc.enable |
Enable camera motion compensation in both runs. | false |
--cmc.method |
Camera-motion compensation method. Options: orb, sift, sparseOptFlow, ecc. |
sparseOptFlow |
--cmc.downscale |
Image downscale factor used by CMC. | 6 |
--mask.device |
Device used by SAM and Cutie in the mask-conditioned run. auto resolves to CUDA when available, otherwise CPU. |
auto |
--mask.enable_isolated_matching |
Allow mask evidence to rescue isolated positive-IoU pairs below the normal association threshold. | false |
--modes |
Tracker configurations to run: --modes=[locked_iou]. |
both locked_iou and mask_conditioned |
--output_dir |
Directory holding one timestamped run directory per invocation; both comparison runs write inside it. | outputs/inspect/mcbyte |