When a mesh fails to appear in Three.js after exporting from Blender, the issue typically stems from coordinate system mismatches, missing geometry data, or incorrect camera positioning. Verify that your export settings preserve normals and tangents, ensure the camera is positioned correctly relative to the object's origin, and check the browser console for loading errors. This guide details the specific troubleshooting steps to resolve visibility issues.
Understanding Coordinate System Mismatches
Blender and Three.js use different default coordinate systems, which is the most common cause of invisible meshes. Blender uses a right-handed system where +Z is forward and +Y is up. Three.js also uses a right-handed system but defaults to +Z as forward and +Y as up in its standard setup, though many developers expect +Y up and +Z forward depending on their scene orientation. However, the critical mismatch often occurs during export if the Y-Up axis is not handled correctly by the exporter. If you exported your model using the glTF format, ensure that the "Forward" and "Up" axes match between Blender and your Three.js loader. In Blender’s glTF export settings, verify that the Forward axis is set to -Z (or +Z depending on your specific pipeline) and Up is set to Y. If these do not align with how your Three.jsGLTFLoader interprets the file, the mesh may be rotated 90 degrees or flipped, appearing outside the camera’s view frustum. Always inspect the transform matrix of the loaded object in the Three.js inspector to confirm its orientation matches your expectations.
Verifying Export Settings
To prevent axis confusion, follow these steps when exporting:- Open the glTF/USDZ Export panel in Blender.
- Set the Forward axis to -Z Forward.
- Set the Up axis to Y Up.
- Ensure "Selected Objects" is checked if you only want to export specific items.
- Disable "Apply Modifiers" for animated meshes unless necessary, but keep it enabled for static geometry to bake transformations.
Checking Geometry and Material Properties
Even with correct coordinates, a mesh might remain invisible due to material properties or missing geometry data. A frequent oversight is exporting the mesh without normals or tangents, which can cause shading artifacts or complete invisibility if back-face culling is active. Ensure that your materials are properly assigned and that no textures are broken or returning null values during the load process. Another common issue is scale. If your model was created at a massive scale in Blender (e.g., using real-world meters), it might appear microscopic in Three.js if the scene units are not synchronized. Conversely, a tiny model might be clipped by the near plane of your camera. Adjust thenear and far clipping planes of your PerspectiveCamera to accommodate the size of your imported geometry. For example, if your model is 1 unit wide, set the near plane to 0.001 and far plane to 1000 to ensure it remains visible within the rendering range.
Debugging Camera and Lighting Issues
A perfectly valid mesh will not render if the camera is inside the object or if there is no light source. When working with standard materials likeMeshStandardMaterial, you must have at least one light source in the scene. If you are using MeshBasicMaterial, lighting is irrelevant, but visibility still depends on camera position.
Use the Three.js OrbitControls to manually navigate around the scene after loading the model. If you can see the mesh while orbiting, the initial camera position was simply wrong. Reset your camera to a known good position, such as (0, 5, 10), looking at the origin (0, 0, 0). Additionally, enable wireframe mode temporarily by setting material.wireframe = true to verify that the geometry exists even if the solid surface is not rendering due to lighting or material errors.
Inspecting Browser Console and Network Errors
Sometimes the mesh is not loading at all due to network failures or CORS restrictions. Open the browser developer tools and check the Console tab for any red error messages related to the GLTFLoader or texture loading. If you see CORS errors, ensure your server headers allow cross-origin requests for the model files. Similarly, check the Network tab to confirm that the .glb or .gltf file is returning a 200 OK status and not a 404 Not Found. If the file loads but appears black, check if the ambient light intensity is zero or if the material color is set to transparent. Add a simpleAmbientLight with full intensity to rule out lighting issues entirely. This diagnostic step isolates whether the problem lies in the geometry/data layer or the rendering/shading layer.
Frequently Asked Questions
Why is my mesh black in Three.js?
This usually indicates that no light sources are present in the scene when using physically based materials like MeshStandardMaterial. Add an AmbientLight or DirectionalLight to illuminate the object and verify that the material’s roughness and metalness values are not causing it to absorb all light.
How do I fix a mesh that is rotated incorrectly?
Check the export settings in Blender to ensure the Forward and Up axes match Three.js expectations. You can also programmatically rotate the loaded object using object.rotation.set() or adjust the import logic in your GLTFLoader callback to apply a corrective rotation matrix.
What causes a 404 error when loading a GLB file?
This error means the browser cannot find the file at the specified URL. Verify the file path is correct relative to your HTML file, ensure the file extension is lowercase .glb, and check that your local server is running and serving static files correctly.
Can I use Blender modifiers before exporting?
Yes, but you must apply them if you want the final shape baked into the geometry. Unapplied modifiers will not be exported by default in most formats, resulting in a simplified or incorrect mesh appearance in Three.js.
Why does my mesh disappear when I zoom out?
Your camera’s near or far clipping planes are likely too close or too far for the object’s distance. Increase the far plane value of your PerspectiveCamera to ensure distant objects remain rendered, or decrease the near plane if the object is very close.