Skip to content

Settings reference

A preset is the JSON file File > Save writes. Its settings are named by their keys joined by dots, as tracell gui get and tracell gui set use them. The same list is in the program: tracell reference settings [NAME] (add --format json for scripts).

The groups adjustment, chopper, contour, mask, tracker are held twice: model.G is what tracking uses and view.G what the tool window shows. TraCell keeps them equal, and tracell gui set changes both whichever you name. tracell track reads model.*, and its frame range from view.chopper.

format

Setting Type Default Unit Allowed Meaning
format int 1 1 Version of the preset format. Written by TraCell; do not change it.

model

What tracking and AutoTrack use. tracell track and tracell live read this part of a preset.

model.adjustment

Setting Type Default Unit Allowed Meaning
model.adjustment.alpha float 1.0 0 to 10 Contrast: every gray value is multiplied by it (Tools > Adjustment).
model.adjustment.beta int 0 gray levels -200 to 200 Brightness: added to every gray value after the contrast.
model.adjustment.gamma float 1.0 0.01 to 5 Gamma of the picture after contrast and brightness; 1 changes nothing.
model.adjustment.tone_enabled bool true true, false Apply the tone-mapping curve. false keeps its points but skips it.
model.adjustment.tone_points list [] gray levels [[in, out], ...], 0 to 255 Points of the tone-mapping curve from input to output gray value; [] for none.

model.chopper

Setting Type Default Unit Allowed Meaning
model.chopper.max_frame int 1 frames min_frame to the last frame Last frame of that range (included).
model.chopper.min_frame int 0 frames 0 to the last frame First frame of the range Track and tracell track use.

model.contour

Setting Type Default Unit Allowed Meaning
model.contour.color list [255, 0, 0, 1] [red, green, blue, alpha], 0 to 255 Color of drawn contours (display only).
model.contour.display bool false true, false Draw the contours on the video (Tools > Contours > Show Contours).
model.contour.max_area int 50 pixels² above min_area Largest mask region that counts as a cell; lower it to leave out clumps.
model.contour.min_area int 0 pixels² 0 or more Smallest mask region that counts as a cell; raise it to leave out debris.
model.contour.thickness int 1 pixels 1 to 5 Line width of drawn contours (display only).

model.live

Setting Type Default Unit Allowed Meaning
model.live.background_frames int 0 frames 0 to 100000 Frames fed once at the start of a session to learn the background; 0 = the method's usual learning.
model.live.camera_partitions int 2 1 or more Partitions of the camera's memory; 2 or more lets it record one while the last is read out.
model.live.camera_port int 52731 1024 to 65535 Port TraCell serves a video played as the camera on.
model.live.camera_service_port int 52740 1024 to 65535 Port of the camera service on this computer (Edit > Preferences sets it).
model.live.capture_keep text "before" before, around, after What a Capture keeps of the camera's memory, relative to the press.
model.live.cell_limit int 1000 cells 1 or more With stop_criteria cells: complete cells to track.
model.live.cell_velocity_mm_s float 0.0 mm/s 0 or more; 0 = not given Typical cell velocity (same use).
model.live.channel_length_um float 0.0 µm 0 or more; 0 = not given Length of the channel in view (for the partition advice and min_track_share).
model.live.chunk_frames int 16 frames 1 or more Frames read from the camera per chunk.
model.live.crop_size int 32 pixels 4 to 512 Side of the square crops.
model.live.edr int 0 µs 0 or more Extreme dynamic range exposure, for cameras that have it; 0 = off.
model.live.exposure int 100 µs 0 or more Camera exposure time.
model.live.features list [] [{"kind": ..., "params": {...}}] Measurements added as table columns from the crops: crop_stats, or http (an External server; see the guide's External server page).
model.live.fps int 100 frames per second 1 or more Camera frame rate. The camera may round it up to its minimum.
model.live.frames_per_partition int 10 frames 1 or more Frames recorded before each read-out and tracking.
model.live.goals list [] [{"kind": ..., "params": {...}}] Stop goals as data (kinds: cells, frames, partitions, time); [] = use stop_criteria.
model.live.goals_mode text "all" all, any With goals: stop when all goals are reached, or any.
model.live.height int 800 pixels 1 or more Camera resolution, height.
model.live.length_unit text "µm" µm, mm, cm Unit the window shows the channel length in (the value stays in µm).
model.live.min_track_share float 0.5 0 to below 1 A track shorter than this share of the crossing time is not counted as a cell; 0 = every uncut track counts.
model.live.mock_video_path text "data/cells.avi" a video file The video replayed as the camera.
model.live.partition_limit int 1 partitions 1 or more With stop_criteria partitions: partitions to track.
model.live.partition_share float 0.8 0, 0.5, 0.8, 0.9 Share of cells a partition should track from entering to leaving, used to suggest frames_per_partition; 0 = typed.
model.live.ram_budget_mb int 1024 MB 0 or more Raw frames kept in RAM for playback; older partitions give theirs up.
model.live.ring_slots int 3 2 or more Shared-memory buffers between camera service and TraCell.
model.live.save_crops text "none" none, with_background, without_background, both Save a small picture of every tracked cell in the session folder.
model.live.save_session bool true true Write the session folder. Always on.
model.live.session_root text "" a folder, or "" Where session folders are made; "" = 'TraCell Sessions' in the home folder.
model.live.stop_criteria text "cells" cells, frames, partitions, time Which limit ends a session.
model.live.time_limit_s float 600.0 s above 0 With stop_criteria time: seconds since the session started.
model.live.total_frame_limit int 1000 frames 1 or more With stop_criteria frames: frames to track.
model.live.use_mock_source bool false true, false Replay mock_video_path instead of the camera (tracell live --virtual-camera).
model.live.velocity_unit text "mm/s" µm/s, mm/s, cm/s, m/s Unit the window shows the velocity in (stays in mm/s).
model.live.width int 1280 pixels 1 or more Camera resolution, width.

model.mask

Setting Type Default Unit Allowed Meaning
model.mask.history int 100 frames 1 to 9999 MOG2 and KNN: how many recent frames the background is learned from.
model.mask.method text "MOG2" MOG2, KNN, onnx, service, or a script's method How cells are told from the background. MOG2 and KNN learn the background from the last frames; onnx runs a segmentation model; service asks a mask service of yours.
model.mask.params dict {} {name: value} Parameters of a method other than MOG2 and KNN, as its form names them (an ONNX file and threshold, a service port, a script's own).
model.mask.script text "" a file path, or "" Python file the method was loaded from. A preset that names one runs it when loaded: use such presets only from people you trust.
model.mask.shadows bool false true, false MOG2 and KNN: detect shadows and leave them out of the mask.
model.mask.threshold int 50 1 to 9999 MOG2 and KNN: how different a pixel must be from the background to be a cell (MOG2: squared distance; KNN: distance).

model.region

Setting Type Default Unit Allowed Meaning
model.region.frame_rate float 0.0 frames per second 0 or more; 0 = unknown Frame rate the video was recorded at. Adds seconds columns to the tables.
model.region.pixel_size_um float 0.0 µm per pixel 0 or more; 0 = not calibrated Calibration: size of one pixel of the unscaled picture. Adds µm columns to the tables.
model.region.roi list [0, 0, 0, 0] pixels [x, y, width, height]; [0, 0, 0, 0] = whole picture Region of interest of the original picture; only it is processed and tracked.
model.region.scale float 1.0 above 0 Resize factor applied after the ROI. Coordinates in the tables are in pixels of this scaled picture.

model.tracker

Setting Type Default Unit Allowed Meaning
model.tracker.buffer_frames int 3 frames 1 to 99 Frames at the start of a range that only train the background and are not tracked.
model.tracker.length int 20 frames 1 to 9999 How many past frames of a track are drawn (display only).
model.tracker.memory int 5 frames 1 to 99 For how many frames a cell may go undetected and keep its track.
model.tracker.method text "" "", default, velocity, flow, flow_gaps, or a script's method Linking method: default = nearest position, velocity = nearest predicted position, flow = flow assignment (flow along the picture's x axis), flow_gaps = flow assignment with gap closing. "" (presets from before the choice) means velocity when velocity is true, else default.
model.tracker.script text "" a file path, or "" Python file a linking method was loaded from; runs when the preset is loaded.
model.tracker.search_range float 10.0 pixels above 0 How far a cell may move from one frame to the next. Too small breaks tracks, too large joins neighbors.
model.tracker.thickness int 2 pixels 1 to 9 Line width of drawn tracks (display only).
model.tracker.velocity bool true true, false Used only when method is "": true links by predicted position.

preferences

Edit > Preferences. Kept per user, not in presets; not reachable with tracell gui.

preferences.camera_service_port

Setting Type Default Unit Allowed Meaning
preferences.camera_service_port int 52740 1024 to 65535 Port the camera service of this computer listens on.

preferences.capture_keep

Setting Type Default Unit Allowed Meaning
preferences.capture_keep text "before" before, around, after What a Capture keeps (see model.live.capture_keep).

preferences.check_updates

Setting Type Default Unit Allowed Meaning
preferences.check_updates bool true true, false Look for a newer release at start.

preferences.recent_presets

Setting Type Default Unit Allowed Meaning
preferences.recent_presets list [] [path, ...] File > Open Recent: presets, newest first.

preferences.recent_videos

Setting Type Default Unit Allowed Meaning
preferences.recent_videos list [] [path, ...] File > Open Recent: videos, newest first.

preferences.show_start_dialog

Setting Type Default Unit Allowed Meaning
preferences.show_start_dialog bool true true, false Ask at start what the session is for.

preferences.theme

Setting Type Default Unit Allowed Meaning
preferences.theme text "system" system, light, dark Color theme.

preferences.undo_steps

Setting Type Default Unit Allowed Meaning
preferences.undo_steps int 100 0 or more How many changes Edit > Undo remembers.

preferences.working_folder

Setting Type Default Unit Allowed Meaning
preferences.working_folder text "" a folder, or "" Where file dialogs start; "" = the folder used last.

view

What the window shows and remembers: its tool windows, the frame range (view.chopper), bookmarks, notes, the export dialog and the Trajectories filters.

view.adjustment

Setting Type Default Unit Allowed Meaning
view.adjustment.alpha float 1.0 0 to 10 Contrast: every gray value is multiplied by it (Tools > Adjustment).
view.adjustment.beta int 0 gray levels -200 to 200 Brightness: added to every gray value after the contrast.
view.adjustment.gamma float 1.0 0.01 to 5 Gamma of the picture after contrast and brightness; 1 changes nothing.
view.adjustment.tone_enabled bool true true, false Apply the tone-mapping curve. false keeps its points but skips it.
view.adjustment.tone_points list [] gray levels [[in, out], ...], 0 to 255 Points of the tone-mapping curve from input to output gray value; [] for none.

view.bookmark

Setting Type Default Unit Allowed Meaning
view.bookmark.bookmarks dict {} {name: frame | [frame, partition] | [frame, partition, cell]} Saved bookmarks.

view.chopper

Setting Type Default Unit Allowed Meaning
view.chopper.max_frame int 1 frames min_frame to the last frame Last frame of that range (included).
view.chopper.min_frame int 0 frames 0 to the last frame First frame of the range Track and tracell track use.

view.contour

Setting Type Default Unit Allowed Meaning
view.contour.color list [255, 0, 0, 1] [red, green, blue, alpha], 0 to 255 Color of drawn contours (display only).
view.contour.display bool false true, false Draw the contours on the video (Tools > Contours > Show Contours).
view.contour.max_area int 50 pixels² above min_area Largest mask region that counts as a cell; lower it to leave out clumps.
view.contour.min_area int 0 pixels² 0 or more Smallest mask region that counts as a cell; raise it to leave out debris.
view.contour.thickness int 1 pixels 1 to 5 Line width of drawn contours (display only).

view.export

Setting Type Default Unit Allowed Meaning
view.export.crop_size int 32 pixels 4 to 512 Side of the exported crops.
view.export.crops text "none" none, with_background, without_background, both Export cell crops (.npz).
view.export.folder text "" a folder, or "" Where File > Export writes; "" = tracell_export next to the video.
view.export.notes_log bool true true, false Export the session-notes log.
view.export.open_folder bool true true, false Open the folder when the export is done.
view.export.preset bool true true, false Export the settings used.
view.export.summary bool true true, false Export the cell summary.
view.export.table_format text "xlsx" xlsx, csv, txt Format of the tables.
view.export.tracks bool true true, false Export the trajectory table.
view.export.video bool false true, false Export the video with traces.
view.export.video_format text "mp4" mp4, avi Format of the video.
view.export.video_fps int 30 frames per second 1 or more Frame rate of the exported video.

view.mask

Setting Type Default Unit Allowed Meaning
view.mask.history int 100 frames 1 to 9999 MOG2 and KNN: how many recent frames the background is learned from.
view.mask.method text "MOG2" MOG2, KNN, onnx, service, or a script's method How cells are told from the background. MOG2 and KNN learn the background from the last frames; onnx runs a segmentation model; service asks a mask service of yours.
view.mask.params dict {} {name: value} Parameters of a method other than MOG2 and KNN, as its form names them (an ONNX file and threshold, a service port, a script's own).
view.mask.script text "" a file path, or "" Python file the method was loaded from. A preset that names one runs it when loaded: use such presets only from people you trust.
view.mask.shadows bool false true, false MOG2 and KNN: detect shadows and leave them out of the mask.
view.mask.threshold int 50 1 to 9999 MOG2 and KNN: how different a pixel must be from the background to be a cell (MOG2: squared distance; KNN: distance).

view.notes

Setting Type Default Unit Allowed Meaning
view.notes.entries dict {} {field: value} The session notes now (Tools > Session Notes).
view.notes.log list [] [{"time": ..., "entries": {...}}] Notes logged before, oldest first.

view.tracker

Setting Type Default Unit Allowed Meaning
view.tracker.buffer_frames int 3 frames 1 to 99 Frames at the start of a range that only train the background and are not tracked.
view.tracker.length int 20 frames 1 to 9999 How many past frames of a track are drawn (display only).
view.tracker.memory int 5 frames 1 to 99 For how many frames a cell may go undetected and keep its track.
view.tracker.method text "" "", default, velocity, flow, flow_gaps, or a script's method Linking method: default = nearest position, velocity = nearest predicted position, flow = flow assignment (flow along the picture's x axis), flow_gaps = flow assignment with gap closing. "" (presets from before the choice) means velocity when velocity is true, else default.
view.tracker.script text "" a file path, or "" Python file a linking method was loaded from; runs when the preset is loaded.
view.tracker.search_range float 10.0 pixels above 0 How far a cell may move from one frame to the next. Too small breaks tracks, too large joins neighbors.
view.tracker.thickness int 2 pixels 1 to 9 Line width of drawn tracks (display only).
view.tracker.velocity bool true true, false Used only when method is "": true links by predicted position.

view.trajectory

Setting Type Default Unit Allowed Meaning
view.trajectory.filters list [] [{"column", "low", "high", "negate", "or"}] Filters of the Trajectories window, in order; low/high null = the whole range.

view.visual

Setting Type Default Unit Allowed Meaning
view.visual.fps int 30 frames per second 1 or more Playback speed in the window.
view.visual.scale float 1.0 above 0 Zoom of the picture in the window (display only).
view.visual.show_background bool true true, false false shows the video minus the learned background, plus 127.
view.visual.windows dict {} {name: [x, y, width, height]} Tool windows open when the preset was saved, and where.