診斷與修復：目標加載失敗

3D 物體跟踪功能高度依賴輸入的 3D 模型質量。當目標模型加載失敗時，EasyAR 會打印詳細的錯誤日誌，幫助開發者定位問題。本章列出常見失敗原因及解決方案，涵蓋材質、紋理、模型文件三類問題。

材質/紋理貼圖文件錯誤

此類錯誤通常由路徑配置或文件格式問題導致。

日誌信息	錯誤原因	解決辦法
Material file not exist	材質文件（.mtl）路徑不存在或未正確引用	檢查模型文件夾中是否存在 .mtl 文件，且 .obj 文件中的 mtllib 路徑指向正確（相對路徑）
Current material has no name	材質定義缺少名稱（newmtl 未指定）	在 .mtl 文件中為每個材質添加名稱，如 newmtl Material1
No texture map exists in material	材質中未指定紋理貼圖（缺少 map_Ka 或 map_Kd）	在 .mtl 文件中添加紋理路徑，如 map_Kd texture.jpg
Read texture map file failed	紋理貼圖文件無法讀取（路徑錯誤、格式不支持）	檢查紋理文件是否在模型文件夾內，格式為 JPG/PNG，且路徑無空格

模型文件錯誤

此類錯誤通常由 OBJ 文件格式不規範或編碼問題導致。

日誌信息	錯誤原因	解決辦法
Error in opening OBJ file	模型文件路徑不存在或權限不足	檢查文件路徑，確保文件可讀
Error in reading OBJ file	文件讀取失敗（編碼非 UTF-8、文件損壞）	用文本編輯器打開 .obj 文件，另存為 UTF-8 編碼格式
Material not exist	面片引用的材質在 .mtl 文件中未找到	檢查 .obj 文件中的 usemtl 字段，確保與 .mtl 中的 newmtl 名稱一致
Vertex format invalid	頂點坐標格式錯誤（v 行數據不符合規範）	檢查 v 格式：v x y z（如 v -4.322898 6.063079 -40.241329），確保為數值
Vertex texture coordinate format invalid	頂點紋理坐標格式錯誤（vt 行數據不符合規範）	檢查 vt 格式：vt u v（如 vt 0.929688 0.094622），確保為 0-1 之間的數值
Face format invalid	面片頂點數小於3（f 行數據無效）	檢查 f 行，確保每個面至少包含3個頂點
Both vertex index and vertex texture coordinate index are required	面片格式錯誤（缺少頂點或紋理索引）	檢查 f 行格式，確保包含頂點和紋理索引（如 f 1/1 2/2 3/3）
Vertex index format invalid	面片頂點索引錯誤（索引超出範圍或非整數）	檢查 f 行中的頂點索引，確保為正整數且不超過頂點總數
Vertex texture coordinate index format invalid	面片頂點紋理坐標索引錯誤	檢查 f 行中的紋理索引，確保為正整數且不超過紋理坐標總數

最佳實踐

遇到加載錯誤時可按照上述表格內的信息做排查。通常而言，您應該遵循以下基本準則：

• 如果您的模型是從專業工具（如 Blender、Maya）中導出的，務必在導出時勾選「寫入材質」和「包含UV」（或類似功能選項），並確保所有文件在同一文件夾內。
• 工具導出的模型文件內部的引用路徑可能是絕對路徑，務必檢查並改成相對路徑，文件名避免使用空格，文件編碼必須為 UTF-8。
• 關於模型格式與規範的詳細要求，參考 模型準備 章節。

提示：若問題仍無法解決，建議將模型文件及錯誤日誌打包，通過 EasyAR 官方論壇或技術支持獲取幫助。