Mathematical Description of HermiteSplineProjectiveConstraint

Data Fields

Links

Methods

{
  "name": "HermiteSplineProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/HermiteSplineProjectiveConstraint.h",
  "doc": "Apply a hermite cubic spline trajectory to given points.\n\nImpose a trajectory to given Dofs following a Hermite cubic spline constraint.\n\tControl parameters are :\n\t  - begin and end points\n\t  - derivates at this points\n\t  - acceleration curve on the trajectory",
  "inherits": [
    "ProjectiveConstraintSet"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_tBegin",
      "type": "Real",
      "xmlname": "BeginTime",
      "help": "Begin Time of the motion"
    },
    {
      "name": "d_tEnd",
      "type": "Real",
      "xmlname": "EndTime",
      "help": "End Time of the motion"
    },
    {
      "name": "d_x0",
      "type": "Vec3R",
      "xmlname": "X0",
      "help": "first control point"
    },
    {
      "name": "d_dx0",
      "type": "Vec3R",
      "xmlname": "dX0",
      "help": "first control tangente"
    },
    {
      "name": "d_x1",
      "type": "Vec3R",
      "xmlname": "X1",
      "help": "second control point"
    },
    {
      "name": "d_dx1",
      "type": "Vec3R",
      "xmlname": "dX1",
      "help": "second control tangente"
    },
    {
      "name": "d_sx0",
      "type": "Vec2R",
      "xmlname": "SX0",
      "help": "first interpolation vector"
    },
    {
      "name": "d_sx1",
      "type": "Vec2R",
      "xmlname": "SX1",
      "help": "second interpolation vector"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "init()",
      "description": "Initializes the constraint with given parameters and sets up necessary configurations."
    },
    {
      "name": "reinit()",
      "description": "Reinitializes the constraints, allowing dynamic updates to parameters or indices during simulation runs."
    },
    {
      "name": "projectResponse(const core::MechanicalParams* mparams, DataVecDeriv& resData)",
      "description": "Projects the response forces onto constrained DOFs based on the current state and mechanical parameters."
    },
    {
      "name": "projectVelocity(const core::MechanicalParams* mparams, DataVecDeriv& vData)",
      "description": "Applies velocity constraints to the specified DOFs during simulation steps."
    },
    {
      "name": "projectPosition(const core::MechanicalParams* mparams, DataVecCoord& xData)",
      "description": "Projects positions of constrained DOFs onto the Hermite spline trajectory at each time step."
    },
    {
      "name": "draw(const core::visual::VisualParams* vparams)",
      "description": "Draws the Hermite spline curve and control points for visualization purposes during simulation runs."
    }
  ],
  "description": "The `HermiteSplineProjectiveConstraint` is a constraint component in the SOFA (Simulation Open-Framework Architecture) framework that imposes a trajectory on specified degrees-of-freedom (DOFs) following a Hermite cubic spline curve. This component allows for precise control over the motion of objects within simulations by defining specific points and their derivatives along the path, ensuring smooth and natural movement.\n\n### Key Features:\n- **Control Parameters:**\n  - **Begin and End Points:** The start (`d_x0`) and end (`d_x1`) positions of the trajectory.\n  - **Derivatives at Control Points:** Velocities (`d_dx0`, `d_dx1`) at the start and end points, which define the tangents to the curve at these points.\n  - **Acceleration Curve:** The acceleration between control points can be defined using a Hermite spline with parameters (`d_sx0` and `d_sx1`).\n\n- **Timing Control:** \n  - Begin Time (`d_tBegin`) and End Time (`d_tEnd`) define the duration of the constraint application.\n\n- **Visualization:** The component includes functionality to draw the trajectory and control points, making it easy to visualize the motion path during simulation runs.\n\n### Usage:\nThis component is particularly useful in scenarios where precise and smooth trajectories are required for objects within a simulated environment. Applications can range from robotics simulations requiring controlled motion paths to character animations needing natural movement curves.\n\n### Initialization and Constraints Management:\n- **Initialization:** The `init()` method sets up the constraint based on the provided parameters, ensuring that it is properly configured before simulation starts.\n- **Constraints Management:** Methods like `clearConstraints()`, `addConstraint(index)`, allow for dynamic management of constrained DOFs during runtime.\n\n### Interface Implementation:\n- Implements methods from the `ProjectiveConstraintSet` interface to project constraints onto velocity, position, and response forces. This includes projecting positions (`projectPosition()`), velocities (`projectVelocity()`), and applying constraints in the Jacobian matrix (`projectJacobianMatrix()`).\n\n### Visualization Support:\n- The `draw()` method provides a visual representation of the trajectory using the provided parameters during visualization.\n\n### Customization for Types:\n- Template specialization is used to support different data types, such as rigid body transforms and vector positions, allowing flexibility in application across various simulation scenarios.\n",
  "parameters": [
    {
      "name": "d_indices",
      "description": "Indices of the DOFs being constrained.",
      "type": "SetIndexArray"
    },
    {
      "name": "d_tBegin",
      "description": "The time step at which the constraint begins to apply.",
      "type": "Real"
    },
    {
      "name": "d_tEnd",
      "description": "The time step at which the constraint stops applying.",
      "type": "Real"
    },
    {
      "name": "d_x0",
      "description": "First control point of the Hermite spline curve (begin position).",
      "type": "Vec3R"
    },
    {
      "name": "d_dx0",
      "description": "Derivative at the first control point (velocity at begin position).",
      "type": "Vec3R"
    },
    {
      "name": "d_x1",
      "description": "Second control point of the Hermite spline curve (end position).",
      "type": "Vec3R"
    },
    {
      "name": "d_dx1",
      "description": "Derivative at the second control point (velocity at end position).",
      "type": "Vec3R"
    },
    {
      "name": "d_sx0",
      "description": "First point of the acceleration curve for Hermite spline interpolation.",
      "type": "Vec2R"
    },
    {
      "name": "d_sx1",
      "description": "Second point of the acceleration curve for Hermite spline interpolation.",
      "type": "Vec2R"
    }
  ],
  "maths": "# Mathematical Description of HermiteSplineProjectiveConstraint\n\n## Overview\nThe `HermiteSplineProjectiveConstraint` is a constraint in the SOFA framework that imposes a trajectory on specified degrees-of-freedom (DOFs) based on a Hermite cubic spline. This mathematical formulation ensures smooth and controlled motion paths for objects within simulations, often used for precise control in robotics or natural movement in character animations.\n\n## Cubic Hermite Spline\nA cubic Hermite spline is defined by two points and their derivatives at those points, ensuring continuity of both position and velocity (first derivative). Mathematically, the spline can be described as follows:\n\n### Basis Functions\nThe Hermite basis functions are given by:\n\n$$\nh_0(t) = 2t^3 - 3t^2 + 1 \\quad\\text{(position at } t=0)\nnh_1(t) = -2t^3 + 3t^2 \\quad\\text{(position at } t=1)\nnh_2(t) = t^3 - 2t^2 + t \\quad\\text{(velocity derivative at } t=0)\nh_3(t) = t^3 - t^2 \\quad\\text{(velocity derivative at } t=1)\n$$\n\n### Spline Definition\nGiven control points and their derivatives, the position of a point on the spline is defined as:\n\n$$\np(t) = h_0(t)p_0 + h_1(t)p_1 + h_2(t)m_0 + h_3(t)m_1\n$$\n\nWhere $p_0$ and $p_1$ are the control points, $m_0$ and $m_1$ are their respective derivatives (velocities).\n\n## Constraints Application\nThe `HermiteSplineProjectiveConstraint` applies these constraints dynamically to specified DOFs within a simulation timeframe defined by `d_tBegin` and `d_tEnd`. The trajectory is calculated based on the provided control parameters.\n\n### Time-Dependent Trajectory Calculation\nGiven time $t$ between `d_tBegin` and `d_tEnd`, the normalized parameter $u \\in [0, 1]$ is used to calculate the position along the spline:\n\n$$\nu = \\frac{t - d_{\\text{tBegin}}}{d_{\\text{tEnd}} - d_{\\text{tBegin}}} \np(t) = h_0(u)d_x0 + h_1(u)d_x1 + h_2(u)d_dx0 + h_3(u)d_dx1\n$$\n\n### Acceleration Curve\nThe acceleration curve is itself defined by another Hermite spline with control points $(0, 0)$ and $(1, 1)$. The acceleration parameters are given by $d_sx0$ and $d_sx1$, ensuring smooth acceleration along the trajectory.\n\n## Projection onto Velocity, Position, and Forces\nThe `HermiteSplineProjectiveConstraint` projects these constraints onto velocity (`projectVelocity()`), position (`projectPosition()`), and response forces (`projectResponse()`) as required by the simulation. This ensures that the constrained DOFs follow the predefined trajectory smoothly and naturally.\n\n### Example of Position Projection\nIn `projectPosition()`, for a time $t$ within the constraint period, the position is calculated using the above formula and applied to the relevant DOF:\n\n$$\np_i(t) = h_0(u)d_x0 + h_1(u)d_x1 + h_2(u)d_dx0 + h_3(u)d_dx1 \nv_i(t) = \\frac{dp}{dt} \\text{(velocity at time } t)\nf_i(t) = -k(p_{\\text{desired}}(t) - p_i(t)) \\quad (\\text{constraint force})\n$$\n\nWhere $p_i(t)$ is the position of the DOF at time $t$, and $v_i(t)$ is its velocity. The constraint force $f_i(t)$ ensures that the actual position converges to the desired trajectory.\n\n### Visualization Support\nThe `draw()` method allows for visualizing the spline, control points, and tangents, providing a clear depiction of the trajectory within the simulation environment.\n\n## Conclusion\nThe `HermiteSplineProjectiveConstraint` leverages cubic Hermite splines to impose smooth and controlled trajectories on DOFs in simulations. This mathematical formulation ensures that motions are both natural and precise, making it an essential tool for applications requiring detailed motion control.",
  "abstract": "Imposes a trajectory on specified degrees-of-freedom (DOFs) using a Hermite cubic spline defined by control points and their derivatives.",
  "sheet": "# HermiteSplineProjectiveConstraint\n\n## Overview\nThe `HermiteSplineProjectiveConstraint` is a constraint component in the SOFA framework that imposes a trajectory on specified degrees-of-freedom (DOFs) based on a Hermite cubic spline. This ensures smooth and controlled motion paths for objects within simulations, often used for precise control in robotics or natural movement in character animations.\n\n## Mathematical Model\nA cubic Hermite spline is defined by two points and their derivatives at those points, ensuring continuity of both position and velocity (first derivative). Mathematically, the spline can be described as follows:\n\n### Basis Functions\nThe Hermite basis functions are given by:\n\n$$\nh_0(t) = 2t^3 - 3t^2 + 1 \\quad\\text{(position at } t=0)\nnh_1(t) = -2t^3 + 3t^2 \\quad\\text{(position at } t=1)\nnh_2(t) = t^3 - 2t^2 + t \\quad\\text{(velocity derivative at } t=0)\nh_3(t) = t^3 - t^2 \\quad\\text{(velocity derivative at } t=1)\n$$\n\n### Spline Definition\nGiven control points and their derivatives, the position of a point on the spline is defined as:\n\n$$\np(t) = h_0(t)p_0 + h_1(t)p_1 + h_2(t)m_0 + h_3(t)m_1\n$$\n\nWhere $p_0$ and $p_1$ are the control points, $m_0$ and $m_1$ are their respective derivatives (velocities).\n\n### Time-Dependent Trajectory Calculation\nGiven time $t$ between `d_tBegin` and `d_tEnd`, the normalized parameter $u \\in [0, 1]$ is used to calculate the position along the spline:\n\n$$\nu = \\frac{t - d_{\\text{tBegin}}}{d_{\\text{tEnd}} - d_{\\text{tBegin}}} \np(t) = h_0(u)d_x0 + h_1(u)d_x1 + h_2(u)d_dx0 + h_3(u)d_dx1\n$$\n\n### Acceleration Curve\nThe acceleration curve is itself defined by another Hermite spline with control points $(0, 0)$ and $(1, 1)$. The acceleration parameters are given by $d_sx0$ and $d_sx1$, ensuring smooth acceleration along the trajectory.\n\n## Parameters and Data\n- **Begin Time (`d_tBegin`)**: Begin time of the motion (Real).\n- **End Time (`d_tEnd`)**: End time of the motion (Real).\n- **First Control Point (`d_x0`)**: First control point (Vec3R).\n- **First Derivative (`d_dx0`)**: First control tangent (Vec3R).\n- **Second Control Point (`d_x1`)**: Second control point (Vec3R).\n- **Second Derivative (`d_dx1`)**: Second control tangent (Vec3R).\n- **First Interpolation Vector (`d_sx0`)**: First interpolation vector (Vec2R).\n- **Second Interpolation Vector (`d_sx1`)**: Second interpolation vector (Vec2R)."
}