`GridTopology` defines a regular 3D grid topology without spatial information, managing points, edges, quads, and hexahedra based on user-defined parameters.
sheet
# GridTopology
**Overview**
`GridTopology` is a topological container that defines a regular grid in three-dimensional space. It inherits from `MeshTopology`, providing methods to manage and compute the topology of points, edges, quads, and hexahedra based on user-defined parameters.
**Parameters and Data**
The significant data fields exposed by this component are:
- **d_n**: Defines the grid resolution as a 3D vector (default = [2, 2, 2]).
- **d_computeHexaList**: Boolean to compute hexahedra during initialization (default=true).
- **d_computeQuadList**: Boolean to compute quads during initialization (default=true).
- **d_computeTriangleList**: Boolean to compute triangles during initialization (default=true).
- **d_computeEdgeList**: Boolean to compute edges during initialization (default=true).
- **d_computePointList**: Boolean to compute points during initialization (default=true).
- **d_createTexCoords**: Boolean to generate virtual texture coordinates using 3D interpolation (default=false).
**Dependencies and Connections**
The `GridTopology` component typically requires no external dependencies but fits into the scene graph as a topological container, often used in conjunction with other components that provide spatial information or physical properties.
**Practical Notes**
- Ensure grid resolution parameters are set appropriately to avoid excessive memory usage for large grids.
- Texture coordinates generation can be useful for visualization purposes but is optional.
Title
GridTopology Component
Description
The GridTopology component is part of the SOFA (Simulation Open-Framework Architecture) library and provides functionality for defining regular grid topologies with no spatial information. This component is particularly useful in simulations where a structured, uniform mesh is required.
Properties
{'name': 'd_n', 'type': 'type::Vec3i', 'description': 'Stores the size of the grid in three dimensions (x, y, z).'}
{'name': 'd_computeHexaList', 'type': 'bool', 'description': 'Boolean flag to determine whether to compute hexahedra during initialization.'}
{'name': 'd_computeQuadList', 'type': 'bool', 'description': 'Boolean flag to determine whether to compute quadrilaterals (quads) during initialization.'}
{'name': 'd_computeTriangleList', 'type': 'bool', 'description': 'Boolean flag to determine whether to compute triangular faces during initialization.'}
{'name': 'd_computeEdgeList', 'type': 'bool', 'description': 'Boolean flag to determine whether to compute edges during initialization.'}
{'name': 'd_createTexCoords', 'type': 'bool', 'description': 'Boolean flag to determine whether to create texture coordinates for the grid elements.'}
Methods
{'name': 'init()', 'description': 'Initializes the GridTopology component, setting up all necessary topological elements based on the configuration options provided.'}
{'name': 'setSize(int nx, int ny, int nz)', 'description': 'Sets the resolution of the grid in the three dimensions (x, y, z).'}
{'name': 'getIndex(int i, int j, int k)', 'description': "Returns the one-dimensional index for a given point's position within the grid."}
{'name': 'getPoint(Index i)', 'description': 'Retrieves the coordinates of a specific point in the grid based on its index.'}
{'name': 'hasPos()', 'description': 'Always returns true, indicating that positional information is available for points in this topology.'}
Notes
GridTopology extends MeshTopology from SOFA's constant container module.
The GridUpdate class acts as a data engine to update the grid structure with edges, quads, triangles, and hexahedra based on the specified dimensions and configuration options.
This component is designed for use in simulation frameworks where a regular grid topology is required for modeling purposes.
maths
# Mathematical and Physical Description of the GridTopology Component
## Overview
The `GridTopology` component in SOFA defines a regular grid topology without any spatial information. It is an extension of the `MeshTopology`, providing methods to manage and compute topological elements such as edges, quads (quadrilaterals), hexahedra, and points on a three-dimensional grid.
## Grid Resolution
The resolution of the grid in each direction can be defined by setting the number of subdivisions along the X, Y, and Z axes. This is represented mathematically as:
- **NX**: Number of divisions along the X-axis (inclusive).
- **NY**: Number of divisions along the Y-axis (inclusive).
- **NZ**: Number of divisions along the Z-axis (inclusive).
The total number of points in the grid can be calculated by:
\[
N_{points} = NX \times NY \times NZ
\]
### Indexing Points on a Grid
Each point on the grid is uniquely identified using 3-dimensional indices, denoted as \((i, j, k)\), where \(0 \leq i < NX\), \(0 \leq j < NY\), and \(0 \leq k < NZ\). The one-dimensional index of a point can be calculated from these 3D indices using the formula:
\[
i_{1D} = k \times (NX imes NY) + j \times NX + i
\]
This is encapsulated in the `getIndex` method.
## Topological Elements
The topological elements of a grid include edges, quads, and hexahedra. The following sections outline how these are constructed based on the grid dimensions.
### Edges
Edges connect adjacent points on the grid. In a regular 3D grid, each point can have up to six connected edges (one for each direction: X+, X-, Y+, Y-, Z+, and Z-).
The total number of edges can be calculated as:
\[
N_{edges} = NX \times NY \times NZ \times 6 - (NX imes NY + NY imes NZ + NX imes NZ) \times 2
\]
The subtraction term accounts for the shared edges and boundary conditions.
### Quads
Quadrilaterals (quads) are formed by connecting four adjacent points. For a grid of dimensions \((NX, NY, NZ)\), quads can be constructed on each face in three orientations: XY-faces, YZ-faces, and XZ-faces. The total number of quads is:
\[
N_{quads} = NX imes (NY-1) imes (NZ-1) + NY imes (NX-1) imes (NZ-1) + NZ imes (NX-1) imes (NY-1)
\]
### Hexahedra
Hexahedra are 3D volumes defined by eight vertices. Each hexahedron in the grid is formed by connecting adjacent quads, and their count can be calculated as:
\[
N_{hexahedra} = (NX-1) imes (NY-1) imes (NZ-1)
\]
## Methods for Topological Elements Computation
The `GridTopology` component provides methods to compute the list of edges, quads, hexahedra, and points. These are controlled by boolean data fields (`d_computeHexaList`, `d_computeQuadList`, etc.), which determine whether these elements should be computed during initialization.
### Point Computation
The coordinates of each point in the grid can vary based on specific spatial information provided by subclasses. The method `getPointInGrid` returns the 3D position of a given point with indices \((i, j, k)\). This is crucial for spatial discretization and further computation.
### Texture Coordinates (Optional)
Optionally, texture coordinates can be generated if `d_createTexCoords` is set to true. These are typically normalized between 0 and 1 in the U-V space and provide additional information for rendering or other purposes.
## Conclusion
The `GridTopology` component provides a flexible way to define and manage regular grid topologies, enabling users to easily compute various topological elements based on their needs. This forms the foundation of many spatial discretizations used in simulations and visualizations.
{
"name": "GridTopology",
"main": {
"name": "GridTopology",
"namespace": "sofa::component::topology::container::grid",
"module": "Sofa.Component.Topology.Container.Grid",
"include": "sofa/component/topology/container/grid/GridTopology.h",
"doc": "Base class fo a regular grid in 3D.\n\nDefine a regular grid topology, with no spatial information.",
"inherits": [
"MeshTopology"
],
"templates": [],
"data_fields": [
{
"name": "d_n",
"type": "type::Vec3i",
"xmlname": "n",
"help": "grid resolution. (default = 2 2 2)"
},
{
"name": "d_computeHexaList",
"type": "bool",
"xmlname": "computeHexaList",
"help": "put true if the list of Hexahedra is needed during init (default=true)"
},
{
"name": "d_computeQuadList",
"type": "bool",
"xmlname": "computeQuadList",
"help": "put true if the list of Quad is needed during init (default=true)"
},
{
"name": "d_computeTriangleList",
"type": "bool",
"xmlname": "computeTriangleList",
"help": "put true if the list of Triangles is needed during init (default=true)"
},
{
"name": "d_computeEdgeList",
"type": "bool",
"xmlname": "computeEdgeList",
"help": "put true if the list of Lines is needed during init (default=true)"
},
{
"name": "d_computePointList",
"type": "bool",
"xmlname": "computePointList",
"help": "put true if the list of Points is needed during init (default=true)"
},
{
"name": "d_createTexCoords",
"type": "bool",
"xmlname": "createTexCoords",
"help": "If set to true, virtual texture coordinates will be generated using 3D interpolation (default=false)."
}
],
"links": [],
"methods": [
{
"name": "setNbGridPoints",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "createTexCoords",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computeHexaList",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computeQuadList",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computeEdgeList",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computePointList",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "checkGridResolution",
"return_type": "void",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "changeGridResolutionPostProcess",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"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": "setSize",
"return_type": "void",
"params": [
{
"name": "nx",
"type": "int"
},
{
"name": "ny",
"type": "int"
},
{
"name": "nz",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setSize",
"return_type": "void",
"params": [
{
"name": "nXnYnZ",
"type": "type::Vec3i"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setNx",
"return_type": "void",
"params": [
{
"name": "value",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setNy",
"return_type": "void",
"params": [
{
"name": "value",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setNz",
"return_type": "void",
"params": [
{
"name": "value",
"type": "int"
}
],
"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": "getIndex",
"return_type": "Index",
"params": [
{
"name": "i",
"type": "int"
},
{
"name": "j",
"type": "int"
},
{
"name": "k",
"type": "int"
}
],
"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": "getPoint",
"return_type": "Vec3",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPointInGrid",
"return_type": "Vec3",
"params": [
{
"name": "i",
"type": "int"
},
{
"name": "j",
"type": "int"
},
{
"name": "k",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPX",
"return_type": "SReal",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPY",
"return_type": "SReal",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPZ",
"return_type": "SReal",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "parse",
"return_type": "void",
"params": [
{
"name": "arg",
"type": "core::objectmodel::BaseObjectDescription *"
}
],
"is_virtual": true,
"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"
},
{
"name": "getQuad",
"return_type": "Quad",
"params": [
{
"name": "x",
"type": "int"
},
{
"name": "y",
"type": "int"
},
{
"name": "z",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getHexahedron",
"return_type": "Hexa",
"params": [
{
"name": "x",
"type": "int"
},
{
"name": "y",
"type": "int"
},
{
"name": "z",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getHexaCopy",
"return_type": "Hexa",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getQuadCopy",
"return_type": "Quad",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "point",
"return_type": "Index",
"params": [
{
"name": "x",
"type": "int"
},
{
"name": "y",
"type": "int"
},
{
"name": "z",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "hexa",
"return_type": "Index",
"params": [
{
"name": "x",
"type": "int"
},
{
"name": "y",
"type": "int"
},
{
"name": "z",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "cube",
"return_type": "Index",
"params": [
{
"name": "x",
"type": "int"
},
{
"name": "y",
"type": "int"
},
{
"name": "z",
"type": "int"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getDimensions",
"return_type": "Grid_dimension",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
}
]
},
"desc": {
"Title": "GridTopology Component",
"Description": "The GridTopology component is part of the SOFA (Simulation Open-Framework Architecture) library and provides functionality for defining regular grid topologies with no spatial information. This component is particularly useful in simulations where a structured, uniform mesh is required.",
"Properties": [
{
"name": "d_n",
"type": "type::Vec3i",
"description": "Stores the size of the grid in three dimensions (x, y, z)."
},
{
"name": "d_computeHexaList",
"type": "bool",
"description": "Boolean flag to determine whether to compute hexahedra during initialization."
},
{
"name": "d_computeQuadList",
"type": "bool",
"description": "Boolean flag to determine whether to compute quadrilaterals (quads) during initialization."
},
{
"name": "d_computeTriangleList",
"type": "bool",
"description": "Boolean flag to determine whether to compute triangular faces during initialization."
},
{
"name": "d_computeEdgeList",
"type": "bool",
"description": "Boolean flag to determine whether to compute edges during initialization."
},
{
"name": "d_createTexCoords",
"type": "bool",
"description": "Boolean flag to determine whether to create texture coordinates for the grid elements."
}
],
"Methods": [
{
"name": "init()",
"description": "Initializes the GridTopology component, setting up all necessary topological elements based on the configuration options provided."
},
{
"name": "setSize(int nx, int ny, int nz)",
"description": "Sets the resolution of the grid in the three dimensions (x, y, z)."
},
{
"name": "getIndex(int i, int j, int k)",
"description": "Returns the one-dimensional index for a given point's position within the grid."
},
{
"name": "getPoint(Index i)",
"description": "Retrieves the coordinates of a specific point in the grid based on its index."
},
{
"name": "hasPos()",
"description": "Always returns true, indicating that positional information is available for points in this topology."
}
],
"Notes": [
"GridTopology extends MeshTopology from SOFA's constant container module.",
"The GridUpdate class acts as a data engine to update the grid structure with edges, quads, triangles, and hexahedra based on the specified dimensions and configuration options.",
"This component is designed for use in simulation frameworks where a regular grid topology is required for modeling purposes."
]
},
"maths": {
"maths": "# Mathematical and Physical Description of the GridTopology Component\n\n## Overview\nThe `GridTopology` component in SOFA defines a regular grid topology without any spatial information. It is an extension of the `MeshTopology`, providing methods to manage and compute topological elements such as edges, quads (quadrilaterals), hexahedra, and points on a three-dimensional grid.\n\n## Grid Resolution\nThe resolution of the grid in each direction can be defined by setting the number of subdivisions along the X, Y, and Z axes. This is represented mathematically as:\n- **NX**: Number of divisions along the X-axis (inclusive).\n- **NY**: Number of divisions along the Y-axis (inclusive).\n- **NZ**: Number of divisions along the Z-axis (inclusive).\n\nThe total number of points in the grid can be calculated by:\n\\[\nN_{points} = NX \\times NY \\times NZ\n\\]\n\n### Indexing Points on a Grid\nEach point on the grid is uniquely identified using 3-dimensional indices, denoted as \\((i, j, k)\\), where \\(0 \\leq i < NX\\), \\(0 \\leq j < NY\\), and \\(0 \\leq k < NZ\\). The one-dimensional index of a point can be calculated from these 3D indices using the formula:\n\\[\ni_{1D} = k \\times (NX \times NY) + j \\times NX + i\n\\]\nThis is encapsulated in the `getIndex` method.\n\n## Topological Elements\nThe topological elements of a grid include edges, quads, and hexahedra. The following sections outline how these are constructed based on the grid dimensions.\n\n### Edges\nEdges connect adjacent points on the grid. In a regular 3D grid, each point can have up to six connected edges (one for each direction: X+, X-, Y+, Y-, Z+, and Z-).\n\nThe total number of edges can be calculated as:\n\\[\nN_{edges} = NX \\times NY \\times NZ \\times 6 - (NX \times NY + NY \times NZ + NX \times NZ) \\times 2\n\\]\nThe subtraction term accounts for the shared edges and boundary conditions.\n\n### Quads\nQuadrilaterals (quads) are formed by connecting four adjacent points. For a grid of dimensions \\((NX, NY, NZ)\\), quads can be constructed on each face in three orientations: XY-faces, YZ-faces, and XZ-faces. The total number of quads is:\n\\[\nN_{quads} = NX \times (NY-1) \times (NZ-1) + NY \times (NX-1) \times (NZ-1) + NZ \times (NX-1) \times (NY-1)\n\\]\n\n### Hexahedra\nHexahedra are 3D volumes defined by eight vertices. Each hexahedron in the grid is formed by connecting adjacent quads, and their count can be calculated as:\n\\[\nN_{hexahedra} = (NX-1) \times (NY-1) \times (NZ-1)\n\\]\n\n## Methods for Topological Elements Computation\nThe `GridTopology` component provides methods to compute the list of edges, quads, hexahedra, and points. These are controlled by boolean data fields (`d_computeHexaList`, `d_computeQuadList`, etc.), which determine whether these elements should be computed during initialization.\n\n### Point Computation\nThe coordinates of each point in the grid can vary based on specific spatial information provided by subclasses. The method `getPointInGrid` returns the 3D position of a given point with indices \\((i, j, k)\\). This is crucial for spatial discretization and further computation.\n\n### Texture Coordinates (Optional)\nOptionally, texture coordinates can be generated if `d_createTexCoords` is set to true. These are typically normalized between 0 and 1 in the U-V space and provide additional information for rendering or other purposes.\n\n## Conclusion\nThe `GridTopology` component provides a flexible way to define and manage regular grid topologies, enabling users to easily compute various topological elements based on their needs. This forms the foundation of many spatial discretizations used in simulations and visualizations."
},
"summary": {
"abstract": "`GridTopology` defines a regular 3D grid topology without spatial information, managing points, edges, quads, and hexahedra based on user-defined parameters.",
"sheet": "# GridTopology\n\n**Overview**\n`GridTopology` is a topological container that defines a regular grid in three-dimensional space. It inherits from `MeshTopology`, providing methods to manage and compute the topology of points, edges, quads, and hexahedra based on user-defined parameters.\n\n**Parameters and Data**\nThe significant data fields exposed by this component are:\n- **d_n**: Defines the grid resolution as a 3D vector (default = [2, 2, 2]).\n- **d_computeHexaList**: Boolean to compute hexahedra during initialization (default=true).\n- **d_computeQuadList**: Boolean to compute quads during initialization (default=true).\n- **d_computeTriangleList**: Boolean to compute triangles during initialization (default=true).\n- **d_computeEdgeList**: Boolean to compute edges during initialization (default=true).\n- **d_computePointList**: Boolean to compute points during initialization (default=true).\n- **d_createTexCoords**: Boolean to generate virtual texture coordinates using 3D interpolation (default=false).\n\n**Dependencies and Connections**\nThe `GridTopology` component typically requires no external dependencies but fits into the scene graph as a topological container, often used in conjunction with other components that provide spatial information or physical properties.\n\n**Practical Notes**\n- Ensure grid resolution parameters are set appropriately to avoid excessive memory usage for large grids.\n- Texture coordinates generation can be useful for visualization purposes but is optional."
}
}