Table of Contents

3D model preparation and optimization

This article details how to prepare 3D models that meet EasyAR requirements, covering format specifications, tool recommendations, and common troubleshooting, helping developers improve tracking success rates from the source.

Model format and specifications

EasyAR 3D object tracking only supports the Wavefront OBJ format. The following requirements and specifications must be followed.

Model file structure

A complete 3D model must include the following files:

  • .obj file: Geometric model data (including vertices, faces, UV coordinates, etc.).
  • .mtl file: Material definitions (colors, texture map paths).
  • Texture maps: At least one JPEG or PNG format image (recommended resolution 512×512 to 2048×2048).

File requirements

  • All files must be in the same folder and referenced using relative paths (e.g., texture.jpg). Absolute paths (e.g., C:\Models\texture.jpg) are prohibited.
  • File names and internal paths must not contain spaces. Use English or numbers.
  • File encoding must be UTF-8 (to avoid loading failures due to garbled characters).

OBJ (.obj) file minimum requirements

  • Must include vertex
    Geometric vertices, represented by \((x, y, z [, w])\) coordinates. \(w\) is optional and defaults to 1.0. Vertex color parameters are not required and will not be loaded by the system if provided.
  • Must include texture coordinates
    Texture coordinates, represented by \((u, v [,w])\) coordinates. \(w\) is optional and defaults to 0. Typically, \(u\) and \(v\) values should be between 0 and 1. For values less than 0 or greater than 1, the system defaults to REPEAT mode (ignoring the integer part of the coordinate, creating an infinitely tiled pattern, identical to GL_REPEAT in OpenGL).
  • Must include face
    Face elements must include at least vertex indices and texture coordinate indices. Polygons with more than 3 vertices (e.g., quadrilaterals) are supported.
  • Must include mtllib
    Reference to a material file. At least one external MTL material file must be specified using a relative path (absolute paths are prohibited).
  • Must include usemtl
    The material name referenced by model elements must match the material name defined in the external MTL file.

MTL (.mtl) file minimum requirements

  • An MTL file must define at least one material.
  • Texture maps are mandatory.
    Typically, only ambient or diffuse texture maps (map_Ka, map_Kd) need to be specified.
    Texture map paths must be relative (absolute paths are prohibited).
  • Other optional texture map parameters are not required and will be ignored by the system if provided.

Model preparation

You can prepare compliant OBJ-format model files through various methods.

  1. Export from existing models
    Use professional tools like Autodesk Maya / 3ds Max to import existing FBX or other format models. Select "OBJ Export" during export and ensure "Materials" and "UVs" options are enabled.

  2. Create new models
    Use modeling tools like Autodesk Maya / 3ds Max to create/draw 3D models and export them in OBJ format.

  3. Scan real objects and perform 3D reconstruction
    Use 3D scanning software like Autodesk ReCap, Bentley ContextCapture, or laser scanners to perform 3D reconstruction of real objects. Export the reconstruction results in OBJ format.

Important

Model textures must accurately reproduce the visual characteristics of real objects; otherwise, recognition and tracking functions will fail.

Model best practices

Common issues and examples encountered during model preparation are listed below for quick reference and verification.

  1. Ensure rich texture details
    The model's textures should have rich texture details.

    Left: Can be detected and tracked by EasyAR. Right: Cannot be detected or tracked due to insufficient texture.

  2. Model shape
    Models support different shapes, but the main structure should be convex.

    Both objects can be detected and tracked by EasyAR.

  3. Check referenced paths in files
    Paths referenced within model files must be relative paths, not absolute paths.

    The model on the right cannot be loaded because EasyAR cannot find files using absolute paths.

    Referenced paths within model files must not contain spaces or special characters.

    The model on the right cannot be loaded because the referenced path contains spaces.

  1. Check the file encoding format
    Model files should use the UTF-8 encoding format.

    The model on the right cannot be loaded due to decoding errors caused by its file encoding issue.

  2. Check the model normals
    The positive direction of the normal vectors for model faces should follow the right-hand rule.

    The shaded faces in the second cube have negative-oriented normal vectors. Such faces are treated as invisible in EasyAR. When viewed from inside the model, it appears as shown in the third cube.
    Models should avoid all faces with negative-oriented normal vectors.

  3. Model face count
    The number of model faces should be minimized while ensuring the object's geometric shape, typically not exceeding 100,000 triangles. Excessive face count leads to:

    • Prolonged model loading times, negatively impacting the user experience during app startup.
    • Increased computational load for texture projection onto faces, affecting the app's frame rate during tracking.

The quality of 3D models directly determines tracking success rates. Developers must strictly follow format specifications, optimize texture details, and ensure error-free file formats.