{
  "name": "GenerateGrid",
  "main": {
    "name": "GenerateGrid",
    "namespace": "sofa::component::engine::generate",
    "module": "Sofa.Component.Engine.Generate",
    "include": "sofa/component/engine/generate/GenerateGrid.h",
    "doc": "Engine generating a grid tetrahedral or hexahedral mesh.\n\nThis class generates a cylinder mesh given its radius, length and height. The output  mesh is composed of tetrahedra elements",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_outputX",
        "type": "VecCoord",
        "xmlname": "output_position",
        "help": "output array of 3d points"
      },
      {
        "name": "d_tetrahedron",
        "type": "SeqTetrahedra",
        "xmlname": "tetrahedra",
        "help": "output mesh tetrahedra"
      },
      {
        "name": "d_quad",
        "type": "SeqQuads",
        "xmlname": "quads",
        "help": "output mesh quads"
      },
      {
        "name": "d_triangle",
        "type": "SeqTriangles",
        "xmlname": "triangles",
        "help": "output mesh triangles"
      },
      {
        "name": "d_hexahedron",
        "type": "SeqHexahedra",
        "xmlname": "hexahedra",
        "help": "output mesh hexahedra"
      },
      {
        "name": "d_minCorner",
        "type": "Vec3",
        "xmlname": "min",
        "help": "the 3 coordinates of the minimum corner"
      },
      {
        "name": "d_maxCorner",
        "type": "Vec3",
        "xmlname": "max",
        "help": "the 3 coordinates of the maximum corner"
      },
      {
        "name": "d_resolution",
        "type": "Vec3Int",
        "xmlname": "resolution",
        "help": "the number of cubes in the x,y,z directions. If resolution in the z direction is  0 then a 2D grid is generated"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "reinit",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "doUpdate",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `GenerateGrid` component is part of the SOFA framework and belongs to the `sofa::component::engine::generate` namespace within the `Sofa.Component.Engine.Generate` module. Its primary role is to generate a grid-based tetrahedral or hexahedral mesh based on specified dimensions and resolution parameters.\n\n**Role in SOFA Ecosystem:**\n- The component inherits from `DataEngine`, which suggests it computes data that can be used by other components in the simulation pipeline.\n- It generates both 2D (quads, triangles) and 3D (hexahedra, tetrahedra) mesh elements depending on the specified resolution parameters.\n\n**Interactions with Other Components:*\n- The `GenerateGrid` outputs various types of geometrical elements (`d_outputX`, `d_tetrahedron`, `d_quad`, `d_triangle`, and `d_hexahedron`) which can be consumed by other components such as visualizers, collision detectors, or solvers.\n\n**Practical Usage Guidance:**\n- Users need to specify the minimum (`minCorner`), maximum (`maxCorner`), and resolution (`resolution`) parameters to define the grid dimensions and its granularity.\n- The `output_position`, `tetrahedra`, `quads`, `triangles`, and `hexahedra` are the primary output data fields, representing the generated mesh elements.\n\n**Data Fields:**\n- **d_outputX (VecCoord):** Output array of 3D points representing vertex positions.\n- **d_tetrahedron (SeqTetrahedra):** Array of tetrahedral elements in the mesh.\n- **d_quad (SeqQuads):** Array of quad elements, primarily used for 2D grids.\n- **d_triangle (SeqTriangles):** Array of triangular elements, useful for both 2D and 3D grids.\n- **d_hexahedron (SeqHexahedra):** Array of hexahedral elements in the mesh.\n- **d_minCorner (Vec3):** Minimum corner coordinates defining one end of the grid bounding box.\n- **d_maxCorner (Vec3):** Maximum corner coordinates defining the opposite end of the grid bounding box.\n- **d_resolution (Vec3Int):** Resolution parameters specifying the number of cubes in each direction (x, y, z). A zero value in the z-direction indicates a 2D grid."
  },
  "maths": {
    "maths": "# Mathematical Description of the GenerateGrid Component\n\n## Overview\nThe `GenerateGrid` component within the SOFA framework is designed to generate a structured grid-based mesh, either tetrahedral or hexahedral, based on specified parameters such as minimum and maximum corner coordinates (`d_minCorner`, `d_maxCorner`) and resolution (`d_resolution`). This component can output various types of geometrical elements: vertices (3D points), tetrahedra, quads, triangles, and hexahedra.\n\n## Parameters\n- **`d_minCorner`:** Minimum corner coordinates $(x_{min}, y_{min}, z_{min})$ that define one vertex of the bounding box for the grid.\n- **`d_maxCorner`:** Maximum corner coordinates $(x_{max}, y_{max}, z_{max})$ that define the opposite vertex of the bounding box for the grid.\n- **`d_resolution`:** Resolution vector $(nx, ny, nz)$ indicating the number of divisions in each direction (x, y, and z) within the bounding box. If $nz = 0$, a 2D grid is generated; otherwise, it generates a 3D mesh.\n\n## Grid Generation Process\n1. **Vertex Generation:**\n   - The vertices $(x_i, y_j, z_k)$ are calculated for each cell in the grid. For each dimension $d \\in \\\\[x, y, z\\//$:\n     $$ x_i = x_{min} + i \\cdot \\Delta_x \\quad \\text{for } i = 0, 1, ..., nx-1 $$\n     where $\\Delta_x = (x_{max} - x_{min}) / (nx - 1)$.\n   - The same process applies for the y and z dimensions.\n\n2. **Tetrahedral Element Generation:**\n   - Tetrahedra are created by subdividing each hexahedron into five or six tetrahedra depending on the meshing criteria.\n   - For a hexahedron defined by vertices $v_0, v_1, v_2, ..., v_7$, the process involves creating the following tetrahedra:\n     $$ T_{i} = \\{v_0, v_1, v_4, v_5\\}, \\quad T_{ii} = \\{v_1, v_2, v_5, v_6\\}, ...$$\n   - This ensures a consistent and non-overlapping decomposition of the hexahedra.\n\n3. **Hexahedral Element Generation:**\n   - Hexahedra are defined by eight vertices $(v_0, ..., v_7)$. Each vertex corresponds to one corner point within each cubic cell in the grid:\n     $$ \\text{Hex}(i,j,k) = (v_{(nx*i + j)*nz + k}, ...)$$\n   - This involves mapping the indices of vertices based on the resolution parameters.\n\n4. **Quad and Triangle Generation:**\n   - For a 2D grid ($z$-resolution $=0$), quads are generated using four vertices:\n     $$ Q(i,j) = (v_{i*ny + j}, v_{(i+1)*ny + j}, ..., v_{(i+1)*(ny+1) + j})$$\n   - Triangles can be derived from these quads by splitting them into two triangles.\n\n## Summary of Output Data Fields\n- **`d_outputX`:** Array of vertices, where each vertex is a 3D point $(x_i, y_j, z_k)$ calculated using the grid resolution and corner coordinates.\n- **`d_tetrahedron`:** Array of tetrahedral elements defined by four vertices per element.\n- **`d_quad`:** Array of quad elements (only relevant for 2D grids).\n- **`d_triangle`:** Array of triangular elements, which can be derived from hexahedra or quads depending on the grid dimensionality.\n- **`d_hexahedron`:** Array of hexahedral elements defined by eight vertices per element.\n\n## Example\nGiven a minimum corner $(0, 0, 0)$ and maximum corner $(1, 1, 1)$ with resolution $(2, 2, 2)$:\n- The grid will generate vertices at positions: $$(0, 0, 0), (\\frac{1}{2}, 0, 0), (1, 0, 0), ..., (1, 1, 1)$$\n- Tetrahedra and hexahedra are then constructed using these vertices to form a structured mesh suitable for finite element analysis or other computational simulations."
  },
  "summary": {
    "abstract": "The `GenerateGrid` component generates a grid-based tetrahedral or hexahedral mesh given dimensions and resolution parameters, outputting vertices, tetrahedra, quads, triangles, and hexahedra for use in SOFA simulations.",
    "sheet": "# GenerateGrid\n\n## Overview\nThe `GenerateGrid` component is an engine that generates a structured grid-based mesh (tetrahedral or hexahedral) based on specified dimensions (`d_minCorner`, `d_maxCorner`) and resolution (`d_resolution`). It outputs various types of geometrical elements: vertices, tetrahedra, quads, triangles, and hexahedra. These output data fields can be consumed by other components such as visualizers, collision detectors, or solvers.\n\n## Parameters and Data\nThe significant Data fields exposed by the component are:\n- **`d_outputX (VecCoord)`**: Output array of 3D points representing vertex positions.\n- **`d_tetrahedron (SeqTetrahedra)`**: Array of tetrahedral elements in the mesh.\n- **`d_quad (SeqQuads)`**: Array of quad elements, primarily used for 2D grids.\n- **`d_triangle (SeqTriangles)`**: Array of triangular elements, useful for both 2D and 3D grids.\n- **`d_hexahedron (SeqHexahedra)`**: Array of hexahedral elements in the mesh.\n- **`d_minCorner (Vec3)`**: Minimum corner coordinates defining one end of the grid bounding box.\n- **`d_maxCorner (Vec3)`**: Maximum corner coordinates defining the opposite end of the grid bounding box.\n- **`d_resolution (Vec3Int)`**: Resolution parameters specifying the number of cubes in each direction (x, y, z). A zero value in the z-direction indicates a 2D grid.\n\n## Grid Generation Process\n1. **Vertex Generation:**\n   - The vertices $(x_i, y_j, z_k)$ are calculated for each cell in the grid. For each dimension $d \\in [x, y, z]$:\n     $$ x_i = x_{min} + i \\cdot \\Delta_x \\quad \\text{for } i = 0, 1, ..., nx-1 $$\n     where $\\Delta_x = (x_{max} - x_{min}) / (nx - 1)$.\n   - The same process applies for the y and z dimensions.\n\n2. **Tetrahedral Element Generation:**\n   - Tetrahedra are created by subdividing each hexahedron into five or six tetrahedra depending on the meshing criteria.\n   - For a hexahedron defined by vertices $v_0, v_1, v_2, ..., v_7$, the process involves creating the following tetrahedra:\n     $$ T_{i} = \\{v_0, v_1, v_4, v_5\\}, \\quad T_{ii} = \\{v_1, v_2, v_5, v_6\\}, ...$$\n   - This ensures a consistent and non-overlapping decomposition of the hexahedra.\n\n3. **Hexahedral Element Generation:**\n   - Hexahedra are defined by eight vertices $(v_0, ..., v_7)$. Each vertex corresponds to one corner point within each cubic cell in the grid:\n     $$ \\text{Hex}(i,j,k) = (v_{(nx*i + j)*nz + k}, ...)$$\n   - This involves mapping the indices of vertices based on the resolution parameters.\n\n4. **Quad and Triangle Generation:**\n   - For a 2D grid ($z$-resolution $=0$), quads are generated using four vertices:\n     $$ Q(i,j) = (v_{i*ny + j}, v_{(i+1)*ny + j}, ..., v_{(i+1)*(ny+1) + j})$$\n   - Triangles can be derived from these quads by splitting them into two triangles."
  }
}