Anatomy Architecture: Audited Isometric SVG and WebGL for AI

Key Takeaways
Anatomy is an open-source technical illustration engine and multi-agent skill distributed under the MIT license in the Anatomy repository. Operating with zero external runtime npm dependencies on Node.js 20.10+, Anatomy translates abstract software concepts into physical isometric mechanisms constructed from dozens of solid parts. It combines an isometric projection and four-tone shading kernel (kit/iso-kit.mjs), arbitrary solids of revolution (kit/lathe.mjs), overlapping fluid pipe routing (kit/tube.mjs), camera-locked isometric WebGL shaders (kit/gl.mjs), and an optional 3D rigid group runtime (kit/turn.mjs). A mathematical geometry auditor (kit/audit.mjs) and headless Chrome DevTools Protocol checks (scripts/lines.mjs) empirically verify that no components collide, no lines terminate in mid-air, and painter’s depth sorting remains monotonic across static and exploded poses.

Shortcomings of abstract software diagrams

Technical documentation frequently relies on abstract boxes-and-arrows flowcharts. While tools like Mermaid or Graphviz capture logical dependencies, they struggle to communicate runtime physical realities such as rate limits, state persistence, fluid concurrency, and physical clearance constraints.

Typical issues with prompt-generated software diagrams include:

• Symbolic detachment: Abstract rectangles labeled “Cache Store” fail to explain how work is queued, throttled, or synchronized.
• Visual clipping: Generative tools frequently output SVG strokes that float in empty canvas space or slice through neighboring geometries.
• Disconnected readouts: Static diagrams display disconnected metrics with no mathematical link to depicted model state.
• Unverified depth order: Background connectors often render across foreground hulls due to unmanaged SVG element ordering.

[Prompt-Based AI Diagramming]
  │
  ├── Unstructured Prompts ────> Abstract Boxes & Loose Floating Arrows
  ├── Unverified Depth Order ──> Background Wires Occlude Foreground Hulls
  └── Disconnected Labels ─────> Metrics Disconnected From Underlying State

==================================== VS ====================================

[Anatomy Mechanical & Empirical Pipeline]
  │
  ├── Physical Metaphor Kernel ──> Abstract Concepts Mapped to Physical Machinery
  ├── Pure Node.js Math Engine ──> 4-Tone Shading & Fritsch-Carlson Normals
  ├── Camera-Locked WebGL ───────> Volumetric Shaders Inside Isometric Planes
  └── Empirical Geometry Audit ──> Clearance Envelopes & Chrome Line Checks

Physical metaphor: turning compute into machinery

Anatomy grounds technical communication by prompting AI coding agents—including Claude Code, Google Antigravity, OpenCode, OpenAI Codex, and MiniMax Code—to invent a tangible physical apparatus mirroring the digital concept:

• A cache key lookup becomes a mechanical pin-tumbler lock that only turns when every spring-loaded pin reaches the exact shear line.
• A GPU context multiplexer becomes a multi-axis gantry plotter whose single motorized print head shuttles across a sixteen-well spot plate.
• A wave interference algorithm becomes a four-legged school ripple tank driven by dual vibrating dippers with optical caustic reflections on paper.
• A token bucket rate limiter becomes a precision fluid hopper that fills continuously while metered drop valves release request units.

Every number displayed on the card’s live digital readout derives directly from the mechanical state model governing the moving parts. If a carriage slides 20 millimeters along an axis, the readout reflects that displacement from the underlying physics tick.

The core isometric mathematics and camera kernel

At the center of Anatomy is kit/iso-kit.mjs, a pure Node.js mathematics library requiring zero external dependencies. The engine maps world coordinates [x, y, z] (where x and y represent the floor plane and z points straight up) into two-dimensional SVG screen coordinates [sx, sy] within a defined viewBox.

The camera defaults to an azimuth of 45 degrees and an elevation of 30 degrees. The transformation computes projection coordinates and painter’s depth:

// kit/iso-kit.mjs camera projection and depth sorting
export function cameraOf({ scale, azimuth = 45, elevation = 30 }) {
  const a = azimuth * (Math.PI / 180);
  const e = elevation * (Math.PI / 180);
  return {
    sinA: Math.sin(a),
    cosA: Math.cos(a),
    sinE: Math.sin(e),
    cosE: Math.cos(e),
    k: scale * Math.sqrt(1.6)
  };
}

export function iso([x, y, z], projection) {
  const { origin } = projection;
  const { sinA, cosA, sinE, cosE, k } = cameraOf(projection);
  return [
    origin[0] + (x * sinA - y * cosA) * k,
    origin[1] + ((x * cosA + y * sinA) * sinE - z * cosE) * k
  ];
}

export function depthOf([x, y, z], projection) {
  const { sinA, cosA, sinE, cosE } = cameraOf(projection);
  return (x * cosA + y * sinA) * cosE + z * sinE;
}

Anatomy enforces a four-tone shading palette (hi, mid, lo, faint) bucketed by how surface normals face a camera-locked directional light vector (normalize([-sinA, cosA, 1.2])).

When rendering prisms via slabOf, cylinder, or extrude, the engine outputs structured paths: fill (solid paper-colored background mask), shades[0..3] (lateral faces grouped by tone), top (highlighted upper polygon), crease (boundary stroke between top and sides), optional bevel (highlight inset along visible edges), and outline (silhouette contour).

To eliminate raster hairline gaps caused by sub-pixel anti-aliasing between abutting tone regions, Anatomy sets paths.seamless = true and applies a 0.4-pixel self-colored stroke to each shaded polygon.

Solids of revolution and smooth normal fields

Standard isometric extrusion works for rectangular chassis, but fails on complex curved geometries like rocket combustion chambers and pressure vessels where hand-placed faceted rings produce tone staircases.

Anatomy resolves this in kit/lathe.mjs by defining solids of revolution around arbitrary 3D frames F = { o, a, u, v }, evaluating Fritsch-Carlson monotone cubic Hermite splines:

// kit/lathe.mjs smooth analytic profile evaluation
export function bandsOf(profile, cuts, F, P, {
  slope = null,
  radius = null,
  steps = 96,
  rows = 8,
  samples = 72
} = {}) {
  // Evaluates normal fields across band boundaries
  // Shares unified normal vectors so tone boundaries transition cleanly
  // Generates single analytic silhouette sidesOf without faceted kinks
}

When authoring a tapered bell or valve casing, setting smooth: { slope } ensures the normal vectors derive from the derivative dr/ds of the analytic curve. The tone transition curves cross band joints without angular steps, while bandsOf permits long curved bodies to be divided into depth-sorted bands that interleave cleanly with wrapping fluid conduits.

Fluid routing, cable bundles, and overlap management

Piping, hydraulic lines, and electrical harnesses present persistent depth sorting challenges in isometric drafting. In kit/tube.mjs, Anatomy decomposes 3D centerlines into managed ribbons:

• Chunking with overlap: Centerlines are partitioned into chunks of at most 30 world units via tubePieces. Each chunk overlaps its neighbor by 0.5 world units, ensuring that anti-aliasing filters at chunk endpoints do not create visual notches or gaps.
• Automated crossings (crossingsOf): The module calculates screen-space intersection points between pairs of conduits and sorts their rendering keys according to relative viewer depth.
• Fitting gap masking: Where a pipe passes under a collar, bracket, or valve body, developers define gaps = [[from, to]]. The conduit suppresses its body along the masked span while projecting elliptical cross-section end caps with highlight and shade stripes at the entry and exit collars.

// Conduit chunking and crossing depth ordering
const pieces = tubePieces(routePoints, 1.2, P, {
  maxLength: 30,
  gaps: [[14, 22]],
  caps: [true, true]
});

pieces.forEach((chunk) => {
  R.put({
    piece: "hydraulic_circuit",
    at: chunk.mid,
    bias: 0.1,
    svg: tubeSvg(chunk, { tone: "hi" }),
    shapes: [A.tube(chunk.points, chunk.radii)]
  });
});

Camera-locked isometric WebGL shaders

While SVG provides crisp vector edges, phenomena like rocket combustion plumes, liquid dispersion, and shadow caustics require continuous volumetric fields. Anatomy solves this in kit/gl.mjs through an embedded WebGL layer that operates inside the identical isometric camera perspective.

A WebGL <canvas> element is sandwiched in the DOM between a background SVG layer (.iso-back) and a foreground SVG layer (.iso-front). Both SVG and WebGL share the exact camera projection parameters:

// kit/gl.mjs GLSL_ISO projection matrix
precision highp float;
uniform vec2 uCanvas;
uniform vec2 uView;
uniform vec2 uOrigin;
uniform float uK;
uniform vec4 uCam; // sinA, cosA, sinE, cosE

vec2 project(vec3 p) {
  return uOrigin + uK * vec2(
    p.x * uCam.x - p.y * uCam.y,
    (p.x * uCam.y + p.y * uCam.x) * uCam.z - p.z * uCam.w
  );
}

vec3 towardViewer() {
  return vec3(uCam.y * uCam.w, uCam.x * uCam.w, uCam.z);
}

Key runtime properties of the shader layer:

• Volumetric ray-marching: Shaders march rays along towardViewer() directly through world coordinates, allowing smoke, exhaust plumes, and caustic light rays to align with physical nozzle rims and beaker edges.
• Resource management: Canvases cap devicePixelRatio at 1.5, pause render loops when scrolled out of view, and provide static SVG fallbacks when WebGL is unavailable or when prefers-reduced-motion is active.

3D rigid kinematics and separating planes

For figures requiring dynamic articulation—such as rotating dials or inspection turntables—Anatomy provides an optional 3D rigid group runtime (kit/turn.mjs and kit/turn-build.mjs).

The runtime supports four kinematic group primitives: turn (continuous rotation), slide (linear travel), hinge (angular rotation within degree bounds), and free (unconstrained matrix translation and tumbling).

Rather than incurring the computational overhead of dynamic Binary Space Partitioning (BSP) trees on every animation frame, turn-build.mjs solves painter’s depth ordering at build time using geometric separating planes. Because the kit’s light source is camera-locked, rotating a turn group by angle $\theta$ around the vertical axis is mathematically equivalent to viewing static geometry at modified azimuth $a – \theta$.

Empirical clearance and collision auditing

A central differentiator of Anatomy is that figures must mathematically verify their own geometric validity. Rather than trusting human eye inspection, builds execute an empirical auditor via kit/audit.mjs.

When a build script runs with node build.mjs --audit, the auditor evaluates every recorded boundary:

• Collision clearance: Verifies that no conduit, wire, or bracket passes through another solid part or structural beam.
• Exploded assembly verification: The auditor evaluates clearance not just at rest, but across all replayed frames and prefix states of an exploded assembly (explodeStates).
• Terminal anchoring: Ensures every pipe, hose, and wire originates on a legitimate mount flange or port, rejecting loose lines hanging in empty space.
• Bend pinch detection: Computes the projected curvature of flexible hoses; if a bend angle produces a visual foldback ($R < 2r / \sin^2(e – \theta)$), the build fails.

# Executing geometry audit on reference figure
node examples/raptor-engine/build.mjs --audit

Headless browser line-end verification

Even with 3D collision checking, SVG line rendering can introduce floating stroke defects. Anatomy includes headless browser automation scripts in scripts/lines.mjs, scripts/capture.mjs, and scripts/drive.mjs.

These tools connect to local Chrome or Chromium instances using direct WebSocket Chrome DevTools Protocol (CDP) commands, bypassing external wrappers like Puppeteer:

• Every open subpath of .iso-line elements must terminate on another stroke, a terminal dot, or pass under an overlapping fill.
• Lines intentionally ending on a flat face (such as dial needles or simulated text rules) must declare explicit data-free attributes.
• scripts/capture.mjs automates high-resolution PNG captures and 4x zoom crops of every mechanical junction in both light and dark themes.

# Validating line terminations across the built SVG figure
node scripts/lines.mjs examples/dial-indicator/dial-indicator.html --tolerance 1

Multi-surface distribution: HTML, React, PDF, and gallery

Anatomy designs figures to be distributed across diverse surfaces without manual redrawing:

1. Standalone HTML: Built via pageHtml with inlined CSS (ISO_CSS) and scripts (kitScript(), glScript()), producing self-contained single-file documents ready for hosting.
2. React 18+ TSX: Provides server-rendered primitives (<Solid>, <Line>, <Wire>, <Plate>) in kit/react/draw.tsx, paired with animation hooks (useLoop, useReadout, spring, follow) in kit/react/live.tsx.
3. Printable Engineering Sheets (A4/Letter): Companion sheet.mjs files define poses, callouts, and explanatory steps. Running node scripts/print.mjs sheet.mjs --format all outputs publication-ready poster, drawing, and multi-page detailed PDF schematics.
4. Community Gallery: Developers run node scripts/publish.mjs <folder> --submit to package and submit figures to wheresryan22/anatomy-community via automated GitHub pull requests.

Adoption decision: selecting the right visual approach

To choose between Anatomy and traditional developer diagramming stacks, evaluate your project’s communication goals against the following criteria:

When an engineering explanation demands clarity without sacrificing physical rigor, Anatomy provides an audited, zero-dependency foundation for turning abstract software architecture into working mechanisms.