Data Fields

Methods

{
  "name": "MechanicalStateController",
  "namespace": "sofa::component::controller",
  "module": "Sofa.Component.Controller",
  "include": "sofa/component/controller/MechanicalStateController.h",
  "doc": "Provides a Mouse & Keyboard user control on a Mechanical State.\n\nMechanicalStateController Class\nProvides a Mouse & Keyboard user control on a Mechanical State.\nOn a Rigid Particle, relative and absolute control is available.",
  "inherits": [
    "Controller"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "d_index",
      "type": "unsigned int",
      "xmlname": "index",
      "help": "Index of the controlled DOF"
    },
    {
      "name": "d_onlyTranslation",
      "type": "bool",
      "xmlname": "onlyTranslation",
      "help": "Controlling the DOF only in translation"
    },
    {
      "name": "d_buttonDeviceState",
      "type": "bool",
      "xmlname": "buttonDeviceState",
      "help": "state of ths device button"
    },
    {
      "name": "d_mainDirection",
      "type": "sofa::type::Vec<3, Real>",
      "xmlname": "mainDirection",
      "help": "Main direction and orientation of the controlled DOF"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "onMouseEvent",
      "return_type": "void",
      "params": [
        {
          "name": "mev",
          "type": "core::objectmodel::MouseEvent *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "onBeginAnimationStep",
      "return_type": "void",
      "params": [
        {
          "name": "dt",
          "type": "const double"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMechanicalState",
      "return_type": "core::behavior::MechanicalState<DataTypes> *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::MechanicalState<DataTypes> *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIndex",
      "return_type": "unsigned int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setIndex",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMainDirection",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const sofa::type::Vec<3, Real>"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMainDirection",
      "return_type": "const sofa::type::Vec<3, Real> &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyController",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The MechanicalStateController is a component in the SOFA framework that provides mouse and keyboard user control over a mechanical state, typically representing a rigid body or particle system.",
  "parameters": [
    {
      "name": "index",
      "type": "unsigned int",
      "default_value": "",
      "description": "Index of the controlled degree-of-freedom (DOF) within the mechanical state."
    },
    {
      "name": "onlyTranslation",
      "type": "bool",
      "default_value": "false",
      "description": "Boolean flag indicating whether to control only translational DOFs or both translation and rotation."
    },
    {
      "name": "mainDirection",
      "type": "Vec3f",
      "default_value": "",
      "description": "The main direction corresponding to the vertical mouse axis for controlling the mechanical state."
    }
  ],
  "input_ports": [
    {
      "name": "mechanicalState",
      "type": "MechanicalState",
      "optional": false,
      "description": "The mechanical state to be controlled by this component."
    },
    {
      "name": "mouseEvent",
      "type": "MouseEvent",
      "optional": true,
      "description": "Mouse event input used for user interaction with the controller."
    }
  ],
  "output_ports": [
    {
      "name": "controlledMechanicalState",
      "type": "MechanicalState",
      "description": "The controlled mechanical state after applying transformations according to user inputs and settings."
    }
  ],
  "maths": "The **MechanicalStateController** is a component in the SOFA framework that provides interactive user control over a mechanical state, typically representing rigid bodies or particle systems. It allows for manipulation via mouse and keyboard input to change positions and orientations of controlled degrees of freedom (DOFs). This description focuses on its mathematical and physical contributions to the FEM simulation pipeline.\n\n### Governing Equations and Operators\n- **Position Update**: The component updates the position vector \\(\\mathbf{x}\\) and orientation quaternion \\(\\mathbf{q}\\) based on user input. For a rigid particle, this can be expressed as:\n  \n  - Translation update (for index \\(i\\)):\n    \\[\n    \\mathbf{x}_i = \\mathbf{x}_{i,0} + \\Delta \\mathbf{v}\n    \\]\n    where \\(\n    \\Delta \\mathbf{v}\\) is the displacement vector derived from mouse movements or keyboard input.\n\n  - Orientation update (for index \\(i\\)):\n    \\[\n    \\mathbf{q}_i = \\mathbf{q}_{i,0} \\otimes \\Delta \\mathbf{q}\n    \\]\n    where \\(\n    \\Delta \\mathbf{q}\\) is a quaternion representing the rotation derived from mouse movements.\n\n### Constitutive or Kinematic Laws Involved\n- **Translation Control**: The component can be set to control DOFs only in translation. This ensures that the orientation remains constant while updating the position vector \\(\\mathbf{x}_i\\).\n- **Rotation Control**: If rotation is enabled, it uses quaternion multiplication to update the orientation \\(\\mathbf{q}_i\\). The orientation quaternion \\(\n    \\Delta \\mathbf{q}\\) represents a small incremental rotation around specific axes based on mouse movement.\n\n### Role in the Global FEM Pipeline\n- **Assembly**: The MechanicalStateController does not directly contribute to assembling global matrices like mass matrix \\(M\\), stiffness matrix \\(K\\), or internal force vector \\(\n    f_{int}\\). Instead, it modifies the state vectors \\(\n    \\mathbf{x}\\) and \\(\n    \\mathbf{q}\\) based on user input.\n- **Time Integration**: The component applies its updates at each animation step, effectively modifying the position and orientation states. This is achieved through the `onBeginAnimationStep` method, which calls `applyController` to update positions and orientations.\n- **Nonlinear Solve**: Since it directly modifies \\(\n    \\mathbf{x}\\) and \\(\n    \\mathbf{q}\\), this component does not contribute to the nonlinear solve process in FEM. Instead, its updates are considered as external displacements or rotations that need to be applied.\n- **Linear Solve**: The controller’s actions do not directly influence the linear solve process but can affect the system state, which is then solved using standard linear solvers like Conjugate Gradient (CG).\n\n### Numerical Methods and Discretization Choices\n- **Mouse and Keyboard Interaction**: User input via mouse movements or keyboard commands is discretized into small incremental updates to position \\(\n    \\Delta \\mathbf{v}\\) and orientation \\(\\Delta \\mathbf{q}\\). These updates are applied in a discrete manner at each animation step.\n\n### Integration with the Variational/Lagrangian Mechanics Framework\n- The MechanicalStateController provides an external means to perturb the system’s state directly, bypassing traditional Lagrangian mechanics. This is useful for interactive simulations where user input should have immediate and direct effects on the mechanical system's position and orientation.\n- While it does not contribute to the variational formulation or weak form derivation, its role in updating the state of the system ensures that these states are consistent with the overall simulation framework, including constraints and mappings.",
  "abstract": "The MechanicalStateController provides interactive user control over the mechanical state of rigid bodies or particle systems via mouse and keyboard input, updating positions and orientations based on this input.",
  "sheet": "# MechanicalStateController\n\n## Overview\nMechanicalStateController is a component in the SOFA framework that allows for interactive user control over the mechanical state of rigid bodies or particle systems. It updates positions and orientations based on mouse and keyboard input.\n\n## Mathematical Model\nThe component updates the position vector \\(\\mathbf{x}\\) and orientation quaternion \\(\\mathbf{q}\\) based on user input:\n- Translation update (for index \\(i\\)):\n  \n  \\[\\mathbf{x}_i = \\mathbf{x}_{i,0} + \\Delta \\mathbf{v}\\]\n  where \\(\n  \\Delta \\mathbf{v}\\) is the displacement vector derived from mouse movements or keyboard input.\n\n- Orientation update (for index \\(i\\)):\n  \n  \\[\\mathbf{q}_i = \\mathbf{q}_{i,0} \\otimes \\Delta \\mathbf{q}\\]\n  where \\(\n  \\Delta \\mathbf{q}\\) is a quaternion representing the rotation derived from mouse movements.\n\n## Parameters and Data\n- **index (unsigned int)**: Index of the controlled DOF. Default value not specified.\n- **onlyTranslation (bool)**: Controls whether only translation is allowed. Default value not specified.\n- **buttonDeviceState (bool)**: State of the device button. Default value not specified.\n- **mainDirection (sofa::type::Vec<3, Real>)**: Main direction and orientation of the controlled DOF. Default value not specified.\n\n## Practical Notes\nThe MechanicalStateController updates positions and orientations at each animation step via the `onBeginAnimationStep` method, which calls `applyController`. It does not directly contribute to assembling global matrices or solving nonlinear equations but modifies the state vectors \\(\\mathbf{x}\\) and \\(\\mathbf{q}\\)."
}