Data Fields

Methods

{
  "name": "RigidMapping",
  "namespace": "sofa::component::mapping::nonlinear",
  "module": "Sofa.Component.Mapping.NonLinear",
  "include": "sofa/component/mapping/nonlinear/RigidMapping.h",
  "doc": "Set the positions and velocities of points attached to a rigid parent.",
  "inherits": [
    "Mapping"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types, sofa::defaulttype::Vec2Types",
    "sofa::defaulttype::Rigid3Types, sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Rigid3Types, sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_points",
      "type": "OutVecCoord",
      "xmlname": "initialPoints",
      "help": "Local Coordinates of the points"
    },
    {
      "name": "m_data",
      "type": "In, Out"
    },
    {
      "name": "d_useX0",
      "type": "bool",
      "xmlname": "useX0",
      "help": "Use x0 instead of local copy of initial positions (to support topo changes)"
    },
    {
      "name": "d_indexFromEnd",
      "type": "bool",
      "xmlname": "indexFromEnd",
      "help": "input DOF index starts from the end of input DOFs vector"
    },
    {
      "name": "d_globalToLocalCoords",
      "type": "bool",
      "xmlname": "globalToLocalCoords",
      "help": "are the output DOFs initially expressed in global coordinates"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "apply()",
      "description": "Applies the mapping from input object to output object, transforming the positions based on rigid body transformations."
    },
    {
      "name": "updateK()",
      "description": "Updates the geometric stiffness matrix based on the current state of the system and external forces applied to the mapped points."
    }
  ],
  "description": "The RigidMapping component in SOFA is used to apply transformations between two mechanical objects, where the source object (input) consists of rigid bodies and the target object (output) consists of deformable elements or points. This mapping allows for the deformation of the target object based on the transformation (translation and rotation) of the corresponding rigid body from the source object.",
  "parameters": [
    {
      "name": "d_points",
      "description": "Local coordinates of the mapped points relative to their parent rigid frame."
    },
    {
      "name": "d_index",
      "description": "Input DOF index which defines the mapping of each point on a specific rigid body. If d_useX0 is false, it refers to the current configuration of the input object; otherwise, it references the initial configuration (x0) of the input object."
    },
    {
      "name": "d_fileRigidMapping",
      "description": "Filename for loading predefined mapping data from an external file."
    },
    {
      "name": "d_useX0",
      "description": "Boolean flag indicating whether to use x0 (initial positions) instead of a local copy of initial positions. This is useful when topological changes are expected in the simulation."
    },
    {
      "name": "d_indexFromEnd",
      "description": "Boolean flag specifying if the input DOF index starts from the end of the input DOFs vector, which can be helpful for certain configurations."
    },
    {
      "name": "d_rigidIndexPerPoint",
      "description": "Vector that specifies for each mapped point, the index of the rigid body it is associated with. This parameter helps in organizing points based on their parent frames and ensures proper mapping during simulations."
    },
    {
      "name": "d_globalToLocalCoords",
      "description": "Boolean flag indicating whether the output DOFs are initially expressed in global coordinates or not. When true, the initial positions of the mapped points are considered to be in the global frame rather than local frames."
    }
  ],
  "usage_examples": [
    {
      "example": "In a simulation where an arm (rigid) is attached to a soft tissue (deformable), RigidMapping can be used to ensure that deformations in the tissue correspond to movements of the arm, providing realistic interaction between rigid and deformable components."
    },
    {
      "name": "Code Example",
      "code": "RigidMapping< sofa::defaulttype::Rigid3Types, sofa::defaulttype::Vec3Types > mapping;\nmapping.init();\nmapping.reinit(); // Recalculates local coordinates of the mapped points\nmapping.applyJ(mparams, outDeriv, inDeriv); // Applies Jacobian transformation"
    }
  ],
  "maths": "The RigidMapping component in the SOFA framework is designed to set the positions and velocities of points that are attached to a rigid parent. This mapping is used for transferring deformations from rigid bodies to deformable objects or points. It ensures consistency between the motion of the rigid body and the deformation of the connected elements.\n\n### Governing Equations and Operators\n- **Transformation Application:** The primary role of RigidMapping is to apply a transformation (translation and rotation) to points attached to a rigid parent. This involves:\n  - Applying translation: \\(\\mathbf{x}_{out} = \text{rotation}(\\mathbf{x}_{in}) + \\mathbf{t}\\), where \\(\text{rotation}(\\cdot)\\) is the rotation matrix and \\(\textbf{t}\\) is a translation vector.\n  - Applying rotation: \\(\\mathbf{x}_{out} = \text{rotation}(\\mathbf{x}_{in})\\).\n- **Jacobian Matrix (\\(\\mathbf{J}\\))**: The Jacobian matrix represents the relationship between changes in input DOFs and output DOFs. It is used to compute the mapping’s effect on forces.\n  \\[\\mathbf{J} = \begin{bmatrix}\n    I & -\text{hat}(\\mathbf{x}_{out})\\\\\n    0 & I\n  \\end{bmatrix},\\]\n  where \\(I\\) is the identity matrix and \\(\text{hat}\\) denotes the skew-symmetric cross product operator.\n- **Geometric Stiffness Matrix (\\(\\mathbf{K}_{geo}\\))**: This term accounts for geometric nonlinearities, arising from changes in stiffness due to deformation. It is computed based on the external forces acting on the deformable points and the positions of these points relative to the rigid parent.\n\n### Constitutive Laws and Kinematic Models\n- **Kinematics:** The kinematic relationship between a point \\(\textbf{x}_{out}\\) attached to a rigid body and its position in the world frame involves rotation by the orientation of the rigid body and translation by the center of mass. \n  - Position: \\(\\mathbf{x}_{out} = R_{in}^{-1}(\\mathbf{x}_{to} - \\mathbf{c}_{from})\\), where \\(\textbf{R}\\) is the rotation matrix, \\(\textbf{c}\\) represents the center of mass.\n  - Orientation: \\(\\omega_{out} = R_{in}^{-1} \\cdot \tilde{\boldsymbol{\theta}}\\), where \\(\tilde{\boldsymbol{\theta}}\\) is a vector representing angular velocity and \\(\textbf{R}\\) denotes the rotation matrix.\n- **Geometric Nonlinearity:** The geometric stiffness matrix accounts for nonlinear effects due to large deformations, particularly rotations. It uses the cross product operator to capture these effects:\n  - Cross Product Matrix: \\\\[C = \begin{bmatrix}0 & -z & y \\\\ z & 0 & -x \\\\-y & x & 0 \\end{bmatrix},\\]\n\n### Role in FEM Pipeline\n- **Assembly Phase:** The RigidMapping component contributes to the assembly phase by providing the Jacobian matrix (\\(\\mathbf{J}\\)) and its transpose (\\(\\mathbf{J}^T\\)). These matrices are used during the linearization step for force mapping between rigid bodies and deformable elements.\n- **Time Integration:** In time integration, RigidMapping ensures that the motions of the rigid parent are correctly propagated to the attached points. The transformation is applied in each time step to update positions and velocities according to the rigid body’s motion.\n\n### Numerical Methods and Discretization Choices\n- **Linear Algebra Operations:** The component uses efficient linear algebra operations for Jacobian computation, matrix assembly (\\(\\mathbf{J}\\) and \\(\\mathbf{K}_{geo}\\)), and force mappings. Sparse matrices are utilized to store these matrices efficiently.\n- **Matrix-Free Implementation:** While not explicitly stated in the source code, RigidMapping can be used within a matrix-free context where Jacobian-vector products are computed directly without storing or assembling large matrices, leading to computational efficiency.\n\n### Variational and Lagrangian Mechanics Framework\nThe mapping fits into the broader framework by ensuring consistency between the rigid body motion and deformable elements. It preserves physical invariants such as momentum conservation through proper application of forces using \\(\\mathbf{J}\\) and \\(\\mathbf{K}_{geo}\\). This ensures that the overall system remains consistent with Lagrangian mechanics principles.",
  "abstract": "RigidMapping applies transformations between rigid bodies and deformable elements, ensuring consistent motion propagation from the rigid parent to attached points.",
  "sheet": "# RigidMapping\n\n## Overview\nRigidMapping is a nonlinear mapping component that sets positions and velocities of points attached to a rigid parent. It ensures consistency in the simulation by propagating the motion of rigid bodies to deformable elements.\n\n## Mathematical Model\nThe primary role of RigidMapping involves applying transformations (translation and rotation) to points attached to a rigid body:\n- **Position Transformation:** \\(\\mathbf{x}_{out} = R_{in}^{-1}(\\mathbf{x}_{to} - \\mathbf{c}_{from}) + \\mathbf{t}\\), where \\(R_{in}\\) is the rotation matrix, \\(\\mathbf{c}_{from}\\) is the center of mass, and \\(\\mathbf{t}\\) is a translation vector.\n- **Orientation Transformation:** \\(\\omega_{out} = R_{in}^{-1} \\cdot \\tilde{\\boldsymbol{\\theta}}\\), where \\(\\tilde{\\boldsymbol{\\theta}}\\) represents angular velocity and \\(R_{in}\\) is the rotation matrix.\n- **Jacobian Matrix:** The Jacobian matrix \\(\\mathbf{J}\\) captures the relationship between input and output DOFs:\n  \\[\\mathbf{J} = \\begin{bmatrix}\n    I & -\\hat{(\\mathbf{x}_{out})} \\\\\n    0 & I\n  \\end{bmatrix},\\]\n  where \\(I\\) is the identity matrix and \\(\\hat{}\\) denotes the skew-symmetric cross product operator.\n- **Geometric Stiffness Matrix:** The geometric stiffness matrix \\(\\mathbf{K}_{geo}\\) accounts for nonlinear effects due to large deformations:\n  \\[C = \\begin{bmatrix}\n    0 & -z & y \\\\\n    z & 0 & -x \\\\\n    -y & x & 0\n  \\end{bmatrix}.\\]\n\n## Parameters and Data\n- **d_points:** Local coordinates of the points (OutVecCoord).\n- **m_data:** Input/Output data field.\n- **d_useX0:** Use initial positions instead of local copy (bool, default: false).\n- **d_indexFromEnd:** Start input DOF index from the end of the vector (bool, default: false).\n- **d_globalToLocalCoords:** Output DOFs initially expressed in global coordinates (bool, default: false).\n\n## Dependencies and Connections\nRigidMapping typically requires interaction with rigid body components to obtain transformations and deformable elements to apply these transformations. It fits into the scene graph by connecting rigid bodies to deformable objects or points.\n"
}