MoTrack is a planned desktop application for measuring motion in video, plotting the results, and comparing measurements with mathematical models. It aims to bring workflows and existing experiments from Open Source Physics Tracker to a C++ application for Windows, macOS, and Linux.
MoTrack is in early development. The desktop prototype opens local movies directly, records new clips from a camera, or imports Tracker .trk files with attached local movies and image sequences. It displays point-mass marks on the frame and in a table, draws imported Tracker vectors as arrows, imports saved image calibration, supports distance calibration and manual marking with undo, plots position and velocity, and exports the selected clip's measurements to CSV. See the migration plan for scope and acceptance criteria.
The full-port plan records requirements, current completion status, proposed architecture, implementation dependencies, and the tests required before claiming Tracker parity.
- C++23 and CMake, with Clang/LLVM on Windows, macOS, and Linux.
- Qt 6 Widgets for the desktop interface, Qt Multimedia for cameras, FFmpeg for video decoding and recording, and libarchive for Tracker experiment archives.
- GoogleTest and CTest, with a 90% minimum line coverage gate for handwritten production C++ from the first code change.
- TaskSmack is the reference for build presets, test organization, and LLVM coverage reporting.
- See Contributing for coding conventions and LLVM checks.
The project targets desktop workflows. Browser support is out of scope.
The application runs without Java or Swift installed. It uses native Qt, FFmpeg, libarchive, and operating-system libraries. Java is used only in development tests against the original Tracker; it is not shipped with MoTrack or used to read and write experiments.
Run the setup script after cloning. It installs the pinned toolchain that CI uses (LLVM 23, with Apple Clang as the macOS compiler) through the platform package manager, installs Qt, FFmpeg, and libarchive in the checkout's ignored .dev-tools directory (shared with its worktrees), checks the result, and builds and tests the app. Add -DryRun or --dry-run to see what it would install first.
Windows x64 (PowerShell 7 with WinGet available)
Windows includes only Windows PowerShell 5.1. If pwsh is not installed, install PowerShell 7 first, then run setup from a new PowerShell 7 window:
winget install --id Microsoft.PowerShell --exact --source winget.\tools\setup-dev.ps1 -BuildUbuntu 24.04 x64 or macOS (Bash, with Homebrew on macOS)
./tools/setup-dev.sh --buildOn Linux, MoTrack needs the PulseAudio client library (libpulse0, which setup installs) to start at
all, because Qt Multimedia links it.
Run build/dev/motrack (motrack.exe on Windows) from an activated developer shell and open tests/fixtures/image-sequence.trk or tests/fixtures/movie.trk from the File menu. Use the controls below the image to play, pause, or step through the clip. The interface follows the system's preferred languages.
Directly opened movies use quarter-turn rotation and reflection metadata. Tracker project imports retain their encoded frame coordinates.
Use File → Open images to start from an image sequence. Enter its frame rate when known, or enter zero to analyze by frame number.
Choose a point mass from the toolbar or create one in the Tracks menu. Shift-click an image to mark the selected point mass and advance one clip step. Shift+Enter repeats the previous mark. The Tracks menu also lets you rename a point mass, delete it, or remove its mark on the current frame. Use File → Export measurements to save the current marks as CSV, or File → Export plot data to save the selected series with its frame numbers, times when available, and units. Use File → Save MoTrack copy as to keep the current tracks, calibration, and media references in a .motrack project. Keep externally linked media in place when reopening it.
Open a Tracker .trz experiment archive from the same project chooser. Every experiment gets a tab, and each can be edited independently. Unopened tabs create their full editor only when selected. Saving the archive includes all member edits and retains its media and unknown files. A .motrack copy embeds the complete archive, so it can reopen after the original archive is removed. MoTrack never extracts archive members with unsafe names, such as the absolute C:/Users/… files some Tracker 6.1 exports contain, and the status bar reports them. Saved .trz files leave out the ones that only duplicate another member and keep the rest unchanged; their names can show the original author's folder or user name. Unlike Tracker, MoTrack refuses an archive whose project name is unsafe, and does not open a project that uses an unsafe-named file. macOS __MACOSX files are not shown as experiments. A project that cannot be read is reported while the others open, and the Experiments menu lists it with the reason (details).
Projects, videos, and image sequences open in the same workspace. Switch or reorder tabs without resetting their playheads or undo histories. The tab × and Hide experiment view hide a view and retain its edits; reopen it from Experiments. Close project… closes the entire source, including hidden archive members, after Save/Discard/Cancel. Closing the window resolves every project before releasing any. Save all projects saves each modified source once, including hidden experiments. Failed or canceled saves retain the unsaved records. If two modified copies share a save destination, save one under a different filename before using Save All or saving both during close. Tracker tabset files and cross-tab import remain unfinished.
File → Revert experiment… discards changes in the selected experiment after confirmation, returning to its last saved state (or its opened state before the first save). It clears that experiment's undo history and resets its view to the first clip step; other experiments keep their edits and histories. A pending save, unresolved recovery or divergent Tracker/native pair prevents reverting until a fresh paired save establishes a common state. Cancel keeps the current editor and edits. Revert does not reload externally changed files.
Choose Tracks → New vector to create an independent vector track, or select an imported vector in the toolbar. Shift-click the tail, then Shift-click the tip to create or replace its arrow on the current frame and advance one clip step. Escape cancels a pending tail; switching frames, tracks, or tools also cancels it. Shift+Enter copies the preceding arrow to the current frame. Rename track, Delete track, Delete mark on this frame, and Undo/Redo work with vectors as well as point masses. Vector tails and components are saved in image pixels and survive reopening a .motrack project. Motion plots and measurement CSV export still cover point masses; dependent vector sums are not yet supported.
New Tracker imports also keep their original XML inside the saved .motrack file, including settings MoTrack cannot yet edit. Supported imported projects can also be saved back to standard Tracker files as described below; full interchange coverage remains unfinished. Standalone movies and images still use external files. Older native projects still open; archive-backed ones need their original .trz until resaved with this version. Data discarded by earlier versions cannot be recovered. See native document compatibility.
Choose File → Capture from camera… to record a new movie experiment. Pick the camera and, where it
reports them, a resolution and frame-rate range (Camera default lets the camera choose). Record
starts and Stop ends a recording while the window previews the camera and shows the elapsed time
and frame count. After Stop, the clip is saved as a QuickTime .mov file named
Capture <date> <time>.mov in a MoTrack folder inside your Videos folder (Movies on macOS; Documents
if that folder cannot be used), then opens at once as a new experiment, as Open video does. The window
stays open for the next take. To rename or move a clip, tick Ask where to save each recording,
which offers Save as… before the clip opens. If the captures folder cannot be created or written,
MoTrack says so and asks where to save instead; Discard recording then drops the clip.
Closing the capture window or the workspace during a recording asks whether to stop and keep the clip (it is saved and opened, then the window closes) or to discard it. A clip waiting for a location asks before it is discarded. If the camera stops, disconnects or changes its frame size during a recording, the frames recorded so far are kept and saved. A failed recording or a camera error leaves the workspace unchanged.
Each frame keeps the time the camera gave it, so an uneven camera rate shows as uneven frame times; MoTrack never assigns a nominal frame rate. A camera without frame times is timed by when frames reach MoTrack, and the summary says so, along with any frames dropped because they arrived faster than they could be recorded and any unusually long frame intervals. Clips are Motion JPEG, every frame stored separately at a fixed high quality.
macOS asks for camera permission the first time (change it later in System Settings → Privacy &
Security → Camera). On Windows, a camera turned off under Settings → Privacy & security → Camera fails
to start with a message. On Linux, capture needs access to /dev/video*. Capture uses no
network connection or browser, unlike Tracker's Video → Capture…, and opens a new experiment instead
of replacing the current tab's video. Camera capture covers timing, platform
backends and the other differences from Tracker.
For a supported imported experiment, choose File → Save Tracker project…. Save a supported linked-movie, local-image or
media-free project as .trk, or a supported imported image/MOV archive as .trz. MoTrack also writes a sibling
.motrack file with the same name. Tracker opens the standard file directly. Existing archives retain
all experiment edits and supporting files, including members whose views are hidden.
For a standard Tracker input, ordinary Save updates that standard file and its MoTrack companion. Save Tracker project… can choose a different standard destination. Save MoTrack copy as… remains available; once paired saving is in use, a native-only copy does not clear outstanding Tracker changes. After reopening a native-only copy, choose Save Tracker project… to select a standard destination again. MoTrack asks before replacing an unrelated existing companion.
Saving shows a cancelable progress window. The files are replaced separately, with the Tracker file first. If interruption leaves one file unfinished, the next save offers to finish the recorded save and then write your current edits. Changes made by another program are preserved and reported as a conflict. Recovery never marks newer edits saved without writing them to both files.
This workflow currently covers audited media-free and local-image experiments, plus complete-group
updates to existing image/MOV archives. The movie writer supports mass, mark and clip-range edits in
audited constant-rate imports after timestamp indexing; its edited-file Tracker save/reopen acceptance
has passed for the pinned linked four-frame AVI and mixed-tab MOV archive cases. Later revisions require
their own CI and review. Archived AVI output is refused because pinned Tracker cannot reopen it;
the original case and compatibility restriction are tracked in #140.
Existing fixed, varying or partly fixed movie calibration can retain axes, distance-scale and length-label
edits through linked saves, MOV archives and paired saving, while preserving its existing fixed settings.
Movie timing, calibration fixed-state changes and track-identity edits, broader movie containers, filters and broader settings remain unfinished. An unsupported export is refused; save a MoTrack copy to retain work.
Image experiments can retain Clip Settings changes to the starting frame, ending frame and frame
interval in linked .trk files, existing image archives and portable image exports. All source images
and marks remain available, including those outside the selected clip; image timing stays unchanged.
Audited linked movies and archived MOV files also retain Clip Settings range and interval edits after indexing. The complete
movie and all measurements stay available; source frame numbers and numeric timing are unchanged.
The format guide records the exact supported edits and compatibility evidence.
For a supported imported image or indexed constant-rate MOV experiment, choose File → Export portable archive…
and save as .trz. MoTrack copies the experiment and its complete linked media without conversion into
one file that can be moved and opened in Tracker. The current project keeps its original save destinations, unsaved edits and undo
history; exporting a copy does not replace ordinary Save or create a companion automatically.
Export runs in the background with a Cancel button. Missing media files are named in the error message, and failures or cancellation before replacement keep an existing archive intact. This command currently supports audited local-image schemas and linked MOV mass/mark/clip-range and existing calibration edits described in the format guide. The entire movie is retained, including frames outside the selected clip. Other movie containers, arbitrary supporting documents and newly created standalone media projects remain unfinished.
Choose position, velocity, speed, acceleration, momentum, or kinetic energy above the plot. Set the selected point mass’s value in the Tracks menu. Select a plotted point to jump to its video frame. Enable Linear fit to see the slope, intercept, and R² for the plotted samples. Position uses the frame number when the project has no known timebase. Derived quantities use frame timestamps or saved image-sequence timing, and are left blank at the clip edges and across gaps in the marks. Velocity and acceleration use Tracker's default Finite Difference algorithm: velocity from the neighbouring steps, and acceleration from Tracker's five-point estimate, so acceleration is blank within two steps of a clip edge or gap. When a movie's frame times are unevenly spaced, MoTrack still uses its earlier estimates that account for the spacing, so it differs from Tracker. They are exact when the timestamps are the true capture times of variable-frame-rate video. But they are wrong for constant-rate video with coarse timestamps, such as the 1 ms timestamps of Matroska/WebM files. There, for an object moving steadily at 2 m/s, they report up to 1.8 m/s² of acceleration at 30 fps (7.4 m/s² at 60 fps) and a 1–2% velocity error, where Tracker's results are accurate. #87 tracks the fix; see motion kernels. Imported movies are indexed in the background and keep Tracker’s saved clip start time.
Use Clip Settings to choose the starting frame, ending frame, and frame interval for an experiment. Existing marks keep their original frame numbers when the clip changes.
To start AutoTracker, return to a frame with a marked point mass and choose AutoTracker. It follows a small textured patch on later frames, stops at existing marks, and asks for a new manual mark when the match becomes uncertain.
To set a known distance, select Calibration Stick, click two distinct points in the displayed image, and enter their distance and unit. Undo restores the previous scale and unit.
Use Set Axes to place the coordinate origin and choose the positive x direction. The existing distance scale is preserved. Toggle the overlay from the View menu.
Use Tools → Measure distance or Measure angle to make a measurement on the current frame. The tools use calibrated coordinates when available and otherwise measure in image pixels.
Zoom from the View menu or hold Ctrl while scrolling over the video. Drag with the middle mouse button or hold Alt while dragging to pan. Fit video to view resets the display.
MoTrack offers every interface language that Tracker offers: Arabic, Catalan, Chinese (Simplified and Traditional), Czech, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Malay, Polish, Portuguese (Portugal and Brazil), Russian, Slovak, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian and Vietnamese. It uses the first language in the system's list that it supports (Chinese for Hong Kong and Macao shows Traditional, for Singapore Simplified) and otherwise shows English. Arabic and Hebrew use a right-to-left layout.
Terms such as point mass, calibration stick and clip settings reuse Tracker's own translations. Most other text is machine-translated and has not yet been reviewed by native speakers; corrections are welcome (see Contributing). Unlike Tracker, MoTrack does not yet have a language preference of its own; change the system language to switch.
From the activated developer shell, run:
cmake --preset stage
cmake --build --preset stage
cmake --install build/stage --prefix "$PWD/build/stage/installed"Launch motrack.app from the install directory on macOS or run bin/motrack (bin/motrack.exe on Windows). This is a local deployment for development and smoke testing.
MoTrack is licensed under the GNU General Public License, version 3 or later. See LICENSE. Dependencies and any materials reused from Tracker retain their applicable notices and terms.