insect-world: a 3D field guide where every insect is generated in code

What insect-world solves, and who it is actually for

Reference sites in this genre treat each organ as a purchased or scanned GLB asset, roughly 3.2 MB per file according to the README. Insects have no equivalent asset library, so this project took the other route: geometry is generated at runtime in TypeScript, and the repository contains no model or texture files. That single decision shapes the audience. This is for people who want to see how a beetle's elytra, a dragonfly's two wing pairs or a mantis's raptorial forelegs differ structurally, and who are willing to accept a stylised silhouette rather than a photogrammetry-grade specimen. It is also for front-end engineers who want to read a real, non-trivial procedural geometry codebase built on Three.js and react-three-fiber. It is not for anyone who needs a citable entomology reference. The README is blunt on this point: the per-species overviews, key figures, life histories and trivia were written by AI and have not been checked line by line against entomological literature or by specialists. Treat the text as a companion to the shapes, not as a source.

How the geometry pipeline works, and where the milliseconds go

Each species is described parametrically: body split into head, thorax and abdomen, three leg pairs and two wing pairs on the thorax, appendages as segmented tapered tubes, wing surfaces supported by radial veins. Adding a species means writing a size and colour description rather than sourcing a new model. Triangle counts per species run from 13,308 for Culex pipiens pallens up to 35,732 for the Antheraea pernyi moth, and the README reports 30 to 90 ms to build one in the browser. The first insect costs far more, 230 to 730 ms, because the procedural surface textures are shared library-wide and generated once on that first build. The production first-load JavaScript is about 424 KB gzipped, split into a 340 KB vendor chunk dominated by Three.js and an 84 KB main bundle; the 103 KB desktop post-processing pipeline is a lazy chunk that phones never download, and species code is split so a species is fetched only when selected. That is the real architecture constraint: you pay a one-off texture cost, then per-species geometry and code on demand.

Running it locally and taking a first look

The README gives a short install path. Node and npm are assumed; nothing else is required for the main site. Run the install, then the dev server, which the README maps to port 5178.

npm install
npm run dev          # main site  http://localhost:5178
                     # model debug  http://localhost:5178/preview.html

Open the main URL and you get the three-column workbench: species list on the left, the 3D stage in the centre, the detail panel on the right. Click a species, or step through with the up and down arrow keys. Drag to rotate the body, scroll to zoom, and click a coloured dot to read the note for that body part. The preview.html page is the model debug bench, which is the more useful entry point if you intend to modify geometry. There is also a test suite of over 4,000 tests and a build that runs the type checker first.

npm test             # 4000+ tests
npm run build        # tsc --noEmit + vite build

Deployment goes to Cloudflare Pages as static hosting with no backend. The README notes that public/_headers sets hashed assets to a one-year immutable cache while HTML revalidates on every request, so a new release takes effect immediately. A Pages Function at functions/index.ts reads Accept-Language and 302s visitors without a Chinese language tag to /en/, leaving crawlers and visitors with an existing language cookie alone, and the response carries Vary: Accept-Language. The README explains that the functions directory is resolved from the current working directory rather than the deployed directory argument, so npm run deploy, which runs at the repository root, picks it up without changes. To check that redirect locally, the README suggests npx wrangler pages dev dist and curling the root path with different Accept-Language and Cookie headers.

The wingbeat decision: deliberate aliasing instead of physical frequency

Eight species hover in place: dragonflies, damselflies, honey bees, bumblebees, hoverflies, lacewings, hawk moths and crane flies. The README states that dragonfly forewings and hindwings flap in antiphase, which is both why they can hover and the visual cue that identifies a dragonfly at a glance. The frequencies are compressed on purpose. A honey bee beats at a real 230 Hz and a hoverfly at 200 Hz, while a 60 fps display has a Nyquist limit of 30 Hz, so driving the geometry at the true rate would produce aliasing: wings appearing to sweep slowly backwards. The project maps the real values logarithmically into 4 to 12 Hz, preserving the ordering between species. The real frequencies stay in the code's data table with the compression function written next to them. That is a defensible choice, and the README does not pretend otherwise. The same honesty applies to the missing walk cycle: the stage is a turntable with the insect centred, so a walking gait without translation would read as a treadmill. Hovering has no such problem, because hovering is genuinely stationary.

Life cycles, and why there is no morph between stages

Thirteen species have full life-cycle models, 35 stage models in total, opened from the life-history card at the bottom of the stage. Complete metamorphosis is represented by the rhinoceros beetle (grub, then a pupa with horn buds, then the glossy adult), the monarch (banded caterpillar and a green pupa with gold spots hanging from its cremaster), the oak silkmoth (larva plus a longitudinally half-sectioned cocoon showing the brown pupa inside), the western honey bee (every stage inside hexagonal cells, with the pupa's compound eyes colouring before the body), the Chinese firefly (egg, larva and pupa all glowing), the dung beetle (egg and larva inside a brood ball), the seven-spot ladybird (an upright egg cluster, a slate-blue larva with orange spots, and a naked pupa still carrying the shed larval skin at its rear) and the Japanese carpenter ant (a cocoon with a window cut in the side wall). Incomplete metamorphosis is shown for contrast: the cicada nymph with digging forelegs and wing pads, the dragonfly nymph with a foldable mask-like labium, the mantis ootheca and the locust egg pod. The wing pads on a nymph are the visual evidence that wings are still at the bud stage, which is the distinction taught first in school biology. Importantly, the project does not interpolate between stages, and the README gives a biological reason: caterpillar to butterfly is not a continuous transformation, since tissues dissociate and imaginal discs develop. The one continuous animation is adult emergence, because that genuinely is continuous: the freshly emerged wing is a crumpled soft mass that inflates with haemolymph and then hardens. The timing curve is 1-(1-u)³, fast then slow, matching peak haemolymph pressure at the start.

Where it falls short, and what to use instead

The clearest limitation is the text. The README states plainly that the 63 species write-ups are AI-authored and unverified, and asks readers to treat them as light reading rather than citable material. If you need accurate species descriptions with provenance, this is the wrong tool, and no amount of geometry quality fixes that. The second limitation is fidelity: procedural geometry cannot match a 3D scan, and the README concedes the trade-off directly. If your purpose is anatomical reference at specimen resolution, a scanned collection is the better source. A more conventional alternative is a GLB-based viewer built on the same Three.js stack, where each specimen is a purchased or scanned asset loaded with a loader such as GLTFLoader. That approach gives you photogrammetry-grade surfaces and no geometry code to maintain, at the cost of asset weight per specimen, a fixed catalogue that grows only by buying or scanning more models, and no way to derive a larval or pupal stage from the adult description. insect-world inverts every one of those properties. The choice is between asset fidelity with a fixed catalogue and code fidelity with an extensible one.

Maintenance, upgrade cost and licence

The repository is not archived and the last push was on 2026-09-09, eight days before this writing, so the project is current. The only listed release is v0.2.0, tagged 2026-08-18 with the note that the insects started moving, which suggests the life-cycle and animation work landed recently and the API surface is still young. Upgrading is cheap if you track upstream: npm run deploy runs the test suite, the type check, the Vite build and then wrangler pages deploy, and the postdeploy hook submits to IndexNow and prints an inbox summary. The cost you inherit is maintenance of the geometry code itself, plus the Cloudflare Pages and D1 configuration implied by the db:schema and db:seed scripts. The licence is MIT, which is permissive for the code. Note that the repository root contains a separate NOTICE-photos.md, so photographic assets carry their own attribution terms distinct from the MIT grant. That is worth reading before reusing any image, and it is not a legal opinion, just a pointer to the file that governs them. The README also credits a reference site for the information architecture, the three-column workbench, the coloured annotation points, the bottom cards and the top-bar entries, while stating that the implementation is original.

Editorial conclusion

Adopt insect-world if you need a zero-asset reference for how insect body plans differ across orders, or if you want a working example of parametric geometry driving a React Three Fiber scene. Skip it if you need citable entomological text or photoreal specimens, since the README states the 63 species write-ups were AI-authored and not checked against literature. Before building on it, open src/ and confirm how one species description maps to geometry, then read docs/perf-notes.md for the first-frame cost. The MIT licence covers the code; NOTICE-photos.md is the file to read before reusing any imagery.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xr843/insect-world on GitHub