Zdog Pseudo-3D Orbit Scene — Flat-Shaded 3D Canvas

There is a large gap between a flat SVG illustration and a full Three.js scene. Three.js means meshes, materials, lights, a camera, and a WebGL context — a lot of machinery when all you want is a small illustrated object that turns. Zdog occupies exactly that gap: a 2.5kb library that renders genuine 3D geometry into a plain 2D canvas, with a deliberately flat, rounded, hand-illustrated look.

The trick that defines the library

The planet in this scene is created like this:

new Zdog.Shape({ addTo: scene, stroke: 150, color: '#7c3aed' })

That is a Shape with no path at all, which means it is a single point in 3D space. It renders as a sphere because stroke: 150 gives that point a 150-unit-thick round cap. Zdog draws every shape as a stroked path with round line caps and joins, so a point becomes a ball, a line becomes a capsule, and a rectangle becomes a rounded slab.

Understanding that one idea explains the entire library. There is no lighting model, no shading, and no depth buffer — Zdog sorts shapes by their z position and paints them in order. That is also why its aesthetic is so consistent: everything looks like it was drawn with a very fat marker, because it was.

Anchors, and why the scene has a hierarchy

Zdog.Anchor is an invisible transform node — the same idea as an empty group in a 3D editor. Children inherit its rotation and translation, which is what makes the moons work:

var moonOrbit = new Zdog.Anchor({ addTo: scene, rotate: { x: TAU / 4 - 0.9 } });

Both moons are added to moonOrbit and simply translated outward on the x axis. Rotating that anchor on z in the animation loop sweeps them both around a shared orbital plane — no trigonometry per moon, no per-frame position math. Tilting the anchor once on x tilts the entire orbit.

The same principle nests further: the light band on the planet is added to planet rather than scene, so it travels with the planet automatically.

Zdog.TAU is a full turn in radians (2π). Zdog exposes it because virtually every rotation in a 3D scene is naturally expressed as a fraction of a full turn — TAU / 4 for a quarter turn is far more legible than 1.5707963.

The render loop is manual, and cheaper than it looks

illo.updateRenderGraph() does two things: it walks the scene graph applying transforms, and it re-sorts every shape by depth before painting. Nothing appears until it is called, which means a completely static Zdog scene costs zero frames — you call it once and stop. Only because this scene animates does it need a requestAnimationFrame loop.

Drag rotation, and yielding to the user

dragRotate: true gives pointer and touch orbiting for free. The interesting part is the callback:

onDragStart: function () { spinning = false; syncSpinBtn(); }

Auto-spin turns itself off the moment the user grabs the scene. Without this, the object keeps rotating underneath the drag and fights whatever the user is trying to look at — a small courtesy that separates a toy from a control. The button label updates in the same handler so the UI never claims spin is on while it is not.

touch-action: none on the canvas is the CSS half of this. Without it, a touch drag scrolls the page instead of rotating the scene, since the browser claims the gesture before Zdog sees it.

Sizing and sharpness

The canvas carries explicit width and height attributes (480×480) while CSS scales it down with width: min(100%, 420px); height: auto. Rendering at a larger backing size than the display size is a simple way to get crisp edges on high-DPI screens without configuring device pixel ratio manually. Zdog also supports resize: true for a canvas that fills its container, but a fixed backing size keeps the scene's proportions predictable.

The zoom slider writes straight to illo.zoom, which scales the whole illustration around its origin — useful, and something that would require moving a camera in a real 3D engine.

Reusing it

Build scenes from the primitives: Shape for points and paths, Ellipse, Rect, RoundedRect, Polygon, Box, Cylinder, Cone, and Hemisphere. Group anything that should move together under an Anchor. Keep stroke widths generous — thin strokes lose the illustrated character that is the whole reason to choose Zdog over a real 3D engine. When you outgrow it and need lighting or textures, a Three.js product viewer is the next step up; for flat rotation only, CSS 3D cube needs no library at all.