Aframe: Add documentation for debugging OBJ/MTL

[donmccurdy]

Pretty sure i've answered this question half a dozen times in slack, but i can't find any permanent FAQ or documentation for it.

Summary of points to cover:

1. Check the console for errors or warnings (CORS, parsing errors, etc.)
2. Open the .mtl file and make sure that paths to textures are relative, not absolute.
3. ???

[donmccurdy]

BEGIN DRAFT

Troubleshooting a 3D model

3D models are created in many different programs, exported to different formats, and often have problems that will show up in some viewers (e.g. A-Frame or THREE.js) but not in the editor that created them (e.g. Blender).

Steps for troubleshooting a 3D model:

1. Open the JavaScript console and check for any errors.
2. If you see an error related to CORS, the file is not correctly hosted. Set up a local server to resolve this, or use a free hosting option like Neocities.
3. Try opening the model in a good native application, like FBX Review. If the model works in FBX Review but not A-Frame, it's likely that something about the model is not supported by THREE.js loaders. Try converting to a different format, or searching for bug reports on the THREE.js issue tracker. If an OBJ, COLLADA, or FBX model cannot be opened in FBX Review, the file is probably corrupt.
4. If there are no errors, but you see nothing: The scale of models are often very, very large in comparison to the camera. They might be 1000 times bigger than the user such that the user is inside the model and cannot see it. Try scaling it down scale=".001 .001 .001" and see where it is. The A-Frame Inspector (ctrl+shift+i) will help with this.

Format-specific issues:

OBJ/MTL — MTL files often have incorrect paths to textures. Open the MTL file in any plaintext editor and look for absolute paths (C:\\foo\bar\baz.png) that should be relative (bar\baz.png).

FBX — THREE.FBXLoader supports only ASCII FBX files, not binary.

---

END DRAFT

Patched together from various SO posts:

• http://stackoverflow.com/questions/40433713/why-does-my-obj-mtl-model-material-show-up-as-black
• http://stackoverflow.com/questions/38740086/why-is-my-model-not-loading-with-a-frame
• http://stackoverflow.com/questions/42149435/a-frame-obj-mtl-why-i-do-not-see-anything

[ngokevin]

Sounds good. We need a standalone guide for Adding Models which this would fit in well.

[paulocf92]

Thanks for your work on this. Sometimes it's hard to make sense why a model isn't showing up correctly, and this will prove really useful. For example, I have a collada model with some squishy stretch marks which may be related to bump/normal maps. I'll remove them tonight and see if the problem persists.

[gurumukhi]

Hi @donmccurdy, if I understand it correctly this issue is open to add a new section on https://aframe.io/docs/0.5.0/introduction/faq.html page, may be right after "Which 3D model formats work?" section?

[donmccurdy]

After I filed this issue, we have added a troubleshooting section to the docs: https://aframe.io/docs/0.5.0/introduction/models.html#troubleshooting

So it's not in the FAQ, but the content is there. I think this can be closed. But we could also add a link to this content from the Why does my asset (e.g., image, video, model) not load? section maybe.