Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
Python 3dai-agentsclaude-codecomputer-graphicsgenerativeimage-to-3dprocedural-generationthreejstypescriptwebgl
Add LICENSE, CONTRIBUTING, and promotion playbook for community outreach
hoainhoa27272dfcaa1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 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/LICENSEnew file mode 100644index 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.mdnew file mode 100644index 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.