Mathematical and Physical Description of ExtrudeSurface Component

Data Fields

Methods

{
  "name": "ExtrudeSurface",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/ExtrudeSurface.h",
  "doc": "Engine creating a mesh from the extrusion of the surface of a given mesh.\n\nThis class extrudes a surface",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "isVisible",
      "type": "bool",
      "xmlname": "isVisible",
      "help": "is Visible ?"
    },
    {
      "name": "heightFactor",
      "type": "Real",
      "xmlname": "heightFactor",
      "help": "Factor for the height of the extrusion (based on normal)"
    },
    {
      "name": "f_extrusionVertices",
      "type": "VecCoord",
      "xmlname": "extrusionVertices",
      "help": "Position coordinates of the extrusion"
    },
    {
      "name": "f_surfaceVertices",
      "type": "VecCoord",
      "xmlname": "surfaceVertices",
      "help": "Position coordinates of the surface"
    }
  ],
  "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"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `ExtrudeSurface` component in the SOFA framework is designed to generate a 3D mesh by extruding the surface of an existing mesh. This process involves extending or pulling out parts of the surface along its normal direction, creating a new set of vertices and triangles that form the extruded shape. The component inherits from `DataEngine`, which means it processes data and generates output based on input data fields.\n\n### Role and Purpose\nThe primary role of `ExtrudeSurface` is to take an existing mesh's surface (defined by its vertices and topology) and create a new set of vertices and triangles that represent the extruded shape. This can be useful in various simulation contexts, such as creating a solid model from a surface mesh for further mechanical or visual processing.\n\n### Interactions with Other Components\n`ExtrudeSurface` interacts with other components through its data fields:\n- `isVisible`: A boolean field to control the visibility of the extruded surface during visualization.\n- `heightFactor`: Controls the height of the extrusion based on the normal direction. The value is a factor that scales the length of the normals.\n- `f_extrusionVertices` and `f_surfaceVertices`: These fields store the position coordinates for the extruded vertices and original surface vertices, respectively.\n\nThe component also inherits virtual methods from its base class `DataEngine`, such as `init()`, `reinit()`, `doUpdate()`, and `draw()`. These methods are responsible for initializing the component, reinitializing data fields, updating the mesh based on input changes, and rendering the extruded surface.\n\n### Practical Usage Guidance\n- **isVisible**: Set to control whether the generated extruded shape is visible during visualization. Default value is `true`.\n- **heightFactor**: Adjust this factor to change the height of the extrusion along the normal direction. The default value is `1.0`, meaning the extrusion length matches the normal's magnitude.\n\nBy manipulating these fields and invoking the relevant methods, users can control how the surface mesh is extruded and visualized within a SOFA simulation.",
  "maths": "# Mathematical and Physical Description of ExtrudeSurface Component\n\n## Overview\nThe `ExtrudeSurface` component in the SOFA framework is designed to generate a three-dimensional mesh by extruding an existing surface mesh. The process involves extending or pulling out parts of the original surface along its normal direction, resulting in a new set of vertices and triangles that form the extruded shape.\n\n## Mathematical Formulation\n### Input Data Fields\n- **Vertices (V)**: A list of 3D coordinates representing the original mesh's vertices. These are stored in `f_surfaceVertices`.\n- **Triangles (T)**: A list of triangular faces defined by indices into the vertex array V, which represent the topology of the original surface. This is stored as a set of triangle IDs (`surfaceTriangles`).\n\n### Extrusion Process\n1. **Normal Calculation**: For each face in the mesh, compute its normal vector `N`. The normal vector for a triangular face with vertices A, B, and C can be calculated using the cross product:\n   \n    $$ N = (B - A) \\times (C - A) $$\n\n2. **Vertex Extrusion**: For each vertex `v` in the original mesh, calculate its extruded position by moving it along its normal vector scaled by a factor (`heightFactor`). The new position of a vertex `v_i` is given by:\n   \n    $$ v_{i}^{\\text{extruded}} = v_i + \\text{heightFactor} \\cdot N(v_i) $$\n\n3. **New Vertices and Triangles**: Create new vertices for the extrusion, resulting in a set of `f_extrusionVertices` that includes both original and extruded positions.\n4. **Triangle Creation**:\n   - For each triangle face in the original mesh, create two new triangles: one using the original vertices (to maintain the surface) and another using the extruded vertices.\n   - Additionally, for the boundaries of the extrusion, additional triangles are created to connect the original and extruded faces, forming a solid volume.\n\n### Example Triangles Generation\nLet's assume we have three vertices `A`, `B`, and `C` with their normals `N_A`, `N_B`, and `N_C`. The vertices after extrusion would be:\n\n$$ A' = A + \\text{heightFactor} \\cdot N_A $$\n$$ B' = B + \\text{heightFactor} \\cdot N_B $$\n$$ C' = C + \\text{heightFactor} \\cdot N_C $$\n\nThe new triangles would be:\n- Original face: `A`, `B`, `C`\n- Extruded face: `A'`, `B'`, `C'`\n- Boundary faces to connect the original and extruded surfaces.\n\n### Visualization Control\n- **isVisible**: A boolean field that controls whether the generated extruded surface is visible during visualization. Default value is `true`.\n- **heightFactor**: Controls the height of the extrusion along the normal direction. The default value is `1.0`, meaning the extrusion length matches the magnitude of the normals.\n\n## Practical Usage\nUsers can adjust the `isVisible` and `heightFactor` parameters to control how the surface mesh is extruded and visualized within a SOFA simulation. By manipulating these fields and invoking relevant methods, users can create complex 3D shapes from simple surface meshes for further mechanical or visual processing.",
  "abstract": "The `ExtrudeSurface` component generates a mesh by extruding the surface of an existing mesh along its normal direction, controlled by parameters for visibility and height factor.",
  "sheet": "# ExtrudeSurface\n\n## Overview\nThe `ExtrudeSurface` component in SOFA is designed to generate a three-dimensional mesh by extruding the surface of an existing mesh. It inherits from `DataEngine`, processing input data fields to create new vertices and triangles that form the extruded shape.\n\n## Mathematical Model\n### Input Data Fields\n- **Vertices (V)**: A list of 3D coordinates representing the original mesh's vertices, stored in `f_surfaceVertices`.\n- **Triangles (T)**: A list of triangular faces defined by indices into the vertex array V, which represent the topology of the original surface.\n\n### Extrusion Process\n1. **Normal Calculation**: For each face with vertices A, B, and C, compute its normal vector `N` using the cross product:\n   \n    $$ N = (B - A) \\times (C - A) $$\n\n2. **Vertex Extrusion**: For each vertex `v`, calculate its extruded position by moving it along its normal vector scaled by a factor (`heightFactor`). The new position of a vertex `v_i` is given by:\n   \n    $$ v_{i}^{\\text{extruded}} = v_i + \\text{heightFactor} \\cdot N(v_i) $$\n\n3. **New Vertices and Triangles**: Create new vertices for the extrusion, resulting in a set of `f_extrusionVertices` that includes both original and extruded positions.\n4. **Triangle Creation**:\n   - For each triangle face in the original mesh, create two new triangles: one using the original vertices (to maintain the surface) and another using the extruded vertices.\n   - Additionally, for the boundaries of the extrusion, additional triangles are created to connect the original and extruded faces, forming a solid volume.\n\n### Example Triangles Generation\nLet's assume we have three vertices `A`, `B`, and `C` with their normals `N_A`, `N_B`, and `N_C`. The vertices after extrusion would be:\n   \n    $$ A' = A + \\text{heightFactor} \\cdot N_A $$\n    $$ B' = B + \\text{heightFactor} \\cdot N_B $$\n    $$ C' = C + \\text{heightFactor} \\cdot N_C $$\n\nThe new triangles would be:\n- Original face: `A`, `B`, `C`\n- Extruded face: `A'`, `B'`, `C'`\n- Boundary faces to connect the original and extruded surfaces.\n\n## Parameters and Data\n- **isVisible**: A boolean field that controls whether the generated extruded surface is visible during visualization. Default value is `true`.\n- **heightFactor**: Controls the height of the extrusion along the normal direction. The default value is `1.0`, meaning the extrusion length matches the magnitude of the normals.\n\n## Practical Notes\nUsers can adjust the `isVisible` and `heightFactor` parameters to control how the surface mesh is extruded and visualized within a SOFA simulation."
}