Skill

Debugging 3D files with 3d-eyes

You have eyes for 3D. The 3d-eyes MCP server renders any mesh or Gaussian splat file so you can look at it instead of guessing from code. Trust what you see in the render plus the JSON report over any assumption.

Workflow

1. Always start with inspect_scene(path). Look at the contact sheet (6 orthographic views + perspective) and read the findings before theorizing.
2. Need a closer look? render_views(path, cameras=[{"azimuth": ..., "elevation": ..., "distance": 1.2}]) - small distance zooms in, ortho: true for exact silhouettes.
3. Fix the problem by editing the user's file or code (trimesh one-liners below).
4. Verify with diff_renders(before, after) and show the user the comparison image. Never claim a fix worked without looking at it.

Symptom → cause table

What you see (or the user reports)	Likely cause	First check	Typical fix
Model renders black / dark in their engine	Flipped normals	Red faces in contact sheet (highlight_backfaces)	mesh.invert() or trimesh.repair.fix_normals(mesh)
Red patches on some sides only	Partially flipped faces	flipped_normals finding says "inconsistent winding"	trimesh.repair.fix_normals(mesh)
Model invisible or microscopic	Scale unit mismatch (mm vs m)	scale_anomaly finding; extents in stats	Scale by 1000 or 0.001 on export
Model gigantic, camera inside it	Same, opposite direction	extents > 1000	Scale by 0.001
Gray/white/magenta untextured surface	Broken texture paths	missing_textures finding lists the files	Fix relative paths or re-export as GLB (embeds textures)
Seams, shading artifacts along an edge	Non-manifold fins	nonmanifold finding	Delete/split extra faces on the offending edges
Raycasts/physics/boolean ops fail on a fine-looking model	Degenerate faces	degenerate_faces finding	mesh.update_faces(mesh.nondegenerate_faces())
Splat scene has blobs floating in mid-air / haze	Training floaters	floaters in the splat report + white specks in renders	Crop by bounding box, prune by opacity, or retrain
File "won't load" anywhere	Corrupt/mislabeled file	inspect_scene returns a parse error report	Follow the error's fix field

Interpreting the contact sheet

• Red triangles (default highlight_backfaces=true) = faces whose winding normal points away from the camera. A closed, correct mesh shows almost no red. Red everywhere = fully inverted; red patches = inconsistent winding.
• Views that look empty at standard distance while stats show geometry = scale or offset problem; check bounds in the report.
• For splats: isolated bright specks away from the subject are floaters; the report's floaters.examples gives their world coordinates for cropping.

Rules of thumb

• Inspect before and after every fix; attach the diff image in your reply.
• The report's symptom fields are written to match what renders show - use them to connect findings to pixels.
• AI-generated assets (Meshy, Tripo, Hunyuan3D, TRELLIS outputs): run inspect_scene as QA before the user ships them - flipped normals and missing textures are the two most common generator defects.
• When the user's engine (Three.js, Unity, Blender) shows a problem that the contact sheet does NOT show, the bug is in their engine setup (lighting, camera, material assignment), not the asset - say so.