Diagnosis and repair: target loading failed
The 3D object tracking feature heavily relies on the quality of the input 3D model. When the target model fails to load, EasyAR prints detailed error logs to help developers locate the issue. This chapter lists common failure causes and solutions, covering material, texture, and model file issues.
Material/texture map file errors
This type of error is usually caused by path configuration or file format issues.
| Log information | Cause of error | Solution |
|---|---|---|
| Material file not exist | The material file (.mtl) path does not exist or is incorrectly referenced | Check if the .mtl file exists in the model folder, and ensure the mtllib path in the .obj file points correctly (relative path) |
| Current material has no name | Material definition lacks a name (newmtl not specified) |
Add a name for each material in the .mtl file, e.g., newmtl Material1 |
| No texture map exists in material | Texture map not specified in the material (missing map_Ka or map_Kd) |
Add the texture path in the .mtl file, e.g., map_Kd texture.jpg |
| Read texture map file failed | Texture map file cannot be read (incorrect path, unsupported format) | Check if the texture file is in the model folder, in JPG/PNG format, and the path contains no spaces |
Model file errors
This type of error is usually caused by non-standard OBJ file formats or encoding issues.
| Log information | Cause of error | Solution |
|---|---|---|
| Error in opening OBJ file | Model file path does not exist or has insufficient permissions | Check the file path and ensure the file is readable |
| Error in reading OBJ file | File read failure (non-UTF-8 encoding, file corruption) | Open the .obj file with a text editor and save it in UTF-8 encoding format |
| Material not exist | Material referenced by a face is not found in the .mtl file | Check the usemtl field in the .obj file and ensure it matches a newmtl name in the .mtl file |
| Vertex format invalid | Vertex coordinate format error (v line data does not conform to specifications) |
Check v format: v x y z (e.g., v -4.322898 6.063079 -40.241329), ensure it contains numerical values |
| Vertex texture coordinate format invalid | Vertex texture coordinate format error (vt line data does not conform to specifications) |
Check vt format: vt u v (e.g., vt 0.929688 0.094622), ensure values are between 0-1 |
| Face format invalid | Face has fewer than 3 vertices (invalid f line data) |
Check the f line and ensure each face contains at least 3 vertices |
| Both vertex index and vertex texture coordinate index are required | Face format error (missing vertex or texture index) | Check the f line format and ensure it includes vertex and texture indices (e.g., f 1/1 2/2 3/3) |
| Vertex index format invalid | Face vertex index error (index out of range or non-integer) | Check the vertex indices in the f line, ensure they are positive integers and do not exceed the total vertex count |
| Vertex texture coordinate index format invalid | Face vertex texture coordinate index error | Check the texture indices in the f line, ensure they are positive integers and do not exceed the total texture coordinate count |
Best practices
When encountering loading errors, troubleshoot using the information in the tables above. Generally, you should follow these basic guidelines:
- If your model is exported from professional tools (like Blender, Maya), ensure "Write Materials" and "Include UVs" (or similar options) are checked during export, and all files are in the same folder.
- Reference paths inside model files exported by tools might be absolute paths. Check and change them to relative paths. Avoid spaces in filenames. File encoding must be UTF-8.
- For detailed requirements on model formats and specifications, refer to the Model Preparation chapter.
Tip: If the issue persists, package the model files and error logs, and seek assistance via the EasyAR official forum or technical support.