Hi all — an interactive 3D field guide to insects, built as a “how far can I get with zero art assets?” experiment.
Live: Insect World — an interactive 3D field guide
Source (MIT): GitHub - xr843/insect-world: Interactive 3D insect field guide: 60 species across 14 orders, every body procedurally generated in the browser with TypeScript + Three.js — no model or texture files in the repo. · GitHub
The constraint: no model files in the repo. Every species’ geometry is generated by TypeScript in the browser at load time.
That turned out to suit the subject. Insect morphology is regular enough to parameterize: head / thorax / abdomen, three pairs of legs and two pairs of wings on the thorax, appendages as tapered segmented tubes, wing membranes carried by radiating veins. Once that kit exists, adding a species means writing proportions and colors rather than sourcing a mesh.
How it is built
- A shared kit: `loft()` over elliptical cross-sections along a body axis, segmented-abdomen envelopes, tapered limb chains, procedural venation, compound eyes
- chitin / velvet / iridescent presets over `MeshPhysicalMaterial` (clearcoat carries the beetle elytra), ACES tone mapping
- 13k–36k triangles per species, 30–90 ms to build; species modules are code-split, so you only download the one you click
- N8AO + bloom are lazy-loaded and desktop-only (103 KB gzip that phones never fetch); `frameloop=“demand”`, and the stage stops rendering entirely once scrolled out of view
Two things that cost me the most time, in case they save someone else’s
1. A winding bug that looked exactly like a material bug. My `loft()` emitted triangle winding inconsistent with the normals it computed. On a closed convex shell you cannot see this — lighting and silhouette are both correct. But wherever two shells overlap, or a shell has an opening, `side: FrontSide` drops those faces and you look straight through the model into the page background. It reads as “the shell has a white crack in it”, so I burned four rounds on materials. What finally found it: render an all-white emissive silhouette from a fixed camera twice — once single-sided, once double-sided — and diff the two silhouettes. The difference is precisely the faces being culled. Ranking every species by that diff exposed six models with the same defect in a single pass. (My first attempt diffed the full-color renders instead; transparency draw-order changes plus AA noise buried the signal at a 36% median difference. Silhouettes only.)
2. Green tests do not mean it looks like the animal. ~4,300 assertions over geometry and data, all passing, while ten of the models simply did not read as insects. Numeric assertions measure ratios and spans — and “wide and flat” is satisfied identically by a flower petal and by a plank. The only gate that catches this is rendering each species from four cameras and actually looking at them.
Beyond the models there is a cross-section view, a layered/exploded view, annotation hotspots the camera flies to, a side-by-side compare mode, and a step-through lesson per species. English and Chinese.
Feedback on the geometry kit or the material setup is very welcome — particularly if anyone has a better approach to procedural wing venation than my current radial-strut one.