Skip to content

Geo-trax

geotrax batch

rfonod/geo-trax

`geotrax batch`¶

Run the full pipeline for a video or directory tree (primary entry point).

usage: geotrax batch [-h] [--yes] [--overwrite] [--dry-run] [--viz-only] [--geo-only]
                     [--plot-only] [--no-geo]
                     [--folders-exclude FOLDERS_EXCLUDE [FOLDERS_EXCLUDE ...]]
                     [--exclude-patterns EXCLUDE_PATTERNS [EXCLUDE_PATTERNS ...]] [--cfg CFG]
                     [--set KEY=VALUE] [--output-folder OUTPUT_FOLDER] [--log-path LOG_PATH]
                     [--verbose] [--model MODEL [MODEL ...]]
                     [--class-names ID=NAME|FILE [ID=NAME|FILE ...]] [--conf CONF]
                     [--classes CLASSES [CLASSES ...]] [--cut-frame-left CUT_FRAME_LEFT]
                     [--cut-frame-right CUT_FRAME_RIGHT] [--interpolate | --no-interpolate]
                     [--sahi | --no-sahi] [--stab-gpu | --no-stab-gpu | -sg]
                     [--stab-gpu-device-id STAB_GPU_DEVICE_ID]
                     [--stab-detector {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}]
                     [--stab-device {auto,cpu,cuda,mps}] [--ortho-folder ORTHO_FOLDER]
                     [--geo-source {metadata-tif,text-file,center-text-file}]
                     [--ref-frame REF_FRAME] [--no-master] [--master-folder MASTER_FOLDER]
                     [--recompute] [--segmentation-folder SEGMENTATION_FOLDER]
                     [--geo-gpu | --no-geo-gpu | -gg] [--geo-gpu-device-id GEO_GPU_DEVICE_ID]
                     [--geo-detector {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}]
                     [--geo-device {auto,cpu,cuda,mps}] [--save | --no-save | -s]
                     [--show | --no-show | -sh] [--viz-mode MODE [MODE ...]]
                     [--plot-trajectories | --no-plot-trajectories | -pt]
                     [--plot-delay PLOT_DELAY] [--show-conf | --no-show-conf | -sc]
                     [--show-lanes | --no-show-lanes | -sl]
                     [--show-class-names | --no-show-class-names | -scn]
                     [--hide-labels | --no-hide-labels | -hl]
                     [--hide-tracks | --no-hide-tracks | -ht]
                     [--hide-speed | --no-hide-speed | -hs] [--speed-unit {km/h,mi/h}]
                     [--speed-deadzone SPEED_DEADZONE]
                     [--class-filter CLASS_FILTER [CLASS_FILTER ...]] [--tail-length TAIL_LENGTH]
                     [--line-width LINE_WIDTH] [--heading-smoothing HEADING_SMOOTHING]
                     [--heading-min-speed HEADING_MIN_SPEED] [--edge-clip-margin EDGE_CLIP_MARGIN]
                     [--edge-clip-smoothing EDGE_CLIP_SMOOTHING]
                     [--plot-save | --no-plot-save | -ps] [--plot-show | --no-plot-show | -psh]
                     [--plot-aggregate | --no-plot-aggregate | -pa]
                     [--plot-points | --no-plot-points | -pp]
                     [--plot-segmentations | --no-plot-segmentations | -pseg]
                     [--plot-class-filter PLOT_CLASS_FILTER [PLOT_CLASS_FILTER ...]]
                     input

Primary entry point for the full Geo-trax pipeline. Runs detection/tracking/stabilization, georeferencing, visualization, and plotting for a single video file or an entire directory tree. Stages are skipped if their output already exists; use --overwrite to force re-execution.

Positional arguments¶

Argument	Value	Config key	Description
`input`			Path to a video file or a directory of video files (searched recursively).

Batch processing options¶

Argument	Value	Config key	Description
`--yes`, `-y`			Automatically confirm prompts without waiting for user input
`--overwrite`, `-o`			Overwrite existing files that have already been processed
`--dry-run`, `-dr`			Preview which files and stages would be processed without executing anything. Add --verbose for full per-stage detail.
`--viz-only`, `-vo`			Skip detection, tracking, stabilization, and georeferencing; only (re-)run visualization. Requires existing .txt tracking results.
`--geo-only`, `-go`			Only run georeferencing; skip detection, tracking, and stabilization
`--plot-only`, `-po`			Only generate plots; skip processing, georeferencing, and visualization
`--no-geo`, `-ng`			Do not georeference the tracking data
`--folders-exclude`, `-fe`	`FOLDERS_EXCLUDE [FOLDERS_EXCLUDE ...]`	`batch.folders_exclude`	Folders to exclude from the batch processing, together with everything below them. Defaults to cfg -> batch -> folders_exclude.
`--exclude-patterns`, `-ep`	`EXCLUDE_PATTERNS [EXCLUDE_PATTERNS ...]`	`batch.exclude_patterns`	File name patterns to exclude (e.g., --exclude-patterns car_test drone_2023). Defaults to cfg -> batch -> exclude_patterns.

Shared options¶

Argument	Value	Config key	Description
`--cfg`, `-c`	`CFG`		Pipeline config: a bundled preset name (default, confident, lenient, stable) or a path to a custom config file. Run 'geotrax config show' to list presets or 'geotrax config copy' to customize.
`--set`, `-st`	`KEY=VALUE`		Override a pipeline config value for this run; repeat for more than one, e.g. --set conf=0.35 --set iou=0.6. KEY is a dotted path ('ultralytics.conf') or any unambiguous tail of one ('conf'); an ambiguous or unknown key is an error that lists the candidates. VALUE is read with YAML rules, so true/null/0.35/[0,1,2] all mean what they do in the config file. Use the dedicated flag instead where one exists (it validates its input); passing both for the same key is an error.
`--output-folder`, `-of`	`OUTPUT_FOLDER`	`output.folder`	Root folder for pipeline outputs. A bare name (e.g. 'results') creates a sub-folder next to each input video; an absolute path is used as-is for all inputs in a batch (not recommended when video filenames are not unique across the batch — outputs may overwrite each other). Also sets the base under which plots/ is created. Defaults to cfg -> output -> folder, historical default: 'results'.
`--log-path`, `-lp`	`LOG_PATH`		Where to write detailed logs: a directory (an auto-named <stage><timestamp><pid>.log file is created inside it, so concurrent or later runs never share a file) or a full file path ending in .log or .txt (any other new path is created as a directory). Defaults to a platform-specific log directory.
`--verbose`, `-v`			Also show INFO messages on the console (default: warnings and key notices only).

Processing options¶

For full detection and tracking control (model, IoU, image size, tracker settings, etc.), use --set (e.g. --set iou=0.6) or edit cfg -> ultralytics and cfg -> tracker in the pipeline config (run 'geotrax config copy').

Argument	Value	Config key	Description
`--model`, `-m`	`MODEL [MODEL ...]`	`extraction.model`	Detection model to use: a local file path OR an 'hf://<org>/<repo>/<path/to/file>.pt' Hugging Face reference (auto-downloaded & cached). Defaults to cfg -> extraction -> model.
`--class-names`, `-cn`	`ID=NAME\|FILE [ID=NAME\|FILE ...]`	`extraction.class_rename`	Rename class-id -> name labels: a .yaml/.json mapping file or inline ID=NAME pairs (e.g. -cn 0=car 1=bus). Defaults to cfg -> extraction -> class_rename, then the model's own names.
`--conf`, `-co`	`CONF`	`ultralytics.conf`	Detection confidence threshold. Defaults to cfg -> ultralytics -> conf.
`--classes`, `-cls`	`CLASSES [CLASSES ...]`	`ultralytics.classes`	Class IDs to extract (e.g., --classes 0 1 2). Defaults to cfg -> ultralytics -> classes.
`--cut-frame-left`, `-cfl`	`CUT_FRAME_LEFT`	`processing.cut_frame_left`	Skip the first N frames. Defaults to cfg -> processing -> cut_frame_left.
`--cut-frame-right`, `-cfr`	`CUT_FRAME_RIGHT`	`processing.cut_frame_right`	Stop processing after this frame. Defaults to cfg -> processing -> cut_frame_right.
`--interpolate`, `--no-interpolate`		`extraction.interpolate`	Fill per-track frame gaps with linear interpolation; adds is_interpolated column to output. Defaults to cfg -> extraction -> interpolate.
`--sahi`, `--no-sahi`		`extraction.sahi.enable`	Detect via SAHI sliced inference for improved small-object recall (requires: python -m pip install 'geo-trax[sahi]'). Slicing parameters live in cfg -> extraction -> sahi. Defaults to cfg -> extraction -> sahi -> enable.
`--stab-gpu`, `--no-stab-gpu`, `-sg`		`stabilo.gpu`	CUDA-accelerate stabilization (requires a CUDA-enabled OpenCV build; no CPU fallback). Defaults to cfg -> stabilo -> gpu.
`--stab-gpu-device-id`, `-sgid`	`STAB_GPU_DEVICE_ID`	`stabilo.gpu_device_id`	CUDA device index used when stabilization GPU is enabled. Defaults to cfg -> stabilo -> gpu_device_id.
`--stab-detector`, `-sdet`	`orb` \| `sift` \| `rsift` \| `brisk` \| `kaze` \| `akaze` \| `xfeat` \| `disk` \| `dedode` \| `keynet` \| `loftr`	`stabilo.detector_name`	Stabilization feature detector. Classical (OpenCV): orb, sift, rsift, brisk, kaze, akaze. Learning-based (kornia, use --stab-device): xfeat, disk, dedode, keynet, loftr. All learned ones except keynet are upright models (matching collapses past ~30 deg rotation) and are memory hungry at high resolution - lower cfg -> stabilo -> downsample_ratio for them. Defaults to cfg -> stabilo -> detector_name.
`--stab-device`, `-sdev`	`auto` \| `cpu` \| `cuda` \| `mps`	`stabilo.device`	Torch device for the learning-based stabilization detectors/matchers ('auto' picks cuda > mps > cpu); ignored by the classical detectors and independent of --stab-gpu (OpenCV CUDA). Defaults to cfg -> stabilo -> device.

Georeferencing options¶

Argument	Value	Config key	Description
`--ortho-folder`, `-orf`	`ORTHO_FOLDER`	`input.ortho_folder`	Custom path to the folder with orthophotos (.png, .tif, .txt). Defaults to cfg -> input -> ortho_folder, then 'ORTHOPHOTOS' at the same level as 'PROCESSED' in 'input'.
`--geo-source`, `-gs`	`metadata-tif` \| `text-file` \| `center-text-file`	`georef.processing.geo_source`	Source of georeferencing parameters. Defaults to cfg -> georef -> processing -> geo_source, then auto-detect.
`--ref-frame`, `-rf`	`REF_FRAME`	`georef.processing.ref_frame`	Reference frame number (must match stabilization setting). Defaults to cfg -> georef -> processing -> ref_frame.
`--no-master`, `-nm`		`georef.processing.use_master` (negated)	Disable the master frame approach regardless of config. When not set, cfg -> georef -> processing -> use_master applies.
`--master-folder`, `-mf`	`MASTER_FOLDER`	`input.master_folder`	Custom path to the folder containing master frame files (.png). Defaults to cfg -> input -> master_folder, then '<ortho-folder>/master_frames'.
`--recompute`, `-r`		`georef.processing.recompute`	Force recompute master->ortho homography even if cached. Defaults to cfg -> georef -> processing -> recompute.
`--segmentation-folder`, `-osf`	`SEGMENTATION_FOLDER`	`input.segmentation_folder`	Path to the folder with lane segmentation CSV files (used for lane assignment during georeferencing); the corresponding overlay PNGs are also used as plot backgrounds when segmentation plotting is enabled. Defaults to cfg -> input -> segmentation_folder, then '<ortho-folder>/segmentations'.
`--geo-gpu`, `--no-geo-gpu`, `-gg`		`georef.matching.gpu`	CUDA-accelerate georeferencing image registration (requires --geo-detector orb / cfg -> georef -> matching -> detector_name: orb AND a CUDA-enabled OpenCV build; no CPU fallback). Defaults to cfg -> georef -> matching -> gpu.
`--geo-gpu-device-id`, `-ggid`	`GEO_GPU_DEVICE_ID`	`georef.matching.gpu_device_id`	CUDA device index used when georeferencing GPU is enabled. Defaults to cfg -> georef -> matching -> gpu_device_id.
`--geo-detector`, `-gdet`	`orb` \| `sift` \| `rsift` \| `brisk` \| `kaze` \| `akaze` \| `xfeat` \| `disk` \| `dedode` \| `keynet` \| `loftr`	`georef.matching.detector_name`	Georeferencing registration detector. Classical (OpenCV): orb, sift, rsift, brisk, kaze, akaze. Learning-based (kornia, use --geo-device): xfeat, disk, dedode, keynet, loftr. CAUTION: the reference frame is registered against a north-up orthophoto, so the pair can differ by an arbitrary rotation - only keynet and the classical detectors are rotation invariant. Orthophotos are also very large; lower cfg -> georef -> matching -> downsample_ratio before using a learned detector. Defaults to cfg -> georef -> matching -> detector_name.
`--geo-device`, `-gdev`	`auto` \| `cpu` \| `cuda` \| `mps`	`georef.matching.device`	Torch device for the learning-based georeferencing detectors/matchers ('auto' picks cuda > mps > cpu); ignored by the classical detectors and independent of --geo-gpu (OpenCV CUDA). Defaults to cfg -> georef -> matching -> device.

Visualization options¶

Argument	Value	Config key	Description
`--save`, `--no-save`, `-s`		`visualization.save`	Save the annotated output video to file. Defaults to cfg -> visualization -> save.
`--show`, `--no-show`, `-sh`		`visualization.show`	Open a live preview window during processing. Defaults to cfg -> visualization -> show.
`--viz-mode`, `-vm`	`0` \| `1` \| `2` \| `3` \| `4`	`visualization.viz_mode`	Frame source(s) for annotation: 0=original, 1=stabilized, 2=reference frame, 3=rotated boxes on the original frame, 4=rotated boxes on the stabilized frame (3 and 4 rotate each box to the vehicle's per-frame heading; both require stabilization). Accepts multiple values, e.g. "--viz-mode 0 1 4" renders one video per mode. Defaults to cfg -> visualization -> viz_mode.
`--plot-trajectories`, `--no-plot-trajectories`, `-pt`		`visualization.plot_trajectories`	Overlay trajectory positions on the first frame. Defaults to cfg -> visualization -> plot_trajectories.
`--plot-delay`, `-pd`	`PLOT_DELAY`	`visualization.plot_delay`	Number of frames to display the trajectory overlay; only relevant when --plot-trajectories is enabled. Defaults to cfg -> visualization -> plot_delay.
`--show-conf`, `--no-show-conf`, `-sc`		`visualization.show_conf`	Include detection confidence in bounding-box labels. Defaults to cfg -> visualization -> show_conf.
`--show-lanes`, `--no-show-lanes`, `-sl`		`visualization.show_lanes`	Include lane ID in bounding-box labels. Defaults to cfg -> visualization -> show_lanes.
`--show-class-names`, `--no-show-class-names`, `-scn`		`visualization.show_class_names`	Include vehicle class name in bounding-box labels. Defaults to cfg -> visualization -> show_class_names.
`--hide-labels`, `--no-hide-labels`, `-hl`		`visualization.hide_labels`	Suppress all label text overlays. Defaults to cfg -> visualization -> hide_labels.
`--hide-tracks`, `--no-hide-tracks`, `-ht`		`visualization.hide_tracks`	Suppress track tail lines. Defaults to cfg -> visualization -> hide_tracks.
`--hide-speed`, `--no-hide-speed`, `-hs`		`visualization.hide_speed`	Suppress speed values in labels. Defaults to cfg -> visualization -> hide_speed.
`--speed-unit`, `-su`	`km/h` \| `mi/h`	`visualization.speed_unit`	Speed display unit: km/h or mi/h. Defaults to cfg -> visualization -> speed_unit.
`--speed-deadzone`, `-sdz`	`SPEED_DEADZONE`	`visualization.speed_deadzone`	Floor displayed speeds at or below this value (in the chosen speed unit) to 0, hiding stationary-vehicle jitter; 0 disables. Defaults to cfg -> visualization -> speed_deadzone.
`--class-filter`, `-cf`	`CLASS_FILTER [CLASS_FILTER ...]`	`visualization.class_filter`	Vehicle class IDs to exclude from visualization (e.g., -cf 1 2). Defaults to cfg -> visualization -> class_filter.
`--tail-length`, `-tl`	`TAIL_LENGTH`	`visualization.tail_length`	Number of past positions drawn as a fading track trail [frames]; [1, inf). Defaults to cfg -> visualization -> tail_length.
`--line-width`, `-lw`	`LINE_WIDTH`	`visualization.line_width`	Bounding-box and track stroke width [px]; [1, inf). Defaults to cfg -> visualization -> line_width.
`--heading-smoothing`, `-hsm`	`HEADING_SMOOTHING`	`visualization.heading_smoothing`	(modes 3, 4) Gaussian smoothing window [frames] for the per-frame heading; larger = steadier, slower to follow turns. Defaults to cfg -> visualization -> heading_smoothing.
`--heading-min-speed`, `-hms`	`HEADING_MIN_SPEED`	`visualization.heading_min_speed`	(modes 3, 4) Minimum smoothed pixel speed [px/frame] for a reliable heading; below this the heading is held from the last reliable frame. Defaults to cfg -> visualization -> heading_min_speed.
`--edge-clip-margin`, `-ecm`	`EDGE_CLIP_MARGIN`	`visualization.edge_clip_margin`	(modes 3, 4) Distance [px] within which a detection box is treated as touching a frame edge, triggering clipping of the oriented box to the visible part (absorbs HBB inaccuracy). Defaults to cfg -> visualization -> edge_clip_margin.
`--edge-clip-smoothing`, `-ecs`	`EDGE_CLIP_SMOOTHING`	`visualization.edge_clip_smoothing`	(modes 3, 4) Gaussian window [frames] for smoothing the clip rectangle of edge-touching boxes; larger = steadier shape as the vehicle exits, 0 disables. Defaults to cfg -> visualization -> edge_clip_smoothing.

Plotting options¶

Argument	Value	Config key	Description
`--plot-save`, `--no-plot-save`, `-ps`		`plotting.save`	Save the plots as .pdf files. Defaults to cfg -> plotting -> save.
`--plot-show`, `--no-plot-show`, `-psh`		`plotting.show`	Show plots in an interactive window. Defaults to cfg -> plotting -> show.
`--plot-aggregate`, `--no-plot-aggregate`, `-pa`		`plotting.aggregate`	When the input is a folder, merge trajectories from all videos sharing the same location ID into a single plot per location. Defaults to cfg -> plotting -> aggregate.
`--plot-points`, `--no-plot-points`, `-pp`		`plotting.plot_points`	Plot discrete trajectory points instead of connected lines. Defaults to cfg -> plotting -> plot_points.
`--plot-segmentations`, `--no-plot-segmentations`, `-pseg`		`plotting.use_segmentations`	Produce an additional trajectory plot overlaid on the lane segmentation overlay PNG (from --segmentation-folder), alongside the standard plain-orthophoto plot. Requires pre-generated overlays (run: python tools/viz_segmentations.py <ortho_folder>/). Defaults to cfg -> plotting -> use_segmentations.
`--plot-class-filter`, `-pcf`	`PLOT_CLASS_FILTER [PLOT_CLASS_FILTER ...]`	`plotting.class_filter`	Vehicle class IDs to exclude from plots (e.g. 1 2). Defaults to cfg -> plotting -> class_filter.