By peter_lzh img2threejs: The AI Skill That Turns a Single Photo Into an Interactive Three.js 3D Model — 5.3K Stars in 11 Days
Browsing GitHub Trending yesterday, I stumbled on a repository created on July 15 that racked up 5,300 stars in just 11 days: img2threejs, an AI skill that converts a single image into an interactive 3D model — as code, not a mesh.
I’d normally be immune to the image-to-3D pitch. The past two years have been full of projects promising 3D from one photo, and they invariably turn out to be cloud API wrappers or spit out multi-megabyte mesh files of wildly variable quality.
This one is different. The README opens with the key claim: it doesn’t generate meshes, it generates code. Feed it a reference photo and it outputs TypeScript — a Three.js model factory function that runs directly in the browser. Now that got my attention.
What This Project Is
img2threejs is a skill that runs inside Claude Code, Codex, or OpenCode. Usage in one sentence: give it a photo of an object, and it rebuilds that object in code using primitive geometry and procedural shaders.
The result isn’t a dead model. It carries a complete runtime hierarchy — joints, attachment points, and colliders — ready for animation rigging out of the box.
The official gallery shows a dozen finished pieces: CS2’s Glock-18, the M9 Bayonet, the Classic Knife, Sony WF-1000XM3 earbuds with their charging case, a BMX bike, even a Doraemon-style house. All of them spin in the browser, and the generated source code is public.
What It Can Actually Do
Photo In, Code Out
Typical image-to-3D tools give you a mesh file — uneditable and unreadable. img2threejs gives you a TypeScript factory function returning a THREE.Group.
The model is text: it diffs, it goes into git, and changing a color means editing a line of code — no Blender required.
Output comes in two parts: a JSON spec documenting the component tree, materials, attachment points, and review records for every stage; plus the factory code. No binary files anywhere in the pipeline — the Gerber paracord knife in the official demo is a whole model with zero mesh files, just TypeScript.
Animation-Ready From Day One
AI-generated 3D models share a chronic flaw: handles, wheels, and other parts float detached from the body, which you only discover at render time.
This project requires every child part to declare how it connects to its parent. Models expose joints, attachment points, colliders, and destruction groups via root.userData.sculptRuntime. The official term is “animation-ready”; in plain language: not a static ornament, but something you can rig.
Eight Stages, No Skipping Quality Gates
This is the part that impressed me most. Instead of one-shot generation, modeling is split into eight fixed stages: blocking, structure, silhouette correction, materials, surface detail, lighting, interaction, and optimization.
After each stage, the model must be rendered, composited side-by-side with the reference photo, and scored by the agent’s vision capability. Fail the score and there are two outcomes: the spec was too shallow — go revise the spec; or the code didn’t match the spec — go fix the code. Until the gate passes, the next stage stays locked.
Any developer will recognize this: it’s a Code Review pipeline bolted onto AI modeling. I’ve seen plenty of one-shot AI projects; ones that voluntarily install quality gates are rare.
Massive Token Savings
All the mechanical work — validation, image cropping, comparison-sheet assembly, pipeline state — is offloaded to Python scripts. Pure standard library, runs on Python 3.10+, zero dependencies; even PNG reading and writing is hand-rolled with struct and zlib.
The LLM’s tokens are spent on exactly one job: looking at a comparison image and judging pass or fail. The code generator also emits only the currently unlocked stage, so the model never has to re-read the entire codebase.
CS2 Weapons Are Its Home Turf
Version 1.4 is literally called “The Weapon Update,” with dedicated support for CS2 weapon skins — three of the gallery pieces are CS2 weapons.
The author even defined separate structural contracts for knives and the Glock: insufficient part coverage or textures masquerading as structure get blocked at review. CS2 players can screenshot skins from their inventory and rebuild them as browser-spinnable models.
Characters work too, via a separate anatomy track with constraints on head-to-body proportions, facial landmarks, and pose. The author is upfront that characters are stylized reconstructions — don’t expect photorealistic likeness.
Two Commands to Get Started
Clone the repository into Claude Code’s skills directory, then paste an image into Claude Code and invoke the skill. The rest runs itself: classifying the object, inventorying details, advancing stage by stage, showing you a comparison sheet at every step.
Codex and OpenCode work the same way — it isn’t host-locked, and the “agent vision” in the docs is just each host’s built-in image understanding. The scripts need only Python 3.10+, zero dependencies, nothing to install.
Where You Can Use It
A few uses I can immediately see:
3D showcases for product or landing pages. The Sony earbuds demo is the template answer: no 3D artist needed — one product photo in, a rotatable model out, pure code, lightning-fast to load.
Game prototyping. Placeholder models ship with attachment points and colliders — good enough for the prototype phase, swap in art assets later.
CS2 fan projects. Turn skins into web 3D for your profile page — classier than screenshots.
Demo presentations. Embedding a real object as interactive 3D beats PPT screenshots. The Doraemon house is a great example: one illustration in, one spinnable little house out.
My Take
Cold water first: a single photo can’t show the back of an object. Occlusion is unsolvable, and unseen faces are inferred by mirroring. The author says it plainly in the README: “this image can’t reach the required fidelity” is a normal outcome.
Now the good part. The project’s value isn’t “AI can sculpt 3D” — it’s that quality control became a process. Eight stages, comparison-sheet scoring, rejection and rework: this turns AI generation from a gacha pull into engineering. The token economy follows the same logic — scripts do the mechanical work, the model only looks at images and judges.
I’m very bullish on this direction; this is exactly the kind of work AI should be doing. The roadmap runs all the way to v2.0 — environment reconstruction, Unity and Unreal export, and auto-rigging are all on the list. With 5.3K stars in 11 days, this is bound to be the next breakout project.
Open-Source Repository
GitHub: github.com/hoainho/img2threejs