Skip to content
Back to search

img2obj

SkillWorks with CodexGitHub

Codex plugin that turns attached object images into code-only, animation-ready procedural Three.js models.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vinhhien112--img2obj/badge.svg)](/listings/vinhhien112--img2obj)

HTML

<a href="/listings/vinhhien112--img2obj"><img src="/api/listings/vinhhien112--img2obj/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the current source:

git clone https://github.com/vinhhien112/img2obj.git
cd img2obj
python3 scripts/sculpt.py --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 179 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # img2obj
  2. Turn a reference image into a quality-gated, animation-ready procedural Three.js object—built entirely with code.
  3. [img2obj](https://github.com/vinhhien112/img2obj) is a Codex plugin that helps analyze an object image, plan its structure, generate procedural Three.js geometry, and review the result against the original reference.
  4. ## Demo
  5. ### Tower Ship
  6. [Open the live Tower Ship demo](https://3dship.harrysoftware.com)
  7. ![Procedural Three.js Tower Ship demo generated from an attached reference image](assets/tower-ship-demo.png)
  8. This study demonstrates procedural geometry, articulated parts, material work, and interactive browser controls.
  9. ### Ancient Autumn Tree
  10. [Open the live Ancient Autumn Tree demo](https://tree.harrysoftware.com/)
  11. ![Procedural Three.js Ancient Autumn Tree reconstructed from an attached reference image](assets/ancient-autumn-tree-demo.png)
  12. This study demonstrates procedural curves, deterministic branching, layered bark, dense foliage, and an animation-ready hierarchy.
  13. ### Cliffside Lantern House — Unreleased Preview
  14. > [!NOTE]
  15. > This is a preview created with an unreleased version of img2obj. It will be updated in future versions.
  16. ![Cliffside Lantern House reconstructed as a procedural Three.js scene with img2obj](assets/cliffside-lantern-house-demo.png)
  17. ## At a Glance
  18. | | |
  19. |---|---|
  20. | **Input** | An attached object image, screenshot, or local image path |
  21. | **Output** | An `ObjectSculptSpec` and a code-only procedural Three.js factory |
  22. | **Goal** | Recreate the visible silhouette, structure, materials, and motion-ready hierarchy |
  23. | **Best for** | Stylized props, mechanical objects, plants, scene assets, and interactive models |
  24. | **Not for** | Photogrammetry, exact mesh extraction, or guaranteed production-ready geometry from one image |
  25. img2obj does not convert pixels directly into a finished mesh. It guides Codex through a controlled reconstruction workflow so that the most recognizable parts of the reference are planned, built, compared, and refined deliberately.
  26. ## How It Works
  27. 1. **Validate the reference** — check image quality, object visibility, complexity, and whether a cleaner source image is needed.
  28. 2. **Plan the object** — describe the component hierarchy, geometry, materials, pivots, sockets, and visual priorities in an `ObjectSculptSpec`.
  29. 3. **Build in phases** — progress through `blockout → form → lookdev → interaction`, keeping later details out of earlier passes.
  30. 4. **Review and refine** — compare browser renders with the active source image, fix the highest-impact differences, and require approval before advancing.
  31. ## Core Capabilities
  32. - Validates whether a reference is suitable for procedural 3D reconstruction.
  33. - Breaks complex objects into assemblies, parts, visible details, and material systems.
  34. - Generates procedural Three.js geometry instead of downloading meshes or art packs.
  35. - Supports hard-surface, organic, vegetation, fabric, glass, hair/fur, emissive, and decal-oriented capability packs.
  36. - Plans pivots, sockets, parent-child relationships, detachable parts, and other animation-ready anchors.
  37. - Extracts reference-derived PBR evidence such as palette, roughness, height, normal, and ambient-occlusion maps.
  38. - Packages reference and render screenshots for visual comparison and quality review.
  39. - Rejects unsupported geometry or unverified corrections instead of silently substituting guessed output.
  40. ## Requirements
  41. - Codex with local plugin support.
  42. - Python 3.10 or newer.
  43. - A browser project using Three.js for the generated object factory.
  44. - AI image and vision access when source cleanup, planning views, or visual review are needed.
  45. ## Install
  46. Clone the current source:
  47. ```bash
  48. git clone https://github.com/vinhhien112/img2obj.git
  49. cd img2obj
  50. python3 scripts/sculpt.py --help
  51. ```
  52. ## Quick Start
  53. After loading the repository as a local Codex plugin, attach an object image and ask:
  54. ```text
  55. Use img2obj to turn the object in this image into a procedural Three.js model built entirely with code.
  56. ```
  57. Add motion requirements only when needed:
  58. ```text
  59. Make the visible hatch open on its hinge. Do not add physics or destruction.
  60. ```
  61. The default workflow validates the image, builds a structured spec, converges the silhouette, adds form and materials, assesses interaction needs, and reviews the final browser render against the reference.
  62. ## CLI Workflow
  63. Use the unified `sculpt.py` entry point for new work:
  64. ```bash
  65. python3 scripts/sculpt.py init "Ancient Autumn Oak" \
  66. --image ./reference/oak-tree.png \
  67. --reference-separation clear \
  68. --complexity complex \
  69. --out object-sculpt-spec.json
  70. python3 scripts/sculpt.py context object-sculpt-spec.json
  71. python3 scripts/sculpt.py validate object-sculpt-spec.json \
  72. --for-pass blockout \
  73. --strict-quality
  74. python3 scripts/sculpt.py generate object-sculpt-spec.json \
  75. --out src/AncientOak.generated.ts \
  76. --wrapper-out src/AncientOak.ts
  77. ```
  78. Run `python3 scripts/sculpt.py --help` to explore comparison, review, correction, capability, probe, and PBR commands. Older individual scripts remain available for compatibility.
  79. ## Quality Model
  80. img2obj evaluates two complementary layers:
  81. - **Overall identity:** silhouette, proportions, camera, materials, and lighting.
  82. - **Critical features:** the small set of parts that makes the object recognizable, such as a roof profile, branch fork, wheel cluster, face, or hand-to-object contact.
  83. A high overall score cannot hide a failed critical feature. Active phases also require visual evidence and explicit user approval before the workflow advances.
  84. ## What img2obj Produces
  85. - A structured `ObjectSculptSpec` describing geometry, materials, hierarchy, motion, and review targets.
  86. - A generated TypeScript factory for the currently unlocked sculpt phase.
  87. - Comparison sheets and evidence manifests for visual review.
  88. - Optional procedural PBR maps and look-development helpers.
  89. - Review history and phase checkpoints for refinement, promotion, or rollback.
  90. ## Limitations
  91. - One image cannot reveal hidden sides or exact dimensions.
  92. - The result is a procedural approximation, not a scanned or extracted mesh.
  93. - Transparent glass, smoke, liquid, fur, fine cloth, and exact likeness may need more references or a lower-fidelity target.
  94. - The generated factory is a construction starting point, not a replacement for a complete production asset pipeline.
  95. - AI vision review is required for visual acceptance; local scripts organize evidence but do not judge similarity by themselves.
  96. ## Project Layout
  97. ```text
  98. .codex-plugin/plugin.json
  99. skills/object-to-threejs-procedural/
  100. scripts/
  101. tests/
  102. assets/
  103. ```
  104. - `skills/object-to-threejs-procedural/` contains the Codex workflow and reference contracts.
  105. - `scripts/sculpt.py` is the recommended command entry point.
  106. - `scripts/` contains validators, generators, visual-review tools, and compatibility commands.
  107. - `tests/` contains the Python regression suite.
  108. ## Development
  109. Run the test suite after changing workflow contracts or scripts:
  110. ```bash
  111. python3 -m unittest discover -s tests
  112. ```
  113. Reload the local plugin after changing its skill, scripts, or manifest so a new Codex task receives the latest version.
  114. ## Support
  115. If img2obj is useful to you, you can support its continued development:
  116. <a href="https://ko-fi.com/harrynguyen112">
  117. <img height="36" src="https://storage.ko-fi.com/cdn/kofi6.png?v=6" alt="Buy Me a Coffee on Ko-fi">
  118. </a>
  119. ## License
  120. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.