# cknishan/synthetic-squat-form-checker architecture

> Architecture diagram of the GitHub repository cknishan/synthetic-squat-form-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cknishan/synthetic-squat-form-checker
- Repository: https://github.com/cknishan/synthetic-squat-form-checker

## Overview

This repository is a synthetic squat-form classification research pipeline, not a dependable exercise-feedback product. The documented workflow generates controlled Blender clips, extracts and validates MediaPipe poses, derives features and grouped splits, then compares rule-based, logistic, clip-MLP and temporal-CNN predictions. It also supports frozen-model exploratory inference on real videos. The README documents the broad pipeline; sampled excerpts and the source index support specific internal links. Uninspected modules and generated-data wiring are represented only where documented.

Main entry points: [`scripts/data/create_milestone_splits.py`](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/create_milestone_splits.py) (Grouped splits), [`scripts/data/compare_real_models.py`](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/compare_real_models.py) (Real-video comparison), [`scripts/blender/render_milestone_dataset.py`](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/render_milestone_dataset.py) (Controlled rendering), [`scripts/data/build_milestone_features.py`](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/build_milestone_features.py) (Clip and frame features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Synthetic generation"]
  node_character_prep["Character preparation"]
  node_motion_variants["Motion variants"]
  node_render["Controlled rendering"]
end

subgraph group_processing["Pose and features"]
  node_extract["Pose extraction"]
  node_pose_qc["Pose quality checks"]
  node_render_qc["Render validation"]
  node_features["Clip and frame features"]
  node_splits["Grouped splits"]
  node_pilot_plots["Pilot feature plots"]
end

subgraph group_evaluation["Model evaluation"]
  node_rules_logistic["Rules and logistic<br/>[train_baselines.py]"]
  node_mlp["Clip MLP<br/>[train_mlp.py]"]
  node_temporal["Temporal CNN<br/>[train_temporal.py]"]
end

subgraph group_inference["Inference"]
  node_video_input["Video sampling<br/>[inference_video.py]"]
  node_video_pose["Video pose extraction"]
  node_inference_features["Inference features"]
  node_logistic_infer["Logistic prediction"]
  node_real_compare["Real-video comparison"]
end

node_researcher(("Researcher"))
node_real_user(("Real-video investigator"))

node_researcher -->|"prepares scene"| node_character_prep
node_character_prep -->|"provides scene"| node_motion_variants
node_motion_variants -->|"provides actions"| node_render
node_render -->|"renders clips"| node_extract
node_extract -->|"validates poses"| node_pose_qc
node_render -->|"validates renders"| node_render_qc
node_pose_qc -->|"checks landmarks"| node_features
node_features -->|"supplies features"| node_splits
node_features -->|"plots features"| node_pilot_plots
node_splits -->|"partitions data"| node_rules_logistic
node_splits -->|"partitions data"| node_mlp
node_splits -->|"partitions data"| node_temporal
node_real_user -->|"supplies video"| node_video_input
node_video_input -->|"samples frames"| node_video_pose
node_video_pose -->|"provides landmarks"| node_inference_features
node_inference_features -->|"provides predictors"| node_logistic_infer
node_real_compare -->|"loads model"| node_logistic_infer
node_real_compare -->|"uses features"| node_inference_features
node_real_compare -->|"compares models"| node_temporal

click node_character_prep "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/prepare_milestone_characters.py"
click node_motion_variants "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/create_milestone_variants.py"
click node_render "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/render_milestone_dataset.py"
click node_extract "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/extract_milestone_landmarks.py"
click node_pose_qc "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/validate_milestone_landmarks.py"
click node_render_qc "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/validate_rendered_dataset.py"
click node_features "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/build_milestone_features.py"
click node_splits "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/create_milestone_splits.py"
click node_rules_logistic "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/train_baselines.py"
click node_mlp "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/train_mlp.py"
click node_temporal "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/train_temporal.py"
click node_pilot_plots "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/plot_pilot_features.py"
click node_video_input "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/inference_video.py"
click node_video_pose "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/extract_mediapipe_landmarks.py"
click node_inference_features "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/inference_features.py"
click node_logistic_infer "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/primary_logistic_inference.py"
click node_real_compare "https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/compare_real_models.py"

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_character_prep,node_motion_variants,node_render toneBlue
class node_extract,node_pose_qc,node_render_qc,node_features,node_splits,node_pilot_plots toneAmber
class node_rules_logistic,node_mlp,node_temporal toneMint
class node_video_input,node_video_pose,node_inference_features,node_logistic_infer,node_real_compare toneRose
class node_researcher,node_real_user toneIndigo
```

## Components

### Synthetic generation

- [Character preparation](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/prepare_milestone_characters.py): `scripts/blender/prepare_milestone_characters.py`
- [Motion variants](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/create_milestone_variants.py): `scripts/blender/create_milestone_variants.py`
- [Controlled rendering](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/blender/render_milestone_dataset.py): `scripts/blender/render_milestone_dataset.py`

### Pose and features

- [Pose extraction](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/extract_milestone_landmarks.py): `scripts/data/extract_milestone_landmarks.py`
- [Pose quality checks](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/validate_milestone_landmarks.py): `scripts/data/validate_milestone_landmarks.py`
- [Render validation](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/validate_rendered_dataset.py): `scripts/data/validate_rendered_dataset.py`
- [Clip and frame features](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/build_milestone_features.py): `scripts/data/build_milestone_features.py`
- [Grouped splits](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/create_milestone_splits.py): `scripts/data/create_milestone_splits.py`
- [Pilot feature plots](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/plot_pilot_features.py): `scripts/data/plot_pilot_features.py`

### Model evaluation

- [Rules and logistic](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/train_baselines.py): `scripts/models/train_baselines.py`
- [Clip MLP](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/train_mlp.py): `scripts/models/train_mlp.py`
- [Temporal CNN](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/train_temporal.py): `scripts/models/train_temporal.py`

### Inference

- [Video sampling](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/inference_video.py): `scripts/data/inference_video.py`
- [Video pose extraction](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/extract_mediapipe_landmarks.py): `scripts/data/extract_mediapipe_landmarks.py`
- [Inference features](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/inference_features.py): `scripts/data/inference_features.py`
- [Logistic prediction](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/models/primary_logistic_inference.py): `scripts/models/primary_logistic_inference.py`
- [Real-video comparison](https://github.com/cknishan/synthetic-squat-form-checker/blob/main/scripts/data/compare_real_models.py): `scripts/data/compare_real_models.py`

### Other components

- **Researcher**
- **Real-video investigator**

## Connections

- Researcher → Character preparation: prepares scene (evidence: `README.md`)
- Character preparation → Motion variants: provides scene (evidence: `README.md`)
- Motion variants → Controlled rendering: provides actions (evidence: `README.md`)
- Controlled rendering → Pose extraction: renders clips (evidence: `README.md`)
- Pose extraction → Pose quality checks: validates poses (evidence: `scripts/data/extract_milestone_landmarks.py`)
- Controlled rendering → Render validation: validates renders (evidence: `scripts/blender/render_milestone_dataset.py`)
- Pose quality checks → Clip and frame features: checks landmarks (evidence: `scripts/data/build_milestone_features.py`)
- Clip and frame features → Grouped splits: supplies features (evidence: `scripts/data/create_milestone_splits.py`)
- Clip and frame features → Pilot feature plots: plots features (evidence: `scripts/data/build_milestone_features.py`)
- Grouped splits → Rules and logistic: partitions data (evidence: `scripts/models/train_baselines.py`)
- Grouped splits → Clip MLP: partitions data (evidence: `scripts/models/train_mlp.py`)
- Grouped splits → Temporal CNN: partitions data (evidence: `scripts/models/train_temporal.py`)
- Real-video investigator → Video sampling: supplies video (evidence: `README.md`)
- Video sampling → Video pose extraction: samples frames (evidence: `scripts/data/inference_video.py`)
- Video pose extraction → Inference features: provides landmarks
- Inference features → Logistic prediction: provides predictors (evidence: `scripts/data/inference_features.py`)
- Real-video comparison → Logistic prediction: loads model (evidence: `scripts/data/compare_real_models.py`)
- Real-video comparison → Inference features: uses features (evidence: `scripts/data/compare_real_models.py`)
- Real-video comparison → Temporal CNN: compares models (evidence: `scripts/data/compare_real_models.py`)
