Heerich.js builds 3D voxel scenes in JavaScript and projects them directly to SVG. Developers define solid volumes with boxes, carve out spaces, and apply boolean operations. The output lands as clean, vector markup—scalable without pixelation and editable via CSS or DOM scripts.
This matters because most 3D engines rasterize to canvas or WebGL for speed, locking you into fixed resolutions and bitmap artifacts. Heerich sidesteps that. Embed the SVG anywhere in a webpage; zoom infinitely or style strokes and fills on the fly. It suits static diagrams, generative art, or data visualizations where precision trumps frame rates.
The library draws from Erwin Heerich’s sculptures—stacked blocks with precise cuts, balancing mass and void. Think geometric abstraction: a 6x4x3 voxel box renders as tiled paths in SVG, using an oblique camera at 315 degrees and 25-unit distance by default. No ground plane; positions anchor to minimum corners.
Core Setup and Primitives
Instantiate with minimal options: tile size in pixels (default around 30×30), camera settings, and voxel styles like fill ‘#ddd’ or stroke width 0.5. Import from ‘heerich.js’, create new Heerich({tile: [30,30], …}), then call engine.toSVG({padding: 30}). It auto-centers via computed bounds, handling negative coords seamlessly.
Start with addBox({position: [0,0,0], size: [6,4,3]}). This fills a rectangular prism voxel-by-voxel. Alignment demands manual math—no built-in helpers. To center a 2x2x2 box inside 6x6x6: offset by half the difference, like [(6-2)/2, …]. Flush tops? Subtract sizes from the larger one’s dimensions.
Efficiency comes from a dirty-flag cache in getFaces(). Changes trigger rebuilds fast; sliders in demos drag smoothly on modest grids. The engine tracks a 3D grid but projects only visible faces, distilling to 2D paths.
Advanced Operations and Rendering
Intro promises extrusion, negative space carving, and booleans—likely via additional methods like subtract or union, though examples focus on boxes. Voxels form a discrete grid; operations merge or excise them programmatically, like a chisel on code.
Camera defaults to oblique projection, mimicking isometric views without perspective distortion. Output SVG uses viewBox for perfect fit, padding optional. Drop it into innerHTML; it renders instantly. Raw bounds via getViewBoxBounds() let you tweak if needed: {x, y, w, h}.
Skeptical note: “Tiny” claims hold if the source clocks under 10KB minified—plausible for voxel basics. But SVG bloats with complexity; a dense 32x32x32 scene could spawn thousands of paths, choking browsers on mobile. Stick to sparse compositions under 100x100x100 for sanity. No animation loop; it’s fire-and-forget.
Implications for Web Development
Heerich fills a niche: vector 3D for web. Use it for architectural mockups, molecule models, or crypto wallet seed phrase diagrams—anywhere crisp edges and scalability beat raster speed. Pair with D3.js for data-driven voxels; morph sizes by market caps or transaction volumes.
Tradeoffs are clear. Real-time? Go Three.js. But for enduring markup—print-ready PDFs from web, or infinite-zoom infographics—Heerich delivers. It exposes 3D logic as SVG paths, opening doors to post-processing: animate with SMIL, filter with CSS, or export to Illustrator.
In a pixel-saturated web, this pushes vector purity. Test the demos; tweak params live. If your project needs 3D without the GPU tax, download and dissect. Open-source potential shines for extensions: add spheres, lighting hacks, or WebAssembly acceleration.
