Skip to content

Scripts and agents

Everything here works from a script or an AI agent that can run commands. Three ways, by what should be seen:

Way Window Use it for
tracell track none Recorded videos, one or many, on a PC or a server
tracell live none An AutoTrack session on the camera, unattended
tracell gui the open TraCell window Working in the window a person watches: the person sees each step and can take over

All three read the presets the app saves (File > Save) and write the same result files. Each command's --help is complete; tracell reference settings|columns|files|exit-codes --format json gives the settings, the columns, the files and the exit codes as data.

Rules for a program

  • Read stdout as JSON. With --json, track and live print one JSON object per line ("event": "video", "partition", "finished", "error"); tracell gui always prints JSON. Progress and messages go to stderr.
  • Check the exit code. 0 done, 1 failed, 2 wrong command line, 3 no TraCell window, 4 the window is busy, 5 gui wait timed out (all codes). On 4, run tracell gui wait and send the command again.
  • Stop with Ctrl+C or SIGTERM. track and live keep what was tracked and end with 0. In the window, tracell gui stop.
  • Name settings by their dotted names (model.tracker.search_range); tracell reference settings NAME says what one means, its unit and the values it allows.
  • Never compare cell IDs between runs: they can differ. Compare tracks.

Track recorded videos

tracell track videos/*.avi --preset p.json --out results --parallel --json

{"event": "video", "video": "videos/run1.avi", "cells": 267, "points": 9369, "written": ["results/run1_tracks.csv", "results/run1_cells.csv", "results/run1_settings.json"]}
{"event": "finished", "ok": true, "stopped": false, "videos": 1, "failed": 0}

A live session

tracell live --preset p.json --cells 2000 --crops with_background --json

One "partition" line arrives per partition while the camera records; each names its table in the session folder, which can be read at once. --virtual-camera video.avi replays a video instead of the camera, to try a session first.

Drive the open window

The person at the microscope keeps the TraCell window open; the agent works in it with tracell gui and the window shows every step. The window's own locks apply: while a job or a live session runs, only stop, reading and opening tool windows are accepted (details).

tracell gui status                         # what is open, what runs
tracell gui open run3.avi
tracell gui get view.tracker               # the tracker settings now
tracell gui set view.tracker.search_range=12 view.tracker.memory=3
tracell gui frame 1200; tracell gui screenshot check.png   # look at the picture
tracell gui track --frames 0 4000
tracell gui wait --timeout 600             # then the status: tracked_cells, message
tracell gui export results --format csv; tracell gui wait
tracell gui status                         # last_export lists the files

A live session in the window, with the settings the Live Tracking window shows:

tracell gui set model.live.stop_criteria=cells model.live.cell_limit=1000
tracell gui autotrack                      # returns the session folder
tracell gui status                         # live_partitions, running
tracell gui wait                           # until the stop rule ends it, or:
tracell gui stop

Anything else in the window: tracell gui controls lists every menu item and visible button and whether it is enabled now; tracell gui menu 'MENU > ITEM' and tracell gui press WINDOW BUTTON press them.

For crawlers and agents

/llms.txt lists these pages in one file.