Data Fields

Links

Methods

{
  "name": "TopologyBoundingTrasher",
  "namespace": "sofa::component::topology::utility",
  "module": "Sofa.Component.Topology.Utility",
  "include": "sofa/component/topology/utility/TopologyBoundingTrasher.h",
  "doc": "Component removing all elements going outside from the given bounding box.\n\nRead file containing topological modification. Or apply input modifications\nA timestep has to be established for each modification.",
  "inherits": [
    "BaseObject"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_positions",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "position coordinates of the topology object to interact with."
    },
    {
      "name": "d_borders",
      "type": "Vec6",
      "xmlname": "box",
      "help": "List of boxes defined by xmin,ymin,zmin, xmax,ymax,zmax"
    },
    {
      "name": "d_drawBox",
      "type": "bool",
      "xmlname": "drawBox",
      "help": "Draw bounding box (default = false)"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "filterElementsToRemove",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "removeElements",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isPointOutside",
      "return_type": "bool",
      "params": [
        {
          "name": "value",
          "type": "const Coord &"
        },
        {
          "name": "bb",
          "type": "const Vec6 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "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": "handleEvent",
      "return_type": "void",
      "params": [
        {
          "name": "event",
          "type": "sofa::core::objectmodel::Event *"
        }
      ],
      "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 **TopologyBoundingTrasher** is a utility component in the SOFA framework designed to remove elements from a topology that go outside a specified bounding box. This component interacts with a linked `BaseMeshTopology` object, which it uses to identify and eliminate elements based on their positions relative to the defined bounds.\n\n#### Role and Purpose:\nThe primary role of **TopologyBoundingTrasher** is to filter out or remove topological elements that exceed given spatial limits, ensuring that only elements within a specific bounding box are retained. This is useful for maintaining simulation accuracy by excluding elements outside the region of interest.\n\n#### Interactions with Other Components:\n- **BaseMeshTopology**: It links to this component to access and modify the topology data.\n- **MechanicalState**: Indirectly interacts through shared topological information, as changes in topology can affect mechanical properties.\n- **Topological Modifiers (EdgeSetTopologyModifier, TriangleSetTopologyModifier, etc.)**: These are used to remove elements based on their type.\n\n#### Practical Usage Guidance:\nThe component requires setting the `topology` link and defining the bounding box through the `box` field. If enabled via `drawBox`, it can also visually represent this bounding box in the simulation environment.\n- **Data Fields**:\n  - **position**: Position coordinates of the topology object to interact with.\n  - **box**: Defines the bounding box by its limits (`xmin, ymin, zmin, xmax, ymax, zmax`).\n  - **drawBox**: Boolean flag to draw the bounding box for visualization (default is false).\n\n#### Key Methods:\nThe component operates through methods like `filterElementsToRemove`, which identifies elements outside the bounding box, and `removeElements`, which removes these identified elements from the topology. It handles events such as simulation updates to continuously filter out any newly created or moved elements that fall outside the defined bounds.",
  "maths": "### Mathematical and Physical Description of TopologyBoundingTrasher\n\n#### Governing Equations and Operators:\n- The **TopologyBoundingTrasher** does not directly contribute to the governing equations such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(f_{int}\\), or residual \\(R\\). Instead, it operates on a higher-level topological basis by removing elements that go outside a specified bounding box.\n\n#### Constitutive and Kinematic Laws:\n- **TopologyBoundingTrasher** does not involve any constitutive laws (strain measures, stress tensors, hyperelastic potentials) or kinematic models. Its functionality is purely geometric/topological, based on the positions of mesh elements relative to the defined bounding box.\n\n#### Role in Global FEM Pipeline:\n- The component operates during the assembly phase by filtering out elements that are outside a given bounding box before further processing like mass and stiffness matrix formation occurs. It acts as a preprocessing step within the simulation pipeline, ensuring only relevant elements are retained for subsequent calculations such as linear solve or nonlinear solve.\n\n#### Numerical Methods and Discretization Choices:\n- **TopologyBoundingTrasher** employs simple geometric checks to determine if an element is outside the bounding box. Specifically, it computes the barycenter of each mesh element (e.g., hexahedron, tetrahedron) and verifies whether this barycenter lies within the defined limits \\([xmin, ymin, zmin]\\), \\([xmax, ymax, zmax]\\).\n\n#### Variational / Lagrangian Mechanics Framework:\n- The component does not directly fit into variational or Lagrangian mechanics as it is a utility for topological management rather than physical simulation. However, by filtering out elements outside the bounding box, **TopologyBoundingTrasher** indirectly supports maintaining a consistent and physically meaningful topology within the simulation domain.\n\n#### Geometric Filtering Method:\n- The component checks if an element’s barycenter lies outside the specified bounding box via the `isPointOutside` method. For example, for an element \\(e\\) with barycenter position \\(\text{bary}\\), it determines whether \\(\text{bary}[i]\\) is within the range defined by the bounding box limits:\n\n\begin{align*}\n  \text{if } (\text{bary}[0] < xmin \text{ or } \text{bary}[0] > xmax) &\\Rightarrow \\text{element outside} \\\\\n  \text{if } (\text{bary}[1] < ymin \text{ or } \text{bary}[1] > ymax) &\\Rightarrow \\text{element outside} \\\\\n  \text{if } (\text{bary}[2] < zmin \text{ or } \text{bary}[2] > zmax) &\\Rightarrow \\text{element outside}\n\tag{1}\n\begin{align*}\n\n- If any of these conditions are met, the element is marked for removal.\n\n#### Example Workflow:\n1. **Initialization**: The component initializes and links to a `BaseMeshTopology` object.\n2. **Event Handling**: On simulation updates (`AnimateEndEvent`), it triggers `filterElementsToRemove`, which computes barycenters of elements and checks them against the bounding box using \\((1)\\).\n3. **Removal**: Identified elements are removed from the topology via respective modifiers (e.g., `EdgeSetTopologyModifier`, `TriangleSetTopologyModifier`).\n4. **Visualization** (optional): If enabled, it draws the defined bounding box for visual verification.\n\n#### Conclusion:\n- **TopologyBoundingTrasher** is a utility component that ensures topological consistency by removing elements outside a specified bounding box, thereby supporting accurate and meaningful FEM simulations.",
  "abstract": "The TopologyBoundingTrasher removes elements from a topology if they go outside a specified bounding box, ensuring only relevant elements are retained within the simulation domain.",
  "sheet": "# TopologyBoundingTrasher\n\n**Overview:**\n- The **TopologyBoundingTrasher** is a utility component that filters out topological elements exceeding given spatial limits. It links to `BaseMeshTopology` for accessing and modifying topology data.\n\n**Parameters and Data**:\n- **position**: Position coordinates of the topology object (`VecCoord`).\n- **box**: Defines the bounding box by its limits (`xmin, ymin, zmin, xmax, ymax, zmax`) (`Vec6`).\n- **drawBox**: Boolean flag to draw the bounding box for visualization (default is false) (`bool`).\n\n**Dependencies and Connections:**\n- The component requires a link to `BaseMeshTopology` to access and modify topology data.\n\n**Practical Notes:**\n- Ensure the `topology` link is set correctly, and define the bounding box through the `box` field. If enabled via `drawBox`, it can visually represent this bounding box in the simulation environment."
}