Data Fields

Links

Methods

{
  "name": "FixedTranslationProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/FixedTranslationProjectiveConstraint.h",
  "doc": "Attach given rigids to their initial positions but they still can have rotations.\n\nAttach given particles to their initial positions.",
  "inherits": [
    "ProjectiveConstraintSet"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec6Types"
  ],
  "data_fields": [
    {
      "name": "data",
      "type": "DataTypes"
    },
    {
      "name": "d_fixAll",
      "type": "bool",
      "xmlname": "fixAll",
      "help": "filter all the DOF to implement a fixed object"
    },
    {
      "name": "d_drawSize",
      "type": "SReal",
      "xmlname": "drawSize",
      "help": "Size of the rendered particles (0 -> point based rendering, >0 -> radius of spheres)"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "clearIndices",
      "description": "Clears all indices from the internal list."
    },
    {
      "name": "addIndex",
      "description": "Adds a new index to the list of fixed points.",
      "parameters": [
        {
          "name": "index",
          "type": "unsigned int",
          "description": "The index of the point to be added."
        }
      ]
    },
    {
      "name": "removeIndex",
      "description": "Removes an index from the list of fixed points if it exists.",
      "parameters": [
        {
          "name": "index",
          "type": "unsigned int",
          "description": "The index of the point to be removed."
        }
      ]
    }
  ],
  "description": "This constraint component in the Sofa framework is designed to fix the translational degrees of freedom (DOFs) of objects while allowing them to rotate freely. Specifically, it ensures that the objects are constrained to their initial positions but still permit rotational movements.",
  "parameters": [
    {
      "name": "indices",
      "type": "VectorIndex",
      "description": "Indices of the points that should be fixed in translation.",
      "default": "[0]"
    },
    {
      "name": "fixAll",
      "type": "bool",
      "description": "If true, all translational DOFs are fixed. If false (default), only the specified indices are fixed.",
      "default": "false"
    },
    {
      "name": "drawSize",
      "type": "SReal",
      "description": "The size of rendered particles for visualization purposes (0 means point-based rendering, values > 0 indicate sphere-based rendering).",
      "default": "0.0"
    }
  ],
  "notes": "This component supports topological changes and can handle various data types such as Rigid3Types, Rigid2Types, and Vec6Types. It is particularly useful for simulating scenarios where objects need to maintain their initial positions but are free to rotate.",
  "implementation_details": "The constraint operations are defined in the `projectResponse`, `projectVelocity`, `projectPosition`, and `projectJacobianMatrix` methods. The visualization of fixed points can be controlled through the draw method, which handles rendering using the provided VisualParams.",
  "type": "Constraint",
  "maths": "### Mathematical and Physical Description of the FixedTranslationProjectiveConstraint Component\n\n#### Overview\nThe **FixedTranslationProjectiveConstraint** is a constraint component designed for use within the Soft-tissue Open-source Framework Application (Sofa) to restrict translational degrees of freedom while allowing rotational movements. This behavior ensures that objects are fixed in their initial positions but can still rotate freely.\n\n#### Degrees of Freedom Restriction\n- **Translational DOFs:** The component enforces a zero displacement in the translational components along the x, y, and z axes for each constrained object or rigid body.\n- **Rotational DOFs:** Rotations about all axes are permitted, ensuring that objects can rotate freely around their initial positions. \n\n#### Mathematical Representation\nLet \\(\\mathbf{p}_0\\) be the initial position vector of an object in its reference configuration and \\(\\mathbf{p}\\) be its current position vector. The constraint enforces:\n$$\n\\Delta \\mathbf{p} = \\mathbf{p} - \\mathbf{p}_0 = 0\n$$\nwhere \\(\\Delta \\mathbf{p}\\) represents the displacement vector.\n\nFor rotational components, if we represent rotations using quaternions (common in rigid body mechanics), the quaternion \\(\\mathbf{q}\\) representing rotation can be defined as:\n$$\n\\mathbf{q} = [s, \\mathbf{v}] = [s, x, y, z]\n$$\nwhere \\(s\\) is the scalar part and \\([x, y, z]\\) are the vector components. The quaternion represents a rotation around an axis by an angle.\n\n#### Constraint Enforcement\nThe constraint is enforced in both velocity (velocity projection) and position updates (position correction). For instance:\n- **Velocity Projection:**\n$$\n\\mathbf{v} = \\mathbf{0}\n$$\nwhere \\(\\mathbf{v}\\) is the translational velocity vector, ensuring that no translational movement occurs.\n\n- **Position Correction (Projection):** The position correction step ensures that any deviation from the initial position is corrected:\n$$\n\\mathbf{p}_{corrected} = \\mathbf{p}_0 + R(\\mathbf{p} - \\mathbf{p}_0)\n$$\nwhere \\(R\\) represents a rotational transformation (e.g., using quaternions), ensuring that only the translational component is reset to zero.\n\n#### Implementation in Sofa\nIn the Sofa framework, this constraint operates through several methods:\n- **Initialization:** The `init` method sets up the topological links and configurations for the constrained objects.\n- **Topological Changes Handling:** Methods like `addIndex`, `removeIndex`, and `clearIndices` manage the indices of points that need to be fixed.\n\nThe constraint is enforced through methods such as:\n- `projectResponse`: Ensures zero displacement by setting translational components of velocity or position change to zero.\n- `draw`: Visualizes the constrained objects in their initial positions with optional rendering features for better visualization and debugging.\n\n#### Visualization\nObjects constrained by this component are visualized using their initial positions. The draw method can render these points as fixed locations, providing a clear indication of the constraint's application during simulation runs.\n\n### Conclusion\nThe **FixedTranslationProjectiveConstraint** effectively restricts objects to remain in their initial translational positions while allowing for rotational freedom. This makes it particularly useful for scenarios where rotational dynamics are important but translational movements need to be controlled or eliminated.",
  "abstract": "The FixedTranslationProjectiveConstraint component fixes objects' translational degrees of freedom at their initial positions while allowing rotational movements.",
  "sheet": "# FixedTranslationProjectiveConstraint\n\n## Overview\nThe **FixedTranslationProjectiveConstraint** is a constraint component that restricts the translational degrees of freedom (DOFs) of objects to their initial positions, while permitting rotations. It inherits from `ProjectiveConstraintSet` and supports various types such as `Rigid2Types`, `Rigid3Types`, and `Vec6Types`. This component ensures that objects remain fixed in translation but can rotate freely around their initial positions.\n\n## Mathematical Model\nThe constraint enforces zero displacement for the translational components while allowing rotations. Let \\(\\mathbf{p}_0\\) be the initial position vector of an object and \\(\\mathbf{p}\\) its current position vector. The constraint is defined as:\n$$\n\\Delta \\mathbf{p} = \\mathbf{p} - \\mathbf{p}_0 = 0\n$$\nFor rotations, if we use quaternions to represent rotations, the quaternion \\(\\mathbf{q}\\) can be written as:\n$$\n\\mathbf{q} = [s, \\mathbf{v}] = [s, x, y, z]\n$$\nThe constraint is enforced through methods such as `projectResponse`, which ensures zero translational velocity and corrects the position to enforce the initial position.\n\n## Parameters and Data\n- **fixAll**: A boolean flag (`bool`) that applies the constraint globally if set to true. Default: false.\n- **drawSize**: The size of rendered particles for visualization (`SReal`). Default: 0 (point-based rendering).\n\n## Dependencies and Connections\nThe component requires a link to a `BaseMeshTopology` object, which provides the topological information necessary for applying constraints."
}