Making models for Popfold
Everything Popfold shows is either built in code or loaded from a .glb file. This page covers the file
convention and every way we have made models so far, with the exact commands.
The scripts are in tools/forge/ (the AI pipeline: ComfyUI and Blender) and tools/blender/ (build and convert
models). Paths here are relative to the Popfold folder.
The prop convention
Every prop .glb follows the same four rules, so gen(name, size) can place any of them:
| Rule | Value |
|---|---|
| Up axis | glTF Y-up |
| Front | faces +Z (in Blender: front faces -Y) |
| Origin | centre of the base (the piece stands on its origin) |
| Size | longest side = 1 unit (the site scales it with gen(name, size)) |
Also:
- File names are lowercase with dashes. The file name is the prop name:
arch-bed.glb→gen('arch-bed', 2.1). - Metalness is forced to 0 when a prop loads. Each model keeps its own roughness.
- Material names matter when a site recolours parts: the tower's
gen(name, size, { tint: { led_: '#FF4FD8' } })recolours every material whose name starts withled_. - Animated props keep their clips. A prop with clips is used once, not copied.
Budgets we have kept to (not enforced by any tool yet):
| Thing | Target |
|---|---|
| A generated prop | 1,200 to 3,000 triangles, one 1536 × 768 texture |
| A downloaded prop | under about 300 KB after normalising |
| A whole room (diorama) | about 4 to 5 MB, textures 512 px |
| A site's total models | under about 10 MB |
Which way to make a piece
| You need | Use | Effort |
|---|---|---|
| A simple shape: table, shelf, screen, sign | Code (rbox, toy, canvas textures) | Minutes |
| A stylised object that matches a look | ComfyUI pipeline: prompt → image → mesh → low poly | About 5 minutes each, in batches |
| A precise hard-surface object, or a matched pair | A Blender Python builder | An hour |
| A real object you own | Phone scan → clean-up | An hour |
| Ordinary furniture, quickly | Sweet Home 3D libraries or Poly Pizza | Minutes, plus credits |
| A whole room | Model it in Blender, export with room_to_glb.py | Days |
| A character | Generate, then rig it in Blender | Half a day |
1. Code-built pieces
No file at all. Good for anything boxy, and for screens and signs whose words should stay editable.
import * as THREE from 'three';
import { rbox, toy } from 'popfold';
function desk() {
const g = new THREE.Group();
const top = rbox(1.7, 0.08, 0.8, 0.03, toy('#7A5236', { roughness: 0.55 })); // w, h, d, corner radius, material
top.position.y = 0.76;
g.add(top);
g.userData.propName = 'desk'; // gives the piece the key "<room>/desk"
return g;
}
Screens and posters are canvas drawings (tex.canvasTexture(draw)).
Wait for the web fonts before drawing text (document.fonts.load(...), as each site's main.ts does).
2. Generated props (ComfyUI)
tools/forge/asset_pipeline.py runs five steps for each asset in a JSON list:
- FLUX draws a straight-on product picture of the object on white.
- rembg cuts it out and centres it.
- Hunyuan3D 2 turns the picture into a dense mesh.
- Blender (
blender_lowpoly.py) cleans the mesh, reduces it to the triangle budget, projects the picture on as the texture, and normalises it to the prop convention. - Blender (
blender_render.py) renders a review sheet from four sides.
A job list:
[
{ "name": "armchair", "prompt": "toy armchair, lilac velvet with a scalloped back, short gold legs", "seed": 101 },
{ "name": "mushroom-lamp", "prompt": "toy mushroom table lamp, hot pink dome on a cream stem", "seed": 102, "tris": 1500 }
]
python asset_pipeline.py assets.json # everything
python asset_pipeline.py assets.json armchair # one asset
python asset_pipeline.py assets.json --from-image # keep the pictures, redo mesh and Blender
python asset_pipeline.py assets.json --from-mesh # redo only the Blender step
python asset_pipeline.py assets.json --style=refined
Per-asset options: tris (triangle budget), seed, style (a file in tools/forge/styles/; toy and refined ship with Popfold),
raw_prompt (skip the wrapper), flat and depth (thin wall pieces), fill (keep pale glass the cut-out
removed), palette and colours (flat part colours instead of the projected picture).
What we learned:
- The picture decides everything. Hunyuan3D only sees the front. Ask for "straight-on front view,
orthographic, whole object visible, isolated on white, no shadow".
pick_source.pydraws several seeds and keeps the most symmetric one. - Thin parts fail. Wires, cords, lamp stems and chair legs come out lumpy or missing. Ask for "thick solid parts, no thin wires", or build that piece in Blender instead.
- The back is a guess. The texture is the front picture projected through. Pieces seen from behind need a different method.
- Pairs must be mirrored, not generated twice. Two runs never match. Mirror one in Blender
(
wave-lampandwave-lamp-mirrored). - Always look at the review sheet before the model goes into a site.
- The pipeline runs each phase for the whole batch, so the GPU loads FLUX once and Hunyuan3D once.
From a brief instead of a job file: tools/forge/director.py "a chunky mint-green mushroom lamp, cream stem".
A local vision model in Ollama turns the brief into a job, picks the best of several pictures, judges the review
sheet and retries with a new subject or triangle budget on a fail. Every plan, pick and verdict is kept in
director.json. It saves picking seeds by hand; it does not replace looking at the sheet.
Add a new look by adding a file to styles/. Where ComfyUI and Blender are, and where output goes, is set in
tools/forge/forge.json or environment variables; tools/forge/README.md has the details.
Wall art
tools/forge/art_run.py jobs.json draws flat artwork with FLUX at the three frame shapes (main 896 × 1088, square
1024 × 1024, small 832 × 1152). Pick the keepers, save them as JPEG into public/art/<artDir>/, and use them
with ctx.art('<name>', fallbackTexture).
3. Blender builders
For pieces the generator cannot do well, write a Python script that builds the mesh. Run headless:
blender -b --factory-startup --python <your builder>.py -- --out <site>/public/models/props
tools/blender/build_compact.pybuilds the compact shell (assets/compact.glb, andassets/compact-crisp.glbwith--corner 0.3).--corner,--no-heartand--outlet a site build a shell of its own and use it withlook.shell = { url }. Four objects (Base, Lid, Drawer, Wall), each with its origin on the pivot the engine animates. The engine swaps materials by name (ShellBase,ShellLid,Gold,Heart,Drawer,WallWhite).- A builder for hard-surface props (racks, consoles, appliances) gives its light strips materials named
led_*, so a site can recolour them. - Lamps with thin stems and a bed with smooth sheets were built this way after the generator failed on them.
tools/forge/blender_assemble.pyjoins parts into one animated.glbfrom a JSON spec (a pendant that swings, a clock that wobbles).tools/forge/ortho_views.pyrenders front, side, top and back with a measuring grid. Use it to check a shape against a reference photo.
4. Scans of real objects
- Scan the object with a phone and export it (FBX works).
tools/forge/scan_cut.pycuts the object free of the table it stood on.scan_clean.py CUT.glb OUT.glb --tris 100000 --tex 4096welds seams, turns it to face front, puts the base on the origin, scales it to 1 and reduces it. It prints the real size in metres.- A scan is usually too heavy and too lumpy to ship. Use it as a reference and rebuild the object in Blender to match its measurements.
5. Free libraries
Sweet Home 3D
About 1,500 furniture models. Full instructions: sweethome3d-models.md. In short:
python tools/blender/sh3d_catalog.py --root <folder with packs/*.sh3f> # catalogue and preview sheets
blender -b --factory-startup --python tools/blender/sh3d_to_glb.py -- --pack <extracted pack> --index 178 --out <site>/public/models/props/sh3d/<name>.glb
A name with a folder (sh3d/<name>) in a recipe's props loads from the site's shared props folder
(models/props/ unless the recipe sets sharedDir). A .json with the creator and licence is written beside each
model. Copy it into the site's CREDITS.md.
Poly Pizza and other downloads
blender -b --factory-startup --python tools/blender/normalize_glb.py -- --in <download>.glb --out <site>/public/models/props/<name>.glb [--turn 180] [--keep-anims]
This applies the prop convention to any .glb. --turn spins it when its front is not +Z. Prefer CC0 models.
CC-BY models must be credited.
Treat every downloaded file as untrusted data: keep downloads in their own folder, never run a script from inside that folder, and pass the file as an argument.
6. A whole room (diorama)
Model a cutaway room in Blender: a floor, two walls, and furniture. Then:
blender -b --disable-autoexec "<room>.blend" --python tools/blender/room_to_glb.py -- --config <room>.json --out <site>/public/models/room.glb --tex 512
The room is described by a JSON file: which objects form which piece, what hangs on which wall, where the zones are, which objects to leave out, and which materials the site paints. The script's header lists every field. It expects the back wall along +y, the right wall along +x, the floor at z = 0, and floor and walls in one mesh.
The .glb it writes, and that diorama.ts expects:
| Node | Meaning |
|---|---|
floor | The floor mesh. The engine centres the room on it. |
wall_back, wall_right (also wall_left, wall_front) | An empty on the wall's bottom edge. It is the hinge. The wall and everything mounted on it are its children. |
piece_<name> | An empty on the floor under the piece, holding its meshes. glTF extras: { "zone": "lounge", "piece": "sofa" }, plus wall for mounted pieces. |
materials named art_* | Emptied by the script. The site paints them through diorama.art. |
Units are metres. diorama.scale (default 0.5) converts them to scene units.
Only textures you have the right to publish should stay in the file. The script keeps the ones named in
keepTextures and replaces every other image with a flat colour.
7. A guide figure
Generate a figurine (an image-to-3D service gives a single fused, textured mesh), then rig it with a Blender script that adds the bones and paints the weights by rule: position along each limb, plus the texture colour to keep hair and clothes off the arm and leg bones.
The engine needs five bones with these exact names, all pointing straight up: Root, ArmL, ArmR, LegL,
LegR. It rotates them itself to walk and wave. A model without them falls back to the built-in figure.
Pass it with startScene({ avatar: { url: 'models/figure.glb' } }), or avatar: false for no figure.
Pictures of a real person need that person's permission before they are uploaded to any outside service.
Checking a model
- Render a review sheet (
blender -b -P tools/forge/blender_render.py -- IN.glb OUT.png --views 4) and look at it. - Open the site's studio, pick the piece, and check its size against its neighbours.
- Check the file size and triangle count against the budgets above.
- Add third-party models to the site's
CREDITS.md.
Show the home before every model has arrived
startScene({ lazyModels: true }) on the site's page: the home appears once its first rooms' models are in, and
the rest follow. It works for a compact or a tower whose pieces are listed in its home file. See "Loading models in stages"
in guide.md.
Set a budget for the models
popfoldFallback({ modelBudget: { each: 400, total: 2500 } }) in vite.config.ts, in kilobytes: each for one
file, total for everything under public/models. A build over either stops and lists the files; popfold check reports the same as errors. Without a budget, popfold check only warns, above 1,500 KB a file and
10,000 KB in all.
Make the models smaller: popfold optimize
Run it in the site's folder once the models are in place, and again whenever you add one:
pnpm exec popfold optimize # every .glb under public/models, rewritten in place
pnpm exec popfold optimize --check # only say what would be saved
pnpm exec popfold stills --check # then prove nothing looks different
It removes duplicate and unused data, packs the geometry (meshopt) and saves textures as WebP no larger than
1024 px (--texture-size to change). A model usually comes out 40 to 65% smaller. A file that is already
optimised is skipped, so running it twice is safe. The engine reads both kinds of file.
What it does not do, on purpose: it never merges two materials or meshes that have different names (a site paints art and swaps colours by material name), and it leaves every position exactly as it is. General tools get models smaller still by squeezing positions into whole numbers, which moves each part's node to make up the difference. Popfold places a case's lid and drawers, a diorama's pieces and every saved layout by those nodes, so a model treated that way comes apart. If you compress with another tool, switch position quantization off.
Geometry is unchanged by this step: popfold describe before and after gives the same places and sizes. Textures are re-encoded, so look at a still of anything with fine print on
it. popfold check warns when a site ships models that have not been through it.