# adambanaszczyk/head_trajectory architecture

> Architecture diagram of the GitHub repository adambanaszczyk/head_trajectory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adambanaszczyk/head_trajectory
- Repository: https://github.com/adambanaszczyk/head_trajectory

## Overview

This repository is an experimental workflow for measuring VR-headset positioning accuracy against robot and motion-capture trajectories. Users collect headset and robot poses, estimate their time offset, prepare synchronized calibration inputs, solve the hand-eye transform, convert and trim trajectories, then compare them with trajectory-evaluation tools. The graph also preserves the documented Unity capture and robot trajectory-generation capabilities. Several subsystems are documented but not sampled; those relationships are shown only where the README explicitly describes the workflow.

Main entry points: [`data/experiments`](https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments) (Experiment recordings), [`prepare_calibration_data/compare_traj_peaks.py`](https://github.com/adambanaszczyk/head_trajectory/blob/main/prepare_calibration_data/compare_traj_peaks.py) (Peak time offset), [`prepare_calibration_data/match_poses_by_time.py`](https://github.com/adambanaszczyk/head_trajectory/blob/main/prepare_calibration_data/match_poses_by_time.py) (Calibration CSV preparation), [`evaluation/trajectory_TUM_match_by_tool_time.py`](https://github.com/adambanaszczyk/head_trajectory/blob/main/evaluation/trajectory_TUM_match_by_tool_time.py) (Synchronized TUM conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Pose capture"]
  node_unitycapture["Unity pose capture"]
  node_robotpublisher["TCP pose publisher"]
  node_experimentdata[("Experiment recordings")]
  node_motiondata[("Head motion recordings")]
end

subgraph group_calibration["Calibration preparation"]
  node_timeoffset["Peak time offset"]
  node_calibrationcsv["Calibration CSV preparation"]
  node_handeye["Hand-eye solver"]
  node_calibrationresult["Unity-to-OptiTrack transform"]
end

subgraph group_processing["Trajectory processing"]
  node_robottrajectory["Robot trajectory calculation"]
  node_tumconversion["Synchronized TUM conversion"]
  node_tumdata[("Aligned trajectories")]
  node_trim["Idle and brake trimming"]
end

subgraph group_evaluation["Accuracy evaluation"]
  node_cutdata[("Trimmed trajectories")]
  node_evo["Trajectory comparison"]
  node_results["Comparison results"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs capture"| node_unitycapture
node_researcher -->|"runs publisher"| node_robotpublisher
node_unitycapture -->|"records poses"| node_experimentdata
node_robotpublisher -->|"publishes TCP poses"| node_experimentdata
node_researcher -->|"estimates offset"| node_timeoffset
node_experimentdata -->|"provides recordings"| node_timeoffset
node_timeoffset -->|"informs synchronization"| node_calibrationcsv
node_experimentdata -->|"provides poses"| node_calibrationcsv
node_calibrationcsv -->|"supplies CSV inputs"| node_handeye
node_handeye -->|"writes transform"| node_calibrationresult
node_researcher -->|"calculates robot motion"| node_robottrajectory
node_motiondata -->|"provides head path"| node_robottrajectory
node_calibrationresult -.->|"provides transform"| node_robottrajectory
node_researcher -->|"converts recordings"| node_tumconversion
node_experimentdata -->|"provides trajectories"| node_tumconversion
node_tumconversion -->|"writes TUM files"| node_tumdata
node_tumdata -->|"provides trajectories"| node_trim
node_trim -->|"writes filtered files"| node_cutdata
node_cutdata -->|"compares trajectories"| node_evo
node_evo -->|"saves metrics"| node_results

click node_unitycapture "https://github.com/adambanaszczyk/head_trajectory/tree/main/unity_tracking_app"
click node_robotpublisher "https://github.com/adambanaszczyk/head_trajectory/blob/main/utility/tool_pose_publisher.py"
click node_experimentdata "https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments"
click node_motiondata "https://github.com/adambanaszczyk/head_trajectory/tree/main/data/real_world_head_trajectories"
click node_timeoffset "https://github.com/adambanaszczyk/head_trajectory/blob/main/prepare_calibration_data/compare_traj_peaks.py"
click node_calibrationcsv "https://github.com/adambanaszczyk/head_trajectory/blob/main/prepare_calibration_data/match_poses_by_time.py"
click node_handeye "https://github.com/adambanaszczyk/head_trajectory/blob/main/HandEyeCalibration/trajectory_alignment.cpp"
click node_calibrationresult "https://github.com/adambanaszczyk/head_trajectory/tree/main/HandEyeCalibration"
click node_robottrajectory "https://github.com/adambanaszczyk/head_trajectory/blob/main/determining_robot_motions/calculate_robot_trajectory.py"
click node_tumconversion "https://github.com/adambanaszczyk/head_trajectory/blob/main/evaluation/trajectory_TUM_match_by_tool_time.py"
click node_tumdata "https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments/linked_tum"
click node_trim "https://github.com/adambanaszczyk/head_trajectory/blob/main/evaluation/auto_remove_idle_and_brake.py"
click node_cutdata "https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments/linked_tum"
click node_results "https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments/linked_tum"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_unitycapture,node_robotpublisher,node_experimentdata,node_motiondata toneBlue
class node_timeoffset,node_calibrationcsv,node_handeye,node_calibrationresult toneAmber
class node_robottrajectory,node_tumconversion,node_tumdata,node_trim toneMint
class node_cutdata,node_evo,node_results toneRose
class node_researcher toneIndigo
```

## Components

### Pose capture

- [Unity pose capture](https://github.com/adambanaszczyk/head_trajectory/tree/main/unity_tracking_app): `unity_tracking_app`
- [TCP pose publisher](https://github.com/adambanaszczyk/head_trajectory/blob/main/utility/tool_pose_publisher.py): `utility/tool_pose_publisher.py`
- [Experiment recordings](https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments): `data/experiments`
- [Head motion recordings](https://github.com/adambanaszczyk/head_trajectory/tree/main/data/real_world_head_trajectories): `data/real_world_head_trajectories`

### Calibration preparation

- [Peak time offset](https://github.com/adambanaszczyk/head_trajectory/blob/main/prepare_calibration_data/compare_traj_peaks.py): `prepare_calibration_data/compare_traj_peaks.py`
- [Calibration CSV preparation](https://github.com/adambanaszczyk/head_trajectory/blob/main/prepare_calibration_data/match_poses_by_time.py): `prepare_calibration_data/match_poses_by_time.py`
- [Hand-eye solver](https://github.com/adambanaszczyk/head_trajectory/blob/main/HandEyeCalibration/trajectory_alignment.cpp): `HandEyeCalibration/trajectory_alignment.cpp`
- [Unity-to-OptiTrack transform](https://github.com/adambanaszczyk/head_trajectory/tree/main/HandEyeCalibration): `HandEyeCalibration`

### Trajectory processing

- [Robot trajectory calculation](https://github.com/adambanaszczyk/head_trajectory/blob/main/determining_robot_motions/calculate_robot_trajectory.py): `determining_robot_motions/calculate_robot_trajectory.py`
- [Synchronized TUM conversion](https://github.com/adambanaszczyk/head_trajectory/blob/main/evaluation/trajectory_TUM_match_by_tool_time.py): `evaluation/trajectory_TUM_match_by_tool_time.py`
- [Aligned trajectories](https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments/linked_tum): `data/experiments/linked_tum`
- [Idle and brake trimming](https://github.com/adambanaszczyk/head_trajectory/blob/main/evaluation/auto_remove_idle_and_brake.py): `evaluation/auto_remove_idle_and_brake.py`

### Accuracy evaluation

- [Trimmed trajectories](https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments/linked_tum): `data/experiments/linked_tum`
- **Trajectory comparison**
- [Comparison results](https://github.com/adambanaszczyk/head_trajectory/tree/main/data/experiments/linked_tum): `data/experiments/linked_tum`

### Other components

- **Researcher**

## Connections

- Researcher → Unity pose capture: runs capture (evidence: `README.md`)
- Researcher → TCP pose publisher: runs publisher (evidence: `README.md`)
- Unity pose capture → Experiment recordings: records poses (evidence: `README.md`)
- TCP pose publisher → Experiment recordings: publishes TCP poses (evidence: `utility/tool_pose_publisher.py`)
- Researcher → Peak time offset: estimates offset (evidence: `README.md`)
- Experiment recordings → Peak time offset: provides recordings (evidence: `prepare_calibration_data/compare_traj_peaks.py`)
- Peak time offset → Calibration CSV preparation: informs synchronization (evidence: `README.md`)
- Experiment recordings → Calibration CSV preparation: provides poses (evidence: `prepare_calibration_data/match_poses_by_time.py`)
- Calibration CSV preparation → Hand-eye solver: supplies CSV inputs (evidence: `README.md`)
- Hand-eye solver → Unity-to-OptiTrack transform: writes transform (evidence: `HandEyeCalibration/trajectory_alignment.cpp`)
- Researcher → Robot trajectory calculation: calculates robot motion (evidence: `README.md`)
- Head motion recordings → Robot trajectory calculation: provides head path (evidence: `determining_robot_motions/calculate_robot_trajectory.py`)
- Unity-to-OptiTrack transform → Robot trajectory calculation: provides transform
- Researcher → Synchronized TUM conversion: converts recordings (evidence: `README.md`)
- Experiment recordings → Synchronized TUM conversion: provides trajectories (evidence: `evaluation/trajectory_TUM_match_by_tool_time.py`)
- Synchronized TUM conversion → Aligned trajectories: writes TUM files (evidence: `evaluation/trajectory_TUM_match_by_tool_time.py`)
- Aligned trajectories → Idle and brake trimming: provides trajectories (evidence: `evaluation/auto_remove_idle_and_brake.py`)
- Idle and brake trimming → Trimmed trajectories: writes filtered files (evidence: `evaluation/auto_remove_idle_and_brake.py`)
- Trimmed trajectories → Trajectory comparison: compares trajectories (evidence: `README.md`)
- Trajectory comparison → Comparison results: saves metrics (evidence: `README.md`)
