img2threejs Showcase

Build the mesh. Keep the source.

Reference-led 3D studies rebuilt as inspectable, animation-ready Three.js code — running live in the browser.

_{Open a study, orbit the model, inspect its parts, trigger its actions, and follow the source back to the code.}

Gallery · How it works · Contribute · Develop · Community

---

About the showcase

This repository is the public gallery for img2threejs. Each study pairs its reference with a reviewable TypeScript implementation, catalog metadata, and a live Three.js scene. The result is not a sealed render: it is code you can inspect, diff, animate, and extend.

Reference-led Silhouette, proportions, materials, and visible details are measured against the supplied source.

Code-owned Runtime geometry and behavior live in the repository. Demo code cannot depend on remote meshes, CDNs, or network calls.

Animation-ready Named parts, pivots, rigs, contact pairs, and effects are authored for interaction rather than flattened into a single asset.

The catalog keeps honest status metadata: final entries are completed reconstructions; placeholder entries remain visible while their final rebuild is in progress. The live source of truth is src/demos/registry.ts.

Recent studies

Study	What to explore
Ocean Blue PRS Guitar	Measured vertex color and PBR samples preserved in code, six addressable strings, and opt-in water-flow actions.
Groot — Heart of the Forest	A navigable woodland scene with retargeted movement, grounded combat, living-wood effects, and lantern spirits.
Mars Cat	Seventeen measured regions streamed at three quality levels without shipping the reference GLB, textures, or UV atlas.
Starship + Super Heavy	Procedural stainless shells, heat-shield tiles, flaps, grid fins, engine arrays, and a staged separation sequence.

Browse every live study

Gallery snapshots

Sony WF-1000XM3 Open the case, lift both earbuds, spin them through a full turn, and settle them back into place.	Gerber Paracord Knife A stonewashed tanto profile, skeletonized tang, hex pommel, and woven orange cord.
Doraemon House An isometric street diorama with layered roofs, overhead wires, a garden, and animated atmosphere.	War-Hauler “SECTOR 07” A weathered six-wheel hauler with a riveted plow, reactor-lit hubs, and drifting exhaust.

From reference to live study

graph LR
    A[Reference image or measured source] --> B[Analysis and sculpt specification]
    B --> C[TypeScript model factory]
    C --> D[Quality and safety gates]
    D --> E[Interactive Three.js study]

Loading

1. Study the source. Record visible proportions, silhouette, material behavior, and unknown depth.
2. Build in code. Assemble geometry, materials, named parts, and optional actions in a TypeScript factory.
3. Measure the result. Compare the render with the source, document inference, and iterate on the largest visible gaps.
4. Publish the study. Add catalog metadata and a local reference; CI builds the gallery and runs the static safety gate.

For the reconstruction workflow itself, start with the img2threejs repository.

Contributing a study

Have an img2threejs model worth sharing? The repository includes a scaffold command and a purpose-built contribution path.

git clone https://github.com/<your-user>/img2threejs-showcase.git
cd img2threejs-showcase
npm ci

git switch -c add-demo/<id>
npm run new-demo -- <id> "<Title>" object   # or: character

# Add the factory and reference, then complete the generated registry entry.
npm run build
node scripts/check-showcase-safety.mjs --base main

A submission must:

• build its runtime geometry in code without fetching remote meshes, textures, fonts, or scripts;
• include a reference image you have the right to use (.png, .jpg, .jpeg, or .webp, at most 800 KB);
• use a unique kebab-case id and complete every required registry field;
• set status: 'final' once the real implementation replaces the scaffold;
• pass both the production build and the same safety scan used by CI.

Read the full contribution guide before opening a pull request.

Local development

Requirements

• Node.js 20
• npm

Commands

npm ci
npm run dev            # start Vite in development mode
npm run build          # run project checks, TypeScript, and the production build
npm run preview        # serve the production build locally
npm run new-demo -- --help
npm run star-history   # regenerate the chart below; requires GITHUB_TOKEN

The gallery uses hash routes (#/ and #/demo/:id) so direct navigation remains compatible with static hosting.

Repository map

src/
  main.ts                 application bootstrap and route mounting
  content.ts              editorial copy for the gallery shell
  site-data.ts            canonical links, release, sponsor, and roadmap data
  pages/demo.ts           study viewer and information panel
  pages/workbench.ts      inspection and export workbench
  scene.ts                renderer, camera, controls, lighting, and disposal
  exporters.ts            browser-side export flows
  demos/registry.ts       catalog metadata and lazy runtime loaders
  demos/<id>/             one implementation folder per study
public/references/         local source references used by the catalog
scripts/
  new-showcase.mjs         contributor scaffold
  check-showcase-safety.mjs static pull-request safety gate
  generate-star-history.mjs repository-owned star chart generator

Quality gates

Pull requests targeting main run the shared Node 20 quality workflow. The repository adds showcase-specific checks for unsafe network access, reference formats and sizes, catalog ids, and contribution boundaries. Merged changes are deployed automatically.

Community

• Discord — feedback, reconstruction discussion, and work-in-progress studies
• Issue tracker — gallery bugs and showcase submissions
• YouTube · X / @NickDevFE — build logs and releases

Support the project

img2threejs and this gallery are open source. If they save you time, you can support ongoing work through Ko-fi or the project donation page.

Star history

_{Generated in-repository by scripts/generate-star-history.mjs and refreshed daily.}