georef

Georeferencing settings.

Parameters for the homography-based georeferencing stage ('geotrax georeference').

Generated from geotrax/cfg/default.yaml; every row below is a key of that file with its shipped default and its inline comment.

georef.transformation

Coordinate reference systems and orthophoto geometry

Key	Default	CLI	Description
source_crs	epsg:4326		CRS of the orthophoto's georeferencing; the Latitude/Longitude columns are computed in it, so keep WGS 84 (epsg:4326); string
target_crs	epsg:5186		Projected CRS in meters for Local_X/Local_Y, in which speeds, accelerations and dimensions are also measured; epsg:5186 (Korea 2000) suits South Korea only, so set one for your area, e.g. its UTM zone (a warning names it when the distortion at the site exceeds 1%); string
cutout_width_px	15000		Original orthophoto cutout width [px]; used to derive geographic resolution when geo_source is 'center-text-file'; null falls back to the provided orthophoto width; [0, inf) or null

georef.matching

Feature matching (MAGSAC++ based image registration against orthophotos). Learning-based detectors need care here: the orthophoto is north-up and large (64 MP in the Songdo data), so lower downsample_ratio first. See https://rfonod.github.io/geo-trax/guides/feature-detectors/

Key	Default	CLI	Description
detector_name	rsift	--geo-detector	Feature detector & descriptor; classical: ['orb', 'sift', 'rsift', 'brisk', 'kaze', 'akaze'], learned: ['xfeat', 'disk', 'dedode', 'keynet', 'loftr']
matcher_name	bf		Descriptor matcher; ['bf', 'flann', 'lightglue'] (lightglue is learned; needs disk/dedode/keynet)
filter_type	ratio		Match filter; ['none', 'ratio', 'distance'] (ratio = Lowe's ratio test)
sift_enable_precise_upscale	true		SIFT/RSIFT precise sub-pixel upscaling at octave -1; [true, false]
downsample_ratio	1.0		Resize images by this factor before detection, then rescale keypoints; (0.0, 1.0]. Lower it for learned detectors
max_features	250000		Maximum number of features kept, the strongest by response; [0, inf)
filter_ratio	0.55		Lowe ratio-test threshold; lower = stricter (fewer but better matches); (0.0, 1.0]
ransac_method	38		RANSAC method (same options as stabilization above)
ransac_epipolar_threshold	3.0		Reprojection error threshold [px] for RANSAC inlier classification, in the pixels of ransac_threshold_space; (0.0, inf)
ransac_threshold_space	unset (commented out; full when enabled)		Pixels the threshold is measured in; ['full' (full resolution), 'processed' (downsampled image: threshold / downsample_ratio)]. Left unset ('full'), since the two agree at downsample_ratio 1.0 and every key in this block feeds the master -> orthophoto cache hash; uncomment it if you lower downsample_ratio
ransac_max_iter	10000		Maximum RANSAC iterations; (0, inf]
ransac_confidence	0.999999		Required probability that the best model is correct; (0.0, 1.0]
rsift_eps	0.00000001		Epsilon added before RootSIFT L1-normalisation to avoid division by zero; > 0.0, keep very small (e.g. 1e-8)
gpu	false	--geo-gpu, --no-geo-gpu	GPU-accelerate registration; requires detector_name: orb AND a CUDA-enabled OpenCV build; [true, false]
gpu_device_id	0	--geo-gpu-device-id	CUDA device index used when gpu is true (multi-GPU machines); [0, inf)
device	auto	--geo-device	Torch device, learned detectors only; ['auto' (cuda > mps > cpu), 'cpu', 'cuda', 'mps']

Learning-based (kornia) detector weights; only used when detector_name is one of them

Key	Default	CLI	Description
loftr_weights	outdoor		LoFTR pretrained weights; [outdoor, indoor]
loftr_confidence	0.0		LoFTR min. correspondence confidence to keep; [0.0, 1.0] (0.0 keeps all)
disk_weights	depth		DISK pretrained weights; [depth, epipolar]
dedode_detector_weights	L-C4-v2		DeDoDe detector weights; [L-upright, L-C4, L-SO2, L-C4-v2]
dedode_descriptor_weights	B-upright		DeDoDe descriptor weights; [B-upright, G-upright, B-C4, B-SO2, G-C4, G-SO2]

georef.filtering

Trajectory kinematics filtering and output quality thresholds

Key	Default	CLI	Description
filter_type	gaussian		Smoothing filter applied to speed before differentiation; choices: [gaussian, savgol]
kernel_size	14		Smoothing kernel / window size [frames]; larger = smoother speed/acceleration; [1, inf)
min_traj_length	15		Minimum number of georeferenced points required to keep a trajectory; shorter ones are discarded; [0, inf)
visibility_margin	4		Distance [px] from any frame edge below which a vehicle is flagged as partially visible; [0, inf)

georef.processing

Processing settings (CLI override)

Key	Default	CLI	Description
ref_frame	0	--ref-frame	Video frame index used as the registration anchor; must match the stabilization reference frame (processing -> cut_frame_left), and is taken from it automatically unless --ref-frame is given explicitly; [0, inf)
use_master	true	--no-master	Use a pre-computed master→orthophoto homography for faster, more robust matching
recompute	false	--recompute	Force recomputation of the master→orthophoto homography even if a cached version exists
geo_source	null	--geo-source	Orthophoto parameter source; null = auto-detect from available files; choices: [null, metadata-tif, text-file, center-text-file]