Projects and Autosave - prnvkhndlwl/Kinetrace GitHub Wiki

  • One folder holds everything: name.kinetrace. File β†’ Save Project (Ctrl+S) writes every camera with its tracks, points, silhouette, events and notes, the offsets, the calibration, lens profiles, 3D results and body poses β€” and exactly how you left the program: frame, zoom, timeline zoom, the side panel, the camera you were in and every toggle. Open Project (Ctrl+Shift+O) puts you back exactly there: open the project folder and choose its kinetrace.json. Choosing an existing project folder in the save window (which opens the folder when you pick its name) asks whether to save your work as that project; the project already open is simply saved.
  • What a save touches: only the files the previous save wrote. Your own files inside the project folder (a spreadsheet made from a table, a note) are never removed, hidden files (.DS_Store, a Mac's ._… files) are ignored, a file in .history/ open in another program does not block a save, renaming a landmark in capital letters only (snout β†’ Snout) keeps its data, and after a failed first save the same name can be used again. If only the tidying after a save fails, the notice reads Saved. Not everything could be tidied up: … β€” the save itself is complete and the next save tries again.
  • Every table is a CSV you can open directly in Excel, MATLAB, R or Python β€” there is nothing to unzip: one file per landmark and camera (cameras/cam1/tracks/snout.csv: frame,x,y,confidence,visible,hand_placed,hidden, one row per frame that has data, pixel centres counted from 0), the landmarks and their settings in points.csv (with the animal each belongs to; empty = Scene), events.csv, notes.csv, each animal's silhouette per frame in silhouette/summary.csv and its clicks, skeleton and settings in segment.json, the 3D result per landmark in reconstruction/points/, JSON for the cameras, calibration and state, and NumPy .npy arrays for the silhouette outlines and body poses. The folder's README.txt says what every file is; every column is described in docs/FORMAT.md.
  • Saving is quick for large projects: a save writes only the files whose data changed (correcting one point rewrites that point's file), and opening reads binary copies kept in the folder's .cache/. Measured on 8 cameras Γ— 30 landmarks Γ— 40,000 frames: a save after an edit 1.4 s, opening 1.8 s, a first full save 4.8 s (a single zip took 21 s for each).
  • Move the whole folder and it opens anywhere, on Windows, Linux or macOS: keep the videos beside the project folder, or put them in its videos/ folder. A video that is not found where it was is looked for by name in the project folder, its videos/ folder and beside it; only then does the app ask.
  • The same picture at every frame number, on every computer. Each OS brings its own video decoder, and phone / action-camera files (edit lists, late starts) have been numbered differently by different versions β€” with the same frame count, so nothing looked wrong while every track sat a frame off. Each camera's frame fingerprint (cameras/<cam>/fingerprint/: the 8 moments where the picture changes most, a full-resolution crop of each, and the decoder that made it) is made in the background when a video is opened and saved with the project. On a computer whose decoder or video file differs, the app compares this computer's frames Nβˆ’2 … N+2 with each crop and says GOOD β€” the same pictures, or opens a window with the evidence: the saved picture beside this computer's Nβˆ’1, N, N+1, the best match marked, a difference view and one sentence (cam2 shows the picture 1 frame later than where the project was made). A video that barely moves gets cannot tell with how far a shift could move a track (GOOD < 0.5 px, OK < 2 px, POOR above). Nothing is ever re-indexed. File β†’ Check Video Frames on This Computer… runs it by hand; there you can also add a fast-moving frame to the fingerprint of a nearly still video.
  • Exact frames when jumping. Every video's seeks are checked when it opens: a file whose jumps land elsewhere than playing from the start (time stamps that skip a dropped frame moved them by a frame here) is then read forward from just before each frame β€” exact, a little slower; the app says so with a re-encode command. Files whose jumps are exact are not slowed down.
  • The project changes only when you save. The files a save replaced are kept in the folder's .history/ β€” that is the previous save; to go back to it run python -m kinetrace.convert previous name.kinetrace. A save that is cut short (the program or the computer stops while saving) is undone the next time you open the project, and the app says so.
  • Editing files by hand: close the project in Kinetrace first, and save CSVs with , separators and . decimals. Kinetrace reads an edited CSV the next time the project opens (the copy in .cache/ is used only while the CSV is unchanged); a file it cannot read is named in the message, with the row for a table. A project that stores no video path for a camera asks you to locate the video.
  • One file to send: File β†’ Export β†’ Project as One File… writes the whole project as one .kinetrace file (a zip of the same files) to e-mail or archive; File β†’ Open Project opens it. A project saved before 2026-09-29 is such a single file: its first Save offers to turn it into a folder (the file is kept as name.kinetrace.bak).
  • Files for other programs at every save: File β†’ Export β†’ Keep Exports Up to Date… ticks DLTdv8 (one file per camera, or every camera for 3D), DeepLabCut, MATLAB, a wide CSV or the 3D xyzpts; they are then written into the project's exports/ folder after every save, only when their data changed.
  • Unsaved work is kept safe every 30 s (also during tracking and at exit) in a recovery copy in the recovery folder inside the Kinetrace folder β€” never in your project. If the app or the machine dies, you lose at most 30 seconds: reopening the project (or, if it was never saved, the video) offers the unsaved work β€” opening just one camera's video of an unsaved multi-camera session brings back every camera, each on its own video. At start-up a notice says when unsaved work is waiting: click it (or File β†’ Recover Unsaved Work…) for the list.
  • The recovery copy is found by the project itself, so moving or renaming the project folder does not lose it. Unsaved work from another copy of the same project opens as a separate, unsaved copy β€” two versions are never mixed. Work you decline is moved to recovery/declined, work that cannot be read to recovery/damaged; nothing is deleted automatically. When the Kinetrace folder is read-only, recovery copies go to your user folder (%LOCALAPPDATA%\Kinetrace\recovery, ~/Library/Application Support/Kinetrace/recovery, ~/.local/share/kinetrace/recovery) and the app says so once.
  • Closing (the window's Γ— or File β†’ Quit, Ctrl+Q) with unsaved changes asks Save / Discard / Cancel and lists what changed since your last save ("cam1: P1 (positions)") β€” a click on the video with a point selected places that point, so a stray click shows up there before it is saved. Moving through the video, zooming and toggles are not changes to save: the project reopens where you left it anyway.
  • Opening another video or project (Open Video, Open Project, Open Folder of Videos, Recover Unsaved Work) with unsaved changes asks the same Save / Discard / Cancel first; Cancel opens nothing.
  • A Save that fails (a full disk, a CSV open in Excel) says so, undoes itself and leaves the previous save as it was; your work stays in the program and in its recovery copy β€” use File β†’ Save Project As… to save somewhere else.

← Working with other programs  |  Home  |  Keyboard & mouse β†’

⚠️ **GitHub.com Fallback** ⚠️