Image to Three.js Agent Workflow Guide

Why the user-owned agent model matters

Image to Three.js is deliberately different from a hosted generation button. A procedural reconstruction is a coding task: the agent must inspect the project, write and run scripts, create a component hierarchy, render the current pass, compare evidence, and revise the source. Running that entire loop inside the user project keeps the agent close to the real codebase and avoids a second remote agent that cannot see local conventions.

The PLAYTEX page therefore behaves like an agent connection surface. It provides one setup prompt, a machine-readable guide, the install command, the expected build stages, and a strict artifact contract. After setup, the conversation continues in the coding agent that already has access to the user project and reference files.

Why a staged sculpt is more reliable than one-shot code

A recognizable model usually fails through accumulation: a slightly wrong silhouette, generic topology, detached appendages, flat materials, missing fasteners, and a camera chosen to hide the weak side. A one-shot prompt can produce many lines of Three.js and still miss the object identity. The staged workflow makes those errors observable before they become expensive.

The quality contract locks the important features first. Blockout proves scale and silhouette. Structure proves hierarchy and attachment. Form adds the characteristic contours. Material work separates albedo, roughness, metalness, normal, and other physical channels. Lighting exposes the form. Interaction adds pivots, sockets, and colliders. Optimization reduces cost without deleting the features that made the object recognizable.

How to ask for a useful revision

A good revision request names the observed mismatch and the evidence view. For example: the top flange is too wide in the three-quarter comparison, the rear housing collapses from the orbit view, or the paint is too glossy compared with the reference crop. The agent should decide whether that means the sculpt spec is wrong or the implementation failed to match a sound spec.

Preserve unrelated parts when revising. Ask the agent to update the factory, spec, result notes, and evidence together. That keeps the artifact set internally consistent and prevents a model from looking revised while its documented hierarchy, material values, or limitations still describe the older version.

Settings Reference

Reference and intent inputs

These inputs determine whether the agent can make honest geometry and which build path it should use.

• Reference image: Defines the visible silhouette, proportions, materials, and identity-defining details that the model must preserve. Use a clear three-quarter view when possible. Add more views when hidden geometry or exact likeness matters.
• Intended use: Changes hierarchy, topology, detail density, pivots, sockets, collision planning, and performance targets. State whether the output is a browser prop, game object, hero render, playable object, destructible asset, or animation rig.
• Quality direction: Sets how much time the agent spends inventorying details, reviewing angles, and correcting mismatches. Use a fast draft for direction, balanced for most real-time assets, and precise when the single reference contains enough detail to justify it.

Quality gates

The workflow separates deterministic checks from visual judgment so weak geometry does not pass on a vague overall score.

• Suitability and reference admission: Rejects unreadable, fragmented, tiny, duplicated, or contradictory references before expensive build work begins. Replace the image when the subject is cropped, blurred, occluded, or too small to support the requested fidelity.
• Quality contract and detail inventory: Names the critical silhouette, material, proportion, attachment, and small-detail targets that must survive every pass. Add explicit priorities when a logo, fastener pattern, contour, appendage, or material finish carries the object identity.
• Multi-angle review: Checks that the result behaves like a volume instead of a flat plane that only works from the reference view. Require more useful orbit angles for complex, organic, asymmetric, or action-ready assets.
• Bounded correction: Stops infinite agent loops by detecting repeated defects, oscillation, plateaus, and hard ceilings. Provide another reference or narrow the fidelity target when the loop correctly reports that the single image is insufficient.

Output contract

A complete run returns source that can be used and inspected, not only a beauty render.

• createModel.ts: Exports a zero-argument-compatible factory that returns a THREE.Group with an editable runtime hierarchy. Ask for project-specific TypeScript style, scale conventions, or material injection without removing the base factory contract.
• object-sculpt-spec.json: Records components, materials, topology choices, attachments, pivots, sockets, passes, and review targets. Revise the spec first when a component, proportion, or material interpretation is wrong rather than patching around it in code.
• Review evidence and result notes: Preserves comparison sheets, scores, assumptions, fidelity, and known limitations for later review. Request more evidence when a critical feature is claimed as complete without a reference-versus-render comparison.

Connect your agent and run the build

Connect your own coding agent to a staged image-to-procedural-Three.js workflow that validates the reference, sculpts in passes, reviews multiple angles, and returns editable source with evidence.

Step 1: Copy the PLAYTEX setup prompt

Open Image to Three.js and copy the setup prompt. It points the agent at the machine-readable PLAYTEX guide, installs the upstream img2threejs skill when needed, and confirms the expected artifact contract.

Open Image to Three.js

Step 2: Install the skill once

Run `npx skills add https://github.com/hoainho/img2threejs --skill img2threejs -g` for a user-wide install. Remove `-g` when the repository should pin its own local copy.

Step 3: Attach one clear reference

Give the agent a readable PNG, JPG, or WEBP image and state the intended use. A real-time browser prop is the default; say when the result must support animation, destruction, close-up rendering, or a stylized character.

Step 4: Let the staged gates run

The agent validates the reference, writes a quality contract, inventories details, creates a strict sculpt spec, builds one pass at a time, compares rendered evidence, and self-corrects within a bounded loop.

Step 5: Review the source and evidence

Use the factory in a Three.js project, inspect the spec and comparison artifacts, and read the fidelity and limitation notes before treating inferred surfaces as authoritative.

Common failure modes

• Do not describe the task as a generic image-to-3D conversion; ask for procedural Three.js source and the full img2threejs quality gates.
• Do not expect a single front view to reveal exact back-side geometry, internal construction, or real-world scale without additional cues.
• Do not accept a render without the TypeScript factory, sculpt spec, comparison evidence, and limitation notes.
• Do not confuse this workflow with photogrammetry, neural mesh extraction, or downloading a stock 3D asset.
• Do not upload confidential references to a hosted service when the local agent workflow already keeps them inside the project.

Does PLAYTEX upload my image or run the coding agent?

No. The current Image to Three.js page gives your own coding agent the setup and build contract. The reference image and generated files stay in your project unless you explicitly send them somewhere else.

Which coding agents are supported?

The upstream skill is agent-agnostic and is designed for Codex, Claude Code, Cursor, OpenCode, and other agents that can read a skill, inspect images, edit files, and run local commands.

Does the result include a GLB or GLTF file?

The canonical output is procedural TypeScript that returns a THREE.Group, plus the sculpt spec and review evidence. Your agent can add an exporter when your project also needs GLB or GLTF, but that is a downstream step rather than the core contract.

Can it reconstruct a person exactly from one photo?

No workflow can guarantee exact hidden geometry or 100 percent likeness from one image. The character path can produce a stylized or projection-assisted reconstruction, but exact likeness needs more views and clear landmarks.

What happens when the reference is not good enough?

The intake gate should report the blocker and request a cleaner image, more views, a narrower target, or accepted stylization instead of inventing confidence.