{
  "name": "DynamicSparseGridTopologyContainer",
  "main": {
    "name": "DynamicSparseGridTopologyContainer",
    "namespace": "sofa::component::topology::container::dynamic",
    "module": "Sofa.Component.Topology.Container.Dynamic",
    "include": "sofa/component/topology/container/dynamic/DynamicSparseGridTopologyContainer.h",
    "doc": "Dynamic sparse grid geometry container.\n\na class that stores a sparse regular grid of hexahedra and provides a better loading and access to neighbors than HexahedronSetTopologyContainer */",
    "inherits": [
      "HexahedronSetTopologyContainer"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_resolution",
        "type": "sofa::type::Vec3i",
        "xmlname": "resolution",
        "help": "voxel grid resolution"
      },
      {
        "name": "d_voxelSize",
        "type": "type::Vec3",
        "xmlname": "voxelSize",
        "help": "Size of the Voxels"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `DynamicSparseGridTopologyContainer` is part of the SOFA framework, specifically within the topology container module designed to handle dynamic sparse grid geometry. It inherits from the `HexahedronSetTopologyContainer`, offering an enhanced method for managing a sparse regular grid of hexahedra. This component provides more efficient loading and access to neighboring elements compared to its base class.\n\n### Role and Purpose:\nThe primary role is to store and manage a sparse regular grid of hexahedra, which can be particularly useful in simulations where the topology needs to be dynamically updated or accessed efficiently. The grid structure helps in organizing the geometric data for computational efficiency, especially during interactive simulations.\n\n### Interactions with Other Components:\nThe component interacts with other SOFA components through its API, primarily inheriting and overriding methods from `HexahedronSetTopologyContainer`. It requires a `VoxelLoader` to initialize voxel data, indicating that it works closely with this loader for initializing the grid structure. The `init()` method ensures proper initialization by mapping indices between regular grids and topology structures.\n\n### Practical Usage Guidance:\nThe component is initialized using parameters such as `resolution`, which defines the size of the grid in each dimension, and `voxelSize`, indicating the dimensions of individual voxels within the grid. Data fields include mappings (`d_idInRegularGrid2IndexInTopo`) between regular grid indices and topology indices, as well as data storage for values indexed by both regular grid and topology structures.\n\n### Key Data Fields:\n- `resolution`: Defines the voxel grid resolution in three dimensions.\n- `voxelSize`: Specifies the size of individual voxels within the grid."
  },
  "maths": {
    "maths": "<maths_md_description>\n\n## Mathematical and Physical Description of `DynamicSparseGridTopologyContainer`\n\n### Overview\nThe `DynamicSparseGridTopologyContainer` is a specialized container in the SOFA framework designed to manage a sparse regular grid of hexahedra (3D cubes). This component enhances computational efficiency by providing an optimized structure for loading and accessing neighboring elements within the grid.\n\n### Role in Simulation\nThis topology container plays a critical role in simulations where dynamic updates or efficient access to geometric data are necessary. By organizing the grid into sparse structures, it reduces memory overhead and speeds up neighbor queries, which is particularly beneficial during interactive or real-time simulations.\n\n### Data Structures\nThe `DynamicSparseGridTopologyContainer` utilizes several key data structures for managing its topology:\n\n1. **Resolution (`d_resolution`)**: This vector defines the dimensions of the voxel grid in three-dimensional space. Let \\(\\mathbf{r} = (r_x, r_y, r_z)\\) represent the resolution where \\(r_x\\), \\(r_y\\), and \\(r_z\\) are the number of voxels along each axis.\n\n2. **Voxel Size (`d_voxelSize`)**: This vector defines the size of individual voxels within the grid. Let \\(\\mathbf{s} = (s_x, s_y, s_z)\\) represent the voxel size where \\(s_x\\), \\(s_y\\), and \\(s_z\\) are the dimensions along each axis.\n\n3. **Indices in Regular Grid (`d_idxInRegularGrid`)**: This vector stores the indices of hexahedra within the regular grid, enabling efficient access to specific elements.\n\n4. **Mapping Between Indices (`d_idInRegularGrid2IndexInTopo`)**: This map provides a mapping between indices in the regular grid and indices in the topology structure, facilitating translation between different indexing schemes.\n\n5. **Values Indexed in Regular Grid (`d_valuesIndexedInRegularGrid`)**: A vector storing values indexed by their positions within the regular grid.\n\n6. **Values Indexed in Topology (`d_valuesIndexedInTopology`)**: Another vector storing values indexed according to the topology structure, which is typically sparser and more efficient for certain operations.\n\n### Initialization\nThe `init()` method initializes the container by setting up mappings and values based on data provided by a `VoxelLoader`. This loader ensures that all necessary information about the grid's geometry and properties is correctly loaded into the component. The initialization process involves:\n\n- Mapping indices between regular grids and topology structures.\n- Initializing voxel data from the `VoxelLoader` to populate the values indexed in both regular grids and topologies.\n\n### Mathematical Representation\nThe mathematical representation of the grid can be described as follows:\n\n1. **Grid Resolution**: The resolution \\(\\mathbf{r} = (r_x, r_y, r_z)\\) defines the number of hexahedra along each axis.\n2. **Voxel Size**: The voxel size \\(\\mathbf{s} = (s_x, s_y, s_z)\\) determines the dimensions of individual voxels within the grid.\n\nThe positions of hexahedra in the grid can be indexed using a 3D coordinate system:\n\n$$\n\\text{Index}(i, j, k) = i + r_x \\cdot (j + r_y \\cdot k)\n$$\n\nwhere \\(i\\), \\(j\\), and \\(k\\) are indices along the respective axes.\n\n### Conclusion\nThe `DynamicSparseGridTopologyContainer` optimizes the management of a sparse regular grid of hexahedra, enhancing efficiency in loading and accessing geometric data. This makes it particularly suitable for simulations requiring dynamic updates or real-time interaction with complex topologies.</maths_md_description>"
  },
  "summary": {
    "abstract": "The `DynamicSparseGridTopologyContainer` manages sparse regular grids of hexahedra for efficient loading and access to neighboring elements in SOFA simulations. It inherits from `HexahedronSetTopologyContainer`, offering enhanced computational efficiency.",
    "sheet": "# DynamicSparseGridTopologyContainer\n\n## Overview\n\nThe `DynamicSparseGridTopologyContainer` is a specialized container within the SOFA framework designed to manage sparse regular grids of hexahedra, enhancing computational efficiency in simulations. It inherits from `HexahedronSetTopologyContainer`, providing optimized loading and access to neighboring elements.\n\n## Parameters and Data\n\n- **resolution (`d_resolution`)**: Defines the voxel grid resolution in three dimensions as a vector \\\\( \\mathbf{r} = (r_x, r_y, r_z) \\\\), where \\\\( r_x \\\\), \\\\( r_y \\\\), and \\\\( r_z \\\\) are the number of voxels along each axis.\n\n- **voxelSize (`d_voxelSize`)**: Specifies the size of individual voxels within the grid as a vector \\\\( \\mathbf{s} = (s_x, s_y, s_z) \\\\), where \\\\( s_x \\\\), \\\\( s_y \\\\), and \\\\( s_z \\\\) are the dimensions along each axis.\n\n## Dependencies and Connections\n\nThe `DynamicSparseGridTopologyContainer` typically requires a `VoxelLoader` to initialize voxel data, indicating that it works closely with this loader for initializing the grid structure. It fits into the scene graph by providing an optimized topology container for managing sparse regular grids of hexahedra."
  }
}