Human Heart Anatomy — Interactive 3D Learning Lab
Live: https://heart-anatomy-lab.vercel.app
An interactive 3D heart for secondary-school and first-year biology:
- Select, search and isolate the chambers, valves, great vessels, coronary arteries and cardiac veins.
- Follow animated blood through the pulmonary and systemic circuits.
- Walk through an 11-step guided tour.
- Works on phones and tablets: the details rise from the bottom in a sheet you can drag, fold or expand, and the structure list opens from the dock.
- See it as it really looks: red-brown muscle with yellow fat along the coronary vessels, pale valves and artery walls, dark veins, and real blood colours (bright red and dark red, never blue).
It is the first simulation of a planned spec-driven simulation platform. The lab renders a validated SimulationDefinition (plain data), so future simulations, including AI-generated ones, go through the same validation gate.
Educational only. This is not a clinical tool, and the text has not been reviewed by a physician. The 3D model is the BodyParts3D adult male reference heart (© DBCLS, CC BY 4.0); see public/ATTRIBUTION.md.
Run
Requires Node.js ≥ 22.12 and npm.
npm install
npm run dev # http://localhost:5180
Production build and preview:
npm run build # type-check + vite build → dist/
npm run preview # http://localhost:5181
Check
npm run typecheck
npm test # unit tests (Vitest)
npm run validate:assets # model hash, nodes, geometry sanity, attribution
npx playwright install chromium # once
npm run build && npm run e2e # browser tests (Playwright, headless Chromium)
See docs/TESTING.md for what each check covers and what is not verified.
Rebuild the heart model
public/models/heart.glb is generated, not hand-made:
node tools/extract-heart.mjs "<path to a BodyParts3D atlas build with atlas.json>"
node tools/bake-shading.mjs # baked shading for the real-tissue look
node tools/validate-assets.mjs
The structure-to-element map is in src/heart/source/structures.source.json. The extraction is deterministic: the same input gives a byte-identical GLB, whose sha256 is recorded in src/heart/generated/provenance.json and public/ATTRIBUTION.md.
Layout
| Path | What |
|---|
src/contract/ | SimulationDefinition schema (zod), approved-asset registry, validation gate |
src/heart/ | Heart definition (structures, layers, flow path, tour, sources), geometry-derived flow streams and label anchors |
src/app/ | Pure state reducer, search, React context |
src/viewer/ | three.js / react-three-fiber scene: model, camera rig, flow particles, labels |
src/ui/ | Panels: structures, details, flow, tour |
tools/ | Model extraction and asset validation |
tests/unit, tests/e2e | Vitest and Playwright suites |
docs/ | Research audit, architecture, testing, AI-generation design |
Deploy
The site is a Vercel project (Vite preset, output dist/) connected to github.com/Niyaz-05/heart-anatomy-lab. Every push to main deploys to https://heart-anatomy-lab.vercel.app; pushes to other branches get preview URLs.
Licences
- 3D model: BodyParts3D, CC BY 4.0. Attribution and the list of changes are in
public/ATTRIBUTION.md.
- Explanatory text: written for this project, with each source cited.
- Application code: no licence has been chosen yet; it is the owner's decision.
