This project provides a small pipeline for analyzing motion tracking CSV files. Configuration is managed entirely through config.yaml.

1. Install dependencies:

   pip install -r requirements.txt

2. Run the analysis:

   python -m tracking_analysis.cli --config config.yaml

   The script will automatically trim the CSV when preprocess.enable is true.

All plots, trimmed files and statistics are written to the directory specified by output.output_dir (default results/). When trimming is enabled a summary file is produced alongside the trimmed CSV.

Each run creates a subfolder inside output.output_dir named with the current date/time and key settings (interval, filter toggles and markers). The same information is appended to the trimmed CSV and summary file names based on the original input file. The exact configuration used is saved as config_used.txt within that folder. Additionally, a run.log file captures progress messages while the same log output is streamed to the console.

Below is an overview of the keys supported in config.yaml.

Path to the CSV file to process.

start_time and end_time specify the slice of the recording in seconds. Use null for end_time to include the entire file.

List of timestamps (seconds) to highlight on the plots. Markers are drawn as small red triangles so the same event can be located across all figures.

List of rigid-body base names to analyse. An empty list means all available groups.

Options for smoothing the computed velocities (smoothing, smoothing_window, smoothing_polyorder, smoothing_method).

Range filters define upper/lower thresholds for linear and angular speed as well as position.

Stationary segments are removed when enable is true. If either linear speed or angular velocity stays at zero for window consecutive frames, that period and the next after frames are discarded.

Controls which figures and exports are produced. full_size_plots enlarges plots to 16x10 inches. x_limit and y_limit specify the axis maxima for time-series plots (set to null for automatic scaling). Set export_head_direction to true to write a JSON file with per-frame head direction for the selected groups. The head_direction.format option selects between degrees (0–360° yaw) and quaternion output; head_direction.include_frames toggles frame numbers in the JSON.

To write kinematic metrics for each group, enable the export_metrics block:

output:
  export_metrics:
    enable: true
    metrics: [trajectory, speed, angular_speed]  # subset is allowed
    format: csv  # or json

The files are saved under the directory given by output.output_dir.

When using the Python API, the same settings can be applied via:

from interactive_app.exporting import export_metrics_cfg
paths = export_metrics_cfg(groups, cfg)

To write kinematic metrics for each group, enable the export_metrics block:

output:
  export_metrics:
    enable: true
    metrics: [trajectory, speed, angular_speed]  # subset is allowed
    format: csv  # or json

The files are saved under the directory given by output.output_dir.

When using the Python API, the same settings can be applied via:

from interactive_app.exporting import export_metrics_cfg
paths = export_metrics_cfg(groups, cfg)

If enable is true, the CSV is trimmed before analysis. The trimmed and summary files are saved inside the run folder with names derived from the input file and current settings. output_file and summary_file are optional paths for writing copies of these files; both default to null.

Controls log output. level sets verbosity (e.g. info, debug) and file defines the log filename inside each run folder. Logs are also printed to the terminal.

You can also run the trimming step manually:

python -m tracking_analysis.trim <input.csv> [output.csv] --summary summary.txt

The interactive_app package is split into small modules so UI logic, data handling and plotting remain independent:

• data_utils.py contains data loading, preprocessing and filtering helpers.
• plotting.py defines the functions that build Plotly figures.
• ui_components.py holds the Dash form builders used in the configuration panel.
• layout.py assembles the Dash layout.
• callbacks.py registers all Dash callbacks.
• utils.py re-exports these helpers for backward compatibility.
• smoothing.py defines pluggable smoothing functions used when computing velocities.

interactive_app.smoothing exposes a register decorator and an apply helper. Built-in functions are registered with names like "savgol", "ema", "window" and "lateral_inhibition". To add a new algorithm simply append a function decorated with @register("my_method") in smoothing.py. Set kinematics.smoothing_method to the same name in config.yaml and app.py will automatically use the new smoother.

The Dash-based web interface mirrors the CLI processing pipeline. It reads config.yaml, applies the same filtering, slicing and smoothing settings and highlights any time markers. Controls for selecting an entity and table display sit at the top of the page followed by a global time slider and playback buttons. Plots are grouped into tabs: the Trajectory tab shows the 3D and 2D paths side by side while the Kinematics tab contains the speed and angular speed time-series. Clicking a point on any graph highlights the same moment on the others using grey markers. Configuration editing now appears as a centred modal dialog with a form generated from config.yaml. Switches toggle boolean options and inputs update numeric or text values. Saving reloads the data without restarting the server. app.py simply wires together the layout and callback modules, keeping the viewer easy to navigate and extend.

python -m interactive_app.app --config config.yaml

The app listens on the port specified by webapp.port (default 3010). If input_file does not exist the viewer falls back to data/input.csv.

Legacy callbacks for the old YAML editor remain commented out in interactive_app/app.py for reference. The web interface now exposes a simple form-based configuration panel instead of a raw text area.