Data Fields

Links

Methods

{
  "name": "DirectionProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/DirectionProjectiveConstraint.h",
  "doc": "Attach given particles to their initial positions.\n\nProject particles to an affine straight line going through the particle original position.",
  "inherits": [
    "ProjectiveConstraintSet"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_drawSize",
      "type": "SReal",
      "xmlname": "drawSize",
      "help": "Size of the rendered particles (0 -> point based rendering, >0 -> radius of spheres)"
    },
    {
      "name": "d_direction",
      "type": "CPos",
      "xmlname": "direction",
      "help": "Direction of the line"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "clearConstraints",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "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": "resData",
          "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": "vData",
          "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": "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": "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": "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": "projectMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "",
          "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"
    }
  ],
  "description": {
    "name": "DirectionProjectiveConstraint",
    "namespace": "sofa::component::constraint::projective",
    "purpose": "The DirectionProjectiveConstraint is a class designed to constrain particles in SOFA simulations to move along an affine straight line that passes through the particle's original position. This constraint can be applied to particles in both 2D and 3D space.",
    "features": [
      {
        "name": "Projection",
        "description": "This component projects particles onto a specified direction, maintaining their movement along an affine straight line that passes through their initial positions."
      },
      {
        "name": "Custom Direction",
        "description": "The user can specify the direction of the line to which the particles will be projected. This provides flexibility in constraining particle motion based on desired simulation requirements."
      },
      {
        "name": "Visualization",
        "description": "Particles constrained by this component can be visualized using both point-based and sphere-based rendering methods, depending on user preference."
      }
    ],
    "parameters": [
      {
        "name": "d_indices",
        "type": "IndexSubsetData",
        "description": "Indices of the particles that are to be constrained by this component."
      },
      {
        "name": "d_drawSize",
        "type": "SReal",
        "description": "Determines the size of the rendered particles for visualization. A value of 0 indicates point-based rendering, while a positive value signifies sphere-based rendering with the specified radius."
      },
      {
        "name": "d_direction",
        "type": "CPos",
        "description": "The direction vector that defines the affine straight line to which the constrained particles will be projected. This line passes through each particle's initial position."
      }
    ],
    "methods": [
      {
        "name": "init()",
        "return_type": "void",
        "description": "Initializes the component, setting up necessary data structures and preparing for simulation."
      },
      {
        "name": "reinit()",
        "return_type": "void",
        "description": "Reinitializes the component, typically called when changes to the constrained system require reconfiguration of constraints."
      },
      {
        "name": "projectResponse()",
        "return_type": "void",
        "parameters": [
          "const core::MechanicalParams* mparams",
          "DataVecDeriv& resData"
        ],
        "description": "Projects the response (force) vector of constrained particles along the specified direction."
      },
      {
        "name": "projectVelocity()",
        "return_type": "void",
        "parameters": [
          "const core::MechanicalParams* mparams",
          "DataVecDeriv& vData"
        ],
        "description": "Projects the velocity vector of constrained particles along the specified direction."
      },
      {
        "name": "projectPosition()",
        "return_type": "void",
        "parameters": [
          "const core::MechanicalParams* mparams",
          "DataVecCoord& xData"
        ],
        "description": "Projects the position vector of constrained particles to maintain their motion along the specified direction."
      },
      {
        "name": "applyConstraint()",
        "return_type": "void",
        "parameters": [
          "const core::MechanicalParams* mparams",
          "linearalgebra::BaseVector* vector",
          "const sofa::core::behavior::MultiMatrixAccessor* matrix"
        ],
        "description": "Applies the constraint to a given vector, typically used in solving systems of equations during simulation."
      }
    ],
    "dependencies": [
      {
        "name": "sofa::core",
        "description": "The core SOFA library containing essential components for building and running simulations."
      },
      {
        "name": "sofa::linearalgebra",
        "description": "Linear algebra support, including sparse matrices which are used to project vectors onto the constrained space."
      }
    ],
    "example_usage": "DirectionProjectiveConstraint is useful in scenarios where particles need to move along specific directions but retain their initial positions as reference points. This can be applied in simulations of robotic arms, linear actuators, or any system requiring directional constraints."
  },
  "maths": "## Mathematical and Physical Description of DirectionProjectiveConstraint\n\n### Purpose\nThe **DirectionProjectiveConstraint** is a component designed to constrain the motion of particles in simulations, ensuring they move along an affine straight line that passes through their initial positions. This constraint enforces directional movement while maintaining the original spatial reference points for each particle.\n\n### Mathematical Formulation\nLet's denote:\n- \\(\\mathbf{x}_i^0\\) as the initial position of a particle indexed by \\(i\\).\n- \\(\\mathbf{d}\\) as the direction vector that defines the affine straight line to which the particles will be projected.\n\n#### Position Projection\nTo project the current position \\(\\mathbf{x}_i(t)\\) of each constrained particle onto this direction, we can define the projection formula:\n$$\n\\mathbf{x}_i^*(t) = \\mathbf{x}_i^0 + \\lambda_i (\\mathbf{d})\n$$\nwhere \\\\(\\lambda_i\\\\) is a scalar parameter that determines how far along the direction vector each particle has moved. The projection ensures that the particle's position at any time remains on the line defined by its initial position and the specified direction.\n\n#### Velocity Projection\nSimilarly, to project the velocity \\(\\mathbf{v}_i(t) = \\dot{\\mathbf{x}}_i(t)\\), we can express it along the same affine straight line:\n$$\n\\mathbf{v}_i^*(t) = \\lambda_i'(t) (\\mathbf{d})\n$$\nwhere \\\\(\\lambda_i'\\\\) is the derivative of \\\\(\\lambda_i\\\\), indicating the rate at which the particle moves along the direction vector.\n\n#### Force Projection\nFor the forces applied to each constrained particle, we project them onto the specified direction:\n$$\n\\mathbf{f}_i^*(t) = \\left( \\frac{(\\mathbf{d} \\. \\mathbf{f}_i(t))}{|\\mathbf{d}|^2} \\right) (\\mathbf{d})\n$$\nwhere the dot denotes the inner product between vectors. This ensures that only the component of forces aligned with the specified direction affects particle motion.\n\n### Physical Interpretation\nThe DirectionProjectiveConstraint enforces directional movement by projecting all relevant vector quantities onto a specified line passing through each particle's initial position. The key physical principle is that particles are allowed to move freely along this pre-defined direction, while any lateral movements perpendicular to the direction vector are constrained or nullified.\n\n- **Position Projection**: Ensures that the current position of each particle remains on an affine straight line defined by its original location and a user-specified direction.\n- **Velocity Projection**: Constrains the velocity vectors so that they align with the specified direction, maintaining consistent directional movement.\n- **Force Projection**: Modifies applied forces to ensure they only influence motion along the specified direction.\n\n### Example Usage\nThis constraint is particularly useful in simulations where particles need to move along specific paths but are anchored at their initial positions as reference points. Applications include modeling robotic arms, linear actuators, or any system requiring directional constraints for particle movement.\n",
  "abstract": "The DirectionProjectiveConstraint projects particles onto an affine straight line defined by their initial positions and a specified direction, constraining their movement along this line.",
  "sheet": "# DirectionProjectiveConstraint\n\n## Overview\nThe DirectionProjectiveConstraint is designed to constrain the motion of particles in simulations, ensuring they move along an affine straight line that passes through their initial positions. This constraint enforces directional movement while maintaining the original spatial reference points for each particle.\n\n## Mathematical Model\nLet's denote:\n- \\(\\mathbf{x}_i^0\\) as the initial position of a particle indexed by \\(i\\).\n- \\(\\mathbf{d}\\) as the direction vector that defines the affine straight line to which the particles will be projected.\n\n#### Position Projection\nTo project the current position \\(\\mathbf{x}_i(t)\\) of each constrained particle onto this direction, we can define the projection formula:\n$$\n\\mathbf{x}_i^*(t) = \\mathbf{x}_i^0 + \\lambda_i (\\mathbf{d})\n$$\nwhere \\(\\lambda_i\\) is a scalar parameter that determines how far along the direction vector each particle has moved.\n\n#### Velocity Projection\nSimilarly, to project the velocity \\(\\mathbf{v}_i(t) = \\dot{\\mathbf{x}}_i(t)\\), we can express it along the same affine straight line:\n$$\n\\mathbf{v}_i^*(t) = \\lambda_i'(t) (\\mathbf{d})\n$$\nwhere \\(\\lambda_i'\\) is the derivative of \\(\\lambda_i\\), indicating the rate at which the particle moves along the direction vector.\n\n#### Force Projection\nFor the forces applied to each constrained particle, we project them onto the specified direction:\n$$\n\\mathbf{f}_i^*(t) = \\left( \\frac{(\\mathbf{d} \\. \\mathbf{f}_i(t))}{|\\mathbf{d}|^2} \\right) (\\mathbf{d})\n$$\nwhere the dot denotes the inner product between vectors.\n\n## Parameters and Data\n- **drawSize**: Size of the rendered particles (0 -> point based rendering, >0 -> radius of spheres).\n- **direction**: Direction vector that defines the affine straight line to which the constrained particles will be projected.\n\n## Practical Notes\nEnsure that the direction vector is non-zero to avoid undefined behavior. The projection operations ensure consistent directional movement along the specified line."
}