Data Fields

Methods

{
  "name": "SubsetTopology",
  "namespace": "sofa::component::engine::select",
  "module": "Sofa.Component.Engine.Select",
  "include": "sofa/component/engine/select/SubsetTopology.h",
  "doc": "Engine used to create subset topology given box, sphere, plan, ...\n\nThis class find all the points located inside a given box.",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "direction",
      "type": "Vec3",
      "xmlname": "direction",
      "help": "Edge direction(if edgeAngle > 0)"
    },
    {
      "name": "normal",
      "type": "Vec3",
      "xmlname": "normal",
      "help": "Normal direction of the triangles (if triAngle > 0)"
    },
    {
      "name": "edgeAngle",
      "type": "Real",
      "xmlname": "edgeAngle",
      "help": "Max angle between the direction of the selected edges and the specified direction"
    },
    {
      "name": "triAngle",
      "type": "Real",
      "xmlname": "triAngle",
      "help": "Max angle between the normal of the selected triangle and the specified normal direction"
    },
    {
      "name": "f_X0",
      "type": "VecCoord",
      "xmlname": "rest_position",
      "help": "Rest position coordinates of the degrees of freedom"
    },
    {
      "name": "d_tetrahedraInput",
      "type": "SetIndex",
      "xmlname": "tetrahedraInput",
      "help": "Indices of the tetrahedra to keep"
    },
    {
      "name": "f_indices",
      "type": "SetIndex",
      "xmlname": "indices",
      "help": "Indices of the points contained in the ROI"
    },
    {
      "name": "f_edgeIndices",
      "type": "SetIndex",
      "xmlname": "edgeIndices",
      "help": "Indices of the edges contained in the ROI"
    },
    {
      "name": "f_triangleIndices",
      "type": "SetIndex",
      "xmlname": "triangleIndices",
      "help": "Indices of the triangles contained in the ROI"
    },
    {
      "name": "f_quadIndices",
      "type": "SetIndex",
      "xmlname": "quadIndices",
      "help": "Indices of the quads contained in the ROI"
    },
    {
      "name": "f_tetrahedronIndices",
      "type": "SetIndex",
      "xmlname": "tetrahedronIndices",
      "help": "Indices of the tetrahedra contained in the ROI"
    },
    {
      "name": "f_hexahedronIndices",
      "type": "SetIndex",
      "xmlname": "hexahedronIndices",
      "help": "Indices of the hexahedra contained in the ROI"
    },
    {
      "name": "f_pointsInROI",
      "type": "VecCoord",
      "xmlname": "pointsInROI",
      "help": "Points contained in the ROI"
    },
    {
      "name": "f_pointsOutROI",
      "type": "VecCoord",
      "xmlname": "pointsOutROI",
      "help": "Points out of the ROI"
    },
    {
      "name": "f_nbrborder",
      "type": "unsigned int",
      "xmlname": "nbrborder",
      "help": "If localIndices option is activated, will give the number of vertices on the border of the ROI (being the n first points of each output Topology). "
    },
    {
      "name": "p_localIndices",
      "type": "bool",
      "xmlname": "localIndices",
      "help": "If true, will compute local dof indices in topological elements"
    },
    {
      "name": "p_drawROI",
      "type": "bool",
      "xmlname": "drawROI",
      "help": "Draw ROI"
    },
    {
      "name": "p_drawPoints",
      "type": "bool",
      "xmlname": "drawPoints",
      "help": "Draw Points"
    },
    {
      "name": "p_drawEdges",
      "type": "bool",
      "xmlname": "drawEdges",
      "help": "Draw Edges"
    },
    {
      "name": "p_drawTriangles",
      "type": "bool",
      "xmlname": "drawTriangle",
      "help": "Draw Triangles"
    },
    {
      "name": "p_drawTetrahedra",
      "type": "bool",
      "xmlname": "drawTetrahedra",
      "help": "Draw Tetrahedra"
    },
    {
      "name": "_drawSize",
      "type": "double",
      "xmlname": "drawSize",
      "help": "rendering size for box and topological elements"
    }
  ],
  "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"
    },
    {
      "name": "computeBBox",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "onlyVisible",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *&"
        },
        {
          "name": "context",
          "type": "core::objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "isPointInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "p",
          "type": "const CPos &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isPointInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "pid",
          "type": "const PointID &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isEdgeInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "e",
          "type": "const Edge &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isTriangleInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "t",
          "type": "const Triangle &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isQuadInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "t",
          "type": "const Quad &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isTetrahedronInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "t",
          "type": "const Tetra &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isHexahedronInROI",
      "return_type": "bool",
      "params": [
        {
          "name": "t",
          "type": "const Hexa &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findVertexOnBorder",
      "return_type": "void",
      "params": [
        {
          "name": "t",
          "type": "const Triangle &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findVertexOnBorder",
      "return_type": "void",
      "params": [
        {
          "name": "t",
          "type": "const Tetra &"
        },
        {
          "name": "idROI",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isPointChecked",
      "return_type": "bool",
      "params": [
        {
          "name": "id",
          "type": "unsigned int"
        },
        {
          "name": "pointChecked",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `SubsetTopology` component is an engine in the SOFA framework used to create subset topologies based on various geometrical regions such as boxes or spheres. It inherits from `DataEngine`, which enables it to operate within the scene graph structure and interact with other components. The primary role of this component is to identify points, edges, triangles, quads, tetrahedra, and hexahedra that fall within specified regions of interest (ROI), typically defined by bounding boxes or spheres.\n\n### Interactions with Other Components:\n- **Mechanical State:** It retrieves the rest position coordinates (`f_X0`) from a `MechanicalState` component, ensuring consistency in data representation.\n- **Mesh Topology:** It also interacts with `BaseMeshTopology` to access edge, triangle, quad, tetrahedron, and hexahedron topologies for processing.\n\n### Data Fields:\n- **Input Data:*\n  - `boxes`: Defines the bounding boxes by specifying min/max coordinates.\n  - `centers`, `radii`: For spherical regions, defines the center(s) and radius(i).\n  - `direction`, `normal`, `edgeAngle`, `triAngle`: Define constraints on edges and triangles based on direction and normal angles.\n- **Topological Data:*\n  - `f_X0`, `f_edges`, `f_triangles`, `f_quads`, `f_tetrahedra`, `f_hexahedra`: Input data representing the rest positions and various topologies of the elements (edges, triangles, quads, tetrahedra, hexahedra).\n- **Output Data:*\n  - `f_indices`, `f_edgeIndices`, `f_triangleIndices`, `f_quadIndices`, `f_tetrahedronIndices`, `f_hexahedronIndices`: Indices of elements contained within the ROI.\n  - `f_pointsInROI`, `f_pointsOutROI`: Points inside and outside the ROI respectively.\n  - `f_edgesInROI`, `f_trianglesInROI`, etc.: Topological elements (edges, triangles, quads, tetrahedra, hexahedra) contained within or outside the ROI.\n- **Parameter Data:*\n  - `p_localIndices`: A flag to compute local DOF indices in topological elements if set to true.\n  - Drawing parameters (`p_drawROI`, `p_drawPoints`, etc.): Control whether ROIs and different types of topology are drawn during visualization.\n\n### Usage Guidance:\n- Use this component when you need to isolate or process specific regions within a model's geometry based on predefined ROI (such as boxes or spheres).\n- Configure the input data fields (`boxes`, `centers`, `radii`) appropriately to define the region of interest.\n- Ensure that the correct topological elements are provided and that the component has access to mechanical states for accurate results.\n- The output indices and elements can be used further in downstream components for targeted operations.",
  "maths": "The `SubsetTopology` component in the SOFA framework is designed to create subset topologies based on geometrical regions, such as boxes or spheres. It operates by identifying and isolating specific elements (points, edges, triangles, quads, tetrahedra, hexahedra) within these predefined regions of interest (ROI). The primary role of this component is to filter and select the relevant topological elements based on their spatial location relative to specified bounding volumes. Here's a detailed mathematical and physical description of its functionality and role in the FEM simulation pipeline.\n\n### Governing Equations or Operators:\n- **Input Data:**\n  - `boxes`: A set of bounding boxes defined by minimum and maximum coordinates: \\(\text{box}_i = (x_{min}^{(i)}, y_{min}^{(i)}, z_{min}^{(i)}, x_{max}^{(i)}, y_{max}^{(i)}, z_{max}^{(i)})\\).\n  - `centers` and `radii`: Centers and radii of spherical regions: \\(\text{center}_i = (x_c^{(i)}, y_c^{(i)}, z_c^{(i)}), \text{radius}_i = r_i\\).\n- **Output Data:**\n  - Indices of elements within the ROI:\n    - `f_indices`: Points contained in the ROI.\n    - `f_edgeIndices`, `f_triangleIndices`, etc.: Edge, triangle, quad, tetrahedron, and hexahedra indices within the ROI.\n  - Lists of points and topological elements inside/outside the ROI:\n    - `f_pointsInROI`, `f_pointsOutROI`: Points inside and outside the ROI, respectively.\n    - `f_edgesInROI`, `f_trianglesInROI`, etc.: Topological elements (edges, triangles, quads, tetrahedra, hexahedra) contained within or outside the ROI.\n\n### Constitutive/Kinematic Laws Involved:\n- **Point Inclusion Check:**\n  - For a point \\(\textbf{p} = (x, y, z)\\), it is included in a box if:\n    \n    \\[\begin{cases}\n      x_{min}^{(i)} \n        & \text{and} &\n      y \notin [y_{min}^{(i)}, y_{max}^{(i)}] &\\text{or} &y \notin [z_{min}^{(i)}, z_{max}^{(i)}]\n    \\end{cases}\n  - For a point inside a sphere of radius \\(r_i\\) centered at \\(\textbf{c}_i = (x_c, y_c, z_c)\\):\n    \n    \\[(\textbf{p} - \textbf{c}_i)^2 \n\n### Role in the Global FEM Pipeline:\n- **Assembly Phase:** The component is used to filter and select elements based on their spatial location within specified regions. It does not contribute directly to assembling global mass or stiffness matrices but rather isolates specific subsets of elements for targeted operations.\n  - Points, edges, triangles, quads, tetrahedra, and hexahedra are filtered based on the defined ROIs using box or spherical inclusion criteria.\n- **Time Integration:** The component operates at a pre-processing stage before time integration. It provides indices and lists of elements for further processing in subsequent steps of the simulation pipeline.\n  - No direct involvement in time-stepping schemes or residual computations; it focuses on defining subsets based on spatial constraints.\n- **Nonlinear Resolution & Linear Solve:** The component outputs are used as inputs to other components that handle nonlinear resolution (e.g., implicit time integration, Newton-Raphson iterations) and linear solves. It does not contribute directly to solving the nonlinear system but provides the necessary input data.\n  - Elements within specific ROIs can be targeted for specialized material properties or boundary conditions in subsequent simulation steps.\n- **Constraint Handling:** The component does not impose constraints itself; however, it can help define regions where constraints (e.g., Dirichlet boundary conditions) might be applied.\n\n### Numerical Methods/Discretization Choices:\n- **Spatial Discretization:**\n  - Elements are classified based on their spatial location within predefined boxes or spheres. This is a preprocessing step that does not involve complex numerical integration but rather simple inclusion checks.\n- **Geometrical Region Definitions:**\n  - Boxes and spheres are defined using simple geometrical parameters, which allows for efficient point-inclusion tests without the need for complex numerical algorithms.\n\n### Fitting into Variational/Lagrangian Mechanics Framework:\n- The `SubsetTopology` component is a preprocessing tool that operates before variational formulations or Lagrangian mechanics principles are applied. It filters and selects elements based on spatial criteria, which can then be used in subsequent steps of the simulation pipeline.\n  - It does not directly contribute to the formulation of the weak form, but it provides essential data (indices, lists) for other components that will use variational or Lagrangian mechanics principles.\n\n### Summary:\n- **Mathematical Content:** The component primarily performs point-inclusion checks based on simple geometrical criteria without involving complex mathematical operators like mass matrices, stiffness matrices, internal forces, or residuals.\n- **Role in Simulation Pipeline:** It is used to define and isolate subsets of elements within specified regions, which can be further processed by other components involved in assembly, time integration, nonlinear solution steps, linear solves, and constraint handling.",
  "abstract": "`SubsetTopology` is an engine that creates subset topologies based on geometrical regions such as boxes or spheres by identifying elements within specified regions of interest (ROI).",
  "sheet": "# SubsetTopology\n\n## Overview\nThe `SubsetTopology` component is an engine used to create subset topologies based on geometrical regions such as boxes or spheres. It inherits from `DataEngine`, enabling it to interact with other components in the scene graph structure. The primary role of this component is to identify and isolate specific elements (points, edges, triangles, quads, tetrahedra, hexahedra) within predefined regions of interest (ROI).\n\n## Parameters and Data\nThe significant data fields exposed by `SubsetTopology` include:\n- **Input Data:*\n  - `direction`: Edge direction if `edgeAngle > 0`.\n  - `normal`: Normal direction of the triangles if `triAngle > 0`.\n  - `edgeAngle`: Max angle between the direction of selected edges and the specified direction.\n  - `triAngle`: Max angle between the normal of selected triangles and the specified normal direction.\n  - `f_X0`: Rest position coordinates of the degrees of freedom.\n  - `d_tetrahedraInput`: Indices of tetrahedra to keep.\n- **Output Data:*\n  - `f_indices`: Indices of points contained in the ROI.\n  - `f_edgeIndices`, `f_triangleIndices`, etc.: Indices of edges, triangles, quads, tetrahedra, and hexahedra contained in the ROI.\n  - `f_pointsInROI`, `f_pointsOutROI`: Points inside and outside the ROI, respectively.\n- **Parameter Data:*\n  - `p_localIndices`: A flag to compute local DOF indices in topological elements if set to true.\n  - Drawing parameters (`p_drawROI`, `p_drawPoints`, etc.): Control whether ROIs and different types of topology are drawn during visualization."
}