Working with Other Programs - prnvkhndlwl/Kinetrace GitHub Wiki

Kinetrace can take over from another program at any stage, or hand its work on. Every conversion below is done by the program — pixel conventions (0- or 1-based, y down or up), axis handedness, transposed MATLAB matrices — and the calibration files are checked against Kinetrace's own projection before they are written. The same conversions are in the menus and in a command-line converter for scripts.

Two things the calibration export tells you about when they happen: coefficients from easyWand or DLTdv usually describe a mirrored (left-handed) world, which K + R/t formats cannot hold, so the exported world is Kinetrace's mirrored in Z (and 3D points exported with it are mirrored the same way); and DLTdv's own lens correction is not an OpenCV model, so one is fitted to it and its largest error is named. 3D → Set World Axes… (an origin and +X / +Y from three landmarks, +Z by the right-hand rule) gives such a calibration a right-handed world, so nothing is mirrored on export. Exported 3D points are always in the same world as the exported cameras. A DLTdv export (xypts or xyzpts) is only the points file and its quoted _pointnames.csv. Otherwise the exported cameras agree with Kinetrace's to about a thousandth of a pixel.

1. Open one video per camera (File → Open Folder of Videos… for a folder of them, or File → Open Video, then ＋ Add video in the CAMERAS panel), line the cameras up (3D → Sync → Sync Cameras), and calibrate (3D → Calibrate → Calibrate a Lens for wide-angle cameras, then 3D → Calibrate → Calibrate Cameras with a Wand).
2. File → Export → Calibration… and tick the program you use next: Anipose's calibration.toml goes in Anipose's calibration folder (rename it calibration.toml); the OpenCV files load with cv2.FileStorage; the MATLAB file with load; the Blender script runs in Blender's Scripting tab; DLTdv8 and easyWand take the dltCoefs.csv.

For scripts and pipelines, with the environment's Python (.venv\Scripts\python on Windows, .venv/bin/python on Linux and macOS):

python -m kinetrace.convert info     FILE
python -m kinetrace.convert check    FILE          # exit 0 clean, 1 warnings, 2 errors
python -m kinetrace.convert calibration IN OUT [--to anipose|opencv-yaml|opencv-json|matlab|blender|dlt|kcal]
                                             [--size WxH ...] [--pixels matlab|bottom-left|opencv]
                                             (--pixels is needed for a dltCoefs.csv or easyWand file)
python -m kinetrace.convert tracks   IN OUT (--video V | --size WxH --frames N)
                                             [--to dlc|dltdv|dltdv-bottomleft|wide|sparse|kinetrace]
python -m kinetrace.convert points3d IN OUT [--to kinetrace|dltdv|anipose]
                                             [--calibration CAL [--size WxH ...] [--pixels P]]
python -m kinetrace.convert masks    PROJECT OUT [--camera NAME] [--animal NAME] [--to json|png]
                                             (--animal is needed when the camera has several animals)
python -m kinetrace.convert offsets  PROJECT OUT
python -m kinetrace.convert import   PROJECT --tracks FILE [--camera NAME] [--out NEW.kinetrace]
python -m kinetrace.convert pack     PROJECT OUT.kinetrace         (a project folder -> one file)
python -m kinetrace.convert unpack   FILE.kinetrace FOLDER.kinetrace (one file -> a project folder)
python -m kinetrace.convert previous PROJECT                       (back one save)

tracks --camera K refuses an all-cameras file for K above 1 (its rows are frames of the reference camera: use import, which maps them through the project's offsets); points3d --calibration writes the 3D points in the same world as the cameras calibration exports from that file. The output format follows --to, or else the output's name (.toml, .yml, .mat, .kinetrace …). A dltCoefs.csv records no picture sizes: give --size once for all cameras or once per camera. import writes the project folder back, only the files that change, with the previous save kept in its .history/ (previous goes back to it; a single-file project keeps its previous version as .bak; use --out for a new project, which gets an identity of its own); do not run it on a project that is open in Kinetrace. New point names land in every camera's list, with data only in the camera imported into — the same shared list the app keeps.

A .kinetrace project is a folder of CSV / JSON (and .npy for silhouette outlines and body poses) — one CSV per landmark and camera — readable and writable without Kinetrace: open cameras/<camera>/tracks/<landmark>.csv in any program. Every file and column is described in docs/FORMAT.md, with a Python reader and a three-file project you can write by hand. For DeepLabCut, DLTdv and MATLAB's own formats, File → Export → Keep Exports Up to Date… writes them into the project's exports/ folder at every save.

A calibration is converted to Kinetrace's own pixels once, when it is imported. The dltCoefs.csv and MATLAB exports are in DLTdv8's convention (first pixel 1, y down), whatever the imported file used: a file counted from the bottom edge comes back top-left. A dltCoefs.csv or easyWand file does not say which row of this table it came from, so the import asks (the command line wants --pixels).

← Export formats  |  Home  |  Projects & autosave →