{
  "name": "ForceFeedback",
  "main": {
    "name": "ForceFeedback",
    "namespace": "sofa::component::haptics",
    "module": "Sofa.Component.Haptics",
    "include": "sofa/component/haptics/ForceFeedback.h",
    "doc": "Base class implementing forcefeedback as a force field",
    "inherits": [],
    "templates": [],
    "data_fields": [
      {
        "name": "d_activate",
        "type": "bool",
        "xmlname": "activate",
        "help": "boolean to activate or deactivate the forcefeedback"
      },
      {
        "name": "d_indice",
        "type": "int",
        "xmlname": "indice",
        "help": "Tool indice in the OmniDriver"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeForce",
        "return_type": "void",
        "params": [
          {
            "name": "x",
            "type": "SReal"
          },
          {
            "name": "y",
            "type": "SReal"
          },
          {
            "name": "z",
            "type": "SReal"
          },
          {
            "name": "u",
            "type": "SReal"
          },
          {
            "name": "v",
            "type": "SReal"
          },
          {
            "name": "w",
            "type": "SReal"
          },
          {
            "name": "q",
            "type": "SReal"
          },
          {
            "name": "fx",
            "type": "SReal &"
          },
          {
            "name": "fy",
            "type": "SReal &"
          },
          {
            "name": "fz",
            "type": "SReal &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeWrench",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const sofa::type::Transform<SReal> &"
          },
          {
            "name": "",
            "type": "const sofa::type::SpatialVector<SReal> &"
          },
          {
            "name": "",
            "type": "sofa::type::SpatialVector<SReal> &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setReferencePosition",
        "return_type": "void",
        "params": [
          {
            "name": "referencePosition",
            "type": "sofa::type::Transform<SReal> &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isEnabled",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setLock",
        "return_type": "void",
        "params": [
          {
            "name": "value",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `ForceFeedback` class is part of the SOFA framework's haptics module and serves as an abstract base class for implementing force feedback in simulations. Its primary role is to act as a controller that can apply forces based on user input from haptic devices, such as the OmniDriver.\n\n### Role and Purpose\n- **Base Class:** It provides the foundational structure for force feedback mechanisms within SOFA's simulation environment. This base class must be subclassed by specific implementations that define how the force feedback is computed and applied.\n\n### Interactions with Other Components\n- **Inheritance:** `ForceFeedback` inherits from `core::behavior::BaseController`, which likely provides it with necessary methods for integration into the SOFA scene graph architecture. \n- **Context Interaction:** The class maintains a pointer to its context (`simulation::Node *context`) and initializes this context in the `init()` method.\n\n### Data Fields\n- **Activate Flag:** A boolean flag (`d_activate`) to enable or disable force feedback.\n- **Tool Indice:** An integer field (`d_indice`) representing the index of a tool within an OmniDriver, indicating which specific haptic device input is being processed.\n\n### Practical Usage Guidance\n- **Subclassing:** Users must subclass `ForceFeedback` and implement pure virtual methods such as `computeForce()` and `computeWrench()`, defining how forces are computed based on user interactions with the haptic devices.\n- **Configuration:** The `activate` field allows users to dynamically enable or disable force feedback during simulation runtime. Similarly, the `indice` field can be configured for different tools in a multi-device setup."
  },
  "maths": {
    "maths": "The `ForceFeedback` class in the SOFA framework's haptics module serves as an abstract base class for implementing force feedback mechanisms within simulations. It acts primarily as a controller that can apply forces based on user input from haptic devices, such as the OmniDriver.\n\n### Role and Mathematical Description\n- **Base Class:** `ForceFeedback` provides foundational methods and structure required by subclasses to compute and apply force feedback in real-time simulations. The abstract nature of this class means it does not define concrete computational behavior; instead, specific implementations must be provided by subclasses that inherit from `ForceFeedback`. \n\n### Pure Virtual Methods for Force Calculation\n- **computeForce Method:** This pure virtual method is defined to compute the Cartesian force components `(fx, fy, fz)` based on user input coordinates `(x, y, z)`, orientation angles `(u, v, w)`, and quaternion `q` representing rotation. The exact mathematical relationship between these inputs and output forces depends on the specific subclass implementation.\n\n- **computeWrench Method:** Another pure virtual method that computes spatial wrenches (a combination of force and torque). This involves transforming input vectors into a reference frame using the provided transformation matrix (`Transform<SReal>`), resulting in a spatial vector representing both force and torque components. The exact mathematical operations involved are determined by subclasses.\n\n### Data Fields for Configuration and Control\n- **Activate Flag:** A boolean flag `d_activate` allows runtime enabling or disabling of force feedback, offering dynamic control over whether haptic interactions influence the simulation.\n\n- **Tool Indice:** An integer field `d_indice` specifies which specific haptic device's input is being processed by this controller. This field helps in multi-device setups where multiple tools are used simultaneously.\n\n### Integration with SOFA Scene Graph Architecture\nThe class inherits from `core::behavior::BaseController`, integrating seamlessly into the SOFA simulation environment. It maintains a pointer to its context (`simulation::Node *context`), allowing it to interact with other components within the scene graph architecture.\n\n### Practical Usage in Simulations\nUsers are expected to subclass `ForceFeedback` and implement the pure virtual methods according to their specific application needs. For instance, if simulating surgical tools interacting with soft tissues, a subclass might compute forces based on tissue deformation models and user input from haptic devices. The `setReferencePosition` method could be used to set a reference position for force feedback calculations in cases where positional changes need to be accounted for.\n\n### Conclusion\nThe `ForceFeedback` class provides the necessary abstract structure and methods required for implementing real-time force feedback within SOFA simulations. By defining pure virtual methods, it enforces that subclasses provide concrete mathematical formulations for computing forces and wrenches based on haptic device input."
  },
  "summary": {
    "abstract": "The `ForceFeedback` component serves as an abstract base class for implementing force feedback in SOFA simulations, providing methods for computing forces and wrenches based on user input from haptic devices.",
    "sheet": "# ForceFeedback\n\n## Overview\n\nThe `ForceFeedback` class is an abstract base class within the SOFA framework's haptics module. It provides foundational structure and methods required by subclasses to compute and apply force feedback in real-time simulations based on user interactions with haptic devices.\n\n## Parameters and Data\n\n- **d_activate**: A boolean flag (`bool`) that enables or disables the force feedback mechanism. Default value is not specified, but it can be configured dynamically during runtime.\n- **d_indice**: An integer field (`int`) representing the index of a tool within an OmniDriver, indicating which specific haptic device input is being processed. This allows for configuration in multi-device setups where multiple tools are used simultaneously.\n\n## Practical Notes\n\nUsers must subclass `ForceFeedback` and implement pure virtual methods such as `computeForce()` and `computeWrench()`, defining how forces are computed based on user interactions with the haptic devices. The `activate` field allows users to dynamically enable or disable force feedback during simulation runtime, providing flexibility in controlling haptic interactions."
  }
}