Image To Three.js With Hunyuan
Build the asset pipeline in separate gates: input, generation, asset validation, scene composition, and browser verification. Never describe a model inferred from one image as a metric reconstruction.
Choose The Provider And Mode
Choose and record the provider before generation:
| Provider | Use when | Cost and runtime |
|---|---|---|
local-free |
Default, or when the user says local/free/offline | Local Hunyuan3D-2mini; no cloud key; GPU required for practical inference |
hunyuan-cloud |
Only when the user asks for paid/cloud quality or supplies an endpoint and credential | User-configured Tencent Hunyuan 3D API; usage may incur fees; all calls stay server-side |
Do not switch to cloud generation merely because local inference is slow or fails. If hunyuan-cloud is requested without an endpoint contract, ask for the official API documentation or a working curl example before submitting an image. Never guess a Tencent endpoint, request signing scheme, model id, or billing parameter.
Read references/hunyuan-cloud.md before configuring the paid provider. Keep the API key in an environment variable or the user's credential vault, never in source, scene.json, browser code, screenshots, or command output.
| Input | Mode | Hunyuan choice |
|---|---|---|
| One foreground object image | single-asset |
Hunyuan3D-2mini by default; standard Hunyuan3D-2 shape generation when its weights and VRAM are available |
| 4-12 consistent views of one object | multiview-asset |
Use a multiview Hunyuan model; preserve order |
| Existing GLB/GLTF | asset-viewer |
Skip generation; validate and present |
| Broad environment coverage | scene-reconstruction |
Do not send it to this GLB workflow |
Inspect every image first. For a single image, identify background contamination, watermarks, severe occlusion, and whether the subject is complete. Request clean foreground imagery or a turntable set when the source cannot support the desired geometry.
Local-Free Hunyuan Gate
Read references/hunyuan-local.md before starting or repairing Hunyuan. Keep the user's model weights, Hub cache, U2NET and output files outside the skill package and browser bundle.
Before generating, verify all of these:
- Resolve this skill's installed directory and invoke its bundled scripts by absolute path. Do not assume the current directory is the skill root.
- Ask for or discover the user's local Hunyuan3D deployment root; do not hard-code a drive letter or package that deployment, model weights, caches, generated assets, or logs.
- Run
check_hunyuan_environment.pyagainst the chosen deployment before submitting work. - The API listens only on an intended local address and port.
- The model process uses CUDA; do not mistake download or API startup for inference.
- The input image is readable and the output destination is outside the source-model directory.
For example, after resolving <skill-root> and <hunyuan-root> for this installation:
python <skill-root>\scripts\check_hunyuan_environment.py --project-root <hunyuan-root> --profile mini --require-api --require-cuda
python <skill-root>\scripts\generate_hunyuan_glb.py --image <input-image> --output <project-root>\assets\object.glb
Pass --texture only when the server was started with its texture pipeline enabled and has enough VRAM. Read the texture section in references/hunyuan-local.md first.
Hunyuan Cloud Gate
When provider=hunyuan-cloud, implement the user's official provider contract in a server-side adapter. The adapter must:
- Submit the source image and explicit shape/texture parameters without exposing credentials to the browser.
- Poll asynchronous jobs until a documented terminal state, with bounded retries and timeout.
- Download the returned GLB to the project asset directory and reject non-GLB bytes.
- Remove temporary signed URLs and request payloads from logs after download.
Keep the cloud adapter separate from the browser viewer. The browser receives only the downloaded GLB and a non-secret manifest. If the cloud API returns a textured GLB, preserve its authored PBR materials; if it returns shape-only geometry, label the viewer as untextured and apply only an intentional preview material.
Asset Gate
Validate every generated GLB before adding it to a page:
python <skill-root>\scripts\validate_glb.py <project-root>\assets\object.glb
python <skill-root>\scripts\create_scene_manifest.py <project-root>\assets\object.glb --source <input-image> --output <project-root>\scene.json
For multiview-asset, repeat --source in the supplied view order and pass --mode multiview-asset.
Reject an asset with no mesh, no faces, non-finite bounds, or a non-GLB response accidentally saved from an API error. Preserve the unmodified generated GLB when optimization is destructive.
Compose The Viewer
Read references/threejs-delivery.md while writing the page.
Use GLTFLoader, preserve authored PBR materials, center the model on X/Z, rest it on Y=0, and derive camera planes, orbit distances, floor size, and shadow camera from the loaded world bounds. Implement loading, error, resize, and disposal states. Use a neutral studio preset: environment contribution, key light, gentle fill, shadow receiver, and a rim light only when it improves silhouette separation.
Keep provider code and input images out of browser runtime logic. Store only public GLB assets and a non-secret scene.json in the project.
Verify
Use a real browser after the page is served:
- Check fresh desktop and mobile loads.
- Confirm the GLB request returns
200, no relevant console errors occur, and the canvas is nonblank. - Test orbit, zoom, and resize/orientation framing.
- Capture desktop and mobile screenshots and record the result in
scene.json.
Treat incorrect one-image geometry as an input-coverage limitation, not a Three.js lighting bug. Read references/threejs-delivery.md for the acceptance checklist and failure triage.
