Methods

{
  "name": "BarycentricMapper",
  "namespace": "sofa::component::mapping::linear::_barycentricmapper_",
  "module": "Sofa.Component.Mapping.Linear",
  "include": "sofa/component/mapping/linear/BarycentricMappers/BarycentricMapper.h",
  "doc": "Base class for barycentric mapping topology-specific mappers",
  "inherits": [
    "BaseObject"
  ],
  "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": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::visual::VisualParams *"
        },
        {
          "name": "out",
          "type": "const typename Out::VecCoord &"
        },
        {
          "name": "in",
          "type": "const typename In::VecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "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": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getJ",
      "return_type": "const BaseMatrix *",
      "params": [
        {
          "name": "outSize",
          "type": "int"
        },
        {
          "name": "inSize",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "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": true,
      "is_pure_virtual": true,
      "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": true,
      "is_pure_virtual": true,
      "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": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyOnePoint",
      "return_type": "void",
      "params": [
        {
          "name": "hexaId",
          "type": "const int &"
        },
        {
          "name": "out",
          "type": "typename Out::VecCoord &"
        },
        {
          "name": "in",
          "type": "const typename In::VecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clear",
      "return_type": "void",
      "params": [
        {
          "name": "reserve",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMatrixContrib",
      "return_type": "void",
      "params": [
        {
          "name": "m",
          "type": "MatrixType *"
        },
        {
          "name": "row",
          "type": "int"
        },
        {
          "name": "col",
          "type": "int"
        },
        {
          "name": "value",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": {
    "summary": "The `BarycentricMapper` is a base class for barycentric mapping topology-specific mappers in the SOFA framework.",
    "details": [
      "This template class serves as an abstract base class that provides a structure and interface for implementing specific barycentric mappings. The class inherits from `BaseObject`, which is part of the object model infrastructure in SOFA.",
      "The `BarycentricMapper` class defines several pure virtual methods (`init`, `draw`, `apply`, `applyJ`, `applyJT`, etc.) that need to be implemented by derived classes for specific topologies (e.g., lines, triangles, tetrahedra).",
      "It also includes helper structures like `MappingData` which are used to store barycentric coordinates and indices associated with different geometric entities.",
      "The class is templated on input (`In`) and output (`Out`) types, allowing for flexibility in handling various data types within the SOFA framework."
    ],
    "methods": {
      "init": "Initializes the mapper given an output coordinate vector `out` and an input coordinate vector `in`. This method must be implemented by derived classes.",
      "draw": "Handles visual representation of the mapping. It takes a `VisualParams*` object, an output coordinate vector `out`, and an input coordinate vector `in`. Derived classes need to implement this method for visualization purposes.",
      "apply": "Applies the barycentric transformation from the input coordinates (`in`) to the output coordinates (`out`). This is another pure virtual function that must be implemented by derived classes.",
      "getJ": "Returns a Jacobian matrix. Although defined in `BarycentricMapper`, it's not implemented and will log an error if called directly without implementation in a derived class.",
      "applyJ": "Applies the Jacobian transformation, converting input derivatives to output derivatives.",
      "applyJT": "Performs the transpose of the Jacobian transformation.",
      "clear": "Clears internal data structures or resets the mapper state. This method is also pure virtual and must be implemented by derived classes."
    },
    "implementation_notes": [
      "The `BarycentricMapper` class contains several methods that are not yet implemented, indicating it serves as an abstract base class for specific mapping implementations.",
      "It defines a protected helper function `addMatrixContrib` which adds values to specific matrix blocks used in the mapping process. This can be useful for derived classes when implementing Jacobian operations."
    ],
    "example_usage": [
      "To use this class, one would typically create a derived class that implements all of its pure virtual methods and provides specific implementations for barycentric mappings on particular geometric entities (e.g., triangles, tetrahedra)."
    ]
  },
  "summary": "The `BarycentricMapper` in the SOFA framework is an abstract base class that facilitates barycentric mapping for various topological elements within a finite element simulation context.",
  "details": [
    "The `BarycentricMapper` class provides a generic interface and structure to handle mappings of geometric entities (such as lines, triangles, tetrahedra) from one set of coordinates (`In`) to another (`Out`). It is designed for the SOFA framework which is used primarily in biomechanical simulation, computer graphics, and virtual reality applications.",
    "The primary purpose of this mapper is to enable transformations that maintain the barycentric relationship between points within a given geometric element. This is crucial when dealing with deformable objects or complex interactions where maintaining the relative positions (barycentric coordinates) of vertices within elements is essential for accurate simulation."
  ],
  "mathematical_description": [
    "In mathematics, barycentric mapping involves transforming points based on their weighted average positions relative to a simplex (e.g., triangle in 2D or tetrahedron in 3D). Each point's position can be expressed as a linear combination of the vertices' coordinates, where the weights sum up to one.",
    "Let \\(P\\) be a point within an element defined by its barycentric coordinates \\((b_1, b_2, ..., b_n)\\), where each \\(b_i\\) represents the weight associated with vertex \\(i\\). The position of \\(P\\) can then be expressed as:",
    "\\[ P = \\\\sum_{i=0}^{n-1} b_i V_i \\]",
    "where \\(V_i\\) are the coordinates of the vertices. In a more generalized form, if we have an input set of points (vertices) and their transformed counterparts (output), the `BarycentricMapper` ensures that this linear combination is maintained.",
    "The Jacobian matrix, returned by the `getJ()` method, represents the derivative of each output component with respect to each input component. This matrix is critical for understanding how changes in one set of coordinates affect another and is often used in solving differential equations and performing transformations."
  ],
  "physical_description": [
    "In a physical context, the barycentric mapping allows simulation of deformable objects while preserving their internal structure. For example, in biomechanical simulations, tissues can be modeled as tetrahedra where each point's position relative to its neighboring vertices (expressed through barycentric coordinates) is crucial for realistic deformation.",
    "When a force is applied, the `BarycentricMapper` ensures that any point within an element moves according to the transformed positions of its vertices. This is vital in maintaining structural integrity and simulating elastic properties accurately.",
    "The use of barycentric mapping also aids in interpolating physical quantities (e.g., stresses, strains) across elements, ensuring smooth transitions and physically plausible deformations."
  ],
  "implementation_notes": [
    "The `BarycentricMapper` class serves as an abstract base class with several pure virtual methods such as `init`, `draw`, `apply`, etc. These must be implemented by derived classes specific to different topological entities (e.g., LineData, TriangleData).",
    "It includes a helper function `addMatrixContrib()` which assists in constructing the Jacobian matrix used for transformation calculations.",
    "By defining common interfaces and data structures, such as `MappingData`, the class allows for consistent handling of barycentric coordinates across various geometric entities."
  ],
  "example_usage": [
    "To use this component effectively, a derived class should be created that specifies the exact topological element (e.g., triangle, tetrahedron) to map. In this derived class, all pure virtual methods must be implemented according to the specific geometry and required transformation behavior.",
    "For instance, for a `TriangleMapper`, one would implement the mapping of barycentric coordinates from input vertices to output positions while handling the specifics related to triangular elements."
  ],
  "abstract": "`BarycentricMapper` is an abstract base class for implementing barycentric mappings on various geometric entities within the SOFA framework. It defines several pure virtual methods that need to be implemented by derived classes.",
  "sheet": "# BarycentricMapper\n\n## Overview\nThe `BarycentricMapper` serves as an abstract base class for implementing specific barycentric mappings in the SOFA framework. This class provides a structure and interface for handling different geometric entities such as lines, triangles, and tetrahedra by defining several pure virtual methods that must be implemented by derived classes.\n\n## Methods\nThe `BarycentricMapper` defines the following pure virtual methods:\n- **init**: Initializes the mapper given an output coordinate vector \\(\\text{out}\\) and an input coordinate vector \\(\\text{in}\\).\n- **draw**: Handles visual representation of the mapping, taking a `VisualParams*` object, an output coordinate vector \\(\\text{out}\\), and an input coordinate vector \\(\\text{in}\\).\n- **apply**: Applies the barycentric transformation from the input coordinates \\(\\text{in}\\) to the output coordinates \\(\\text{out}\\).\n- **getJ**: Returns a Jacobian matrix, although it is not implemented in this base class and will log an error if called directly.\n- **applyJ**: Applies the Jacobian transformation, converting input derivatives to output derivatives.\n- **applyJT**: Performs the transpose of the Jacobian transformation.\n- **clear**: Clears internal data structures or resets the mapper state."
}