human-atlas

# Human Atlas: Architectural Deep-Dive & Review Rendering dense, high-polygon 3D anatomical models in a web browser often leads to frame drops and memory overhead. Human Atlas solves this engineering challenge effectively. Built on React, Three.js, and shadcn/ui, this open-source tool presents the BodyParts3D 4.0 adult male reference dataset—spanning 2,234 individually selectable meshes, 15 anatomical systems, and 3,432 named concepts. --- ## Under the Hood: Rendering & Performance Architecture Handling 2,288,268 triangles while maintaining high frame rates requires deliberate rendering optimizations. Rather than spawning thousands of distinct scene objects and draw calls, `human-atlas` implements a batched geometry pipeline. ### GPU-Driven State Management * Batched Geometry: Individual source meshes are merged into unified batch buffers to keep draw calls minimal during orbit, zoom, and panning operations. * Texture-Controlled Transforms: Per-structure GPU textures manage translation, visibility toggles, and highlight selections on the shaders. This allows individual structures to move into exploded inventory layouts without re-instantiating scene graphs. * Precise Picking: While rendering uses batched geometry, component geometry is retained for accurate raycasting and structure selection. * Geometry Compression: Mesh data is simplified specifically for browser delivery, compressing the entire 2.2M+ polygon model down to an initial ~33 MB payload. * WebMCP Integration: The application includes optional WebMCP tools that expose anatomy search and inspection contracts to compatible browsers. --- ## Local Setup Getting the project running locally requires Node.js 22.13 or newer. No environment variables, database setup, or API keys are required. ```sh # Clean install dependencies npm ci # Start the local dev server npm run dev ``` By default, the development server runs on `http://localhost:3016`. To generate the static production build: ```sh npm run build ``` The compiled output is saved directly to the `dist/` directory. --- ## Testing and Validation Pipeline The repository ships with an extensive set of scripts to validate geometry data, mesh bounds, and user interaction mechanics. ```sh npm run check node scripts/validate-atlas.mjs node scripts/validate-interactions.mjs npm run build ``` ### What these checks cover: 1. Mesh & Data Contracts: Validates mesh buffers, named concept memberships, and search mapping contracts. 2. Exploded Layouts: Programmatically verifies non-overlapping spatial packing algorithms across both desktop and constrained mobile viewports (tested at 390×844, 320×568, and 844×390 aspect ratios). 3. Gesture Disambiguation: Ensures tap-versus-drag thresholds function correctly so user rotations do not trigger accidental structure selections. --- ## Technical Assessment `human-atlas` demonstrates how to handle dense spatial data inside a standard web stack. By shifting mesh state management to GPU textures and leveraging geometry batching, it delivers complex multi-mesh isolation, full-text search, and non-overlapping exploded views directly in the browser without sacrificing responsiveness.