Table of Contents

3D Model preparation and optimization

This article details how to prepare 3D models that meet EasyAR's requirements, covering format specifications, tool recommendations, and common troubleshooting to help developers improve tracking success 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 when using it.

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 placed in the same folder and referenced using relative paths (e.g., texture.jpg). Absolute paths (e.g., C:\Models\texture.jpg) are prohibited.
  • Filenames and paths within files must not contain spaces. It is recommended to use English or numbers.
  • The file encoding format must be UTF-8 (to avoid loading failures due to garbled characters).

Minimum requirements for OBJ (.obj) files

  • 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 if provided, the system will not load them.
  • Must include texture coordinates
    Texture coordinates, represented by \((u, v [,w])\) coordinates. \(w\) is optional and defaults to 0. Typically, the values of \(u\) and \(v\) should be between 0 and 1. For values less than 0 or greater than 1, the system defaults to REPEAT mode, where the integer part of the coordinate is ignored, creating an infinitely repeating pattern (similar to GL_REPEAT in OpenGL).
  • Must include face
    Face elements must include at least vertex indices and texture coordinate indices. Polygonal faces with more than 3 vertices (e.g., quadrilaterals) are also supported.
  • Must include mtllib
    A reference to a material file, requiring at least one external MTL material file to be specified. The file path must be relative, not absolute.
  • Must include usemtl
    The material referenced by the model element must specify the material name, which should match the material name defined in the external MTL material file.

Minimum requirements for MTL (.mtl) files

  • An MTL file must define at least one material.
  • Texture maps are mandatory.
    Typically, only the ambient or diffuse texture map (map_Ka, map_Kd) needs to be specified;
    The texture map path must be a relative path, not an absolute path;
  • Other optional parameters for texture maps are not mandatory, and if provided, the system will not adopt them.

Model preparation

You can prepare OBJ-format model files that meet the specifications in several ways.

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

  2. Create a new model from scratch
    Use modeling tools such as Autodesk Maya / 3ds Max to create/draw a 3D model and export it in OBJ format.

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

Important

The model textures must accurately reproduce the visual characteristics of the real object, otherwise the recognition and tracking functions will not work properly.

Model best practices

Below are some common issues and examples encountered when preparing models, provided for your quick reference and verification.

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

    Reference left: Can be detected and tracked by EasyAR. Reference right: Cannot be detected or tracked, 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 reference 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.

    Paths referenced 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 UTF-8 encoding.

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

  2. Check the model normal
    The positive direction of the normal vector for model polygons should follow the right-hand rule.

    The polygons in the shaded area of the second cube have a negative normal orientation. Such polygons are treated as non-visible surfaces in EasyAR. When viewed from inside the model, it appears as shown in the third cube.
    Models should avoid all polygons with negatively oriented normals.

  3. Model polygon count
    The number of polygons in the model should be minimized while ensuring the geometric shape, typically not exceeding 100,000 triangular polygons. Excessive polygon counts can lead to:

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

The quality of 3D models directly determines tracking success rate. Developers must strictly adhere to format specifications, prioritize optimizing texture details, and ensure error-free file formats.