{
  "name": "FixedRotationProjectiveConstraint",
  "main": {
    "name": "FixedRotationProjectiveConstraint",
    "namespace": "sofa::component::constraint::projective",
    "module": "Sofa.Component.Constraint.Projective",
    "include": "sofa/component/constraint/projective/FixedRotationProjectiveConstraint.h",
    "doc": "Prevents rotation around x or/and y or/and z axis.\n\nPrevents rotation around X or Y or Z axis",
    "inherits": [
      "ProjectiveConstraintSet"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types"
    ],
    "data_fields": [
      {
        "name": "d_fixedXRotation",
        "type": "bool",
        "xmlname": "FixedXRotation",
        "help": "Prevent Rotation around X axis"
      },
      {
        "name": "d_fixedYRotation",
        "type": "bool",
        "xmlname": "FixedYRotation",
        "help": "Prevent Rotation around Y axis"
      },
      {
        "name": "d_fixedZRotation",
        "type": "bool",
        "xmlname": "FixedZRotation",
        "help": "Prevent Rotation around Z axis"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectResponse",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "dx",
            "type": "DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectVelocity",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "dx",
            "type": "DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectPosition",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "x",
            "type": "DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectJacobianMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "c",
            "type": "DataMatrixDeriv &"
          }
        ],
        "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": {
    "description": "The `FixedRotationProjectiveConstraint` is a SOFA component designed to prevent rotation around the X, Y, or Z axis for a given object in the simulation environment. It inherits from the `ProjectiveConstraintSet` class and operates within the constraint projective module of SOFA.\n\nThis component primarily interacts with other mechanical components such as those managing positions, velocities, and Jacobian matrices through methods like `projectPosition`, `projectVelocity`, and `projectJacobianMatrix`. During initialization (`init`), it records the initial orientations for each vertex to ensure that rotations can be constrained correctly during simulation.\n\nPractical usage involves configuring boolean parameters `FixedXRotation`, `FixedYRotation`, and `FixedZRotation` to control which axes should prevent rotation. For instance, setting `FixedXRotation` to true will enforce no rotation around the X-axis for the object under constraint."
  },
  "maths": {
    "maths": "The `FixedRotationProjectiveConstraint` component in the SOFA framework is designed to prevent rotation around specific axes (X, Y, or Z) for a given object. This constraint operates by decomposing and recomposing rotations based on predefined boolean parameters (`d_fixedXRotation`, `d_fixedYRotation`, and `d_fixedZRotation`).\n\n### Mathematical Description\n\n1. **Initialization**:\n   - During the initialization phase (`init`), the current orientation of each vertex is stored in a vector named `previousOrientation`. This vector contains quaternions representing the initial orientations.\n   \n2. **Decomposition and Projection**:\n   - For each vertex, the current orientation quaternion $Q$ and its corresponding previous orientation quaternion $Q_{prev}$ are obtained.\n   - A projection function is defined to project a 3D vector onto another 3D vector using the dot product: \n     \\[ \text{project}(a, b) = (a \bullet b) \times b \\]\n   - The quaternion $Q$ and $Q_{prev}$ are decomposed into twist and swing components along specified axes.\n\n3. **Removing Rotations**:\n   - For each axis where rotation is fixed (`d_fixedXRotation`, `d_fixedYRotation`, or `d_fixedZRotation` set to true), the corresponding rotation component in $Q$ is removed using the decomposition function.\n   - Specifically, if `FixedXRotation` is enabled, rotations around the X-axis are decomposed and then removed by setting the twist component along the X-axis to identity.\n\n4. **Updating Orientation**:\n   - The remaining orientation quaternion after removing specified rotations is recomposed with the retained components.\n   - Finally, the new orientation of each vertex is set as follows: \n     \\[ Q_{new} = Q_{remaining} \times Q_{to\\_keep} \\]\n\n### Physical Description\n\nThe `FixedRotationProjectiveConstraint` enforces constraints on rotational degrees of freedom for an object in a simulation. When active, it ensures that the object cannot rotate around specified axes (X, Y, or Z). This is particularly useful in scenarios where certain orientations need to be maintained or controlled.\n\n- **Constraints**: The component allows specifying constraints by setting boolean parameters (`d_fixedXRotation`, `d_fixedYRotation`, and `d_fixedZRotation`) to true. For example, if `FixedXRotation` is set to true, the object will not rotate around the X-axis.\n\n- **Quaternion Decomposition**: Quaternions are used to represent orientations since they avoid singularities associated with Euler angles (such as gimbal lock). The decomposition process allows isolating and removing specific rotational components based on constraints.\n\n### Example Usage\n\nSuppose an object needs to maintain its orientation around the X-axis but can rotate freely around Y and Z axes. You would configure the constraint parameters as follows:\n```xml\n<FixedRotationProjectiveConstraint FixedXRotation='true' FixedYRotation='false' FixedZRotation='false'/>\n```\nThis configuration will prevent any rotation around the X-axis while allowing rotations around the Y and Z axes."
  },
  "summary": {
    "abstract": "Prevents rotation around specified axes (X, Y, or Z) by decomposing and recomposing quaternions representing orientations based on boolean parameters.",
    "sheet": "# FixedRotationProjectiveConstraint\n\n**Overview**: This component prevents rotation around the X, Y, or Z axis for a given object in the simulation environment. It inherits from `ProjectiveConstraintSet` and operates within the constraint projective module of SOFA.\n\n**Mathematical Model**: The component decomposes quaternions representing orientations to isolate and remove specific rotational components based on boolean parameters (`d_fixedXRotation`, `d_fixedYRotation`, and `d_fixedZRotation`). During initialization, it stores the initial orientation quaternion $Q_{prev}$ for each vertex. For each axis where rotation is fixed (parameters set to true), the corresponding rotation component in the current orientation quaternion $Q$ is removed using a decomposition function.\n\n**Parameters and Data**: The significant data fields exposed by this component are:\n- `FixedXRotation`: Prevents rotation around the X-axis (`bool`, default: false).\n- `FixedYRotation`: Prevents rotation around the Y-axis (`bool`, default: false).\n- `FixedZRotation`: Prevents rotation around the Z-axis (`bool`, default: false)."
  }
}