SparseGridTopology

sofa::component::topology::container::grid::SparseGridTopology

MeshTopology

Doc (from source)

Sparse grid in 3D. A sparse grid topology. Like a sparse FFD building from the bounding box of the object. Starting from a RegularGrid, only valid cells containing matter (ie intersecting the original surface mesh or totally inside the object) are considered. Valid cells are tagged by a Type BOUNDARY or INSIDE WARNING: the corresponding node in the XML file has to be placed BEFORE the MechanicalObject node, in order to execute its init() before the MechanicalObject one in order to be able to give dofs

Abstract (AI generated)

The `SparseGridTopology` creates sparse grid representations in 3D by retaining only cells containing matter or entirely inside an object, categorizing them as BOUNDARY or INSIDE.

Metadata

module

Sofa.Component.Topology.Container.Grid

namespace

sofa::component::topology::container::grid

include

sofa/component/topology/container/grid/SparseGridTopology.h

inherits

MeshTopology

description

Mathematical and Physical Description of SparseGridTopology

Overview

The SparseGridTopology is designed to represent a sparse grid topology in 3D, which begins from a regular grid but only retains valid cells that either contain matter or are entirely within the object. This approach reduces computational overhead by avoiding unnecessary dense grids.

Governing Equations and Operators

Resolution Parameters:
- Grid resolution is defined by d_n, a vector of integers indicating the number of points in each direction (x, y, z).
- Bounding box dimensions are given by d_min and d_max, which specify the minimum and maximum coordinates for the grid.
Boundary Conditions:
- Valid cells are categorized into two types: BOUNDARY (containing part of the surface) and INSIDE (completely within the object).
- The boundary conditions are handled by tagging each cell appropriately based on its intersection with the original surface mesh or complete containment within the object.

Constitutive or Kinematic Laws

Stiffness Coefficients:
- Each hexahedron in the sparse grid has associated stiffness coefficients. These can be adjusted based on whether the cell is categorized as BOUNDARY (default 0.5) or INSIDE (default 1).
- The stiffness coefficient for a given element can be accessed via getStiffnessCoef(Index elementIdx).
Mass Coefficients:
- Similarly, each hexahedron has associated mass coefficients which are also categorized based on the cell type (BOUNDARY or INSIDE).
- The mass coefficient for a given element can be accessed via getMassCoef(Index elementIdx).

Role in FEM Pipeline

Mesh Generation:
- The sparse grid topology is generated by initializing from various inputs, including triangle meshes (buildFromTriangleMesh), voxel files (buildFromVoxelFile), or directly from regular grids (buildAsFinest).
Assembly Phase:
- After the mesh generation and categorization of cells into BOUNDARY and INSIDE, the topology is assembled. This includes defining hexahedra, computing stiffness coefficients, and mass coefficients.

Numerical Methods or Discretization Choices

Discretization:
- The grid is discretized based on the specified resolution (d_n) and bounding box dimensions (d_min, d_max).
- Only valid cells are retained in the topology, leading to a sparse grid structure.

Variational Mechanics Framework

Variational Formulation:
- The variational formulation is implicitly handled by categorizing cells into BOUNDARY and INSIDE. This ensures that only relevant parts of the mesh contribute to the overall system dynamics and mechanics.

Summary

The SparseGridTopology in SOFA provides a flexible and efficient way to manage complex 3D topologies while minimizing computational overhead. By leveraging sparse grid structures, it enables more detailed simulations with fewer resources.

Data Fields

Name	Type	Help
`d_fillWeighted`	bool	Is quantity of matter inside a cell taken into account? (.5 for boundary, 1 for inside)
`d_bOnlyInsideCells`	bool	Select only inside cells (exclude boundary cells)
`d_n`	sofa::type::Vec<3, int>	grid resolution
`d_min`	type::Vec3	Min
`d_max`	type::Vec3	Max
`d_cellWidth`	SReal	if > 0 : dimension of each cell in the created grid
`d_nbVirtualFinerLevels`	int	create virtual (not in the animation tree) finer sparse grids in order to dispose of finest information (useful to compute better mechanical properties for example)
`d_dataResolution`	type::Vec3i	Dimension of the voxel File
`d_voxelSize`	type::Vec3	Dimension of one voxel
`d_marchingCubeStep`	unsigned int	Step of the Marching Cube algorithm
`d_convolutionSize`	unsigned int	Dimension of the convolution kernel to smooth the voxels. 0 if no smoothing is required.

Methods

void init () virtual

void buildAsFinest () virtual

void buildFromFiner () virtual

void buildVirtualFinerLevels () virtual

int getNbVirtualFinerLevels ()

void setNbVirtualFinerLevels (int n)

sofa::type::Vec<3, int> getN ()

int getNx ()

int getNy ()

int getNz ()

void setN (type::Vec3i _n)

void setNx (int _n)

void setNy (int _n)

void setNz (int _n)

void setMin (type::Vec3 val)

void setXmin (SReal val)

void setYmin (SReal val)

void setZmin (SReal val)

void setMax (type::Vec3 val)

void setXmax (SReal val)

void setYmax (SReal val)

void setZmax (SReal val)

type::Vec3 getMin ()

SReal getXmin ()

SReal getYmin ()

SReal getZmin ()

type::Vec3 getMax ()

SReal getXmax ()

SReal getYmax ()

SReal getZmax ()

bool hasPos () virtual

Index findCube (const type::Vec3 & pos, SReal & fx, SReal & fy, SReal & fz) virtual

Index findNearestCube (const type::Vec3 & pos, SReal & fx, SReal & fy, SReal & fz) virtual

int findneighboorCubes (Index indice)

Type getType (Index i) virtual

float getStiffnessCoef (Index elementIdx) virtual

float getMassCoef (Index elementIdx) virtual

SparseGridTopology * getFinerSparseGrid ()

void setFinerSparseGrid (SparseGridTopology * fsp)

SparseGridTopology * getCoarserSparseGrid ()

void setCoarserSparseGrid (SparseGridTopology * csp)

void updateMesh ()

type::Vec3 getPointPos (Index i)

void getMesh (sofa::helper::io::Mesh & m)

void setDimVoxels (int a, int b, int c)

void setSizeVoxel (SReal a, SReal b, SReal c)

bool getVoxel (unsigned int x, unsigned int y, unsigned int z)

bool getVoxel (unsigned int index)

void buildFromData (type::Vec3i numPoints, type::BoundingBox box, const int & filling)

void updateEdges () virtual

void updateQuads () virtual

void launchPropagationFromSeed (const type::Vec3i & point, int regularGrid, int & regularGrdidTypes, int & alreadyTested, int & seed)

void propagateFrom (const type::Vec3i & point, int regularGrid, int & regularGridTypes, int & alreadyTested, int & seed)

void computeBoundingBox (const int & vertices, SReal & xmin, SReal & xmax, SReal & ymin, SReal & ymax, SReal & zmin, SReal & zmax)

void voxelizeTriangleMesh (helper::io::Mesh * mesh, int regularGrid, int & regularGridTypes)

void buildFromTriangleMesh (sofa::helper::io::Mesh * mesh)

void buildFromRegularGridTypes (int regularGrid, const int & regularGridTypes)

void buildFromVoxelFile (const int & filename)

void buildFromRawVoxelFile (const int & filename)

void buildFromVoxelLoader (sofa::core::loader::VoxelLoader * loader)

void constructCollisionModels (const int & list_mesh, const int & list_X)

void setVoxel (int index, unsigned char value)

const int & getHexahedra ()

int getNbPoints ()

int getNbHexahedra ()

{
  "name": "SparseGridTopology",
  "namespace": "sofa::component::topology::container::grid",
  "module": "Sofa.Component.Topology.Container.Grid",
  "include": "sofa/component/topology/container/grid/SparseGridTopology.h",
  "doc": "Sparse grid in 3D.\n\nA sparse grid topology. Like a sparse FFD building from the bounding box of the object. Starting from a RegularGrid, only valid cells containing matter (ie intersecting the original surface mesh or totally inside the object) are considered.\nValid cells are tagged by a Type BOUNDARY or INSIDE\nWARNING: the corresponding node in the XML file has to be placed BEFORE the MechanicalObject node, in order to execute its init() before the MechanicalObject one in order to be able to give dofs",
  "inherits": [
    "MeshTopology"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_fillWeighted",
      "type": "bool",
      "xmlname": "fillWeighted",
      "help": "Is quantity of matter inside a cell taken into account? (.5 for boundary, 1 for inside)"
    },
    {
      "name": "d_bOnlyInsideCells",
      "type": "bool",
      "xmlname": "onlyInsideCells",
      "help": "Select only inside cells (exclude boundary cells)"
    },
    {
      "name": "d_n",
      "type": "sofa::type::Vec<3, int>",
      "xmlname": "n",
      "help": "grid resolution"
    },
    {
      "name": "d_min",
      "type": "type::Vec3",
      "xmlname": "min",
      "help": "Min"
    },
    {
      "name": "d_max",
      "type": "type::Vec3",
      "xmlname": "max",
      "help": "Max"
    },
    {
      "name": "d_cellWidth",
      "type": "SReal",
      "xmlname": "cellWidth",
      "help": "if > 0 : dimension of each cell in the created grid"
    },
    {
      "name": "d_nbVirtualFinerLevels",
      "type": "int",
      "xmlname": "nbVirtualFinerLevels",
      "help": "create virtual (not in the animation tree) finer sparse grids in order to dispose of finest information (useful to compute better mechanical properties for example)"
    },
    {
      "name": "d_dataResolution",
      "type": "type::Vec3i",
      "xmlname": "dataResolution",
      "help": "Dimension of the voxel File"
    },
    {
      "name": "d_voxelSize",
      "type": "type::Vec3",
      "xmlname": "voxelSize",
      "help": "Dimension of one voxel"
    },
    {
      "name": "d_marchingCubeStep",
      "type": "unsigned int",
      "xmlname": "marchingCubeStep",
      "help": "Step of the Marching Cube algorithm"
    },
    {
      "name": "d_convolutionSize",
      "type": "unsigned int",
      "xmlname": "convolutionSize",
      "help": "Dimension of the convolution kernel to smooth the voxels. 0 if no smoothing is required."
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildAsFinest",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildFromFiner",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildVirtualFinerLevels",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNbVirtualFinerLevels",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setNbVirtualFinerLevels",
      "return_type": "void",
      "params": [
        {
          "name": "n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getN",
      "return_type": "sofa::type::Vec<3, int>",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNx",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNy",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNz",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setN",
      "return_type": "void",
      "params": [
        {
          "name": "_n",
          "type": "type::Vec3i"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setNx",
      "return_type": "void",
      "params": [
        {
          "name": "_n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setNy",
      "return_type": "void",
      "params": [
        {
          "name": "_n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setNz",
      "return_type": "void",
      "params": [
        {
          "name": "_n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMin",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "type::Vec3"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setXmin",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setYmin",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setZmin",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMax",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "type::Vec3"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setXmax",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setYmax",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setZmax",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMin",
      "return_type": "type::Vec3",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getXmin",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getYmin",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getZmin",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMax",
      "return_type": "type::Vec3",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getXmax",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getYmax",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getZmax",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "hasPos",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findCube",
      "return_type": "Index",
      "params": [
        {
          "name": "pos",
          "type": "const type::Vec3 &"
        },
        {
          "name": "fx",
          "type": "SReal &"
        },
        {
          "name": "fy",
          "type": "SReal &"
        },
        {
          "name": "fz",
          "type": "SReal &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findNearestCube",
      "return_type": "Index",
      "params": [
        {
          "name": "pos",
          "type": "const type::Vec3 &"
        },
        {
          "name": "fx",
          "type": "SReal &"
        },
        {
          "name": "fy",
          "type": "SReal &"
        },
        {
          "name": "fz",
          "type": "SReal &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findneighboorCubes",
      "return_type": "int",
      "params": [
        {
          "name": "indice",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getType",
      "return_type": "Type",
      "params": [
        {
          "name": "i",
          "type": "Index"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStiffnessCoef",
      "return_type": "float",
      "params": [
        {
          "name": "elementIdx",
          "type": "Index"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMassCoef",
      "return_type": "float",
      "params": [
        {
          "name": "elementIdx",
          "type": "Index"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFinerSparseGrid",
      "return_type": "SparseGridTopology *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setFinerSparseGrid",
      "return_type": "void",
      "params": [
        {
          "name": "fsp",
          "type": "SparseGridTopology *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCoarserSparseGrid",
      "return_type": "SparseGridTopology *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setCoarserSparseGrid",
      "return_type": "void",
      "params": [
        {
          "name": "csp",
          "type": "SparseGridTopology *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateMesh",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPointPos",
      "return_type": "type::Vec3",
      "params": [
        {
          "name": "i",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMesh",
      "return_type": "void",
      "params": [
        {
          "name": "m",
          "type": "sofa::helper::io::Mesh &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDimVoxels",
      "return_type": "void",
      "params": [
        {
          "name": "a",
          "type": "int"
        },
        {
          "name": "b",
          "type": "int"
        },
        {
          "name": "c",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setSizeVoxel",
      "return_type": "void",
      "params": [
        {
          "name": "a",
          "type": "SReal"
        },
        {
          "name": "b",
          "type": "SReal"
        },
        {
          "name": "c",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getVoxel",
      "return_type": "bool",
      "params": [
        {
          "name": "x",
          "type": "unsigned int"
        },
        {
          "name": "y",
          "type": "unsigned int"
        },
        {
          "name": "z",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getVoxel",
      "return_type": "bool",
      "params": [
        {
          "name": "index",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildFromData",
      "return_type": "void",
      "params": [
        {
          "name": "numPoints",
          "type": "type::Vec3i"
        },
        {
          "name": "box",
          "type": "type::BoundingBox"
        },
        {
          "name": "filling",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateEdges",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "updateQuads",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "launchPropagationFromSeed",
      "return_type": "void",
      "params": [
        {
          "name": "point",
          "type": "const type::Vec3i &"
        },
        {
          "name": "regularGrid",
          "type": "int"
        },
        {
          "name": "regularGrdidTypes",
          "type": "int &"
        },
        {
          "name": "alreadyTested",
          "type": "int &"
        },
        {
          "name": "seed",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "propagateFrom",
      "return_type": "void",
      "params": [
        {
          "name": "point",
          "type": "const type::Vec3i &"
        },
        {
          "name": "regularGrid",
          "type": "int"
        },
        {
          "name": "regularGridTypes",
          "type": "int &"
        },
        {
          "name": "alreadyTested",
          "type": "int &"
        },
        {
          "name": "seed",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeBoundingBox",
      "return_type": "void",
      "params": [
        {
          "name": "vertices",
          "type": "const int &"
        },
        {
          "name": "xmin",
          "type": "SReal &"
        },
        {
          "name": "xmax",
          "type": "SReal &"
        },
        {
          "name": "ymin",
          "type": "SReal &"
        },
        {
          "name": "ymax",
          "type": "SReal &"
        },
        {
          "name": "zmin",
          "type": "SReal &"
        },
        {
          "name": "zmax",
          "type": "SReal &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "voxelizeTriangleMesh",
      "return_type": "void",
      "params": [
        {
          "name": "mesh",
          "type": "helper::io::Mesh *"
        },
        {
          "name": "regularGrid",
          "type": "int"
        },
        {
          "name": "regularGridTypes",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "buildFromTriangleMesh",
      "return_type": "void",
      "params": [
        {
          "name": "mesh",
          "type": "sofa::helper::io::Mesh *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "buildFromRegularGridTypes",
      "return_type": "void",
      "params": [
        {
          "name": "regularGrid",
          "type": "int"
        },
        {
          "name": "regularGridTypes",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "buildFromVoxelFile",
      "return_type": "void",
      "params": [
        {
          "name": "filename",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "buildFromRawVoxelFile",
      "return_type": "void",
      "params": [
        {
          "name": "filename",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "buildFromVoxelLoader",
      "return_type": "void",
      "params": [
        {
          "name": "loader",
          "type": "sofa::core::loader::VoxelLoader *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "constructCollisionModels",
      "return_type": "void",
      "params": [
        {
          "name": "list_mesh",
          "type": "const int &"
        },
        {
          "name": "list_X",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "setVoxel",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        },
        {
          "name": "value",
          "type": "unsigned char"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getHexahedra",
      "return_type": "const int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNbPoints",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNbHexahedra",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `SparseGridTopology` is a specialized topology container in SOFA, designed to create sparse grid representations for 3D objects. It starts from a regular grid but only retains valid cells that contain matter or are entirely inside the object. These cells are categorized as either BOUNDARY (containing part of the surface) or INSIDE (completely within the object). This component is particularly useful in simulations where detailed interior structures need to be preserved without the computational overhead of a fully dense grid.\n\nIt interacts with other SOFA components, such as `RegularGridTopology` and mechanical models like `MechanicalState`, through its API. The `SparseGridTopology` ensures that it initializes before any connected `MechanicalObject` nodes, which is critical for assigning degrees of freedom correctly during simulation initialization.\n\nPractical usage involves setting grid resolution parameters (`d_n`) and bounding box dimensions (`d_min` and `d_max`). Users can also specify if the quantity of matter inside a cell should be considered (`fillWeighted`), whether to select only interior cells (`onlyInsideCells`), and the number of virtual finer levels for more detailed mechanical property computations (`nbVirtualFinerLevels`).",
  "maths": "### Mathematical and Physical Description of SparseGridTopology\n\n#### Overview\nThe `SparseGridTopology` is designed to represent a sparse grid topology in 3D, which begins from a regular grid but only retains valid cells that either contain matter or are entirely within the object. This approach reduces computational overhead by avoiding unnecessary dense grids.\n\n#### Governing Equations and Operators\n- **Resolution Parameters**: \n    - Grid resolution is defined by `d_n`, a vector of integers indicating the number of points in each direction (x, y, z).\n    - Bounding box dimensions are given by `d_min` and `d_max`, which specify the minimum and maximum coordinates for the grid.\n\n- **Boundary Conditions**:\n    - Valid cells are categorized into two types: `BOUNDARY` (containing part of the surface) and `INSIDE` (completely within the object).\n    - The boundary conditions are handled by tagging each cell appropriately based on its intersection with the original surface mesh or complete containment within the object.\n\n#### Constitutive or Kinematic Laws\n- **Stiffness Coefficients**: \n    - Each hexahedron in the sparse grid has associated stiffness coefficients. These can be adjusted based on whether the cell is categorized as `BOUNDARY` (default 0.5) or `INSIDE` (default 1).\n    - The stiffness coefficient for a given element can be accessed via `getStiffnessCoef(Index elementIdx)`.\n\n- **Mass Coefficients**: \n    - Similarly, each hexahedron has associated mass coefficients which are also categorized based on the cell type (`BOUNDARY` or `INSIDE`).\n    - The mass coefficient for a given element can be accessed via `getMassCoef(Index elementIdx)`.\n\n#### Role in FEM Pipeline\n- **Mesh Generation**:\n    - The sparse grid topology is generated by initializing from various inputs, including triangle meshes (`buildFromTriangleMesh`), voxel files (`buildFromVoxelFile`), or directly from regular grids (`buildAsFinest`).\n\n- **Assembly Phase**: \n    - After the mesh generation and categorization of cells into `BOUNDARY` and `INSIDE`, the topology is assembled. This includes defining hexahedra, computing stiffness coefficients, and mass coefficients.\n\n#### Numerical Methods or Discretization Choices\n- **Discretization**:\n    - The grid is discretized based on the specified resolution (`d_n`) and bounding box dimensions (`d_min`, `d_max`).\n    - Only valid cells are retained in the topology, leading to a sparse grid structure.\n\n#### Variational Mechanics Framework\n- **Variational Formulation**:\n    - The variational formulation is implicitly handled by categorizing cells into `BOUNDARY` and `INSIDE`. This ensures that only relevant parts of the mesh contribute to the overall system dynamics and mechanics.\n\n### Summary\nThe `SparseGridTopology` in SOFA provides a flexible and efficient way to manage complex 3D topologies while minimizing computational overhead. By leveraging sparse grid structures, it enables more detailed simulations with fewer resources.",
  "abstract": "The `SparseGridTopology` creates sparse grid representations in 3D by retaining only cells containing matter or entirely inside an object, categorizing them as BOUNDARY or INSIDE.",
  "sheet": "# SparseGridTopology\n\n## Overview\nThe `SparseGridTopology` is a specialized topology container that generates sparse grid representations for 3D objects. It starts from a regular grid but retains only valid cells containing matter (BOUNDARY) or entirely inside the object (INSIDE). This component interacts with other SOFA components, particularly mechanical models like `MechanicalState`, and must initialize before any connected `MechanicalObject` nodes.\n\n## Parameters and Data\nThe significant parameters exposed by this component include:\n- **fillWeighted**: Determines if the quantity of matter inside a cell is taken into account (0.5 for BOUNDARY, 1 for INSIDE).\n- **onlyInsideCells**: Selects only interior cells, excluding boundary cells.\n- **n**: Grid resolution in each direction (x, y, z).\n- **min** and **max**: Minimum and maximum coordinates of the bounding box.\n- **cellWidth**: Dimension of each cell in the created grid if greater than 0.\n- **nbVirtualFinerLevels**: Creates virtual finer sparse grids to provide more detailed mechanical properties.\n\n## Dependencies and Connections\nThe `SparseGridTopology` must be placed before any connected `MechanicalObject` nodes in the scene graph. It interacts with other SOFA components such as `RegularGridTopology`, `MechanicalState`, and various loaders for initializing the grid from triangle meshes, voxel files, or raw data.\n\n## Practical Notes\n- Ensure that the `SparseGridTopology` initializes before any connected `MechanicalObject` nodes to correctly assign degrees of freedom during simulation initialization.\n- The component can be configured with options like weighted filling and virtual finer levels for more detailed mechanical property computations."
}