Image to Sculpt Lets Your Agent Turn One Image Into a 3D Sculpt

Use this skill when the user gives one image (an AI-generated character, a render, a photo of a figurine or product, a hand-drawn sketch, or just an idea) and wants a 3D model that matches that image. It comes from gokayfem/image-to-sculpt, under the MIT license.

Unlike calling an image-to-3D model directly, it proves whether the result is accurate:

• The faces the photo can see are fitted to the photo's own normals, outline and depth.
• The hidden back and sides are filled with generated multi-angle views. A view is only used after it agrees with the other views.
• Every step is recorded, then replayed in Blender as a time-lapse video, and exported as GLB, OBJ and STL.

When to use

Use it when the user says things like "turn this image into a 3D model", "sculpt this figurine or character", "I need a model I can 3D print", "make a time-lapse video of the sculpting", or "check how far this model is from the original artwork."

Not a good fit:

• Scenes and rooms, fine structures like hair strands, and transparent or mirror materials. Tell the user this before starting.
• Requests with no image that generate 3D from text only. You can first generate one image with imagine, then run the workflow.
• Rigging and animation, PBR textures, and industrial parts that need exact dimensions.

Hard rules

1. State the cost before spending anything. Masks, depth, normals and generated views all use fal's paid endpoints, usually about $2 per model. Tell the user the rough cost before starting, and set a cap with --budget. Write each call's request id to case.json before waiting for the result, and do not resubmit blindly.
2. Never display keys. Keep FAL_KEY only in an environment variable. Do not print it, write it to a file, or put it in a reply.
3. Where the photo can see, the photo wins. Generated views only fill in what the photo cannot see. Do not use their depth, and do not average their normals with the photo's normals.
4. Find the angle of every generated view again, and filter before use. Do not trust the angle that was requested (in tests it was often off by 20 to 155 degrees). Remove any view that does not match the others (a changed pose, an extra arm), and say why.
5. Keep one view for verification. It takes no part in the fit, and its result is reported separately.
6. Show the user an image at every checkpoint. Show the annotated comparison image first, then the numbers. Do not report a bare "quality score" without explaining what it means.
7. Say what is guessed. If there is only a front photo, the back is guessed by the generator. State this when delivering.
8. Do not rewrite the record. Every step goes into build/steps/ and build/log.jsonl. Corrections are added as new steps, and old records are not changed.

Installation

Check first:

ls ~/.claude/skills/image-to-sculpt/SKILL.md ~/.agents/skills/image-to-sculpt/SKILL.md 2>/dev/null || claude plugin list 2>/dev/null | grep -i image-to-sculpt || echo "not installed"

If it is not installed, explain that a Skill and a few Python packages will be installed. After the user agrees:

Agent	Install
Claude Code	claude plugin marketplace add gokayfem/image-to-sculpt, then claude plugin install image-to-sculpt@image-to-sculpt; or copy skills/image-to-sculpt to ~/.claude/skills/
Codex, Cursor, Gemini CLI, Copilot	npx skills add gokayfem/image-to-sculpt
Codex (manual)	Copy skills/image-to-sculpt to ~/.agents/skills/
Gemini CLI (manual)	gemini extensions install https://github.com/gokayfem/image-to-sculpt

Runtime requirements:

• Python 3.10 or newer: pip install -r requirements.txt (numpy, scipy, scikit-image, Pillow, fal-client, matplotlib).
• Blender 5.2 or newer ($BLENDER, blender on the PATH, or the macOS app) and ffmpeg, used for playback and video output.
• The FAL_KEY environment variable, used for masks, depth, normals and generated views. Without a key, you can only use a PNG with an alpha channel plus the user's own photos, or make the front only (the back is then guessed).

Check the setup after installing (this does not print the key):

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

Choose a route by input

Input	What to do
AI-generated or 3D-rendered character, creature, figurine or product	new, then run. This is the main route.
Photo of a real object	new --kind photo, then run. Uses the photo's real focal length and depth to set the scale.
PNG with a transparent channel	Use the transparent channel directly as the mask. This saves one call.
Several things in one image	prep --select "the red dragon" to pick the subject.
Hand-drawn sketch or flat illustration	prep --restyle to convert it to a 3D-render style first, keeping the pose.
Several photos of the same object	views --import DIR, using the photos in place of generated views.
Only an idea	imagine OUT.png "idea" to generate one clean full-body image first.

Workflow

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

--subject is a short noun phrase you write after looking at the image. It goes into every view's prompt. run covers all the steps after new, and each step can also run on its own:

Command	What it does	What to show the user when done
prep	Mask, depth, focal length and normals for the front	ref/front_mask.png, ref/front_normals.png
views	9 generated views by default, plus 1 kept for verification (--set minimal gives only 5)	Each view, pointing out changed poses, extra limbs, and cropped parts
hull	Finds the angle of each view again, filters out views that do not match, carves the main shape, and finds the symmetry plane	The actual angles in case.json and the views that were removed
fit --stage all	Fitting in three stages (forms, surface, detail), with 38 logged fitting passes in total	Comparison image for each view
cut, smooth	Opens the gaps that should exist between fingers, legs, arms and body, and removes webbing and fragments	Before and after comparison images
check	One comparison image and metrics per view (silhouette overlap, silhouette distance, normal angle, roughness, depth)	checks/sheet_*.png
finish, blender, film	Final surface; Blender playback, 360-degree turntable, .blend and GLB/OBJ/STL; time-lapse video and cover image	The time-lapse video and the view comparison sheet
report	out/REPORT.md, out/index.html and a curve for each step	The report

To fix a weak area, target it: parts CASE --prompt "hands" outlines the region, then run fit --stage focus --region hands and cut --region hands. Without before and after comparison images, you cannot say it is fixed.

Reference files

File	When to read it
references/inputs.md	When the input is unusual: masks, restyling, picking a subject, importing photos, or only an idea
references/views.md	Generating, judging, setting angles, filtering and filling in views
references/fitting.md	What each fit does, its parameters, and cut / smooth / focus
references/checking.md	Reading comparison images and metrics, and deciding what to fix next
references/blender-and-delivery.md	Playback, video, export and the report
references/lessons.md	Pitfalls the author ran into, and why the rules above exist

Output format

1. Before starting: which route the input falls under, the expected cost, and any parts beyond what this skill can do.
2. At each checkpoint: an annotated comparison image, followed by the numbers.
3. Delivery: the time-lapse video, the view comparison sheet, the metrics table, the GLB/OBJ/STL paths, which parts the generator guessed, and where the result is still weak. Then stop and let the user decide whether to keep refining.

In one line

State the cost and the limits up front, show an image at every checkpoint, filter generated views before using them, and say which parts were guessed when delivering.