{
  "name": "BarycentricMapperSparseGridTopology",
  "main": {
    "name": "BarycentricMapperSparseGridTopology",
    "namespace": "sofa::component::mapping::linear",
    "module": "Sofa.Component.Mapping.Linear",
    "include": "sofa/component/mapping/linear/BarycentricMappers/BarycentricMapperSparseGridTopology.h",
    "doc": "Class allowing barycentric mapping computation on a SparseGridTopology",
    "inherits": [
      "TopologyBarycentricMapper"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types, sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "const typename Out::VecCoord &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "clear",
        "return_type": "void",
        "params": [
          {
            "name": "reserve",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addPointInCube",
        "return_type": "int",
        "params": [
          {
            "name": "cubeIndex",
            "type": "const int"
          },
          {
            "name": "baryCoords",
            "type": "const SReal *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "apply",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "typename Out::VecCoord &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJ",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "typename Out::VecDeriv &"
          },
          {
            "name": "in",
            "type": "const typename In::VecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "typename In::VecDeriv &"
          },
          {
            "name": "in",
            "type": "const typename Out::VecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "typename In::MatrixDeriv &"
          },
          {
            "name": "in",
            "type": "const typename Out::MatrixDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getJ",
        "return_type": "const BaseMatrix *",
        "params": [
          {
            "name": "outSize",
            "type": "int"
          },
          {
            "name": "inSize",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const VisualParams *"
          },
          {
            "name": "out",
            "type": "const typename Out::VecCoord &"
          },
          {
            "name": "in",
            "type": "const typename In::VecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resize",
        "return_type": "void",
        "params": [
          {
            "name": "toModel",
            "type": "core::State<Out> *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "Barycentric Mapper (Sparse Grid)",
    "description": "The BarycentricMapper(SparseGridTopology) is a component used in the SOFA (Simulation Open Framework Architecture) framework for mapping points between two different meshes with sparse grid topology.",
    "parameters": [
      {
        "name": "In",
        "description": "Defines the type of input data. In this case, it's Coord. This indicates that the mapper takes coordinate data as its input."
      },
      {
        "name": "Out",
        "description": "Defines the type of output data, which is also Coord in this context. It signifies that the component outputs coordinate data."
      }
    ],
    "features": [
      {
        "name": "Mapping Points Between Meshes",
        "description": "The main functionality of the BarycentricMapper(SparseGridTopology) is to map points from one mesh (sparse grid topology) to another, using barycentric coordinates. This is particularly useful for interpolating data between different meshes."
      },
      {
        "name": "Sparse Grid Topology",
        "description": "The mapper specifically deals with sparse grids, meaning that it can handle situations where the points in the input and output are not densely packed or uniformly distributed. Sparse grids often arise in simulations to efficiently represent large spaces or complex geometries."
      },
      {
        "name": "Barycentric Coordinates",
        "description": "The mapping process utilizes barycentric coordinates, which are a way of describing points within geometric shapes (typically simplices like triangles). In the case of sparse grids, this allows for an efficient and accurate interpolation between different grid configurations."
      },
      {
        "name": "Derivative Mapping",
        "description": "The mapper supports not only positional mapping but also derivative (velocity or force) mapping. This is important for physics-based simulations where forces need to be transferred from one mesh to another in a realistic manner."
      }
    ],
    "usage_examples": [
      {
        "example": "Mapping Particle System to Sparse Grid",
        "description": "A particle system can be mapped onto a sparse grid topology using this mapper. This is useful when you want to simulate particles within a large space where not every point is of interest, and you need to efficiently interpolate their positions or forces."
      },
      {
        "example": "Interpolating Forces in Sparse Grids",
        "description": "Forces applied to one mesh can be interpolated onto another using the BarycentricMapper. This allows for efficient force propagation through sparse grids without needing a dense mesh, making simulations more computationally feasible."
      }
    ],
    "code_snippet": {
      "language": "C++",
      "snippet": "// Example of how to use BarycentricMapper(SparseGridTopology) in SOFA\n// Assuming 'mapper' is an instance of BarycentricMapper(SparseGridTopology)\nVecCoord inputCoordinates; // Input coordinates from the source mesh\nVecCoord outputCoordinates; // Output coordinates for the destination sparse grid\nclass BarycentricMapper<Coord, Coord>::apply(outputCoordinates, inputCoordinates);"
    }
  },
  "maths": {
    "title": "Mathematical and Physical Description of BarycentricMapperSparseGridTopology Component",
    "description": [
      {
        "section": "Overview",
        "content": [
          "The BarycentricMapperSparseGridTopology is a specialized component in the SOFA (Simulation Open Framework Architecture) framework. It facilitates the mapping of points from one mesh to another, particularly when both meshes have sparse grid topologies."
        ]
      },
      {
        "section": "Mathematical Foundations",
        "content": [
          "The core principle behind BarycentricMapperSparseGridTopology is barycentric interpolation, which is a method for interpolating points within the domain of a simplex (such as triangles or tetrahedra). In the context of sparse grid topologies, this involves identifying and mapping points across different meshes based on their relative positions within these simplices.",
          "Given a point in one mesh with known barycentric coordinates (fx, fy, fz) within an enclosing simplex (typically a tetrahedron for 3D grids), the component interpolates the position of this point in another mesh. This is achieved by calculating weighted averages based on these coordinates."
        ]
      },
      {
        "section": "Physical Interpretation",
        "content": [
          "Physically, BarycentricMapperSparseGridTopology can be understood as a tool for transferring physical properties (such as forces or displacements) from one set of mesh nodes to another. This is particularly useful in simulations where different parts of the simulation require different resolutions or topologies.",
          "For example, consider a scenario where a soft tissue model with detailed tetrahedral elements needs to be mapped onto a coarser grid for efficient computation. The BarycentricMapperSparseGridTopology would interpolate the positions and forces from the fine-resolution mesh to the coarse-resolution mesh based on barycentric coordinates."
        ]
      },
      {
        "section": "Implementation Details",
        "content": [
          "The implementation involves several key methods:",
          "- **Initialization**: The mapper is initialized with the source (sparse grid) topology and target topology.",
          "- **Mapping Points**: Using barycentric interpolation, each point in the source mesh is mapped to its corresponding location in the target mesh. This process involves identifying the enclosing simplex (tetrahedron) for each point and calculating the weighted average of vertex positions based on barycentric coordinates.",
          "- **Applying Interpolations**: Methods like `applyJT` and `applyJ` are used to transfer forces or displacements from the source mesh to the target mesh. These methods ensure that physical properties (forces, velocities) are correctly interpolated across the meshes.",
          "- **Visualization**: The component also includes methods for visualizing these mappings and interpolations, such as `applyJT` and `applyJ`, which can be useful for debugging and validation."
        ]
      },
      {
        "section": "Algorithmic Steps",
        "content": [
          "1. Identify the enclosing simplex (tetrahedron) in the source mesh for each point to be mapped.",
          "2. Calculate the barycentric coordinates (fx, fy, fz) of these points within their respective simplices.",
          "3. Use these coordinates to interpolate positions and forces from the source mesh nodes to corresponding locations in the target mesh.",
          "4. Ensure consistency by applying appropriate weighting based on the relative positions of vertices within the simplex."
        ]
      },
      {
        "section": "Example Application",
        "content": [
          "Consider a simulation where deformable objects are modeled using tetrahedral elements with varying resolutions. The BarycentricMapperSparseGridTopology can be used to transfer forces from a high-resolution mesh (with detailed deformation properties) to a low-resolution mesh for efficient computation.",
          "In this scenario, the component interpolates positions and forces based on barycentric coordinates within each tetrahedron, ensuring that physical properties are accurately transferred between different resolutions."
        ]
      }
    ]
  },
  "summary": {
    "abstract": "The BarycentricMapperSparseGridTopology performs barycentric mappings on sparse grid topologies in SOFA simulations.",
    "sheet": "# BarycentricMapperSparseGridTopology\n\n## Overview\nThe BarycentricMapperSparseGridTopology is a mapping component that facilitates barycentric transformations between two meshes with sparse grid topology. It inherits from the TopologyBarycentricMapper class and provides methods for initializing, clearing points, adding points in cubes, applying mappings, and drawing visualizations.\n\n## Dependencies and Connections\nThis component typically requires a SparseGridTopology to define the source and target mesh structures. It fits into the SOFA scene graph by connecting with other components that manage topology, such as `SparseGridTopology`, and those responsible for rendering or further processing of mapped points."
  }
}