geotrax extract

Stage 1: vehicle detection, tracking, and stabilization.

usage: geotrax extract [-h] [--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}]
                       source

Vehicle Detection, Tracking, and Stabilization Pipeline

Positional arguments

Argument	Value	Config key	Description
source			Path to the input video file.

Optional arguments

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 arguments

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.