{
  "name": "BeamLinearMapping",
  "main": {
    "name": "BeamLinearMapping",
    "namespace": "sofa::component::mapping::linear",
    "module": "Sofa.Component.Mapping.Linear",
    "include": "sofa/component/mapping/linear/BeamLinearMapping.h",
    "doc": "Set the positions and velocities of points attached to a beam using linear interpolation between DOFs.",
    "inherits": [],
    "templates": [
      "sofa::defaulttype::Rigid3Types, sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "localCoord",
        "type": "bool"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "apply",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "out",
            "type": "Data<typename Out::VecCoord> &"
          },
          {
            "name": "in",
            "type": "const Data<typename In::VecCoord> &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJ",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "out",
            "type": "Data<typename Out::VecDeriv> &"
          },
          {
            "name": "in",
            "type": "const Data<typename In::VecDeriv> &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "out",
            "type": "Data<typename In::VecDeriv> &"
          },
          {
            "name": "in",
            "type": "const Data<typename Out::VecDeriv> &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "out",
            "type": "Data<typename In::MatrixDeriv> &"
          },
          {
            "name": "in",
            "type": "const Data<typename Out::MatrixDeriv> &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getJ",
        "return_type": "const sofa::linearalgebra::BaseMatrix *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "BeamLinearMapping",
    "description": "This component sets the positions and velocities of points attached to a beam using linear interpolation between degrees of freedom (DOFs). It is designed for use with rigid body models where the child model's nodes are interpolated along the parent beam's DOFs.",
    "parameters": [
      {
        "name": "index",
        "type": "Int",
        "description": "The index used to select specific elements. This parameter is not explicitly defined in the code but may be referenced elsewhere."
      },
      {
        "name": "drawSize",
        "type": "Float",
        "description": "Size of points and segments drawn when using this mapping for visualization purposes.",
        "default_value": 0.01
      }
    ],
    "input_ports": [
      {
        "name": "fromModel",
        "description": "The parent model containing the beam DOFs from which data is interpolated."
      },
      {
        "name": "toModel",
        "description": "The child model whose positions and velocities are set based on interpolation of the parent beam's DOFs."
      }
    ],
    "output_ports": [],
    "functions": [
      {
        "name": "draw",
        "parameters": [
          "vparams: VisualParams"
        ],
        "return_type": "",
        "description": "Draws the mapping for visualization purposes if displayFlags.getShowMappings() is true. It draws points representing the positions of nodes in the child model."
      },
      {
        "name": "getJ",
        "parameters": [],
        "return_type": "const sofa::linearalgebra::BaseMatrix*",
        "description": "Returns the Jacobian matrix (matrix J) which represents the linear mapping between parent and child models. The matrix is updated if necessary."
      }
    ],
    "details": [
      {
        "title": "Interpolation Details",
        "content": "The component interpolates positions and velocities of points attached to a beam using linear interpolation between DOFs. It supports rigid body types for the parent model (Rigid3Types) and vector types for the child model (Vec3Types)."
      },
      {
        "title": "Visualization",
        "content": "The component can visualize the mapping by drawing points at the positions of nodes in the child model if visualization flags are set to show mappings."
      },
      {
        "title": "Jacobian Matrix Update",
        "content": "A Jacobian matrix is computed and updated as necessary. This matrix represents how changes in the parent model's DOFs affect the child model's nodes through linear interpolation."
      }
    ],
    "example_usage": [
      "BeamLinearMapping can be used when you have a rigid body beam and want to interpolate positions of additional points along the beam for simulation or visualization purposes."
    ]
  },
  "maths": {
    "maths": "The BeamLinearMapping component in the SOFA framework is designed to interpolate positions and velocities for points attached to a beam using linear interpolation between degrees of freedom (DOFs). This mapping is particularly useful when dealing with rigid body models where child model nodes are interpolated along the parent beam's DOFs. Here’s a detailed mathematical and physical description:\n\n### Mathematical Description\n\n#### Position Interpolation\nLet us consider two consecutive points on the beam, denoted by their position vectors $\\mathbf{p}_0$ and $\\mathbf{p}_1$. The interpolation parameter $t \\in [0, 1]$ is used to linearly interpolate between these positions. For a point attached at an interpolated position $x$, we have:\n\n$$\n\\mathbf{x}(t) = (1 - t) \\cdot \\mathbf{p}_0 + t \\cdot \\mathbf{p}_1\n$$\n\nHere, $t$ is determined based on the interpolation factor along the beam.\n\n#### Velocity Interpolation\nThe velocities of these points are similarly interpolated. If $\\mathbf{v}_0$ and $\\mathbf{v}_1$ represent the velocities at positions $\\mathbf{p}_0$ and $\\mathbf{p}_1$, respectively, then the velocity at position $x(t)$ is given by:\n\n$$\n\\mathbf{v}(t) = (1 - t) \\cdot \\mathbf{v}_0 + t \\cdot \\mathbf{v}_1\n$$\n\n#### Rotation Interpolation\nIn addition to linear interpolation for positions and velocities, the rotational components are also considered. The orientation of the rigid body is interpolated using quaternions or rotation matrices. For a quaternion $\\mathbf{q}(t)$, the interpolation would be:\n\n$$\n\\mathbf{q}(t) = (1 - t) \\cdot \\mathbf{q}_0 + t \\cdot \\mathbf{q}_1\n$$\nwhere $\\mathbf{q}_0$ and $\\mathbf{q}_1$ are the quaternions at positions $\\mathbf{p}_0$ and $\\mathbf{p}_1$, respectively. This ensures smooth orientation transitions along the beam.\n\n#### Jacobian Matrix Calculation\nThe Jacobian matrix $J$ represents how changes in the parent model's DOFs affect the child model’s nodes. The entries of the Jacobian matrix are derived from partial derivatives of the interpolated positions and velocities with respect to the parent model DOFs:\n\n$$\nJ = \\begin{bmatrix}\n\\frac{\\partial x}{\\partial p_{0x}} & \\frac{\\partial x}{\\partial p_{1x}} \\\\\n\\frac{\\partial y}{\\partial p_{0y}} & \\frac{\\partial y}{\\partial p_{1y}} \\\\\n\\frac{\\partial z}{\\partial p_{0z}} & \\frac{\\partial z}{\\partial p_{1z}}\n\\end{bmatrix}\n$$\n\n### Physical Description\nThe BeamLinearMapping component models the physical interactions by distributing the forces and motions from the parent beam to its child nodes in a manner consistent with linear interpolation. The physical behavior of the points attached to the beam is determined through:\n\n1. **Position Interpolation**: This ensures that each point along the beam smoothly transitions between the defined positions $\\mathbf{p}_0$ and $\\mathbf{p}_1$, providing a continuous spatial representation.\n2. **Velocity Interpolation**: Ensures smooth velocity distribution, reflecting the dynamics of the rigid body motion interpolated between the two points on the beam.\n3. **Rotation Interpolation**: This ensures that rotational effects are smoothly transitioned along the beam, maintaining physical consistency in orientation changes.\n4. **Jacobian Calculation**: The Jacobian matrix helps in computing how external forces or constraints applied to the child nodes propagate back to the parent model’s DOFs, ensuring accurate and physically consistent mappings.\n\nIn summary, the BeamLinearMapping component ensures that the positions, velocities, and orientations of points attached to a beam are interpolated linearly between its parent rigid body's DOFs, maintaining physical consistency in both position and velocity domains."
  },
  "summary": {
    "abstract": "The BeamLinearMapping component interpolates positions, velocities, and orientations of points attached to a beam using linear interpolation between degrees of freedom (DOFs).",
    "sheet": "# BeamLinearMapping\n\n## Overview\nBeamLinearMapping is responsible for interpolating the positions, velocities, and orientations of points attached to a beam using linear interpolation between degrees of freedom (DOFs).\n\n## Mathematical Model\n### Position Interpolation\nLet us consider two consecutive points on the beam, denoted by their position vectors \\(\\mathbf{p}_0\\) and \\(\\mathbf{p}_1\\). The interpolation parameter \\(t \\in [0, 1]\\) is used to linearly interpolate between these positions. For a point attached at an interpolated position \\(x(t)\\), we have:\n\n$$\n\\mathbf{x}(t) = (1 - t) \\cdot \\mathbf{p}_0 + t \\cdot \\mathbf{p}_1\n$$\n\n### Velocity Interpolation\nThe velocities of these points are similarly interpolated. If \\(\\mathbf{v}_0\\) and \\(\\mathbf{v}_1\\) represent the velocities at positions \\(\\mathbf{p}_0\\) and \\(\\mathbf{p}_1\\), respectively, then the velocity at position \\(x(t)\\) is given by:\n\n$$\n\\mathbf{v}(t) = (1 - t) \\cdot \\mathbf{v}_0 + t \\cdot \\mathbf{v}_1\n$$\n\n### Rotation Interpolation\nIn addition to linear interpolation for positions and velocities, the rotational components are also considered. The orientation of the rigid body is interpolated using quaternions or rotation matrices. For a quaternion \\(\\mathbf{q}(t)\\), the interpolation would be:\n\n$$\n\\mathbf{q}(t) = (1 - t) \\cdot \\mathbf{q}_0 + t \\cdot \\mathbf{q}_1\n$$\nwhere \\(\\mathbf{q}_0\\) and \\(\\mathbf{q}_1\\) are the quaternions at positions \\(\\mathbf{p}_0\\) and \\(\\mathbf{p}_1\\), respectively. This ensures smooth orientation transitions along the beam.\n\n### Jacobian Matrix Calculation\nThe Jacobian matrix \\(J\\) represents how changes in the parent model's DOFs affect the child model’s nodes. The entries of the Jacobian matrix are derived from partial derivatives of the interpolated positions and velocities with respect to the parent model DOFs:\n\n$$\nJ = \\begin{bmatrix}\n\\frac{\\partial x}{\\partial p_{0x}} & \\frac{\\partial x}{\\partial p_{1x}} \\\\\n\\frac{\\partial y}{\\partial p_{0y}} & \\frac{\\partial y}{\\partial p_{1y}} \\\\\n\\frac{\\partial z}{\\partial p_{0z}} & \\frac{\\partial z}{\\partial p_{1z}}\n\\end{bmatrix}\n$$\n\n## Parameters and Data\n- **localCoord**: A boolean parameter that controls whether the coordinates are local (true) or global (false). Default is false."
  }
}