Data Fields

Methods

{
  "name": "SkeletalMotionProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/SkeletalMotionProjectiveConstraint.h",
  "doc": "Animate a skeleton.",
  "inherits": [
    "ProjectiveConstraintSet"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types"
  ],
  "data_fields": [
    {
      "name": "d_skeletonJoints",
      "type": "type::SVector<SkeletonJoint<TDataTypes>>",
      "xmlname": "joints",
      "help": "skeleton joints"
    },
    {
      "name": "d_skeletonBones",
      "type": "type::SVector<SkeletonBone>",
      "xmlname": "bones",
      "help": "skeleton bones"
    },
    {
      "name": "d_animationSpeed",
      "type": "float",
      "xmlname": "animationSpeed",
      "help": "animation speed"
    },
    {
      "name": "d_active",
      "type": "bool",
      "xmlname": "active",
      "help": "is the constraint active?"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reset",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAnimationSpeed",
      "return_type": "float",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setAnimationSpeed",
      "return_type": "void",
      "params": [
        {
          "name": "speed",
          "type": "float"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findKeyTimes",
      "return_type": "void",
      "params": [
        {
          "name": "ct",
          "type": "Real"
        }
      ],
      "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": "resData",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectVelocity",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "vData",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectPosition",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "xData",
          "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": "cData",
          "type": "DataMatrixDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "vector",
          "type": "linearalgebra::BaseVector *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "M",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "offset",
          "type": "unsigned int"
        }
      ],
      "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"
    },
    {
      "name": "localToGlobal",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setSkeletalMotion",
      "return_type": "void",
      "params": [
        {
          "name": "skeletonJoints",
          "type": "const int &"
        },
        {
          "name": "skeletonBones",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addChannel",
      "return_type": "void",
      "params": [
        {
          "name": "jointIndex",
          "type": "unsigned int"
        },
        {
          "name": "channel",
          "type": "Coord"
        },
        {
          "name": "time",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectResponseT",
      "return_type": "void",
      "params": [
        {
          "name": "dx",
          "type": "DataDeriv &"
        },
        {
          "name": "clear",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "interpolatePosition",
      "return_type": "void",
      "params": [
        {
          "name": "cT",
          "type": "Real"
        },
        {
          "name": "",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `SkeletalMotionProjectiveConstraint` is designed to animate a skeleton within the SOFA simulation framework, specifically for simulating articulated systems like character rigs or biological structures. It inherits from `ProjectiveConstraintSet`, which allows it to apply constraints on mechanical models in an interactive and projective manner. The component manages the joints and bones of a skeletal hierarchy, where each joint can have associated channels (local transformations) at specific times, enabling keyframe-based animation.\n\n### Role and Purpose:\nThe primary role is to animate the skeleton by interpolating between predefined motion states over time, based on the specified animation speed. It supports both position and velocity projection to ensure consistent movement during simulation steps.\n\n### Interactions with Other Components:\n- **MechanicalState**: The component interacts directly with `MechanicalState` to access and modify positions (`VecCoord`) and velocities (`VecDeriv`).\n- **VisualParams**: For visualization purposes, it uses `VisualParams` to draw joints and bones.\n- **Collision Detection and Response**: Although not explicitly shown in the metadata or source code, this component likely interacts with collision models to ensure realistic interactions during animation. It implements several methods required by the SOFA framework for constraint projection (`projectResponse`, `applyConstraint`) and matrix manipulation (`projectMatrix`).\n\n### Data Fields:\n- **d_skeletonJoints**: Stores a vector of skeleton joints, each containing keyframe channels and times.\n- **d_skeletonBones**: Contains indices of bones that need to be updated according to the animated nodes.\n- **d_animationSpeed**: Controls how fast the animation is played relative to simulation time.\n- **d_active**: Indicates whether the constraint is active in the simulation.\n\n### Practical Usage Guidance:\nThe component can be configured with a set of skeleton joints and bones, which are defined by their rest positions and keyframe channels. The user can adjust the `animationSpeed` and enable/disable the animation using the `active` flag. Methods like `addChannel`, `setSkeletalMotion`, and `findKeyTimes` help in setting up and animating the skeleton. The component automatically interpolates between motion states to create smooth animations, which are crucial for interactive simulations and visualizations.\n\n### Key Methods:\n- **projectResponse**: Projects the response of the system based on mechanical parameters.\n- **projectVelocity** & **projectPosition**: Interpolate positions and velocities over time using keyframe data.\n- **draw**: Visualizes the skeleton by drawing joints and bones in 3D space.\n\nOverall, `SkeletalMotionProjectiveConstraint` is a versatile component for incorporating animated skeletons into SOFA simulations.",
  "maths": "The `SkeletalMotionProjectiveConstraint` is designed to animate a skeleton within the SOFA simulation framework, specifically for simulating articulated systems like character rigs or biological structures. It inherits from `ProjectiveConstraintSet`, which allows it to apply constraints on mechanical models in an interactive and projective manner. The component manages the joints and bones of a skeletal hierarchy, where each joint can have associated channels (local transformations) at specific times, enabling keyframe-based animation.\n\n### Governing Equations or Operators:\nThe `SkeletalMotionProjectiveConstraint` does not directly contribute to typical FEM operators such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(\boldsymbol{f}_{int}\\), residual \\(R\\). Instead, it focuses on projecting positions and velocities based on predefined motion channels. The interpolation of joint positions over time is the primary mechanism for animation.\n\n### Constitutive or Kinematic Laws:\nThe component does not involve any material constitutive laws but rather kinematic constraints that enforce specific motion states at defined times. Each `SkeletonJoint` has a set of keyframes represented as local transformations (`mChannels`) and associated times (`mTimes`). The interpolation between these keyframes is performed using linear or spline-based methods, depending on the implementation details not explicitly shown in the provided metadata.\n\n### Role in the Global FEM Pipeline:\nThe `SkeletalMotionProjectiveConstraint` plays a critical role in the time integration phase by updating positions and velocities at each simulation step. It ensures that the mechanical model adheres to predefined animation paths, thereby maintaining consistency with user-defined motion sequences.\n\n1. **Initialization (init)**: Sets up internal data structures and initializes joint states.\n2. **Position and Velocity Projection**:\n   - `projectResponse`: Projects response based on mechanical parameters but clears responses in this implementation due to its constraints not involving forces directly.\n   - `projectVelocity`: Computes the velocities at each simulation step by interpolating between keyframe positions using finite differences.\n   - `projectPosition`: Interpolates joint positions over time, ensuring smooth transitions between predefined motion states.\n3. **Visualization (draw)**: Draws joints and bones for visual feedback during animation.\n\n### Numerical Methods or Discretization Choices:\nThe component uses linear interpolation to compute the position of each joint at a given simulation time. This method is straightforward but may lead to non-smooth transitions between keyframes if the motion data is not finely sampled. The velocity computation relies on finite differences, approximating the derivative of the interpolated positions.\n\n### Integration into Variational/Lagrangian Mechanics Framework:\nThe `SkeletalMotionProjectiveConstraint` fits into the broader Lagrangian mechanics framework by enforcing kinematic constraints that align with the specified motion sequences. Although it does not directly participate in deriving or solving the variational problem (such as forming the weak form), it ensures that any mechanical state updates respect predefined animation paths. This is particularly useful for applications where specific motions are required, such as character animations or controlled biological simulations.\n\n### Specific Methods:\n- **projectResponse**: Clears response data if active.\n   \n   \\[\\text{projectResponse} : \\boldsymbol{x}_{res} = 0\\]\n\n- **projectVelocity**: Computes velocity based on finite differences of interpolated positions.\n   \n   \\[\n   \\boldsymbol{v}(t) = \\frac{\\boldsymbol{x}(t + \\Delta t) - \\boldsymbol{x}(t)}{\\Delta t}\n   \\]\n\n- **projectPosition**: Interpolates joint positions over time.\n   \n   Given keyframe times and transformations, for a given simulation time `ct`, the position is interpolated linearly between two nearest keyframes:\n   \n   \\[\n   \\boldsymbol{x}(t) = (1 - dt)\\boldsymbol{x}_{prev} + dt\\boldsymbol{x}_{next}\n   \\]\n\n- **draw**: Visualizes the skeleton by drawing joints and bones at their interpolated positions.\n\nIn summary, the `SkeletalMotionProjectiveConstraint` is a key component for animating articulated systems within SOFA simulations, ensuring that predefined motion sequences are smoothly followed over time.",
  "abstract": "The `SkeletalMotionProjectiveConstraint` animates a skeleton by interpolating between predefined motion states over time based on specified animation speed.",
  "sheet": "# SkeletalMotionProjectiveConstraint\n\n## Overview\n\nThe `SkeletalMotionProjectiveConstraint` is designed to animate skeletons within SOFA simulations. It inherits from `ProjectiveConstraintSet`, allowing it to apply constraints in an interactive and projective manner. The component manages the joints and bones of a skeletal hierarchy, enabling keyframe-based animation by interpolating between predefined motion states over time.\n\n## Parameters and Data\n\n- **d_skeletonJoints**: Stores a vector of skeleton joints with associated channels (local transformations) at specific times.\n- **d_skeletonBones**: Contains indices of bones that need to be updated according to the animated nodes.\n- **d_animationSpeed**: Controls how fast the animation is played relative to simulation time.\n- **d_active**: Indicates whether the constraint is active in the simulation.\n\n## Dependencies and Connections\n\nThe component interacts with `MechanicalState` to access and modify positions (`VecCoord`) and velocities (`VecDeriv`). It also uses `VisualParams` for visualization purposes. Although not explicitly shown, it likely interacts with collision models to ensure realistic interactions during animation.\n\n## Practical Notes\n\n- The user can configure the component with a set of skeleton joints and bones, defined by their rest positions and keyframe channels.\n- Adjusting the `animationSpeed` and enabling/disabling the constraint using the `active` flag allows for dynamic control over the animation.\n- Methods like `addChannel`, `setSkeletalMotion`, and `findKeyTimes` help in setting up and animating the skeleton. The component automatically interpolates between motion states to create smooth animations, which are crucial for interactive simulations and visualizations."
}