Data Fields

Methods

{
  "name": "PlaneROI",
  "namespace": "sofa::component::engine::select",
  "module": "Sofa.Component.Engine.Select",
  "include": "sofa/component/engine/select/PlaneROI.h",
  "doc": "Find the primitives inside a given plane.\n\nThis class find all the points located inside a given box.",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_X0",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "Rest position coordinates of the degrees of freedom"
    },
    {
      "name": "f_computeEdges",
      "type": "bool",
      "xmlname": "computeEdges",
      "help": "If true, will compute edge list and index list inside the ROI."
    },
    {
      "name": "f_computeTriangles",
      "type": "bool",
      "xmlname": "computeTriangles",
      "help": "If true, will compute triangle list and index list inside the ROI."
    },
    {
      "name": "f_computeTetrahedra",
      "type": "bool",
      "xmlname": "computeTetrahedra",
      "help": "If true, will compute tetrahedra list and index list inside the ROI."
    },
    {
      "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_tetrahedronIndices",
      "type": "SetIndex",
      "xmlname": "tetrahedronIndices",
      "help": "Indices of the tetrahedra contained in the ROI"
    },
    {
      "name": "f_pointsInROI",
      "type": "VecCoord",
      "xmlname": "pointsInROI",
      "help": "Points contained in the ROI"
    },
    {
      "name": "p_drawBoxes",
      "type": "bool",
      "xmlname": "drawBoxes",
      "help": "Draw Box(es)"
    },
    {
      "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": "drawTriangles",
      "help": "Draw Triangles"
    },
    {
      "name": "p_drawTetrahedra",
      "type": "bool",
      "xmlname": "drawTetrahedra",
      "help": "Draw Tetrahedra"
    },
    {
      "name": "_drawSize",
      "type": "float",
      "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": "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": "isPointInPlane",
      "return_type": "bool",
      "params": [
        {
          "name": "p",
          "type": "const CPos &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isPointInPlane",
      "return_type": "bool",
      "params": [
        {
          "name": "pid",
          "type": "const PointID &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isEdgeInPlane",
      "return_type": "bool",
      "params": [
        {
          "name": "e",
          "type": "const Edge &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isTriangleInPlane",
      "return_type": "bool",
      "params": [
        {
          "name": "t",
          "type": "const Triangle &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isTetrahedronInPlane",
      "return_type": "bool",
      "params": [
        {
          "name": "t",
          "type": "const Tetra &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computePlane",
      "return_type": "void",
      "params": [
        {
          "name": "planeIndex",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `PlaneROI` component in the SOFA framework is designed to find geometric primitives (points, edges, triangles, and tetrahedra) that lie within specified planes or regions of interest (ROIs). This class inherits from `core::DataEngine`, which means it processes input data to produce new outputs based on computational operations.\n\n### Role in the SOFA Ecosystem:\nThe primary purpose of `PlaneROI` is to perform spatial queries by identifying and extracting points, edges, triangles, and tetrahedra that are located inside a given plane or ROI. It operates on topological elements extracted from input data such as rest positions, edge lists, triangle lists, and tetrahedron lists.\n\n### Interactions with Other Components:\nThe `PlaneROI` component interacts with other components through the SOFA API by receiving input data fields like `f_X0`, which represents the rest position coordinates of degrees of freedom. It can also integrate with topology-related components to access edge, triangle, and tetrahedron lists if they are not directly provided.\n\n### Practical Usage Guidance:\nThe component allows users to specify whether to compute edges (`f_computeEdges`), triangles (`f_computeTriangles`), and tetrahedra (`f_computeTetrahedra`) inside the ROI. Output fields include indices of points, edges, triangles, and tetrahedra within the ROI as well as their geometric representations.\n\n- **Input Fields**:\n  - `f_X0`: Rest position coordinates of degrees of freedom (required).\n  - `planes`: List of planes defined by three points and a depth distance.\n  - `f_edges`, `f_triangles`, `f_tetrahedra`: Lists representing edge, triangle, and tetrahedron topologies.\n\n- **Output Fields**:\n  - `f_indices`, `f_edgeIndices`, `f_triangleIndices`, `f_tetrahedronIndices`: Indices of points, edges, triangles, and tetrahedra inside the ROI.\n  - `f_pointsInROI`, `f_edgesInROI`, `f_trianglesInROI`, `f_tetrahedraInROI`: Geometric representations of elements within the ROI.\n\n- **Parameter Fields**:\n  - `p_drawBoxes`, `p_drawPoints`, `p_drawEdges`, `p_drawTriangles`, `p_drawTetrahedra`: Flags to control visualization of various topological elements within the ROI.\n  - `_drawSize`: Controls rendering size for box and topological elements.\n\n### Methods:\nThe component includes methods such as `doUpdate` which computes and updates indices of geometric primitives inside specified planes, `init` for initialization, and `draw` to visualize these elements if enabled.",
  "maths": "The `PlaneROI` component in the SOFA framework is designed to identify geometric primitives (points, edges, triangles, and tetrahedra) located within specified planes or regions of interest (ROIs). This class does not contribute directly to the governing equations or operators typically involved in finite element simulations such as mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, or residual $R$. Instead, it operates on topological elements and extracts subsets based on spatial criteria.\n\n### Governing Equations:\nSince `PlaneROI` does not implement any governing equations related to mechanics, it does not contribute directly to the variational formulation or weak form of the system. Its role is purely geometric, focusing on identifying and extracting elements within specified planes.\n\n### Constitutive Laws:\nThe component itself does not involve constitutive laws, stress tensors, hyperelastic potentials, damping models, constraint Jacobians, etc., as it operates at a higher level of abstraction—manipulating topological data rather than mechanical properties.\n\n### Role in the Global FEM Pipeline:\nIn the broader context of the FEM simulation pipeline, `PlaneROI` plays a supporting role by providing spatial queries and filtering operations on geometric entities. It does not directly participate in assembly, time integration, nonlinear solve, linear solve, constraint handling, or mappings.\n\n### Numerical Methods and Discretization Choices:\nThe component uses basic geometric checks to determine if points, edges, triangles, or tetrahedra are located within specified planes. Specifically, it computes whether a primitive lies inside a plane defined by three points and a depth distance, using vector operations such as dot products and cross products for the spatial queries.\n\n### Integration into Variational / Lagrangian Mechanics Framework:\nThe `PlaneROI` component does not directly integrate into the variational or Lagrangian mechanics framework. Instead, it provides auxiliary functionality that can be used in conjunction with other components to perform geometric operations or filtering tasks on topological elements.\n\n### Detailed Mathematical Description of Geometric Checks:\n- **Point In Plane Check**: For a point $p$, determine if it lies within the defined plane by checking its distance from the plane boundaries. Specifically, for each face of the bounding box (defined by three points and depth), compute distances using dot products and compare to the width, length, and depth dimensions.\n\n    \n  - **Edge In Plane Check**: For an edge $e$ with endpoints $p_1$ and $p_2$, check if both endpoints lie within the plane. If either endpoint is outside the plane boundaries, the entire edge is considered outside.\n\n      \n  - **Triangle In Plane Check**: For a triangle $t$ with vertices $p_1$, $p_2$, and $p_3$, verify that all three vertices are inside the plane using the same point-in-plane checks.\n\n      \n  - **Tetrahedron In Plane Check**: Similarly, for a tetrahedron $t$ with vertices $p_1$, $p_2$, $p_3$, and $p_4$, ensure all four vertices lie within the plane boundaries.\n\n    These checks are performed iteratively over multiple planes if specified in the input data. The component outputs indices of primitives inside each defined ROI, facilitating further operations or visualizations based on these filtered geometric entities.",
  "abstract": "The `PlaneROI` component identifies geometric primitives (points, edges, triangles, tetrahedra) within specified planes or regions of interest, providing indices and geometric representations of elements inside these ROIs.",
  "sheet": "# PlaneROI\n\n## Overview\nThe `PlaneROI` component in the SOFA framework is designed to identify points, edges, triangles, and tetrahedra that lie within specified planes or regions of interest (ROIs). It inherits from `DataEngine`, processing input data to produce indices and geometric representations of elements inside these ROIs.\n\n## Parameters and Data\nThe significant Data fields exposed by the component include:\n- **Input Fields**:\n  - `f_X0`: Rest position coordinates of degrees of freedom (required).\n  - `planes`: List of planes defined by three points and a depth distance.\n  - `f_edges`, `f_triangles`, `f_tetrahedra`: Lists representing edge, triangle, and tetrahedron topologies.\n- **Output Fields**:\n  - `f_indices`, `f_edgeIndices`, `f_triangleIndices`, `f_tetrahedronIndices`: Indices of points, edges, triangles, and tetrahedra inside the ROI.\n  - `f_pointsInROI`, `f_edgesInROI`, `f_trianglesInROI`, `f_tetrahedraInROI`: Geometric representations of elements within the ROI.\n- **Parameter Fields**:\n  - `p_drawBoxes`, `p_drawPoints`, `p_drawEdges`, `p_drawTriangles`, `p_drawTetrahedra`: Flags to control visualization of various topological elements within the ROI.\n  - `_drawSize`: Controls rendering size for box and topological elements.\n\n## Practical Notes\nThe component allows users to specify whether to compute edges, triangles, and tetrahedra inside the ROI through parameters `f_computeEdges`, `f_computeTriangles`, and `f_computeTetrahedra`. The indices of geometric primitives within each defined plane are computed iteratively using basic geometric checks."
}