Ops

22 ops are registered. An op is the unit mosaic run --kind <kind> executes: a tracker, a model training or inference run, a frame extraction, or a media operation. Features transform tables that already exist; ops are what produce them and what reaches outside the process.

4 of these are not discoverable from the CLI

mosaic tracking list shows only the ops whose domain is tracking. It omits export-joined, export-store, preprocess and transcode, which mosaic run --kind runs all the same. This page reads OPS directly and lists every op.

In the tables below, required means the parameter has no default and must be supplied. constructed means it is optional but its default is built by a factory rather than being a literal, so there is no value to print.

Tracking

convert

convert-labels

Version 0.1 · mosaic.core.pipeline.convert_ops.ConvertLabelsOp

Convert one format's raw labels into a labels variant of one kind.

Parameter	Type	Default	Constraints	Description
kind	string	"behavior"		The label kind to convert into, such as 'behavior'.
source_format	string	required		The registered converter's src_format, such as 'calms21_npy'. One step converts one format and names one variant.
params	object	{}		The label converter's own params, such as fps or group_from. A key the converter does not declare is refused.

convert-points

Version 0.2 · mosaic.tracking.ops.convert.ConvertPointsOp

Convert CVAT point annotations into a POLO point-detection dataset + data.yaml.

Parameter	Type	Default	Constraints	Description
source_format	"cvat_points"	"cvat_points"		Which annotation format this run converts.
cvat_xml	string	required		The CVAT 'for Images 1.1' XML export to convert.
images_dir	string	required		Directory of images whose filenames match the XML's image name attributes.
class_names	list of string	required		Ordered class names, index used as the class id. An empty list auto-detects names from the XML in order of first appearance.
radii	object	required		Detection radius for each class name. Every class the conversion resolves needs an entry, whether class_names named it or auto-detection found it. [px]
class_attribute	string	"class"		Name of the XML attribute that names each point's class. Empty means single-class, with every point assigned class 0.
split	tuple of (number, number, number)	[0.8, 0.15, 0.05]	min items 3, max items 3	Train, validation and test fractions of the annotated images.
split_by	string	"group"		How images are grouped before the split is drawn. group keeps frames from the same video together in one split.
seed	integer	42		Random seed for the train, validation and test split assignment.
symlink_images	boolean	true		Symlink source images into the dataset instead of copying them.

convert-tracks

Version 0.1 · mosaic.core.pipeline.convert_ops.ConvertTracksOp

Convert one format's raw tracks into a tracks variant.

Parameter	Type	Default	Constraints	Description
source_format	string	required		The registered converter's src_format, such as 'calms21_npy'. One step converts one format and names one variant.
params	object	{}		The converter's own params, such as fps. A key the converter does not declare is refused.
merge_per_sequence	boolean | None	null		Merge a sequence's several files into one table. Unset asks the converter.
group_from	"filename" | "infile" | "both" | None	null		Which group a converted entry is filed under: 'filename' (the scan's file-level group, the default), 'infile' or 'both'.

litpose

Version 2.3 · mosaic.tracking.ops.litpose.LitposeOp · resource class gpu

Run Lightning Pose inference over scoped videos, bridging results into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
convert_to_tracks	boolean	true		Convert the tool's native output into a standardized tracks table once tracking finishes, instead of leaving the output where the tool wrote it.
idle_timeout	number	900		How long a phase may go without a line of output from the tool before it is killed. A generous default, because an epoch on a large set is slow and a watchdog must not mistake slow for dead. [s]
max_runtime	number | None	null		Absolute wall-clock ceiling for one phase. Unset leaves the ceiling to whatever queue submitted the run. [s]
model_path	string	required		A trained Lightning Pose model directory (config.yaml plus a checkpoint under tb_logs/).
litpose_overrides	object | None	null		Hydra config overrides applied at inference time.
precision	string	"fp32"		The forward-pass precision: fp32, fp16, or bf16.

prepare-training-data

Version 0.2 · mosaic.tracking.ops.prepare.PrepareTrainingDataOp

Merge revisions of keypoint annotation sets into one training dataset.

Parameter	Type	Default	Constraints	Description
sets	list of KeypointSetRef	required	min items 1	The annotation sets to train on, merged into one dataset.
target	"yolo-pose" | "polo" | "sleap" | "litpose"	"yolo-pose"		Which trainer's layout to write.
pose	integer | string | None	null		Which pose to train, by its id or its name. Left unset, every set must hold exactly one pose. One dataset has one keypoint layout.
class_by	"alias" | None	null		alias makes each alias a class, and refuses an object of the pose without one. Unset, the pose is the one class. sleap and litpose train one class.
track_by	"alias" | None	null		sleap only: alias gives each object its alias as its track, which is what a SLEAP identity model learns.
bbox	BboxPolicy | None	null		How a box the annotator did not draw is derived from its keypoints. Unset, each set's own padding: the box the annotator saw. A drawn box is used as drawn.
point_index	integer	0	>= 0	polo only: which keypoint of each instance is the point.
radius	number	100.0	> 0	polo only: the detection radius. [px]
split	tuple of (number, number, number)	[0.8, 0.15, 0.05]	min items 3, max items 3	Train, validation and test fractions.
split_by	"sequence" | "group" | "frame"	"sequence"		What is kept together when the split is drawn. sequence keeps one recording's frames in one split, which is what makes a validation score honest. group keeps a whole sequence_groups label together. frame splits image by image, and its scores are optimistic.
sequence_groups	object	constructed		group only: the group each sequence belongs to, keyed by sequence name or by ':' where names repeat across datasets. A sequence not listed is a group of its own.
seed	integer	42		Random seed for the split assignment.
symlink_images	boolean	false		Symlink images instead of copying them. Off by default: a symlinked tree stops being reproducible the moment a source dataset moves.

BboxPolicy

Parameter	Type	Default	Constraints	Description
method	"tight" | "isotropic" | "oriented"	"tight"		Which strategy derives the box from the keypoints when the source supplied none. Known values are tight, isotropic and oriented.
margin	number	0.1		The padding added around the tight hull of valid keypoints, as a fraction of the hull's own size. Used only when method is tight.
pad_frac_of_body	number	0.3		The padding added around the tight hull of valid keypoints, as a fraction of body length. Used when method is isotropic, and as the isotropic fallback for oriented when the head or tail keypoint is invalid, or when the head-tail distance is zero.
min_pad_px	number	20.0		The floor for the padding around the tight hull, for degenerate or overlapping keypoints. Used when method is isotropic, and as the isotropic fallback for oriented when the head or tail keypoint is invalid, or when the head-tail distance is zero. [px]
length_pad_frac	number	0.25		The padding extending the oriented rectangle beyond the head and tail, as a fraction of the head-tail distance. Used only when method is oriented.
side_pad_frac	number	0.35		The padding extending the oriented rectangle across the head-tail axis, as a fraction of the head-tail distance. Used only when method is oriented.
head_index	integer | None	null		The keypoint index of the head. Required when method is oriented. When given together with tail_index for isotropic, body length is the distance between them instead of the tight hull's diagonal.
tail_index	integer | None	null		The keypoint index of the tail. Required when method is oriented. When given together with head_index for isotropic, body length is the distance between them instead of the tight hull's diagonal.

KeypointSetRef

Parameter	Type	Default	Constraints	Description
set_key	string	required		The set's key in the keypoints label series.
origin_uuid	string	""		The manifest uuid of the dataset the set was saved in. Needed only when two datasets' sets share a key; empty matches the one that has it.
revision	integer | None	null		Which revision to read. Left unset, the latest one indexed when the run is named. The number selects and is recorded; only the content it resolves to enters the run identifier.

resample-tracks

Version 0.1 · mosaic.tracking.ops.resample.ResampleTracksOp

Place a dataset's tracks tables on one uniform frame rate.

Parameter	Type	Default	Constraints	Description
target_fps	number	required		The uniform frame rate every table is re-gridded onto, which is what makes one constant expressed in frames mean one duration dataset-wide. [fps]
source_tracks_run_id	string | None	null		Which tracks variant to read, e.g. 'trex.0.1-abc123def0'. Unset resolves whichever variant the scope's entries hold, and refuses when they hold two.
prefilter	number | None	null		Displacement from the predecessor above which a native sample is rejected before interpolating. A rejected mis-detection is dropped instead of blended into its neighbors. Unset interpolates the samples as they are. [units/s]

sleap

Version 1.6 · mosaic.tracking.ops.sleap.SleapOp · resource class gpu

Run SLEAP (infer + track) over scoped videos, bridging results into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
convert_to_tracks	boolean	true		Convert the tool's native output into a standardized tracks table once tracking finishes, instead of leaving the output where the tool wrote it.
idle_timeout	number	900		How long a phase may go without a line of output from the tool before it is killed. A generous default, because an epoch on a large set is slow and a watchdog must not mistake slow for dead. [s]
max_runtime	number | None	null		Absolute wall-clock ceiling for one phase. Unset leaves the ceiling to whatever queue submitted the run. [s]
model_paths	list of string	required		One trained SLEAP model directory, or two for a top-down model (centroid, then centered-instance).
tracking	boolean	true		Assign identities to detections across frames. When False, no tracker is attached.
use_flow	boolean	false		Shift each candidate pose by optical flow before matching it to a detection, sent as --use_flow.
candidates_method	"fixed_window" | "local_queues"	"fixed_window"		Where match candidates come from, sent as --candidates_method: fixed_window takes every instance of the last few frames, local_queues the last few instances of each track.
features	"keypoints" | "centroids" | "bboxes" | "image"	"keypoints"		What a detection and a candidate are compared by, sent as --features: keypoints, centroids, bboxes or image.
scoring_method	"oks" | "cosine_sim" | "iou" | "euclidean_dist"	"oks"		How that comparison is scored, sent as --scoring_method: oks, cosine_sim, iou or euclidean_dist.
track_matching_method	"hungarian" | "greedy"	"hungarian"		How detections are assigned to tracks from those scores, sent as --track_matching_method: hungarian or greedy.
tracking_window_size	integer	5		How many frames, or instances per track under local_queues, are kept as match candidates, sent as --tracking_window_size.
max_tracks	integer | None	null		The maximum number of tracks, sent as --max_tracks. sleap-nn enforces it only through local_queues candidates, so it requires that candidates_method.
max_instances	integer | None	null		The maximum number of instances to detect per frame.
peak_threshold	number	0.2		The minimum confidence for a detected peak.
analysis_range	tuple of (integer, integer) | None	null		The first and last frame to analyze. Unset, SLEAP analyzes the whole video.
sleap_extra_settings	object | None	null		Additional sleap-nn track options, sent as --key value pairs. A boolean value becomes a bare --key flag when true and is omitted when false, and a None value is skipped.
batch_size	integer	4		The inference batch size.
device	string | None	null		The device to run inference on: cpu, cuda, mps, a CUDA index such as 0, or cuda:. Unset and auto leave the choice to sleap-nn; a named device fails where it is absent. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.

trex

Version 0.3 · mosaic.tracking.ops.trex.TrexOp · resource class gpu

Run TRex (convert + track) over scoped videos, bridging results into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
convert_to_tracks	boolean	true		Convert the tool's native output into a standardized tracks table once tracking finishes, instead of leaving the output where the tool wrote it.
idle_timeout	number	900		How long a phase may go without a line of output from the tool before it is killed. A generous default, because an epoch on a large set is slow and a watchdog must not mistake slow for dead. [s]
max_runtime	number | None	null		Absolute wall-clock ceiling for one phase. Unset leaves the ceiling to whatever queue submitted the run. [s]
detect_model	string | None	null		A YOLO .pt path, or the run id of the training op that produced the weights. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
detect_type	string | None	null		The detection algorithm. Known values are yolo, background_subtraction and points.
detect_conf_threshold	number | None	null		The minimum YOLO detection confidence. Unset, TREx applies 0.1.
detect_iou_threshold	number | None	null		The NMS IoU threshold for suppressing overlapping detections. TREx leaves it unset by default: unset preserves the upstream model's default postprocessing, and setting it may disable end-to-end NMS-free inference. A number here is a choice about the detector as well as a threshold.
cm_per_pixel	number | None	null		The spatial calibration factor. Unset, TREx derives it from meta_real_width / video_width. [cm/px]
meta_encoding	string | None	null		The pixel encoding. Known values are gray and rgb8.
convert_extra_settings	object | None	null		Additional TREx parameters sent as -key value pairs for the conversion phase. A None value removes a parameter mosaic would otherwise send.
track_max_individuals	integer | None	null		The maximum number of simultaneous individuals to track. Unset, TREx applies 1024.
track_max_speed	number | None	null		The maximum plausible speed. Its meaning depends on the cm_per_pixel the conversion applied. [cm/s]
track_max_reassign_time	number | None	null		How long to wait before giving up on a lost individual. Unset, TREx applies 0.5. [s]
track_trusted_probability	number | None	null		The probability below which the current tracklet ends and a new one starts. Unset, TREx applies 0.25. Lowering it produces longer tracklets held together by weaker evidence.
analysis_range	tuple of (integer, integer) | None	null		The frame range to analyze. -1 means the beginning or the end of the video.
visual_identification_model_path	string | None	null		Pre-trained identity weights (.pth, without the extension), or the run id of the identity-training op that produced them. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
auto_train	boolean	false		Train visual identification automatically after tracking.
detect_keypoint_count	integer | None	null		How many keypoints detect_model reports. Set it whenever that model is a pose model, or the tracks come back without their keypoint columns. TREx derives the poseX / poseY names from a keypoint format it learns by loading the model, and mosaic converts and tracks as two invocations, so the exporting process has never loaded one.
track_extra_settings	object | None	null		Additional TREx parameters sent as -key value pairs for the tracking phase. A None value removes a parameter mosaic would otherwise send.

ultralytics

Version 8.4 · mosaic.tracking.ops.ultralytics.UltralyticsOp · resource class gpu

Track scoped videos with a YOLO model, bridging results into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
convert_to_tracks	boolean	true		Convert the tool's native output into a standardized tracks table once tracking finishes, instead of leaving the output where the tool wrote it.
idle_timeout	number	900		How long a phase may go without a line of output from the tool before it is killed. A generous default, because an epoch on a large set is slow and a watchdog must not mistake slow for dead. [s]
max_runtime	number | None	null		Absolute wall-clock ceiling for one phase. Unset leaves the ceiling to whatever queue submitted the run. [s]
model_path	string	required		The YOLO weights to track with: a .pt path, or the run id of the training op that produced them. Identity records the weights' content digest when the reference is a bare path, and the training run id when it is one.
task	"pose" | "detect"	"pose"		Which head the weights carry. Declared rather than read off the file, because it is part of the identifier and a run must not re-mean itself when the weights behind a path change. The loaded model is checked against it and a mismatch is refused by name.
tracker	"botsort" | "bytetrack" | "deepocsort" | "fasttrack" | "ocsort" | "tracktrack"	"bytetrack"		Which backend associates detections across frames. bytetrack is the default rather than Ultralytics' own, because botsort, deepocsort and tracktrack default to optical-flow camera motion compensation whose RANSAC is unseeded, and a run under one of those is not reproducible bit for bit. bytetrack constructs no motion estimator. The others stay one parameter away and are the right choice for a moving camera.
tracker_overrides	BotsortConfig | BytetrackConfig | DeepocsortConfig | FasttrackConfig | OcsortConfig | TracktrackConfig | None	null		The chosen backend's settings. Every setting that backend has appears here with its declared default, so a caller states the ones it cares about and leaves the rest. Identity records the fully resolved table: restating a default mints the same identifier as passing nothing, and changing one setting mints a different one.
conf	number	0.1	> 0.0, <= 1.0	The minimum detection confidence. Ultralytics' track mode replaces a falsy confidence with 0.1, so its documented predict default of 0.25 never applies here and 0.0 would be recorded as 0.0 and run as 0.1. The lower bound refuses that one value.
iou	number	0.7	>= 0.0, <= 1.0	The NMS IoU threshold for suppressing overlapping detections.
imgsz	integer	640	> 0	The side each frame is letterboxed to for inference. Predictions are mapped back to source pixels, so this changes what the detector sees rather than what the coordinates mean. [px]
max_det	integer	300	> 0	The most detections kept from one frame.
classes	list of integer | None	null		Which detector class indexes to keep. Unset keeps every class. Identity records the set sorted and de-duplicated, so the order a filter was typed in does not move the identifier.
agnostic_nms	boolean	false		Suppress overlapping detections across classes instead of within each one.
start_frame	integer	0	>= 0	The first frame index tracked. It is part of identity for a stronger reason than in the inference ops: a tracker is stateful, so a different starting frame gives different identities rather than a subset of the same ones.
end_frame	integer | None	null		The frame index tracking stops before. Unset tracks to the end of the video.
frame_step	integer	1	>= 1	Track every nth frame. A step above 1 changes what the tracker sees between observations, so it changes the identities as well as the count.
device	string	"0"		Which CUDA device index, or cpu, runs inference. A property of the machine rather than of the result, so it stays out of identity. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
precision	"fp32" | "fp16"	"fp32"		The numeric precision inference runs at. fp16 halves the memory a batch needs and can move a detection across a threshold.
batch_size	integer	8	>= 1	How many frames are decoded and handed to the model per forward pass. Tracking still advances one frame at a time within a batch.
prefetch	boolean	true		Decode the next batch on a background thread while the current one runs.

BotsortConfig

Parameter	Type	Default	Constraints	Description
tracker_type	"botsort"	"botsort"		Which backend this configuration is for. It is the tag the schema discriminates on, and a configuration naming a different backend than the run's tracker is refused.
track_high_thresh	number	0.25		The confidence a detection must reach to enter the first association pass. Raising it produces cleaner tracks and keeps fewer detections.
track_low_thresh	number	0.1		The confidence below which a detection is discarded. Between this and track_high_thresh a detection is kept for the second association pass, which trades recovery against drift.
new_track_thresh	number	0.25		The confidence an unmatched detection must reach to start a new track. Raising it produces fewer spurious tracks.
track_buffer	integer	30		How long a lost track stays alive before it is removed. A longer buffer survives more occlusion and risks more identity switches. [frames]
match_thresh	number	0.8		The similarity a detection and a track must reach to be associated in the first pass. Tune it with the detector's quality.
fuse_score	boolean	true		Multiply the association similarity by the detection confidence before matching, which stabilizes weak detections.
gmc_method	"sparseOptFlow" | "orb" | "sift" | "ecc" | "none"	"sparseOptFlow"		Which estimator cancels camera motion between frames. sparseOptFlow, orb and sift run an unseeded RANSAC, so a run under one of those is not reproducible bit for bit. none constructs no estimator.
proximity_thresh	number	0.5		The overlap a detection and a track must share before their appearance embeddings are compared. Raising it makes re-identification stricter.
appearance_thresh	number	0.8		The appearance similarity a re-identification match must reach. Raising it avoids identity swaps.
with_reid	boolean	false		Match on appearance embeddings beside motion and overlap, which costs a further model and further compute.
model	"auto"	"auto"		Which checkpoint supplies the appearance embeddings. Fixed at auto, the detector's own features: mosaic refuses every other value, because a checkpoint reaching a run identifier must be named by content digest.

BytetrackConfig

Parameter	Type	Default	Constraints	Description
tracker_type	"bytetrack"	"bytetrack"		Which backend this configuration is for. It is the tag the schema discriminates on, and a configuration naming a different backend than the run's tracker is refused.
track_high_thresh	number	0.25		The confidence a detection must reach to enter the first association pass. Raising it produces cleaner tracks and keeps fewer detections.
track_low_thresh	number	0.1		The confidence below which a detection is discarded. Between this and track_high_thresh a detection is kept for the second association pass, which trades recovery against drift.
new_track_thresh	number	0.25		The confidence an unmatched detection must reach to start a new track. Raising it produces fewer spurious tracks.
track_buffer	integer	30		How long a lost track stays alive before it is removed. A longer buffer survives more occlusion and risks more identity switches. [frames]
match_thresh	number	0.8		The similarity a detection and a track must reach to be associated in the first pass. Tune it with the detector's quality.
fuse_score	boolean	true		Multiply the association similarity by the detection confidence before matching, which stabilizes weak detections.

DeepocsortConfig

Parameter	Type	Default	Constraints	Description
tracker_type	"deepocsort"	"deepocsort"		Which backend this configuration is for. It is the tag the schema discriminates on, and a configuration naming a different backend than the run's tracker is refused.
track_high_thresh	number	0.3		The confidence a detection must reach to enter the first association pass. Raising it produces cleaner tracks and keeps fewer detections.
track_low_thresh	number	0.1		The confidence below which a detection is discarded. Between this and track_high_thresh a detection is kept for the second association pass, which runs only under use_byte.
new_track_thresh	number	0.3		The confidence an unmatched detection must reach to start a new track. Raising it produces fewer spurious tracks.
track_buffer	integer	30		How long a lost track stays alive before it is removed. A longer buffer survives more occlusion and risks more identity switches. [frames]
match_thresh	number	0.8		The similarity a detection and a track must reach to be associated in the first pass. Tune it with the detector's quality.
fuse_score	boolean	true		Multiply the association similarity by the detection confidence before matching, which stabilizes weak detections.
delta_t	integer	3		How far back the observation-centric velocity direction is measured. A longer window smooths more. [frames]
inertia	number	0.2		The weight the velocity-consistency term gets in the association cost. Raising it penalizes a direction change more.
use_byte	boolean	false		Run ByteTrack's low-confidence second association pass as well.
gmc_method	"sparseOptFlow" | "orb" | "sift" | "ecc" | "none"	"none"		Which estimator cancels camera motion between frames. sparseOptFlow, orb and sift run an unseeded RANSAC, so a run under one of those is not reproducible bit for bit. none constructs no estimator.
with_reid	boolean	false		Match on appearance embeddings beside motion and overlap, which costs a further model and further compute.
model	"auto"	"auto"		Which checkpoint supplies the appearance embeddings. Fixed at auto, the detector's own features: mosaic refuses every other value, because a checkpoint reaching a run identifier must be named by content digest.
proximity_thresh	number	0.5		The overlap a detection and a track must share before their appearance embeddings are compared. Raising it makes re-identification stricter.
appearance_thresh	number	0.9		The appearance similarity a re-identification match must reach. Raising it avoids identity swaps.
alpha_fixed_emb	number	0.95		The base exponential-moving-average factor for a track's appearance embedding. Raising it updates the embedding more slowly.

FasttrackConfig

Parameter	Type	Default	Constraints	Description
tracker_type	"fasttrack"	"fasttrack"		Which backend this configuration is for. It is the tag the schema discriminates on, and a configuration naming a different backend than the run's tracker is refused.
track_high_thresh	number	0.25		The confidence a detection must reach to enter the first association pass. Raising it produces cleaner tracks and keeps fewer detections.
track_low_thresh	number	0.1		The confidence below which a detection is discarded. Between this and track_high_thresh a detection is kept for the second association pass, which trades recovery against drift.
new_track_thresh	number	0.25		The confidence an unmatched detection must reach to start a new track. Raising it produces fewer spurious tracks.
track_buffer	integer	30		How long a lost track stays alive before it is removed. A longer buffer survives more occlusion and risks more identity switches. [frames]
match_thresh	number	0.8		The similarity a detection and a track must reach to be associated in the first pass. Tune it with the detector's quality.
fuse_score	boolean	true		Multiply the association similarity by the detection confidence before matching, which stabilizes weak detections.
reset_velocity_offset_occ	integer	5		How far back the Kalman filter's velocity is restored from when an occlusion starts. [frames]
reset_pos_offset_occ	integer	3		How far back the Kalman filter's position is restored from when an occlusion starts. [frames]
enlarge_bbox_occ	number	1.1		The one-shot height scale applied to an occluded track's box, which widens the region searched for it.
dampen_motion_occ	number	0.5		How much of an occluded track's velocity is kept while it stays occluded, between 0 and 1.
active_occ_to_lost_thresh	integer	10		How long an active track survives continuous occlusion before it is marked lost. [frames]
occ_cover_thresh	number	0.7		The fraction of a track's area another must cover for the track to count as occluded.
occ_reappear_window	integer	40		How long a recently occluded lost track stays re-findable. [frames]
init_iou_suppress	number	0.7		The overlap with an active track at or above which a new track is not started. 1.0 starts every new track.

OcsortConfig

Parameter	Type	Default	Constraints	Description
tracker_type	"ocsort"	"ocsort"		Which backend this configuration is for. It is the tag the schema discriminates on, and a configuration naming a different backend than the run's tracker is refused.
track_high_thresh	number	0.25		The confidence a detection must reach to enter the first association pass. Raising it produces cleaner tracks and keeps fewer detections.
track_low_thresh	number	0.1		The confidence below which a detection is discarded. Between this and track_high_thresh a detection is kept for the second association pass, which runs only under use_byte.
new_track_thresh	number	0.25		The confidence an unmatched detection must reach to start a new track. Raising it produces fewer spurious tracks.
track_buffer	integer	30		How long a lost track stays alive before it is removed. A longer buffer survives more occlusion and risks more identity switches. [frames]
match_thresh	number	0.8		The similarity a detection and a track must reach to be associated in the first pass. Tune it with the detector's quality.
fuse_score	boolean	true		Multiply the association similarity by the detection confidence before matching, which stabilizes weak detections.
delta_t	integer	3		How far back the observation-centric velocity direction is measured. A longer window smooths more. [frames]
inertia	number	0.2		The weight the velocity-consistency term gets in the association cost. Raising it penalizes a direction change more.
use_byte	boolean	false		Run ByteTrack's low-confidence second association pass as well.

TracktrackConfig

Parameter	Type	Default	Constraints	Description
tracker_type	"tracktrack"	"tracktrack"		Which backend this configuration is for. It is the tag the schema discriminates on, and a configuration naming a different backend than the run's tracker is refused.
track_high_thresh	number	0.6		The confidence a detection must reach to enter the first association pass. Raising it produces cleaner tracks and keeps fewer detections.
track_low_thresh	number	0.25		The confidence below which a detection is discarded. Between this and track_high_thresh a detection is kept for the second association pass, which trades recovery against drift.
new_track_thresh	number	0.7		The score an unmatched detection must reach for track-aware initialization to start a new track from it.
track_buffer	integer	30		How long a lost track stays alive before it is removed. A longer buffer survives more occlusion and risks more identity switches. [frames]
match_thresh	number	0.7		The similarity the first iteration of the assignment accepts. Each later iteration lowers it by reduce_step.
lost_match_thr	number	0.0		The looser cost gate for rebinding a track that is still lost. 0.0 skips the relaxed second pass; a value above match_thresh suits long occlusions.
iou_weight	number	0.5		The weight the overlap distance gets in the cost matrix.
reid_weight	number	0.5		The weight the appearance cosine distance gets in the cost matrix. It falls back to the overlap distance where re-identification is off.
conf_weight	number	0.1		The weight the confidence distance gets in the cost matrix.
angle_weight	number	0.05		The weight the corner-angle distance gets in the cost matrix.
penalty_p	number	0.2		The cost penalty a low-confidence detection is charged during iterative assignment.
penalty_q	number	0.4		The cost penalty a deleted or recovered detection is charged during iterative assignment.
reduce_step	number	0.05		How much the matching threshold drops on each iteration of the assignment.
tai_thr	number	0.55		The overlap at which track-aware initialization suppresses a new track.
min_track_len	integer	3		How much history a track needs before it is confirmed. [frames]
gmc_method	"sparseOptFlow" | "orb" | "sift" | "ecc" | "none"	"sparseOptFlow"		Which estimator cancels camera motion between frames. sparseOptFlow, orb and sift run an unseeded RANSAC, so a run under one of those is not reproducible bit for bit. none constructs no estimator.
with_reid	boolean	false		Match on appearance embeddings beside motion and overlap, which costs a further model and further compute.
model	"auto"	"auto"		Which checkpoint supplies the appearance embeddings. Fixed at auto, the detector's own features: mosaic refuses every other value, because a checkpoint reaching a run identifier must be named by content digest.

extract

extract-frames

Version 0.1 · mosaic.tracking.frame_extraction.dataset_runs.ExtractFramesOp

Sample representative video frames as PNGs for annotation.

Parameter	Type	Default	Constraints	Description
method	"uniform" | "kmeans" | "list"	"uniform"		How the frames are chosen: 'uniform' spaces them evenly over the candidate range, 'kmeans' clusters the candidates by pixel content and keeps one frame per cluster, and 'list' writes exactly the frames listed in frames.
n_frames	integer | None	null		How many frames to write per camera. Required by 'uniform' and 'kmeans', and refused by 'list', whose listed frames are what is written.
frames	list of EntryFrames | None	null		The frames to write under 'list', one item per entry, and refused by the other methods. The list chooses the entries: a run covers every listed entry, narrowed by its scope. Each item's frames apply to every camera of the entry.
start_frame	integer | None	null		First frame of the range frames are chosen from, inclusive. Unset starts at the beginning of the video. Refused by 'list'.
end_frame	integer | None	null		Last frame of the range frames are chosen from, inclusive. Unset runs to the end of the video. Refused by 'list'.
candidate_step	integer	1		Stride between candidate frames within the range. A wider stride samples a long recording without decoding every frame of it.
crop	tuple of (integer, integer, integer, integer) | None	null		Crop rectangle (x, y, width, height) applied to every written frame. Unset writes the full frame.
random_state	integer	42		Seed for k-means and for breaking ties between candidates.
kmeans_resize	tuple of (integer, integer)	[64, 64]	min items 2, max items 2	Width and height a candidate frame is resized to before its pixels become the clustering feature vector. [px]
kmeans_grayscale	boolean	true		Convert a candidate frame to grayscale before flattening it into a feature vector, which clusters on layout instead of color.
kmeans_max_candidates	integer | None	5000		Cap on how many candidate frames are decoded for clustering; the stride widens to stay under it. Unset decodes every candidate in the range.
kmeans_batch_size	integer	1024		How many feature vectors one mini-batch k-means update reads.
kmeans_max_iter	integer	100		Ceiling on mini-batch k-means iterations.
kmeans_n_init	string | integer	"auto"		How many centroid seedings k-means tries before keeping the best. 'auto' leaves the count to scikit-learn.
revision	integer	0		Bump to extract a second selection under the same settings. It is the one term allowed to move the extraction identifier, and only a non-zero value enters it. Revision 0 reproduces every identifier already on disk.
parallel_workers	integer | string | None	"auto"		How many cameras are extracted at once. 'auto' reads the machine, and an integer pins the count.
parallel_mode	"thread" | "process"	"thread"		Which executor runs the cameras: 'thread' shares one process, 'process' forks, which a decoder holding the interpreter lock needs.

EntryFrames

Parameter	Type	Default	Constraints	Description
group	string	""		The entry's group; empty for a dataset with none.
sequence	string	required	min length 1	The entry's sequence.
indices	list of integer	required	min items 1	Frame indices on the entry's media axis: 0 is its first frame, and a recording in several clips counts across them in order, as its tracks' frame column does. Order and repeats do not matter.

infer

infer-localizer

Version 0.4 · mosaic.tracking.ops.infer.InferLocalizerOp

Run a trained heatmap localizer over scoped videos, bridging into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
model	string	required		The weights to predict with, as a path or as the run identifier of the training run that produced them.
conf_threshold	number	0.25		Minimum detection confidence a prediction must reach to be written.
imgsz	integer	640		Longest side a frame is resized to before the model reads it. It must match what the model was trained at. [px]
frame_step	integer	1		Stride between the frames predicted on. A wider stride covers a long recording without predicting on every frame of it.
start_frame	integer	0		First frame to predict on, inclusive.
end_frame	integer | None	null		The frame that prediction stops before. Unset runs to the end of the video.
max_frames	integer | None	null		Ceiling on how many frames are predicted on per entry. Unset predicts on the whole range.
convert_to_tracks	boolean	true		Bridge the predictions into a standardized tracks table once inference finishes, instead of leaving them in the run directory alone.
device	string	"0"		Which accelerator the model runs on, in the tool's own spelling: a GPU index, or 'cpu'. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
batch_size	integer	8		How many frames the model reads in one forward pass.
save_images	boolean	false		Write an annotated image per predicted frame beside the predictions, which is for inspecting a model rather than for any consumer downstream.
num_classes	integer	4		How many output heatmap channels the localizer network has. Must match the architecture the referenced model was trained with.
initial_channels	integer	32		Base channel width of the localizer network. Must match the architecture the referenced model was trained with.
thresholds	number	0.5		Minimum confidence a detected peak must reach, applied to every class.

infer-points

Version 0.5 · mosaic.tracking.ops.infer.InferPointsOp

Run a trained POLO point model over scoped videos, bridging into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
model	string	required		The weights to predict with, as a path or as the run identifier of the training run that produced them.
conf_threshold	number	0.25		Minimum detection confidence a prediction must reach to be written.
imgsz	integer	640		Longest side a frame is resized to before the model reads it. It must match what the model was trained at. [px]
frame_step	integer	1		Stride between the frames predicted on. A wider stride covers a long recording without predicting on every frame of it.
start_frame	integer	0		First frame to predict on, inclusive.
end_frame	integer | None	null		The frame that prediction stops before. Unset runs to the end of the video.
max_frames	integer | None	null		Ceiling on how many frames are predicted on per entry. Unset predicts on the whole range.
convert_to_tracks	boolean	true		Bridge the predictions into a standardized tracks table once inference finishes, instead of leaving them in the run directory alone.
device	string	"0"		Which accelerator the model runs on, in the tool's own spelling: a GPU index, or 'cpu'. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
batch_size	integer	8		How many frames the model reads in one forward pass.
save_images	boolean	false		Write an annotated image per predicted frame beside the predictions, which is for inspecting a model rather than for any consumer downstream.
max_det	integer	300	> 0	The most detections kept from one frame.
agnostic_nms	boolean	false		Suppress overlapping detections across classes instead of within each one.
precision	"fp32" | "fp16"	"fp32"		The numeric precision inference runs at. fp16 halves the memory a batch needs and can move a detection across a threshold.
dor	number | None	null		Distance-over-radius threshold of POLO's point suppression. A point whose distance to a higher-scoring point, divided by its radius, is below it is dropped. Unset uses the threshold the checkpoint was trained with, or POLO's 0.3 for a checkpoint that records none.

infer-pose

Version 0.5 · mosaic.tracking.ops.infer.InferPoseOp

Run a trained YOLO pose model over scoped videos, bridging into tracks/.

Parameter	Type	Default	Constraints	Description
media	string	""		The run id of a preprocess media variant to read in place of the entry's original media. The tool reads that derived video, and its tracks are published in the entry's own pixels and frames. Empty reads the original recording from media_raw. A frame window cannot be combined with it. The variant's trim and decimate steps set the range.
model	string	required		The weights to predict with, as a path or as the run identifier of the training run that produced them.
conf_threshold	number	0.25		Minimum detection confidence a prediction must reach to be written.
imgsz	integer	640		Longest side a frame is resized to before the model reads it. It must match what the model was trained at. [px]
frame_step	integer	1		Stride between the frames predicted on. A wider stride covers a long recording without predicting on every frame of it.
start_frame	integer	0		First frame to predict on, inclusive.
end_frame	integer | None	null		The frame that prediction stops before. Unset runs to the end of the video.
max_frames	integer | None	null		Ceiling on how many frames are predicted on per entry. Unset predicts on the whole range.
convert_to_tracks	boolean	true		Bridge the predictions into a standardized tracks table once inference finishes, instead of leaving them in the run directory alone.
device	string	"0"		Which accelerator the model runs on, in the tool's own spelling: a GPU index, or 'cpu'. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
batch_size	integer	8		How many frames the model reads in one forward pass.
save_images	boolean	false		Write an annotated image per predicted frame beside the predictions, which is for inspecting a model rather than for any consumer downstream.
max_det	integer	300	> 0	The most detections kept from one frame.
agnostic_nms	boolean	false		Suppress overlapping detections across classes instead of within each one.
precision	"fp32" | "fp16"	"fp32"		The numeric precision inference runs at. fp16 halves the memory a batch needs and can move a detection across a threshold.
iou	number	0.7	>= 0.0, <= 1.0	The NMS IoU threshold for suppressing overlapping detections.

train

train-litpose

Version 0.1 · mosaic.tracking.ops.train_litpose.TrainLitposeOp · resource class gpu

Train a Lightning Pose model, registering the directory it produces.

Parameter	Type	Default	Constraints	Description
project	string	required		A Lightning Pose project directory, written with the labeled data to train on. Its config.yaml supplies only the data half of the training configuration.
base_config	string	""		The complete Lightning Pose config to train from, dataset-relative or absolute. Unset uses the template config included with mosaic. The project's own config.yaml supplies the data half and is merged over it.
base_model	string	""		Weights to fine-tune from, as a path or as the run id of the training op that produced them. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
model_type	"heatmap" | "heatmap_mhcrnn" | "regression" | "heatmap_multiview_transformer"	"heatmap"		Which prediction head trains. heatmap_mhcrnn adds temporal context over five frames. The multiview transformer is for synchronized cameras.
backbone	string	"resnet50_animal_ap10k"		The feature extractor. Defaults to a ResNet-50 pretrained on animal pose rather than ImageNet.
max_epochs	integer	300		How long the model trains at most. [epochs]
litpose_overrides	object | None	null		Hydra key=value overrides applied last, over model_type, backbone and max_epochs as well as anything else Lightning Pose exposes with no field here. A key set here wins over base_model where they would set the same key. The data-loader worker count is refused here: set num_workers, which leaves the run identity alone.
device	string	"auto"		Which CUDA devices train the model, as a comma-separated list of indices. auto takes whatever Lightning Pose finds. There is no cpu setting: Lightning Pose fixes its trainer's accelerator to gpu. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
idle_timeout	number	1800		How long the training subprocess may go without output before it is killed. A generous default, because an epoch on a large set is slow and a watchdog must not mistake slow for dead. [s]
max_runtime	number | None	null		Absolute wall-clock ceiling for the training run. Unset leaves the ceiling to whatever queue submitted the run, and idle_timeout still applies. [s]
num_workers	integer | None	null		Worker processes loading training data. Throughput only: excluded from the run identity, so changing it never retrains a model. Unset leaves the tool's own default.

train-localizer

Version 0.1 · mosaic.tracking.ops.train.TrainLocalizerOp

Train the heatmap localizer, registering the directory it produces.

Parameter	Type	Default	Constraints	Description
dataset_dir	string	required		The directory convert_coco_localizer writes its train and valid patch sets into.
base_model	string	""		Weights to fine-tune from, as a path or as the run id of the training op that produced them. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
num_classes	integer	4		The number of output heatmap channels.
initial_channels	integer	32		The base channel width of the localizer network.
freeze_encoder	boolean	false		Freeze every layer except the 1x1 output head. Useful when fine-tuning on a small dataset.
epochs	integer	200		How long the model trains at most. [epochs]
lr	number	0.001		The initial Adam learning rate.
early_stopping_patience	integer	20		How long training continues without validation-loss improvement before stopping early. [epochs]
augment	boolean	true		Apply the light augmentation preset -- flip and rotation -- during training. False applies none.
seed	integer	42		The random seed for the training run.
device	string	"0"		Which accelerator trains the model: a GPU index, or cpu. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
batch_size	integer	128		How many training patches the model reads in one forward pass.

train-points

Version 0.2 · mosaic.tracking.ops.train.TrainPointsOp

Train a POLO point-detection model, registering the directory it produces.

Parameter	Type	Default	Constraints	Description
data	string	required		Path to the data.yaml declaring the training dataset: its classes, per-class radii and splits.
model	string	"polo26n.yaml"		What training starts from: a model config, a bare asset name Ultralytics resolves itself, or a path to weights. base_model overrides it, and a resume overrides both with this run's last checkpoint.
base_model	string	""		Weights to fine-tune from, as a path or as the run id of the training op that produced them. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
epochs	integer	300		How long the model trains at most. [epochs]
imgsz	integer	640		The side a training image is resized to before the model reads it. [px]
patience	integer	50		How long training continues without improvement before stopping early. [epochs]
resume	boolean	false		Continue training from this run's own last checkpoint instead of starting from the given weights.
augmentation	string | object | None	null		A preset name, or a dict with a preset key to start from one and override, or without one to replace the augmentation set outright. A resumed run applies no augmentation.
train_overrides	object | None	null		Extra keyword arguments forwarded verbatim to yolo.train. Keys that would collide with a typed field or with an argument the op supplies are refused.
device	string	"0"		Which accelerator trains the model: a GPU index, or cpu. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
batch	integer	16		How many training images the model reads in one forward pass.
workers	integer | None	null		Worker processes loading training data. Throughput only: excluded from the run identity, so changing it never retrains a model. Unset leaves the tool's own default.
loc	number	5.0		The localization loss weight, a POLO train keyword.
loc_loss	string	"mse"		Which localization loss POLO minimizes.
dor	number	0.8		Distance-over-radius threshold of the point suppression POLO's validator applies during training. The checkpoint records it, and infer-points predicts with it unless the run sets its own.
backend	string	"polo"		The point-detection backend. polo is the only value the op accepts.

train-pose

Version 0.2 · mosaic.tracking.ops.train.TrainPoseOp

Train a YOLO pose model, registering the directory it produces.

Parameter	Type	Default	Constraints	Description
data	string	required		Path to the data.yaml declaring the training dataset: its classes, keypoint shape and splits.
model	string	"yolo11n-pose.pt"		What training starts from: a model config, a bare asset name Ultralytics resolves itself, or a path to weights. base_model overrides it, and a resume overrides both with this run's last checkpoint.
base_model	string	""		Weights to fine-tune from, as a path or as the run id of the training op that produced them. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
epochs	integer	300		How long the model trains at most. [epochs]
imgsz	integer	640		The side a training image is resized to before the model reads it. [px]
patience	integer	50		How long training continues without improvement before stopping early. [epochs]
resume	boolean	false		Continue training from this run's own last checkpoint instead of starting from the given weights.
augmentation	string | object | None	null		A preset name, or a dict with a preset key to start from one and override, or without one to replace the augmentation set outright. A resumed run applies no augmentation.
train_overrides	object | None	null		Extra keyword arguments forwarded verbatim to yolo.train. Keys that would collide with a typed field or with an argument the op supplies are refused.
device	string	"0"		Which accelerator trains the model: a GPU index, or cpu. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
batch	integer	16		How many training images the model reads in one forward pass.
workers	integer | None	null		Worker processes loading training data. Throughput only: excluded from the run identity, so changing it never retrains a model. Unset leaves the tool's own default.

train-sleap

Version 0.2 · mosaic.tracking.ops.train_sleap.TrainSleapOp · resource class gpu

Train a SLEAP model, registering the directory it produces.

Parameter	Type	Default	Constraints	Description
labels	string	required		The .slp file to train on.
base_model	string	""		Weights to fine-tune from, as a path or as the run id of the training op that produced them. Identity records the training run id when the reference is one, and the weights' content digest when it is a bare path.
head	"single_instance" | "centroid" | "centered_instance" | "bottomup" | "multi_class_bottomup" | "multi_class_topdown"	"centered_instance"		Which task the network is trained for. centroid and centered_instance are the two halves of a top-down model, trained separately and passed to inference as a pair. The multi_class_ heads add identity classification, so they need labels that carry it: a .slp whose instances have no track trains one of them against no classes at all, which succeeds and produces a model that learned nothing.
backbone	"unet" | "convnext" | "swint"	"unet"		The feature extractor architecture, independent of the head.
max_epochs	integer	200		How long the model trains at most. [epochs]
seed	integer	42		Seeds sleap-nn's initialization.
validation_fraction	number	0.1		Fraction of labels held out for validation, when no separate validation file is given.
sleap_overrides	object | None	null		Hydra key=value overrides applied over the generated config, for anything sleap-nn exposes with no field here. A key the generated config does not carry is appended for you, so it needs no + prefix; a key written with an explicit + or ~ is passed through as written. A key set here wins over base_model and device where they would set the same key. The data-loader worker count is refused here: set num_workers, which leaves the run identity alone.
device	string	"auto"		Which accelerator trains the model. auto leaves the choice to sleap-nn; cpu, gpu and mps each name a family; a comma-separated list of CUDA indices such as 0 or 0,1 names devices within the gpu family. A GPU index counts within the GPUs the run may use: under a queue worker pinned to one GPU, or a cluster allocation, 0 is the first GPU it was given.
idle_timeout	number	1800		How long the training subprocess may go without output before it is killed. A generous default, because an epoch on a large set is slow and a watchdog must not mistake slow for dead. [s]
max_runtime	number | None	null		Absolute wall-clock ceiling for the training run. Unset leaves the ceiling to whatever queue submitted the run, and idle_timeout still applies. [s]
num_workers	integer | None	null		Worker processes loading training data. Throughput only: excluded from the run identity, so changing it never retrains a model. Unset leaves the tool's own default. Sets both the training and the validation loader. sleap-nn's own caveat: under its default data pipeline, workers above 0 can fail on labels that read frames from video, which does not pickle.

Media

preprocess

preprocess

Version 0.1 · mosaic.core.pipeline.preprocess.PreprocessOp · resource class heavy

Write one media variant file per scoped entry.

Parameter	Type	Default	Constraints	Description
steps	list of (CropStep | MaskStep | TrimStep | DecimateStep | GrayscaleStep | AdjustStep | ClaheStep)	required		The steps applied to each frame, in order. Every position and frame number that a step names is in the entry media's pixels and frames, whatever the step's position in the list. Empty only with codec 'h264', which copies every frame of the source into H.264.
media	string	""		The run identifier of a variant to read in place of the entry media. These steps then apply after that variant's. Empty reads the entry media.
fps	number | None	null		The frame rate that the output file is labeled at, which sets its frames' timestamps and therefore the time base of a tool's per-second thresholds. Unset, it is the rate that the kept frames were recorded at: the first clip's rate divided by the decimation. Under any other label the tracker's per-second columns are scaled by the label instead of the recording rate, and they are dropped when its table is mapped back. [fps]
codec	"av1" | "h264"	"av1"		The output codec. 'h264' is a fallback for a decoder without AV1 support, such as the DALI 2.3 video reader in Lightning Pose. It needs an ffmpeg built with libx264.
quality	integer | None	null		The encoder's constant rate factor, on the chosen codec's scale, where lower is better: SVT-AV1 CRF from 0 to 63 for 'av1', x264 CRF from 0 to 51 for 'h264'. Unset uses mosaic's default, 14 for AV1 and 16 for H.264.
allow_hardware	boolean	false		Permit the av1_nvenc hardware encoder where the machine offers a usable one. The encode falls back to the CPU encoder where it does not, and an 'h264' variant always encodes on the CPU. As a permission, it leaves the variant's run identifier unchanged.

AdjustStep

Parameter	Type	Default	Constraints	Description
step	"adjust"	"adjust"		The step's name, which selects this step in a list of steps.
brightness	number	0.0	>= -255.0, <= 255.0	The level added to every scaled pixel value, from -255 to 255. Zero leaves the values unchanged.
contrast	number	1.0	> 0.0	The factor that every pixel value is scaled by before the brightness is added. One leaves the contrast unchanged.
gamma	number	1.0	> 0.0	The gamma applied after brightness and contrast, as 255 * (v / 255) ** (1 / gamma). Above one brightens the mid-tones, and one leaves them unchanged.

ClaheStep

Parameter	Type	Default	Constraints	Description
step	"clahe"	"clahe"		The step's name, which selects this step in a list of steps.
clip_limit	number	2.0	> 0.0	The contrast limit of the equalization. Higher equalizes harder and amplifies more noise.
tile_grid_size	integer	8	>= 1	The number of tiles along each side of the image. Each tile is equalized on a histogram of its pixels alone.

CropStep

Parameter	Type	Default	Constraints	Description
step	"crop"	"crop"		The step's name, which selects this step in a list of steps.
x	integer	required	>= 0	The source column of the rectangle's left edge. [px]
y	integer	required	>= 0	The source row of the rectangle's top edge. [px]
width	integer	required	>= 4	The rectangle's width. Even, because the variant is encoded as yuv420p, and at least the AV1 encoder's minimum. [px]
height	integer	required	>= 4	The rectangle's height. Even, because the variant is encoded as yuv420p, and at least the AV1 encoder's minimum. [px]

DecimateStep

Parameter	Type	Default	Constraints	Description
step	"decimate"	"decimate"		The step's name, which selects this step in a list of steps.
every	integer	required	>= 2	Keep one frame in this many, starting with the first.

GrayscaleStep

Parameter	Type	Default	Constraints	Description
step	"grayscale"	"grayscale"		The step's name, which selects this step in a list of steps.

MaskStep

Parameter	Type	Default	Constraints	Description
step	"mask"	"mask"		The step's name, which selects this step in a list of steps.
polygon	list of tuple of (integer, integer)	required	min items 3	The polygon's vertices as (x, y) source coordinates, at least three. It may extend outside the image but may not lie wholly outside it. [px]
keep	boolean	true		Keep the pixels inside the polygon and black out the rest. False blacks out the inside instead.

TrimStep

Parameter	Type	Default	Constraints	Description
step	"trim"	"trim"		The step's name, which selects this step in a list of steps.
start	integer	required	>= 0	The first source frame of the range kept.
stop	integer	required		The source frame that the kept range stops before.

transcode

export-joined

Version 0.2 · mosaic.core.pipeline.joined_export.JoinedExportOp · resource class heavy

Join one entry's clips into the single video an external tool opens.

Parameter	Type	Default	Constraints	Description
reencode	boolean	false		Normalise clips whose stream profile differs from the rest before joining them, instead of refusing. Off by default: it re-encodes, which costs time and a generation of quality, so it is opted into rather than inherited.

export-store

Version 0.2 · mosaic.core.pipeline.store_export.StoreExportOp · resource class heavy

Export one entry's imgstore recordings as plain video and link them.

Parameter	Type	Default	Constraints	Description
av1_crf	integer	14		AV1 constant-rate factor, 0 (lossless) to 63, defaulting to what an analysis transcode encodes at. Named for its scale because this writer encodes AV1, whose crf argument is a deprecated shim in x264's scale.

transcode

Version 0.2 · mosaic.core.pipeline.transcode.TranscodeOp

Transcode the scoped entries' originals for a target, linking both ways.

Parameter	Type	Default	Constraints	Description
target	"analysis" | "playback"	"analysis"		Which derivative to write: 'analysis' is the one a tool decodes frame by frame, 'playback' the one a browser streams.
allow_hardware	boolean	false		Permit a hardware encoder where the machine offers a usable one. The encode falls back to the CPU encoder where it does not.