CLI reference¶
Installing stabilo provides the stabilo console command with three subcommands: video stabilizes a video, tracks stabilizes per-frame object annotations, and config prints or copies the default configuration.
Every Stabilizer option in stabilo/cfg/default.yaml can be set through a file passed to --custom-config, and most also have a dedicated flag. Precedence is explicit CLI flags > custom config file > built-in defaults. See Usage: Command-Line Interface for the workflow and the API reference for every key.
The help texts below are generated from the installed parsers when the site is built, so they always match the released command. On the command line, run stabilo <subcommand> --help to see the same text.
stabilo¶
usage: stabilo [-h] [--version] {video,tracks,config} ...
Stabilize videos or per-frame object annotations with respect to a reference frame.
positional arguments:
{video,tracks,config}
video stabilize a video with respect to a reference frame
tracks stabilize per-frame object annotations (tracks) with respect to a
reference frame
config inspect or copy the default stabilo configuration
options:
-h, --help show this help message and exit
--version, -V show program's version number and exit
stabilo video¶
usage: stabilo video [-h] [--output OUTPUT] [--save] [--ref-frame REF_FRAME] [--debug] [--no-mask]
[--mask-path MASK_PATH] [--mask-frame-idx MASK_FRAME_IDX]
[--mask-start-idx MASK_START_IDX] [--mask-end-idx MASK_END_IDX]
[--mask-enc {yolo,pascal,coco,xywha,four,polygon,circle}] [--viz]
[--save-viz] [--no-lines] [--no-boxes] [--speed SPEED]
[--custom-config CUSTOM_CONFIG]
[--detector-name {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}]
[--max-features MAX_FEATURES] [--ref-multiplier REF_MULTIPLIER]
[--matcher-name {bf,flann,lightglue}] [--filter-type {none,ratio,distance}]
[--filter-ratio FILTER_RATIO] [--transformation-type {projective,affine}]
[--ransac-method METHOD]
[--ransac-epipolar-threshold RANSAC_EPIPOLAR_THRESHOLD]
[--ransac-threshold-space {full,processed}]
[--ransac-max-iter RANSAC_MAX_ITER] [--ransac-confidence RANSAC_CONFIDENCE]
[--clahe | --no-clahe | -c] [--downsample-ratio DOWNSAMPLE_RATIO]
[--mask-margin-ratio MASK_MARGIN_RATIO] [--gpu | --no-gpu | -g]
[--gpu-device-id GPU_DEVICE_ID] [--device {auto,cpu,cuda,mps}]
input
Stabilize a video with respect to a reference frame using the stabilo library.
options:
-h, --help show this help message and exit
input and output:
input input video filepath
--output OUTPUT, -o OUTPUT
output folder [default: same as input]
--save, -s save the stabilized video
--ref-frame REF_FRAME, -rf REF_FRAME
custom reference frame index [default: 0]
--debug, -d enable debug mode
exclusion masks:
Regions (e.g. moving vehicles) excluded from feature detection.
--no-mask, -nm disable exclusion masks during stabilization
--mask-path MASK_PATH, -mp MASK_PATH
custom mask file [default: input with .txt extension]
--mask-frame-idx MASK_FRAME_IDX, -mfi MASK_FRAME_IDX
frame number column index in mask file
--mask-start-idx MASK_START_IDX, -msi MASK_START_IDX
start column index for bbox in mask file
--mask-end-idx MASK_END_IDX, -mei MASK_END_IDX
exclusive end column index for mask columns [default: auto from format,
required for 'polygon' that does not span to the last column]
--mask-enc {yolo,pascal,coco,xywha,four,polygon,circle}, -me {yolo,pascal,coco,xywha,four,polygon,circle}
mask format [default: yolo]
visualization:
--viz, -v visualize the transformation process (press 'q' to quit)
--save-viz, -sv save the visualization as a video at original FPS
--no-lines, -nl hide lines between matched feature points
--no-boxes, -nb hide bounding boxes on the (un-)stabilized frames
--speed SPEED, -sp SPEED
visualization speed in ms (0 for manual control)
stabilo configuration file:
Precedence: built-in defaults < --custom-config file < explicit CLI flags below.
--custom-config CUSTOM_CONFIG, -cc CUSTOM_CONFIG
custom stabilo config file (YAML)
stabilo: feature detection:
'xfeat', 'disk', 'dedode', 'keynet', and 'loftr' are learning-based; they download pretrained
weights on first use, need more memory (lower --downsample-ratio for large frames), and,
except for 'keynet', are upright models that degrade under large in-plane rotation.
--detector-name {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}, -dn {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}
detector type [default: orb]
--max-features MAX_FEATURES, -mf MAX_FEATURES
max features to detect [default: 2000]
--ref-multiplier REF_MULTIPLIER, -rm REF_MULTIPLIER
multiplier for max features in reference frame (ref_multiplier x
max_features) [default: 2]
stabilo: feature matching and filtering:
'lightglue' is a learned matcher usable with the 'disk', 'dedode', and 'keynet' detectors; it
does its own filtering. 'loftr' is detector-free and ignores these options entirely.
--matcher-name {bf,flann,lightglue}, -mn {bf,flann,lightglue}
matcher type [default: bf]
--filter-type {none,ratio,distance}, -ft {none,ratio,distance}
filter type for the match filter [default: ratio]
--filter-ratio FILTER_RATIO, -fr FILTER_RATIO
filter ratio for the match filter [default: 0.9]
stabilo: transformation estimation:
'projective' works with every --ransac-method; 'affine' (cv2.estimateAffinePartial2D) accepts
only 4 (LMEDS), 8 (RANSAC) and is rejected with any other method. The epipolar threshold is
measured in full-resolution pixels unless --ransac-threshold-space says otherwise, so a value
tuned at one --downsample-ratio does not transfer to another.
--transformation-type {projective,affine}, -tt {projective,affine}
transformation type [default: projective]
--ransac-method METHOD, -r METHOD
RANSAC method: 4 LMEDS, 8 RANSAC, 16 RHO, 32 USAC-Default (LO-RANSAC), 33
USAC-Parallel (LO-RANSAC), 35 USAC-Fast (LO-RANSAC), 36 USAC-Accurate (GC-
RANSAC), 37 PROSAC, 38 MAGSAC++ [default: 38 (MAGSAC++)]
--ransac-epipolar-threshold RANSAC_EPIPOLAR_THRESHOLD, -ret RANSAC_EPIPOLAR_THRESHOLD
RANSAC epipolar threshold [default: 2.0]
--ransac-threshold-space {full,processed}, -rts {full,processed}
pixels the epipolar threshold is measured in: 'full' (full resolution) or
'processed' (downsampled image, i.e. divided by the downsample ratio
before estimation) [default: full]
--ransac-max-iter RANSAC_MAX_ITER, -rmi RANSAC_MAX_ITER
RANSAC maximum iterations [default: 5000]
--ransac-confidence RANSAC_CONFIDENCE, -rc RANSAC_CONFIDENCE
RANSAC confidence [default: 0.999999]
stabilo: image pre-processing:
--clahe, --no-clahe, -c
apply CLAHE to grayscale images [default: False]
--downsample-ratio DOWNSAMPLE_RATIO, -dr DOWNSAMPLE_RATIO
detect on frames resized by this factor, then rescale keypoints [default:
0.5]
--mask-margin-ratio MASK_MARGIN_RATIO, -mmr MASK_MARGIN_RATIO
mask margin ratio [default: 0.15]
stabilo: hardware acceleration:
--gpu is OpenCV CUDA acceleration for the classical detectors (currently 'orb' only, and it
needs a CUDA-enabled OpenCV build, see docs/cuda.md). --device selects the torch device for
the learning-based detectors and matchers. The two are independent and cannot be combined.
--gpu, --no-gpu, -g use CUDA GPU acceleration [default: False]
--gpu-device-id GPU_DEVICE_ID, -gid GPU_DEVICE_ID
CUDA device index when --gpu is set [default: 0]
--device {auto,cpu,cuda,mps}, -dv {auto,cpu,cuda,mps}
torch device for the learning-based detectors [default: auto]
examples:
stabilo video video.mp4 --save stabilize and save the result
stabilo video video.mp4 --viz preview the stabilization live
stabilo video video.mp4 -dn sift -mn flann --save pick a classical detector and matcher
stabilo video video.mp4 --no-mask --viz ignore the exclusion masks
stabilo video video.mp4 --ref-frame 15 --save-viz stabilize against frame 15
stabilo video video.mp4 -cc config.yaml --save take defaults from a config file
stabilo video video.mp4 -dn xfeat -dr 0.25 --save learning-based detector on smaller frames
stabilo video video.mp4 --gpu --save OpenCV CUDA (see docs/cuda.md)
stabilo tracks¶
usage: stabilo tracks [-h] [--output OUTPUT] [--save] [--ref-frame REF_FRAME] [--tracks TRACKS]
[--boxes-frame-idx BOXES_FRAME_IDX] [--boxes-start-idx BOXES_START_IDX]
[--boxes-end-idx BOXES_END_IDX] [--boxes-enc {yolo,pascal,coco,xywha,four}]
[--no-mask] [--mask-path MASK_PATH] [--mask-frame-idx MASK_FRAME_IDX]
[--mask-start-idx MASK_START_IDX] [--mask-end-idx MASK_END_IDX]
[--mask-enc {yolo,pascal,coco,xywha,four,polygon,circle}] [--viz]
[--save-viz] [--speed SPEED] [--tail-length TAIL_LENGTH]
[--tail-radius TAIL_RADIUS] [--canvas-x CANVAS_X]
[--custom-config CUSTOM_CONFIG]
[--detector-name {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}]
[--max-features MAX_FEATURES] [--ref-multiplier REF_MULTIPLIER]
[--matcher-name {bf,flann,lightglue}] [--filter-type {none,ratio,distance}]
[--filter-ratio FILTER_RATIO] [--transformation-type {projective,affine}]
[--ransac-method METHOD]
[--ransac-epipolar-threshold RANSAC_EPIPOLAR_THRESHOLD]
[--ransac-threshold-space {full,processed}]
[--ransac-max-iter RANSAC_MAX_ITER] [--ransac-confidence RANSAC_CONFIDENCE]
[--clahe | --no-clahe | -c] [--downsample-ratio DOWNSAMPLE_RATIO]
[--mask-margin-ratio MASK_MARGIN_RATIO] [--gpu | --no-gpu | -g]
[--gpu-device-id GPU_DEVICE_ID] [--device {auto,cpu,cuda,mps}]
input
Stabilize per-frame object annotations (tracks) using the stabilo library.
options:
-h, --help show this help message and exit
input and output:
input input video filepath
--output OUTPUT, -o OUTPUT
output folder [default: same as input]
--save, -s save the stabilized tracks to a file
--ref-frame REF_FRAME, -rf REF_FRAME
custom reference frame index [default: 0]
tracks to stabilize:
--tracks TRACKS, -t TRACKS
filepath to the tracks file [default: input with .txt extension]
--boxes-frame-idx BOXES_FRAME_IDX, -bfi BOXES_FRAME_IDX
frame number column index in the tracks file
--boxes-start-idx BOXES_START_IDX, -bsi BOXES_START_IDX
start column index for bbox in the tracks file
--boxes-end-idx BOXES_END_IDX, -bei BOXES_END_IDX
exclusive end column index for box columns [default: auto from format,
required for 'polygon' that does not span to the last column]
--boxes-enc {yolo,pascal,coco,xywha,four}, -be {yolo,pascal,coco,xywha,four}
bbox encoding [default: yolo]
exclusion masks:
Regions (e.g. moving vehicles) excluded from feature detection.
--no-mask, -nm disable exclusion masks during stabilization
--mask-path MASK_PATH, -mp MASK_PATH
custom mask file for stabilization [default: same as boxes]
--mask-frame-idx MASK_FRAME_IDX, -mfi MASK_FRAME_IDX
frame number column index in mask file
--mask-start-idx MASK_START_IDX, -msi MASK_START_IDX
start column index for bbox in mask file
--mask-end-idx MASK_END_IDX, -mei MASK_END_IDX
exclusive end column index for mask columns [default: auto from format,
required for 'polygon' that does not span to the last column]
--mask-enc {yolo,pascal,coco,xywha,four,polygon,circle}, -me {yolo,pascal,coco,xywha,four,polygon,circle}
mask format [default: yolo]
visualization:
--viz, -v show the stabilized and un-stabilized tracks
--save-viz, -sv save the visualization as a video at original FPS
--speed SPEED, -sp SPEED
visualization speed in ms (0 for manual control)
--tail-length TAIL_LENGTH, -tl TAIL_LENGTH
tail length for visualization
--tail-radius TAIL_RADIUS, -tr TAIL_RADIUS
tail radius for visualization
--canvas-x CANVAS_X, -cx CANVAS_X
canvas enlargement factor (>= 1)
stabilo configuration file:
Precedence: built-in defaults < --custom-config file < explicit CLI flags below.
--custom-config CUSTOM_CONFIG, -cc CUSTOM_CONFIG
custom stabilo config file (YAML)
stabilo: feature detection:
'xfeat', 'disk', 'dedode', 'keynet', and 'loftr' are learning-based; they download pretrained
weights on first use, need more memory (lower --downsample-ratio for large frames), and,
except for 'keynet', are upright models that degrade under large in-plane rotation.
--detector-name {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}, -dn {orb,sift,rsift,brisk,kaze,akaze,xfeat,disk,dedode,keynet,loftr}
detector type [default: orb]
--max-features MAX_FEATURES, -mf MAX_FEATURES
max features to detect [default: 2000]
--ref-multiplier REF_MULTIPLIER, -rm REF_MULTIPLIER
multiplier for max features in reference frame (ref_multiplier x
max_features) [default: 2]
stabilo: feature matching and filtering:
'lightglue' is a learned matcher usable with the 'disk', 'dedode', and 'keynet' detectors; it
does its own filtering. 'loftr' is detector-free and ignores these options entirely.
--matcher-name {bf,flann,lightglue}, -mn {bf,flann,lightglue}
matcher type [default: bf]
--filter-type {none,ratio,distance}, -ft {none,ratio,distance}
filter type for the match filter [default: ratio]
--filter-ratio FILTER_RATIO, -fr FILTER_RATIO
filter ratio for the match filter [default: 0.9]
stabilo: transformation estimation:
'projective' works with every --ransac-method; 'affine' (cv2.estimateAffinePartial2D) accepts
only 4 (LMEDS), 8 (RANSAC) and is rejected with any other method. The epipolar threshold is
measured in full-resolution pixels unless --ransac-threshold-space says otherwise, so a value
tuned at one --downsample-ratio does not transfer to another.
--transformation-type {projective,affine}, -tt {projective,affine}
transformation type [default: projective]
--ransac-method METHOD, -r METHOD
RANSAC method: 4 LMEDS, 8 RANSAC, 16 RHO, 32 USAC-Default (LO-RANSAC), 33
USAC-Parallel (LO-RANSAC), 35 USAC-Fast (LO-RANSAC), 36 USAC-Accurate (GC-
RANSAC), 37 PROSAC, 38 MAGSAC++ [default: 38 (MAGSAC++)]
--ransac-epipolar-threshold RANSAC_EPIPOLAR_THRESHOLD, -ret RANSAC_EPIPOLAR_THRESHOLD
RANSAC epipolar threshold [default: 2.0]
--ransac-threshold-space {full,processed}, -rts {full,processed}
pixels the epipolar threshold is measured in: 'full' (full resolution) or
'processed' (downsampled image, i.e. divided by the downsample ratio
before estimation) [default: full]
--ransac-max-iter RANSAC_MAX_ITER, -rmi RANSAC_MAX_ITER
RANSAC maximum iterations [default: 5000]
--ransac-confidence RANSAC_CONFIDENCE, -rc RANSAC_CONFIDENCE
RANSAC confidence [default: 0.999999]
stabilo: image pre-processing:
--clahe, --no-clahe, -c
apply CLAHE to grayscale images [default: False]
--downsample-ratio DOWNSAMPLE_RATIO, -dr DOWNSAMPLE_RATIO
detect on frames resized by this factor, then rescale keypoints [default:
0.5]
--mask-margin-ratio MASK_MARGIN_RATIO, -mmr MASK_MARGIN_RATIO
mask margin ratio [default: 0.15]
stabilo: hardware acceleration:
--gpu is OpenCV CUDA acceleration for the classical detectors (currently 'orb' only, and it
needs a CUDA-enabled OpenCV build, see docs/cuda.md). --device selects the torch device for
the learning-based detectors and matchers. The two are independent and cannot be combined.
--gpu, --no-gpu, -g use CUDA GPU acceleration [default: False]
--gpu-device-id GPU_DEVICE_ID, -gid GPU_DEVICE_ID
CUDA device index when --gpu is set [default: 0]
--device {auto,cpu,cuda,mps}, -dv {auto,cpu,cuda,mps}
torch device for the learning-based detectors [default: auto]
examples:
stabilo tracks video.mp4 --save stabilize the tracks and save them
stabilo tracks video.mp4 --save --ref-frame 100 stabilize against frame 100
stabilo tracks video.mp4 --viz --save-viz --speed 20 preview and record the visualization
stabilo tracks video.mp4 --no-mask --save ignore the exclusion masks
stabilo tracks video.mp4 -cc config.yaml --save take defaults from a config file
stabilo tracks video.mp4 -dn xfeat -dr 0.25 --save learning-based detector on smaller frames
stabilo tracks video.mp4 --gpu --save OpenCV CUDA (see docs/cuda.md)
stabilo config¶
usage: stabilo config [-h] [--output OUTPUT] {show,copy}
Inspect the default stabilo configuration or copy it locally for editing.
positional arguments:
{show,copy} 'show' prints the default configuration; 'copy' writes an editable copy
locally
options:
-h, --help show this help message and exit
--output OUTPUT, -o OUTPUT
destination file for 'copy' [default: ./custom.yaml]