Data Fields

Methods

{
  "name": "MeshOBJLoader",
  "namespace": "sofa::component::io::mesh",
  "module": "Sofa.Component.IO.Mesh",
  "include": "sofa/component/io/mesh/MeshOBJLoader.h",
  "doc": "Specific mesh loader for OBJ file format.",
  "inherits": [
    "MeshLoader"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_handleSeams",
      "type": "bool",
      "xmlname": "handleSeams",
      "help": "Preserve UV and normal seams information (vertices with multiple UV and/or normals)"
    },
    {
      "name": "d_loadMaterial",
      "type": "bool",
      "xmlname": "loadMaterial",
      "help": "Load the related MTL file or use a default one?"
    },
    {
      "name": "d_material",
      "type": "sofa::type::Material",
      "xmlname": "defaultMaterial",
      "help": "Default material"
    },
    {
      "name": "d_faceList",
      "type": "type::SVector<type::SVector<int>>",
      "xmlname": "faceList",
      "help": "List of face definitions."
    },
    {
      "name": "d_texIndexList",
      "type": "type::SVector<type::SVector<int>>",
      "xmlname": "texcoordsIndex",
      "help": "Indices of textures coordinates used in faces definition."
    },
    {
      "name": "d_normalsIndexList",
      "type": "type::SVector<type::SVector<int>>",
      "xmlname": "normalsIndex",
      "help": "List of normals of elements of the mesh loaded."
    },
    {
      "name": "d_computeMaterialFaces",
      "type": "bool",
      "xmlname": "computeMaterialFaces",
      "help": "True to activate export of Data instances containing list of face indices for each material"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "doLoad",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readOBJ",
      "return_type": "bool",
      "params": [
        {
          "name": "file",
          "type": "int &"
        },
        {
          "name": "filename",
          "type": "const char *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "readMTL",
      "return_type": "bool",
      "params": [
        {
          "name": "filename",
          "type": "const char *"
        },
        {
          "name": "d_materials",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "addGroup",
      "return_type": "void",
      "params": [
        {
          "name": "g",
          "type": "const sofa::core::loader::PrimitiveGroup &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "doClearBuffers",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "type",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "MeshOBJLoader is a component in the Sofa framework designed for loading 3D geometry data stored in the OBJ file format. The OBJ file format is widely used to represent and exchange 3D models among various software applications due to its simplicity and ease of parsing.\n\n### Key Features:\n\n- **Loading OBJ Files:** MeshOBJLoader can read and interpret .obj files which typically contain vertex positions, texture coordinates (UVs), normals, and face definitions. It supports three types of faces: edges, triangles, and quads.\n- **Material Support:** The component can also load materials defined in associated MTL files if enabled via the `d_loadMaterial` parameter. This allows for more detailed visualization with proper shading, textures, and other material properties.\n- **Handle Seams Information:** With the `d_handleSeams` option set to true, the loader preserves UV and normal seam information by splitting vertices into separate entities when they have different texture coordinates or normals.\n- **Material Management:** The component maintains a list of materials defined in MTL files through the `d_materials` data field. It also provides a default material via `d_material` if no MTL file is loaded or specified.\n- **Face and Vertex Data Handling:** MeshOBJLoader stores face definitions (`d_faceList`) along with associated texture coordinates (`d_texIndexList`, `d_texCoordsList`) and normals (`d_normalsIndexList`, `d_normalsList`). It also maintains vertex position data through the `d_positionsList` field.\n- **Customization Options:** Users can customize how the loader processes UV seams and material loading. Additionally, if vertices have multiple normals or texture coordinates, it separates them into distinct vertices with the help of `d_vertPosIdx` and `d_vertNormIdx` fields.\n- **Visualization Support:** The component allows for exporting face indices per material via the `d_computeMaterialFaces` option, which can be used to create subsets for visualization purposes.\n\n### Usage:\nTo use MeshOBJLoader in a Sofa scene, it should be added as a child component of an object that requires geometry data. The OBJ file path is specified using standard Sofa framework mechanisms (typically through XML configuration files). Once loaded, the geometry and material information can be accessed by other components for further processing or visualization.\n\n### Example:\n```xml\n<VisualModel>\n    <MeshOBJLoader filename=\"path/to/model.obj\" loadMaterial=\"true\"/>\n</VisualModel>\n```\nThis XML snippet demonstrates how to include an OBJ loader in a Sofa scene, specifying the path to the model and enabling material loading.\n\n### Considerations:\nThe component's functionality relies on efficient parsing of text-based 3D geometry data. It is optimized for typical use cases but may require customization or additional processing steps depending on specific application requirements.",
  "parameters": [
    {
      "name": "filename",
      "description": "Path to the OBJ file containing the 3D model geometry."
    },
    {
      "name": "loadMaterial",
      "type": "bool",
      "default_value": "false",
      "description": "Enable or disable loading of materials defined in an associated MTL file. If enabled, the loader reads material properties from a .mtl file linked to the OBJ file and applies them during visualization."
    },
    {
      "name": "handleSeams",
      "type": "bool",
      "default_value": "false",
      "description": "Preserve UV and normal seam information by splitting vertices with multiple texture coordinates or normals into separate entities. This ensures accurate visual representation when textures are applied to the model."
    }
  ],
  "output_data_fields": [
    {
      "name": "positionsList",
      "type": "vector<Vec3>",
      "description": "Holds the vertex positions of the loaded OBJ file, representing 3D coordinates in space."
    },
    {
      "name": "texCoordsList",
      "type": "vector<Vec2>",
      "description": "Contains the texture coordinate (UV) data for each face defined in the OBJ file. This data is used to map textures onto the model surfaces accurately."
    },
    {
      "name": "normalsList",
      "type": "vector<Vec3>",
      "description": "Stores the normal vectors at vertices, which are essential for proper lighting and shading of the 3D geometry during rendering."
    }
  ],
  "maths": "MeshOBJLoader is a component within the Sofa framework responsible for loading 3D geometry data from OBJ files, which are commonly used to represent and exchange 3D models. The OBJ format includes vertex positions, texture coordinates (UVs), normals, and face definitions, supporting edges, triangles, and quads. This description does not contain significant mathematical or physical content as it primarily serves the role of reading geometric data from files without involving governing equations, constitutive laws, or numerical methods used in FEM simulations. Therefore, its role is mainly to provide initial geometry and material information for further processing by other Sofa components involved in mechanical simulation.\n\n### Key Features:\n- **Loading OBJ Files:** The component reads vertex positions (`\textbf{p}_i`), texture coordinates (`\textbf{t}_i`), normals (`\textbf{n}_i`), and face definitions (edges, triangles, quads) from .obj files.\n- **Material Support:** It supports loading materials defined in associated MTL files via the `d_loadMaterial` parameter. This allows for detailed visualization with proper shading, textures, and other material properties.\n- **Handle Seams Information:** The option `d_handleSeams` preserves UV and normal seam information by splitting vertices into separate entities if they have different texture coordinates or normals.\n- **Face and Vertex Data Handling:** It stores face definitions (`\textbf{F}`), associated texture coordinates (`\textbf{T}`, `\textbf{I}_T`), and normals (`\textbf{N}`, `\textbf{I}_N`). It also maintains vertex position data through the `d_positionsList` field.\n- **Customization Options:** Users can customize how the loader processes UV seams and material loading. If vertices have multiple normals or texture coordinates, it separates them into distinct vertices with the help of `d_vertPosIdx` and `d_vertNormIdx` fields.\n- **Visualization Support:** The component allows exporting face indices per material via the `d_computeMaterialFaces` option for creating subsets used in visualization.\n\n### Role in the FEM Pipeline:\nMeshOBJLoader plays a preparatory role by providing initial geometric data (vertices, faces) and material properties. This data is then utilized by other Sofa components such as mesh generators, mechanical object definitions, and force fields to build the finite element model for simulation.\n\n### Numerical Methods:\nThe component does not involve numerical methods or discretization choices but rather focuses on accurately parsing text-based 3D geometry data into a structured format suitable for further processing within the Sofa framework.",
  "abstract": "MeshOBJLoader loads OBJ files into SOFA, handling vertex positions, texture coordinates, normals, and face definitions. It supports loading materials from associated MTL files if enabled.",
  "sheet": "# MeshOBJLoader\n\n## Overview\n\nMeshOBJLoader is a component in the Sofa framework designed to load 3D geometry data stored in OBJ files. It handles vertex positions, texture coordinates (UVs), normals, and face definitions. The component also supports loading materials defined in associated MTL files if enabled via the `d_loadMaterial` parameter.\n\n## Parameters and Data\n\n- **handleSeams (`bool`)**: Preserve UV and normal seam information by splitting vertices into separate entities when they have different texture coordinates or normals (default: false).\n- **loadMaterial (`bool`)**: Load the related MTL file or use a default one (default: false).\n- **defaultMaterial (`sofa::type::Material`)**: Default material used if no MTL file is loaded.\n- **faceList (`type::SVector<type::SVector<int>>`)**: List of face definitions.\n- **texcoordsIndex (`type::SVector<type::SVector<int>>`)**: Indices of texture coordinates used in faces definition.\n- **normalsIndex (`type::SVector<type::SVector<int>>`)**: List of normals of elements of the mesh loaded.\n- **computeMaterialFaces (`bool`)**: True to activate export of Data instances containing list of face indices for each material (default: false).\n\n## Dependencies and Connections\n\nMeshOBJLoader is typically used in conjunction with other components that require geometric data, such as mechanical objects or visual models. It fits into the scene graph by providing initial geometry and material information."
}