진단 및 수리: 대상 로드 실패
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 공식 포럼 또는 기술 지원을 통해 도움을 받으세요.