gokayfem/image-to-sculpt

Turn one image of anything into a 3D sculpt measured against that image: registered views, map-fitting passes, Blender replay and timelapse. A skill for coding agents

Summary

gokayfem/image-to-sculpt is a Python-based skill for coding agents that reconstructs a 3D sculpt from an image while measuring the result against that image’s outline, normals, depth, and camera. It registers generated or imported views, rejects inconsistent views, reserves one view for independent checking, and records each modeling pass so Blender can replay the build.

What it is useful for

This workflow is useful when an engineer needs an inspectable 3D starting point from concept art, a character render, a product photo, a figurine image, or a transparent PNG. The source image governs visible surfaces, while additional views help complete unseen sides.

For example, an engineer can:

• Import four photographs of a statue with views --import DIR instead of relying on generated views.
• Compare the sculpt against each view using silhouette IoU, outline distance, normal angle, roughness, and source-image depth.
• Keep one view out of fitting so its agreement is reported separately.
• Review every intermediate cut and map-fitting pass rather than receiving only a final mesh.
• Replay the process in Blender and export GLB, OBJ, or STL files.

The project is aimed at agents such as Claude Code, Codex, Cursor, Copilot, and Gemini. It also exposes individual stages for preparation, view generation, fitting, cleanup, checking, reporting, Blender rendering, and film generation.

How engineers can use it

For agents that support the skills format, the README documents:

npx skills add gokayfem/image-to-sculpt

Claude Code users can instead run:

claude plugin marketplace add gokayfem/image-to-sculpt
claude plugin install image-to-sculpt@image-to-sculpt

The documented prerequisites are Python 3.10+, Blender 5.2+, ffmpeg, and a fal API key in FAL_KEY. Python dependencies can be installed with:

pip install -r requirements.txt

Check the local environment with:

python3 skills/image-to-sculpt/scripts/i2s.py doctor

A typical case begins with a subject description and input image:

python3 skills/image-to-sculpt/scripts/i2s.py new cases/owl --input owl.jpg --subject "carved wooden owl figurine"
python3 skills/image-to-sculpt/scripts/i2s.py run cases/owl

The run command executes the stages after scaffolding. Individual commands such as prep, views, fit, check, finish, blender, and report can also be run when iteration is needed. Paid requests are controlled through a per-case --budget, and request IDs are recorded before results are awaited.

The repository also documents fast and slow test runs:

python3 tests/run_tests.py
python3 tests/run_tests.py --slow

The README explicitly excludes scenes and rooms, hair-thin structures, and transparent or mirror materials. Without an API key, the supported fallback is a cut-out PNG with your own views, or front-only reconstruction with a guessed depth and inflated silhouette.