Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

Add LICENSE, CONTRIBUTING, and promotion playbook for community outreach

hoainhoa27272dfcaa1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9e93cb0
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,43 @@
+# Contributing to img2threejs
+
+Thanks for your interest. img2threejs turns a reference image into a code-only, procedural,
+quality-gated Three.js model. Contributions that keep that identity sharp are very welcome.
+
+## Good first areas
+
+- New procedural material or geometry recipes in `references/procedural-patterns.md`.
+- Object-domain templates and detail-inventory taxonomy improvements.
+- Generator primitives, bevels, instancing, and surface-band tuning in `scripts/generate_threejs_factory.py`.
+- More pipeline tests in `scripts/tests/test_pipeline.py`.
+- Documentation and worked examples.
+
+## Where the project is strong vs honest limits
+
+- Strong: hard-surface objects, props, stylized/low-poly assets.
+- Stylized-only: characters and creatures read as game/figurine avatars, not photoreal likeness.
+- Out of scope today: photoreal reconstruction of a specific person, animal, or landscape from a
+ single image. That needs photo-texture projection or ML image-to-3D, which breaks the code-only
+ promise. See `docs/UPGRADE_PLAN.md` for the analysis and the tiered roadmap.
+
+Please do not add code that silently downloads meshes or art packs — the core promise is
+reconstruction by code. If you want a projection or generative-assist path, propose it as an
+explicit, flagged, opt-in mode.
+
+## Development
+
+- Scripts are pure Python 3.10+ standard library. No pip dependencies.
+- Run the test suite from the skill root: `python3 scripts/tests/test_pipeline.py`.
+- Validate a spec before generation: `python3 scripts/validate_sculpt_spec.py spec.json --strict-quality`.
+- Keep changes backward compatible: existing object specs must continue to validate.
+- No emojis in source, docs, or generated output.
+
+## Pull requests
+
+- Keep PRs focused and describe the behavior change plus how you verified it.
+- Add or update tests for new gates, schema fields, or templates.
+- Update `docs/UPGRADE_PLAN.md` status when you land a roadmap item.
+
+## Reporting issues
+
+Include the reference image characteristics, the command you ran, the spec or generated output,
+and what you expected versus what you got. Screenshots of the render help a lot.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..97f6660
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hoainho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/PROMOTION.md b/docs/PROMOTION.md
new file mode 100644
index 0000000..061cae4
--- /dev/null
+++ b/docs/PROMOTION.md
@@ -0,0 +1,94 @@
+# Promotion playbook (attract stars and contributors, without spamming)
+
+This is copy you post from your own accounts. It is deliberately honest about scope so the
+project earns trust instead of a spam label. Repo: https://github.com/hoainho/img2threejs
+
+## Ground rules (read first)
+
+- Do NOT open issues or pull requests on three.js, react-three-fiber, or other libraries just to
+ advertise this project. That is spam, gets closed, and damages your reputation.
+- DO post in venues that exist for showing work, and DO submit to curated lists that accept
+ entries. Post once per venue, respond to comments, do not cross-post aggressively.
+- Lead with an honest scope line every time: strong for objects, stylized-only for characters.
+ The demo GIF is a chest (its strongest result), not a person.
+
+## 1. three.js Discourse — Showcase category
+
+Venue: https://discourse.threejs.org/ (category: Showcase)
+
+Title: img2threejs - rebuild an object photo as a code-only procedural Three.js model
+
+Body:
+> I built a skill/toolkit that reconstructs the object in a single reference image as a
+> code-only, procedural Three.js model - primitives, procedural shaders, and generated geometry,
+> no downloaded meshes or art packs. It runs a staged pipeline (blockout, structure, form,
+> material, lighting) with a screenshot-vs-reference review loop at each step.
+>
+> Honest scope: it is strong for hard-surface objects and stylized/low-poly assets. Characters
+> currently read as game/figurine avatars, not photoreal likeness - that is a documented limit.
+>
+> Repo (MIT, pure-Python stdlib tooling + generated TypeScript): https://github.com/hoainho/img2threejs
+> Feedback and contributors welcome, especially on procedural material recipes.
+
+## 2. Reddit - r/threejs and r/webgl
+
+Title: img2threejs: turn an object photo into a procedural, code-only Three.js model (MIT)
+
+Body:
+> Open-source toolkit that rebuilds the object in one reference image as procedural Three.js code
+> (no mesh downloads), gated by a staged pipeline with a render-vs-reference review loop. Strong
+> for hard-surface objects; characters are stylized-only for now (documented). Would love feedback
+> and contributors. Repo: https://github.com/hoainho/img2threejs
+
+Flair: Showcase / Project. Post to r/threejs first; wait a day before r/webgl.
+
+## 3. Hacker News - Show HN
+
+Title: Show HN: img2threejs - rebuild an object photo as procedural Three.js code
+
+Text:
+> It reconstructs the object in a single image as a code-only procedural Three.js model, gated by
+> a staged pipeline (blockout to material to lighting) with a screenshot-vs-reference review loop.
+> Pure-Python stdlib tooling emits diffable TypeScript; no downloaded meshes. Honest about limits:
+> great for hard-surface objects, stylized-only for people. MIT. Feedback welcome.
+> https://github.com/hoainho/img2threejs
+
+Post during US morning (weekday) for visibility. Reply to every comment.
+
+## 4. Short social post (X / Bluesky / Mastodon)
+
+> img2threejs: give it one photo of an object, get back a code-only procedural Three.js model -
+> no mesh downloads, quality-gated by a render-vs-reference loop. MIT, contributors welcome.
+> https://github.com/hoainho/img2threejs
+
+Attach the demo GIF (assets/demo.gif).
+
+## 5. Awesome-list submission (the welcomed "contribute to a known repo" path)
+
+Candidate lists (verify each list's contribution rules and that the project fits before opening a PR):
+- awesome-threejs
+- awesome-webgl
+- awesome-creative-coding (procedural-generation section)
+
+Entry line to add (match the list's existing format):
+> - [img2threejs](https://github.com/hoainho/img2threejs) - Rebuild the object in a reference image as a code-only, procedural, quality-gated Three.js model.
+
+PR description:
+> Adds img2threejs, an MIT-licensed toolkit that reconstructs an object photo as procedural
+> Three.js code (no downloaded assets), with a staged review pipeline. Placed under the
+> tools/generators section. Happy to adjust wording or placement.
+
+Submit from your own GitHub account, one list at a time, and follow each list's CONTRIBUTING rules.
+
+## 6. Make the repo itself convert visitors
+
+- Topics set: threejs, webgl, 3d, procedural-generation, image-to-3d, generative, typescript, computer-graphics, ai-agents, claude-code.
+- README opens with the demo GIF and an honest scope line. Done.
+- LICENSE and CONTRIBUTING present. Done.
+- Consider a hosted live demo later (the chest project) and link it as the repo homepage - a
+ clickable demo converts far better than a GIF.
+
+## Metrics to watch
+
+- Where stars come from (GitHub traffic - referrers). Double down on the venue that converts.
+- Issues/PRs opened - reply within a day to keep momentum and turn visitors into contributors.