geotrax georeference

Stage 2: map stabilized trajectories to real-world coordinates.

usage: geotrax georeference [-h] [--cfg CFG] [--set KEY=VALUE] [--output-folder OUTPUT_FOLDER]
                            [--log-path LOG_PATH] [--verbose] [--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}]
                            source

Georeferencing the tracking data using orthophotos.

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).

Georeferencing arguments

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.