{"id":50857847,"url":"https://github.com/stussysenik/lua-breaking","last_synced_at":"2026-06-14T19:31:28.292Z","repository":{"id":348390626,"uuid":"1195632491","full_name":"stussysenik/lua-breaking","owner":"stussysenik","description":"Interactive explorable explanations for breakdancing physics — visual companion to bboy-analytics","archived":false,"fork":false,"pushed_at":"2026-03-31T23:59:43.000Z","size":7892,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T01:55:47.022Z","etag":null,"topics":["bboy-analytics","breakdancing","computer-vision","explorable-explanations","love2d","physics"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stussysenik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"stussysenik"}},"created_at":"2026-03-29T22:32:08.000Z","updated_at":"2026-03-31T23:59:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stussysenik/lua-breaking","commit_stats":null,"previous_names":["stussysenik/lua-breaking"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/stussysenik/lua-breaking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stussysenik%2Flua-breaking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stussysenik%2Flua-breaking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stussysenik%2Flua-breaking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stussysenik%2Flua-breaking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stussysenik","download_url":"https://codeload.github.com/stussysenik/lua-breaking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stussysenik%2Flua-breaking/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34335688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bboy-analytics","breakdancing","computer-vision","explorable-explanations","love2d","physics"],"created_at":"2026-06-14T19:31:26.113Z","updated_at":"2026-06-14T19:31:28.260Z","avatar_url":"https://github.com/stussysenik.png","language":"Lua","funding_links":["https://github.com/sponsors/stussysenik"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003elua-breaking\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cem\u003eInteractive explorable explanations for breakdancing physics\u003c/em\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"#sections\"\u003e\u003cimg src=\"https://img.shields.io/badge/sections-12%20%2F%2024-blue\" alt=\"Sections\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/stussysenik/bboy-analytics\"\u003e\u003cimg src=\"https://img.shields.io/badge/research-bboy--analytics-orange\" alt=\"Research\"\u003e\u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/runtime-Love2D%2011.4-e74a99\" alt=\"Love2D\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\nA Love2D desktop app that turns computer vision research into hands-on simulations. Every concept from the [`bboy-analytics`](https://github.com/stussysenik/bboy-analytics) pipeline — joint kinematics, force fields, musicality scoring, pose validation — becomes something you can drag, scrub, and tweak.\n\nBuilt to teach. Synced to research.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/graph-light.png\" width=\"720\" alt=\"Graph navigation — light mode\" /\u003e\n  \u003cbr/\u003e\n  \u003csub\u003eGraph navigation — light mode\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/graph-dark.png\" width=\"720\" alt=\"Graph navigation — dark mode\" /\u003e\n  \u003cbr/\u003e\n  \u003csub\u003eGraph navigation — dark mode\u003c/sub\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n![Demo](demo.gif)\n\n\n```bash\n# macOS\nbrew install love\n\n# Run\ncd lua-breaking\nlove .\n```\n\nClick a node to enter a section. `ESC` to return. `T` to toggle light/dark mode.\n\n## Sections\n\n12 interactive sections built, 12 more planned. Each section is a self-contained explorable explanation with educational text, interactive parameters, and formula overlays.\n\n### Foundation\n\n| ID | Section | Status |\n|----|---------|--------|\n| 1.1 | **The Joint Model** — Interactive SMPL skeleton, 24 joints, click to inspect hierarchy | Done |\n| 1.2 | Coordinate Systems — World/camera/screen transforms | Planned |\n| 1.3 | FK/IK Basics — Forward and inverse kinematics | Planned |\n\n### Physics\n\n| ID | Section | Status |\n|----|---------|--------|\n| 2.1 | **Joint Velocity Vectors** — Per-joint speed arrows with timeline scrubber | Done |\n| 2.2 | **Kinetic Energy Flow** — Energy as heat through the skeleton, body-part bar chart | Done |\n| 2.3 | Energy Acceleration — dK/dt with beat overlay | Planned |\n| 2.4 | Angular Momentum — Conservation demo for powermoves | Planned |\n| 2.5 | **Force Vector Field** — Electric-field-style contact force visualization | Done |\n| 2.6 | **Center of Mass \u0026 Stability** — COM tracking with support polygon | Done |\n| 2.7 | Compactness — Body shape morphing and spin speed | Planned |\n| 2.8 | Balance \u0026 Stability — Box2D freeze physics | Planned |\n\n### Signal Processing\n\n| ID | Section | Status |\n|----|---------|--------|\n| 3.1 | **Beat Detection** — Waveform, energy envelope, onset function, threshold | Done |\n| 3.2 | **8D Audio Signature** — Radar chart of 8 psychoacoustic dimensions | Done |\n| 3.3 | **Musicality (mu)** — Cross-correlation between movement and audio | Done |\n| 3.4 | Cycle Detection — Autocorrelation for powermove periodicity | Planned |\n\n### Computer Vision\n\n| ID | Section | Status |\n|----|---------|--------|\n| 4.1 | 3D Reconstruction — Depth ambiguity in monocular recovery | Planned |\n| 4.2 | Why Inversions Break — Training distribution gaps | Planned |\n| 4.3 | **Validation Gate Pipeline** — Animated frames through 5 quality gates | Done |\n| 4.4 | BRACE Ground Truth — PCK scoring explained | Planned |\n\n### Breakdancing Domain\n\n| ID | Section | Status |\n|----|---------|--------|\n| 5.1 | Move Taxonomy — Toprock/footwork/powermove/freeze tree | Planned |\n| 5.2 | **Powermove Physics** — Windmill, flare, headspin simulations | Done |\n| 5.3 | Freeze Balance — COM + support polygon for freeze poses | Planned |\n| 5.4 | Musicality in Practice — Full audio + motion + score integration | Planned |\n\n## Research Context\n\nThis is the visual companion to [`bboy-analytics`](https://github.com/stussysenik/bboy-analytics) — a quantitative computer vision pipeline for analyzing breakdancing battles. The research uses:\n\n| Model | Paper | Role |\n|-------|-------|------|\n| **JOSH** | ICLR 2026 | 3D human reconstruction from monocular video |\n| **GVHMR** | SIGGRAPH Asia 2024 | World-grounded motion recovery |\n| **BeatNet+** | — | Real-time beat/downbeat detection |\n| **BRACE** | ECCV 2022 | Red Bull BC One breakdancing dataset |\n| **CoTracker3** | ICLR 2025 | Dense point tracking through occlusions |\n\nThe hardest problem: **no model handles inverted breakdancing**. Headspins, windmills, and flares produce out-of-distribution poses that break every reconstruction baseline. lua-breaking makes this visible and interactive.\n\n## Sync with bboy-analytics\n\nlua-breaking stays synchronized with [`bboy-analytics`](https://github.com/stussysenik/bboy-analytics) through two mechanisms:\n\n### Data Bridge\n\nExport real motion data from the research pipeline:\n\n```bash\npython tools/export_motion.py \\\n  --joints path/to/joints.npy \\\n  --output data/bcone_seq4.json \\\n  --model josh --fps 29.97\n```\n\nSections with data bridge support load real JOSH/GVHMR joint reconstructions instead of simulated data.\n\n### Concept Manifest\n\nTag commits in bboy-analytics with `[concept: name]` to auto-generate visualization stubs:\n\n```bash\n# In bboy-analytics\ngit commit -m \"feat: add cyclic score metric [concept: cycle_detection]\"\n\n# Then sync\npython lua-breaking/tools/sync_manifest.py \\\n  --repo-dir . --manifest-dir ../lua-breaking\n```\n\n## The 8D Audio Signature\n\nOne of the key innovations in [`bboy-analytics`](https://github.com/stussysenik/bboy-analytics) is characterizing music with 8 psychoacoustic dimensions:\n\n| # | Dimension | What it measures | Why it matters for bboy |\n|---|-----------|-----------------|------------------------|\n| 1 | Bass Energy | Low-freq power (20-250Hz) | Footwork timing, groove foundation |\n| 2 | Percussive Strength | Transient-to-sustained ratio | Beat hits, freeze timing |\n| 3 | Vocal Presence | Mid-freq formant energy | Call-and-response, phrase structure |\n| 4 | Beat Stability | Inter-beat interval consistency | Predictability for anticipatory movement |\n| 5 | Spectral Flux | Rate of spectral change | Musical \"activity\" to react to |\n| 6 | Rhythm Complexity | Syncopation/polyrhythm | Off-beat musicality challenges |\n| 7 | Harmonic Richness | Overtone density | Emotional quality, movement style |\n| 8 | Dynamic Range | Loudness variance | Build-up/release, dynamic freezes |\n\nThese feed into the **musicality score**: `mu = max_tau corr(M(t), H(t-tau))`, where `H(t)` is the weighted combination of all 8 dimensions.\n\n## Musicality Scoring\n\nThe core metric: **how well does a dancer's movement sync to the music?**\n\n```\nmu = max_tau corr(M(t), H(t - tau))\n\nM(t) = movement energy (sum of 3D joint velocity magnitudes)\nH(t) = audio heat (weighted 8D signature)\ntau  = time lag (dancers hit slightly ahead or behind the beat)\nmu   = peak Pearson correlation across all lags\n```\n\n| Grade | Threshold | Meaning |\n|-------|-----------|---------|\n| **S** | \u003e= 0.90 | Exceptional musicality |\n| **A** | \u003e= 0.75 | Strong musicality |\n| **B** | \u003e= 0.55 | Good musicality |\n| **C** | \u003e= 0.35 | Some musical awareness |\n| **D** | \u003c 0.35 | Weak correlation |\n\nSection 3.3 makes this tangible — drag the tau slider and watch the correlation change in real-time.\n\n## Architecture\n\n```\nmain.lua                    Entry point + input routing\nshell/\n  graph.lua                 Node graph navigation (zoom, pan, click)\n  theme.lua                 Light/dark mode, layer colors, spacing tokens\nlib/\n  skeleton.lua              SMPL 24-joint topology + drawing\n  vector.lua                2D/3D vector math (no-garbage variants)\n  physics.lua               Kinetic energy, COM, angular momentum, stability\n  signal.lua                Cross-correlation, autocorrelation, windowing\n  draw.lua                  Arrows, vector fields, grids, formulas, badges\n  widgets.lua               Sliders, buttons (immediate-mode)\n  data_loader.lua           JSON motion data loader with frame interpolation\n  json.lua                  rxi/json.lua (MIT) safe parser\n  timeline.lua              Playback scrubber\nsections/\n  X_Y_name/init.lua         Self-contained section modules\ntools/\n  export_motion.py          joints.npy -\u003e JSON for Love2D\n  sync_manifest.py          Git hook: detect new concepts, generate stubs\n```\n\nEach section follows a standard interface: `load()`, `update(dt)`, `draw()`, mouse/key callbacks, `unload()`. The graph shell loads all sections from `sections/*/init.lua` and arranges them as clickable nodes.\n\n## Controls\n\n| Key | Action |\n|-----|--------|\n| Click | Enter section / interact |\n| ESC | Return to graph |\n| T | Toggle light/dark mode |\n| Scroll | Zoom graph |\n| Drag | Pan graph / drag elements |\n| Space | Play/pause (timeline sections) |\n| R | Reset (section-specific) |\n| 1-5 | Tab switch (multi-tab sections) |\n\n## Tech Stack\n\n- **[Love2D](https://love2d.org) 11.4** — Desktop app framework with Box2D physics\n- **Lua 5.1** — via LuaJIT in Love2D\n- **Python 3.10+** — Data export and sync tooling\n- **[rxi/json.lua](https://github.com/rxi/json.lua)** — Safe JSON parsing (MIT)\n\n## Related\n\n- [`bboy-analytics`](https://github.com/stussysenik/bboy-analytics) — The research pipeline this visualizes\n- [BRACE Dataset](https://github.com/dmoltisanti/brace) — Red Bull BC One breakdancing annotations\n- [Love2D](https://love2d.org) — The runtime\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstussysenik%2Flua-breaking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstussysenik%2Flua-breaking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstussysenik%2Flua-breaking/lists"}