gokayfem/image-to-sculpt

What it does

Image 2 Sculpt is a skill for coding agents such as Claude Code, Codex, Cursor, Copilot and Gemini. Given one image, the agent builds a watertight 3D sculpt and fits it to that image's own mask, depth, normals and camera instead of trusting a black-box image-to-3D model. Sides the photo cannot see are filled from generated views that are registered and screened first; one view is held out from fitting and reported separately.

The build is recorded as numbered passes in build/steps/. Blender replays those steps from the photo's camera, produces a 360° turntable and per-view renders, and exports .blend, GLB, OBJ and STL. A timelapse and a per-view map sheet accompany the result, so match quality is shown per view rather than reduced to one number.

It targets AI renders, character or product images, photos of real figurines and statues, cut-out PNGs, and multiple photos of one object. Scenes, hair-thin structures and transparent or mirror materials are stated as out of scope.

Install and run

Requirements are Python 3.10+ with numpy, scipy, scikit-image and Pillow, Blender 5.2+, ffmpeg, and a FAL_KEY for masks, depth, normals and generated views. Run pip install -r requirements.txt for the full dependency set. Check the environment with:

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

Install for Claude Code:

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

Other agents can use skills via npx skills add gokayfem/image-to-sculpt, or copy the skill directory manually. Instructions for agents without skill support are in adapters.

Then scaffold and run a case from the repository root. For example, owl.jpg:

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

run executes every stage after scaffolding. Individual stages such as prep, views, hull, fit, check and blender can also be invoked separately. Outputs live under cases/owl, which is git-ignored.

Constraints and cost

Paid calls (generated views, masks, depth, normals) go through a per-case budget set with --budget, and each request ID is logged to case.json before waiting for a result. The README estimates a typical case at about $2 for 10 generated views plus the photo's maps. Without an API key you can work from a cut-out PNG and your own imported views; front-only input is supported but the unseen shape is inferred.

Inputs are padded, never cropped, to an aspect ratio the view generator supports, and units are normalized per subject. Registration, surface fitting and the exact signed distance field are verified by the test suite:

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

The fast tests take about a minute. The slow run adds an end-to-end synthetic pipeline. CI runs both on Linux without fal, Blender or ffmpeg.

HotRepo's take

On the HotRepo new-project list for 9 November 2026, the repository recorded 105 stars and 4 forks over a growth window that started on 8 November; it has no recorded GitHub all-language daily rank. With only a single snapshot, there is no basis for a trend claim. The technically relevant point is the measurement-first design: per-view checks against the reference image, a held-out view, and recorded passes that Blender can replay distinguish it from a one-shot image-to-3D call, and the synthetic tests cover registration and surface accuracy rather than just output presence.