{
  "name": "GenerateCylinder",
  "main": {
    "name": "GenerateCylinder",
    "namespace": "sofa::component::engine::generate",
    "module": "Sofa.Component.Engine.Generate",
    "include": "sofa/component/engine/generate/GenerateCylinder.h",
    "doc": "Engine generating a cylindrical tetrahedral mesh.",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "f_outputTetrahedraPositions",
        "type": "VecCoord",
        "xmlname": "output_TetrahedraPosition",
        "help": "output array of 3d points of tetrahedra mesh"
      },
      {
        "name": "f_outputTrianglesPositions",
        "type": "VecCoord",
        "xmlname": "output_TrianglesPosition",
        "help": "output array of 3d points of triangle mesh"
      },
      {
        "name": "f_tetrahedra",
        "type": "SeqTetrahedra",
        "xmlname": "tetrahedra",
        "help": "output mesh tetrahedra"
      },
      {
        "name": "f_triangles",
        "type": "SeqTriangles",
        "xmlname": "triangles",
        "help": "output triangular mesh"
      },
      {
        "name": "f_radius",
        "type": "Real",
        "xmlname": "radius",
        "help": "input cylinder radius"
      },
      {
        "name": "f_height",
        "type": "Real",
        "xmlname": "height",
        "help": "input cylinder height"
      },
      {
        "name": "f_origin",
        "type": "Coord",
        "xmlname": "origin",
        "help": "cylinder origin point"
      },
      {
        "name": "f_openSurface",
        "type": "bool",
        "xmlname": "openSurface",
        "help": "if the cylinder is open at its 2 ends"
      }
    ],
    "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 `GenerateCylinder` component in the SOFA framework is an engine that generates a tetrahedral mesh representing a cylindrical shape. This component inherits from `DataEngine`, which enables it to process and produce data for further use within the simulation pipeline.\n\n### Role and Purpose:\nThe primary purpose of `GenerateCylinder` is to create a geometric representation of a cylinder, both in terms of tetrahedra (for volume) and triangles (for surface). The component takes parameters such as radius (`f_radius`), height (`f_height`), origin point (`f_origin`), and resolution settings (`f_resolutionCircumferential`, `f_resolutionRadial`, `f_resolutionHeight`) to generate the mesh.\n\n### Interactions with Other Components:\nThe output of this component includes arrays of 3D points for tetrahedra and triangles (`f_outputTetrahedraPositions` and `f_outputTrianglesPositions`). These outputs can be used by other components such as collision detection engines or rendering systems to integrate the cylinder into a simulation scenario. Additionally, the generated mesh data can serve as input for various mechanical models within SOFA.\n\n### Practical Usage:\nThe component offers several key fields that can be configured through XML parameters:\n- `f_radius`: Sets the radius of the cylinder.\n- `f_height`: Specifies the height of the cylinder.\n- `f_origin`: Defines the origin point of the cylinder in 3D space.\n- `f_openSurface`: Determines whether the ends of the cylinder are open or closed.\n- `f_resolutionCircumferential`, `f_resolutionRadial`, and `f_resolutionHeight` control the resolution along different axes, impacting the density of the mesh.\n\nThe component also supports rational Bezier tetrahedra and triangles (`f_bezierTriangleWeight`, `f_isBezierTriangleRational`, etc.), providing more flexibility in modeling curved surfaces with higher accuracy. The generated meshes can be utilized directly by other SOFA components for simulation, visualization, or further processing."
  },
  "maths": {
    "maths": "### Mathematical and Physical Description\n\nThe `GenerateCylinder` component in the SOFA framework is designed to generate a tetrahedral mesh representing a cylindrical shape. This engine computes the spatial discretization required for finite element analysis (FEA). The primary purpose of this component is to provide a geometric representation that can be used by other mechanical components and solvers within the simulation pipeline.\n\n#### Inputs:\nThe following inputs are provided as parameters to define the cylinder geometry and resolution:\n- **Radius** ($r$): \n  \\[ r = f_{\\text{radius}}.getValue() \\]\n- **Height** ($h$):\n  \\[ h = f_{\\text{height}}.getValue() \\]\n- **Origin Point** ($O$):\n  \\[ O = f_{\\text{origin}}.getValue() \\]\n- **Resolution Parameters**: \n  - Circumferential resolution ($N_\\theta$)\n    \\[ N_\\theta = f_{\\text{resolutionCircumferential}}.getValue() \\]\n  - Radial resolution ($N_r$)\n    \\[ N_r = f_{\\text{resolutionRadial}}.getValue() \\]\n  - Height resolution ($N_z$) \n    \\[ N_z = f_{\\text{resolutionHeight}}.getValue() \\]\n\n#### Output Data Structures:\nThe `GenerateCylinder` component generates the following output data structures:\n- **Tetrahedra Positions**: Array of tetrahedral mesh vertices.\n  \\[ \\mathbf{V}_{\\text{Tetra}} = f_{\\text{outputTetrahedraPositions}}.getValue() \\]\n- **Triangles Positions**: Array of triangular mesh vertices (for surface representation).\n  \\[ \\mathbf{V}_{\\text{Tri}} = f_{\\text{outputTrianglesPositions}}.getValue() \\]\n\n#### Mesh Generation Process:\nThe generation process involves several steps to create the tetrahedral and triangular meshes based on the specified resolutions.\n\n##### Vertex Positioning for Tetrahedra:\nThe vertices of the cylinder are computed using polar coordinates in 3D space. The positioning is done by varying angles ($\\theta$) and radial distances from the center of the cylinder, while ensuring vertical alignment along the height direction ($z$).\n- **Vertices**:\n  \\[ \n    x_i = r_j \\cos(\\theta_k), \\quad y_i = r_j \\sin(\\theta_k), \\quad z_i = h_m\n  \\]\n  where $r_j = j * (r / N_r)$, $\\theta_k = k * (2 \\pi / N_\\theta)$, and $z_m = m * (h / (N_z - 1))$.\n- **Total Number of Vertices**:\n  \\[ \n    n_{\\text{vertices}} = (N_\\theta \\times N_r + 1) \\times N_z\n  \\]\n\n##### Tetrahedral Elements:\nThe tetrahedra are formed by connecting vertices based on the resolution and geometry of the cylinder. The algorithm generates triangular prisms along each circumferential ring and decomposes them into three tetrahedra, then constructs hexahedral elements between adjacent rings.\n- **Total Number of Tetrahedra**:\n  \\[\n    n_{\\text{tetrahedra}} = 3 N_\\theta (N_z - 1) + 6 (N_r - 1) N_\\theta (N_z - 1)\n  \\]\n\n#### Bezier Tetrahedra and Triangles:\nThe component also supports rational Bezier tetrahedra and triangles for more accurate modeling of curved surfaces.\n- **Bezier Degree**: \n  \\[ d_{\\text{bez}} = f_{\\text{bezierTetrahedronDegree}}.getValue() \\]\n\nFor higher-order elements ($d_{\\text{bez}} > 1$), additional control points are added along edges and within triangles to capture the geometry accurately.\n- **Weighting**: \n  - For rational tetrahedra: weights (`f_bezierTetrahedronWeight`) are adjusted based on the location of vertices relative to circular surfaces.\n  - For rational triangles: similar weighting logic applies, ensuring accurate representation along curved edges.\n\n#### Surface Representation:\nThe component generates a triangular surface mesh for visualization and collision detection purposes. The number of surface triangles is determined by the resolution parameters, and they are distributed along the cylindrical surface.\n- **Total Number of Triangles**:\n  \\[\n    n_{\\text{triangles}} = \begin{cases}\n      2 N_\\theta (N_z - 1) & \\text{(if openSurface is true)}\\\\\n      2 N_\\theta (N_z - 1) + 2 N_\\theta + 4 (N_r - 1) N_\\theta & \\text{(if openSurface is false)}\n    \\end{cases}\n  \\]\n\n#### Role in FEM Pipeline:\nThe `GenerateCylinder` component fits into the broader variational / Lagrangian mechanics framework by providing the necessary spatial discretization for subsequent analysis steps. The generated tetrahedral mesh can be used to approximate continuous material behavior through finite element formulations, while the triangular surface representation enables accurate visualization and interaction within the simulation environment.\n\nThe output data structures (`f_outputTetrahedraPositions`, `f_tetrahedra`, etc.) are essential for downstream components like mechanical models (e.g., linear elasticity), collision detection engines, or rendering systems. The Bezier elements allow for higher-order approximations of curved surfaces, enhancing the accuracy and realism of simulations involving deformable bodies.\n\n### Summary:\nThe `GenerateCylinder` component in SOFA is a powerful tool for generating geometric representations of cylindrical shapes with high resolution. It provides both volumetric (tetrahedral) and surface (triangular) discretizations that can be used seamlessly within the FEM simulation pipeline, enabling accurate modeling and analysis of deformable systems."
  },
  "summary": {
    "abstract": "The `GenerateCylinder` engine generates tetrahedral and triangular meshes for a cylindrical shape based on specified radius, height, origin point, and resolution settings. It provides geometric representations suitable for simulation or visualization tasks within SOFA.",
    "sheet": "# GenerateCylinder\n\n## Overview\n\nThe `GenerateCylinder` component is an engine that generates a tetrahedral mesh representing a cylindrical shape. This component inherits from `DataEngine`, enabling it to process and produce data for further use in the simulation pipeline. It takes parameters such as radius, height, origin point, and resolution settings to generate both volumetric (tetrahedra) and surface (triangles) representations of the cylinder.\n\n## Parameters and Data\n\nThe `GenerateCylinder` component exposes several significant Data fields that control its behavior:\n\n- **f_radius**: Sets the radius of the cylinder. Type: Real, Default: Not specified.\n- **f_height**: Specifies the height of the cylinder. Type: Real, Default: Not specified.\n- **f_origin**: Defines the origin point of the cylinder in 3D space. Type: Coord, Default: Not specified.\n- **f_openSurface**: Determines whether the ends of the cylinder are open or closed. Type: bool, Default: false.\n\nAdditionally, it provides output arrays for the generated mesh:\n\n- **f_outputTetrahedraPositions**: Output array of 3D points for tetrahedral mesh vertices. Type: VecCoord.\n- **f_outputTrianglesPositions**: Output array of 3D points for triangular mesh vertices (surface representation). Type: VecCoord.\n- **f_tetrahedra**: Output mesh tetrahedra. Type: SeqTetrahedra.\n- **f_triangles**: Output triangular mesh. Type: SeqTriangles."
  }
}