Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
title: "Convert a GLB to a GitHub-renderable 3D block" description: "Take any GLB/glTF, OBJ, or binary STL and turn it into an interactive 3D model in your README with one command."
Convert a GLB
You have a model - a GLB from a game asset pack, a Blender export, a 3D scan, an AI generation. This tutorial turns it into an interactive block in your README.
1. Convert
npx readme-3d model.glb
The markdown block prints to stdout, and a summary goes to stderr:
model.glb: 48210 → 1500 facets, 214.8 KB
Pipe it straight into your README, or write a standalone file:
npx readme-3d model.glb >> README.md
npx readme-3d model.glb -o model.md --stl model-ascii.stl
2. Fit your budget
GitHub renders markdown files up to 512 KB. If your README already has content, give the model an explicit byte budget instead of a facet count:
npx readme-3d model.glb --budget 150kb >> README.md
npx readme-3d check README.md
check reports the file's total size, every embedded STL block, and your remaining headroom - and exits non-zero if GitHub would refuse to render it, so you can use it in a pre-commit hook.
3. Tune the result
| Problem | Fix |
|---|---|
| Model lies on its face | source was already Z-up: pass --up z (or --up y to force rotation) |
| Too chunky after simplification | raise --facets, or lower --precision to 1 to spend bytes on triangles instead of decimals |
| Huge README diff | write to a separate file: -o model.md, then link to it |
| Model dwarfed by whitespace | --no-normalize keeps your original coordinates |
| Big block dominates the page | --details wraps it in a collapsed <details> section |
4. What the converter actually does
- Parses GLB/glTF (including Draco- and meshopt-compressed), OBJ, or binary/ASCII STL into a triangle soup, baking every node transform.
- Welds duplicate vertices, prunes tiny disconnected floaters (typical AI-mesh debris), and simplifies with meshoptimizer: the quadric simplifier runs first with a progressively loosened error tolerance, and a topology-ignoring sloppy pass finishes the job when a heavily-disconnected mesh will not collapse cleanly - so your
--facets/--budgettarget is always reached. - Rotates Y-up sources to STL's Z-up convention, normalizes to a compact 100-unit scale, grounds the model at z=0, and centers it.
- Serializes ASCII STL with fixed 2-decimal precision and recomputed facet normals.
Textures and colors are gone - STL is geometry only, and GitHub renders it monochrome. Models with a strong silhouette survive; flat logos and texture-dependent details don't.