图片转 3D 页面（Hunyuan3D + Three.js）

概述

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:

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](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.

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](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:

1. Resolve this skill's installed directory and invoke its bundled scripts by absolute path. Do not assume the current directory is the skill root.
2. 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.
3. Run check_hunyuan_environment.py against the chosen deployment before submitting work.
4. The API listens only on an intended local address and port.
5. The model process uses CUDA; do not mistake download or API startup for inference.
6. 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>scriptscheck_hunyuan_environment.py --project-root <hunyuan-root> --profile mini --require-api --require-cuda
python <skill-root>scriptsgenerate_hunyuan_glb.py --image <input-image> --output <project-root>assetsobject.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](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:

1. Submit the source image and explicit shape/texture parameters without exposing credentials to the browser.
2. Poll asynchronous jobs until a documented terminal state, with bounded retries and timeout.
3. Download the returned GLB to the project asset directory and reject non-GLB bytes.
4. 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>scriptsvalidate_glb.py <project-root>assetsobject.glb
python <skill-root>scriptscreate_scene_manifest.py <project-root>assetsobject.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](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:

1. Check fresh desktop and mobile loads.
2. Confirm the GLB request returns 200, no relevant console errors occur, and the canvas is nonblank.
3. Test orbit, zoom, and resize/orientation framing.
4. 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](references/threejs-delivery.md) for the acceptance checklist and failure triage.