Table of Contents

Diagnosis and Fix: Target Loading Failure

The 3D object tracking feature depends heavily on the quality of the input 3D model. When target model loading fails, EasyAR prints detailed error logs to help developers locate the issue. This chapter lists common causes and solutions, covering material, texture, and model file issues.

Material/Texture Map File Errors

These errors are usually caused by path configuration or file format issues.

Log Message Error Cause Solution
Material file not exist The material file (.mtl) path does not exist or is not referenced correctly Check whether the .mtl file exists in the model folder and whether the mtllib path in the .obj file points correctly to it as a relative path
Current material has no name The material definition lacks a name (newmtl is not specified) Add a name for each material in the .mtl file, such as newmtl Material1
No texture map exists in material No texture map is specified in the material (map_Ka or map_Kd is missing) Add a texture path in the .mtl file, such as map_Kd texture.jpg
Read texture map file failed The texture map file cannot be read (wrong path or unsupported format) Check that the texture file is inside the model folder, is in JPG/PNG format, and that the path contains no spaces

Model File Errors

These errors are usually caused by non-standard OBJ file format or encoding issues.

Log Message Error Cause Solution
Error in opening OBJ file The model file path does not exist or permissions are insufficient Check the file path and make sure the file is readable
Error in reading OBJ file File read failed (non-UTF-8 encoding or file corruption) Open the .obj file in a text editor and save it as UTF-8 encoding
Material not exist The material referenced by the face is not found in the .mtl file Check the usemtl field in the .obj file and make sure it matches the newmtl name in the .mtl file
Vertex format invalid Vertex coordinate format error (v line data does not comply with the specification) Check the v format: v x y z (for example v -4.322898 6.063079 -40.241329), and make sure all values are numeric
Vertex texture coordinate format invalid Vertex texture coordinate format error (vt line data does not comply with the specification) Check the vt format: vt u v (for example vt 0.929688 0.094622), and make sure the values are between 0 and 1
Face format invalid The face has fewer than 3 vertices (f line data is invalid) Check the f line and make sure 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 make sure it contains vertex and texture indices (for example f 1/1 2/2 3/3)
Vertex index format invalid Face vertex index error (index out of range or not an integer) Check the vertex indices in the f line and make sure they are positive integers not exceeding the total number of vertices
Vertex texture coordinate index format invalid Face vertex texture coordinate index error Check the texture indices in the f line and make sure they are positive integers not exceeding the total number of texture coordinates

Best Practices

When a loading error occurs, troubleshoot according to the information in the tables above. In general, follow these basic guidelines:

  • If your model is exported from professional tools such as Blender or Maya, make sure to select "write materials" and "include UVs" (or similar options) during export, and make sure all files are in the same folder.
  • Reference paths inside model files exported by tools may be absolute paths. Be sure to check and change them to relative paths, avoid spaces in filenames, and ensure the file encoding is UTF-8.
  • For detailed requirements on model format and specifications, see Model Preparation.

Tip: If the issue still cannot be resolved, package the model files and error logs, and get help through the EasyAR official forum or technical support.