# glyphform
Turn a photo into a living 3D figure drawn entirely in coloured ASCII letters, in the browser.
[](docs/demo.mp4)
*20-second showcase in the rain: [watch the full video (MP4)](docs/demo.mp4).*
From the front it is the photo; turn it and it is a solid you can walk around: fur on the back of the head, a cape flying in the wind, a sword that catches the light, all in letters. Built with TypeScript, three.js and WebGL. No build-time assets beyond the photo.
| paper (default) | scenery | snow | dark |
| --- | --- | --- | --- |
|  |  |  |  |
## Quick start
```bash
npm install
npm run dev
```
Open the printed URL. Drag to turn the knight (180°) and tilt the view. `W` cycles rain, snow and clear; `Space` pauses.
URL options, combined with `&`:
| option | values | |
| --- | --- | --- |
| `#bg=` | `paper` (default), `scene`, `dark` | off-white paper, the photo's own scenery, or plain black |
| `#weather=` | `rain` (default), `snow`, `off` | |
| `#yaw=` | radians, e.g. `0.8` | hold one view (for screenshots) |
```bash
npm run build # type-check and build to dist/
npm run typecheck
```
## How it works
1. **Photo space.** Every measurement is a pixel in the reference photo. `PhotoSpace` maps photo pixels to world units, so the model lines up with the photo from the front.
2. **Proxy model.** The subject is rebuilt from simple shapes (ellipsoids, capsules, cones, extruded outlines) at the photo's coordinates, with real depth.
3. **Photo material.** Surfaces facing the front show the photo, projected straight on; surfaces turning away fade into the part's own lit colour (fur, steel, cream cloth). The photo is pinned to each part's rest pose, so it moves with the part.
4. **Letters.** The scene is rendered small, then every cell becomes one symbol: brightness picks from a 69-step ramp (`· ˙ ' . , : ; ° ∘ ◦ … # ¤ M W & 8 % B @ $`), the silhouette and depth steps become `| / \ - _`, the colour comes from the surface. The last frame fades behind the new one and the brightest letters glow.
5. **Life.** The cape is a Verlet cloth pushed by gusty wind like a sail; the kitten breathes, looks around, blinks, twitches its ears and swishes its tail; a light runs up the blade.
## Project layout
```
src/
engine/ reusable pieces, exported from engine/index.ts
ascii-renderer.ts any three.js scene → coloured letters (dark or paper)
photo-space.ts photo pixels ↔ world units
mask.ts part outlines → mask texture; photo pixel helpers
photo-material.ts photo in front, part colour round the sides; metal shine
shapes.ts blob / limb / cone / slab / pivot, in photo coordinates
cloth.ts Verlet cloth for capes, flags, banners
life.ts blink, twitch, spring, gusty wind
weather.ts rain and snow as letters
backdrop.ts the photo's own scenery, subject painted out
orbit.ts drag to turn (limited), tilt, idle sway
examples/cat-knight/ the complete example
outlines.ts traced outlines and measured points (photo px)
knight.ts the proxy model and its animation
main.ts page setup: renderer, orbit, weather, backdrop
tools/trace.html trace outlines and measure points on any photo
public/cat-knight/ the reference photo
.claude/skills/ the skill for building new components (below)
```
### Engine in brief
```ts
import * as THREE from 'three';
import { AsciiRenderer, DragOrbit, PhotoSpace, fitDistance, maskTexture, photoMaterials, pinPhotoToRestPose, shapes } from './engine';
THREE.ColorManagement.enabled = false;
const ascii = new AsciiRenderer(canvas, { background: 'paper' }); // or 'dark'
const space = new PhotoSpace(photoW, photoH, centreX, groundY); // photo px → world
const mask = maskTexture(photoW, photoH, { r: [bodyOutline] });
const { make } = photoMaterials(space, photoTexture, mask);
const { blob, limb } = shapes(space, group);
blob(space.P(630, 588), [168, 152, 150], make({ base: [0.8, 0.64, 0.5], strands: 1 })); // a furry head
pinPhotoToRestPose(group);
const orbit = new DragOrbit(canvas); // 180° of turning
ascii.renderer.setAnimationLoop(() => {
orbit.update(dt);
orbit.place(camera, centre, fitDistance(camera, halfHeight, halfWidth));
ascii.render(scene, camera, dt);
});
```
Materials tell the letter pass what a pixel is through alpha: `1` the subject (outlined), `0.5–0.9` scenery (letters, no outline), `0` empty.
## Make your own
1. Put a clear, whole-figure photo in `public/<name>/`.
2. Run `npm run dev` and open `/tools/trace.html?img=/<name>/<file>`. Click to trace each part's outline in photo pixels, Shift+click to log single points (eyes, pivots, ear tips). Copy the result into `src/examples/<name>/outlines.ts`.
3. Copy `src/examples/cat-knight`, then rebuild the proxy model for your subject.
4. Check it from the front, ±45° and ±90° (`#yaw=…`).
The skill at [`.claude/skills/ascii-3d-component/SKILL.md`](.claude/skills/ascii-3d-component/SKILL.md) walks through the whole process, with the modelling rules and the pitfalls that come up. Claude Code picks it up automatically in this repo; copy the folder to `~/.claude/skills/` to use it elsewhere.
## Performance
The letter grid is about 4×7 CSS px per cell (a 1440×900 window is ~360×130 letters). The scene renders at 3× the grid, then one full-screen pass draws the letters. On slower GPUs, raise the cell size: `new AsciiRenderer(canvas, { cell: { w: 6, h: 10, font: 10 } })`.
## Licence
Code: MIT. The cat knight photo is a widely shared image of unknown origin, included only to demonstrate the technique; replace it with your own image before publishing anything built from it.