Methods

{
  "name": "DynamicSparseGridGeometryAlgorithms",
  "namespace": "sofa::component::topology::container::dynamic",
  "module": "Sofa.Component.Topology.Container.Dynamic",
  "include": "sofa/component/topology/container/dynamic/DynamicSparseGridGeometryAlgorithms.h",
  "doc": "Dynamic sparse grid geometry algorithms.\n\nA class that provides geometry information on an HexahedronSet.",
  "inherits": [
    "HexahedronSetGeometryAlgorithms"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "findNearestElementInRestPos",
      "return_type": "int",
      "params": [
        {
          "name": "pos",
          "type": "const Coord &"
        },
        {
          "name": "baryC",
          "type": "type::Vec3 &"
        },
        {
          "name": "distance",
          "type": "Real &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTopoIndexFromRegularGridIndex",
      "return_type": "core::topology::BaseMeshTopology::HexaID",
      "params": [
        {
          "name": "index",
          "type": "unsigned int"
        },
        {
          "name": "existing",
          "type": "bool &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRegularGridIndexFromTopoIndex",
      "return_type": "unsigned int",
      "params": [
        {
          "name": "index",
          "type": "core::topology::BaseMeshTopology::HexaID"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": {
    "summary": "The `DynamicSparseGridGeometryAlgorithms` class is part of the SOFA (Simulation Open-Framework Architecture) framework and provides algorithms for managing hexahedral elements in a sparse grid topology container.",
    "details": [
      "It inherits from `HexahedronSetGeometryAlgorithms`, which implies it handles operations specific to hexahedral mesh structures.",
      "This component is used to manage and manipulate hexahedral elements within a sparse grid, providing functionality for initializing the grid, finding nearest elements in rest positions, and converting between regular grid indices and topology indices.",
      "The `init()` method initializes the grid by retrieving the necessary mappings and containers from the context.",
      "The `getTopoIndexFromRegularGridIndex()` method retrieves the topology index corresponding to a given regular grid index.",
      "The `getRegularGridIndexFromTopoIndex()` method converts a topology index into its corresponding regular grid index.",
      "The `findNearestElementInRestPos()` method finds the nearest hexahedral element in rest position based on a given point, and computes the barycentric coefficients for that element."
    ],
    "methods": {
      "init()": {
        "description": "Initializes the grid by retrieving necessary mappings and containers from the context.",
        "implementationDetails": [
          "Retrieves `topoContainer` and `dof` from the context.",
          "Logs an error if these cannot be found."
        ]
      },
      "getTopoIndexFromRegularGridIndex(unsigned int index, bool& existing)": {
        "description": "Converts a regular grid index to its corresponding topology index.",
        "implementationDetails": [
          "Uses a map from `topoContainer` to find the mapping.",
          "Returns 0 if the conversion fails."
        ]
      },
      "getRegularGridIndexFromTopoIndex(BaseMeshTopology::HexaID index)": {
        "description": "Converts a topology index to its corresponding regular grid index.",
        "implementationDetails": [
          "Uses `topoContainer`'s internal data to perform the conversion."
        ]
      },
      "findNearestElementInRestPos(const Coord& pos, sofa::type::Vec3& baryC, Real& distance) const": {
        "description": "Finds the nearest hexahedral element in rest position based on a given point.",
        "implementationDetails": [
          "Projects the input point to the bounding box if it is outside the grid range.",
          "Iterates over neighboring elements to find the closest one and computes its distance and barycentric coefficients."
        ]
      }
    },
    "dependencies": {
      "HexahedronSetGeometryAlgorithms": "Base class providing common hexahedral geometry algorithms.",
      "DynamicSparseGridContainer": "Manages sparse grid topology, including mapping between regular and topology indices."
    },
    "usageExamples": [
      "This component can be used in simulations requiring efficient management of hexahedral elements within a sparse grid. For example, it can help in identifying the nearest element for point queries or computing distances in rest positions."
    ]
  },
  "maths": "### Mathematical and Physical Description\n\nThe `DynamicSparseGridGeometryAlgorithms` class in the SOFA framework is designed to manage hexahedral elements within a sparse grid topology container. The following sections detail the mathematical concepts and physical principles involved.\n\n#### Hexahedral Grid Structure\nA hexahedral mesh consists of elements that are six-faced polyhedra, typically cubes or rectangular prisms in 3D space. Each element can be represented by its vertices, with each vertex having coordinates (x, y, z).\n\nLet's denote a hexahedron as $H = \\{V_1, V_2, \\dots, V_8\\}$ where $V_i$ are the vertices of the hexahedron.\n\n#### Sparse Grid Topology\nA sparse grid is a data structure that efficiently manages elements in regions with varying densities. It allows for efficient storage and querying within regions where elements might be sparsely distributed or densely packed. The sparse grid stores elements using regular indices, which are mapped to topology indices used by the hexahedral mesh.\n\n#### Regular Grid Indices vs. Topology Indices\nThe `DynamicSparseGridGeometryAlgorithms` class provides methods for converting between these two index systems:\n- **Regular Grid Index**: A 3D coordinate system where each element is indexed based on its position in a regular grid structure, e.g., $(i, j, k)$.\n- **Topology Index**: An internal representation used by the hexahedral mesh to uniquely identify elements within the topology container.\n\nThe conversion methods are:\n1. **getTopoIndexFromRegularGridIndex(unsigned int index, bool& existing)**: Converts a regular grid index to its corresponding topology index.\n   - Let $G = (i, j, k)$ be a 3D coordinate in the regular grid.\n   - The conversion involves mapping $G$ to a unique topology index using the map provided by `topoContainer`.\n2. **getRegularGridIndexFromTopoIndex(BaseMeshTopology::HexaID index)**: Converts a topology index back to its corresponding regular grid index.\n   - This is typically performed by looking up the internal data structure in `topoContainer` that stores this mapping.\n\n#### Finding Nearest Element in Rest Position\nThe `findNearestElementInRestPos(const Coord& pos, sofa::type::Vec3& baryC, Real& distance) const` method computes the nearest hexahedral element to a given point and calculates its barycentric coefficients. The procedure involves:\n1. **Projection onto Bounding Box**: Project the input point $\\mathbf{p} = (x_p, y_p, z_p)$ onto the bounding box of the grid.\n   - This ensures that the query point lies within the valid range of indices in the sparse grid.\n2. **Nearest Element Search**:\n   - For a given projected point $\\mathbf{p}$, the method searches for the nearest hexahedral element by iterating over neighboring elements.\n   - The distance measure to each candidate element is computed using `computeElementRestDistanceMeasure(index, pos)`.\n3. **Barycentric Coefficients**:\n   - Once the closest element $H$ is found, its barycentric coefficients are calculated using `computeHexahedronRestBarycentricCoeficients(index, pos)`. These coefficients represent the position of $\\mathbf{p}$ within the hexahedron in terms of the relative contribution from each vertex.\n\n#### Initialization\nThe `init()` method initializes the grid by retrieving necessary mappings and containers from the context:\n- **topoContainer**: Manages the sparse grid topology, including mapping between regular and topology indices.\n- **dof**: Degrees-of-freedom object that might be required for further operations within the hexahedral mesh.\n\n### Summary\nThe `DynamicSparseGridGeometryAlgorithms` class leverages efficient data structures and algorithms to manage hexahedral elements in a sparse grid. It provides methods to convert between regular and topology indices, find nearest elements based on distance measures, and compute barycentric coefficients for accurate position representation within hexahedra.\n\nThese functionalities are critical for simulations requiring precise element management and querying within sparsely distributed regions.",
  "abstract": "The `DynamicSparseGridGeometryAlgorithms` class manages hexahedral elements within a sparse grid, providing methods for initializing the grid, converting between regular and topology indices, and finding nearest elements in rest positions.",
  "sheet": "# DynamicSparseGridGeometryAlgorithms\n\n## Overview\n\nThe `DynamicSparseGridGeometryAlgorithms` class is part of the SOFA framework and manages hexahedral elements within a sparse grid. It inherits from `HexahedronSetGeometryAlgorithms`, providing functionality for initializing the grid, converting between regular and topology indices, and finding nearest elements in rest positions.\n\n## Parameters and Data\n\nThis component does not expose any significant data fields.\n\n## Dependencies and Connections\n\nThe `DynamicSparseGridGeometryAlgorithms` class typically requires a `topoContainer` to manage sparse grid topology and mappings between regular and topology indices. It also interacts with the degrees-of-freedom (dof) object for further operations within the hexahedral mesh.\n\n## Practical Notes\n\nInitialization of the grid is critical, as it retrieves necessary mappings and containers from the context. The `findNearestElementInRestPos` method projects input points onto the bounding box if they are outside the grid range, ensuring valid queries. Conversion methods between regular and topology indices rely on internal data structures managed by `topoContainer`. Proper configuration of these dependencies is essential for accurate element management and querying within sparsely distributed regions."
}