Methods

{
  "name": "PickHandler",
  "namespace": "sofa::gui::common",
  "module": "Sofa.GUI.Common",
  "include": "sofa/gui/common/PickHandler.h",
  "doc": "",
  "inherits": [],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "activateRay",
      "return_type": "void",
      "params": [
        {
          "name": "width",
          "type": "int"
        },
        {
          "name": "height",
          "type": "int"
        },
        {
          "name": "root",
          "type": "core::objectmodel::BaseNode *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "deactivateRay",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "allocateSelectionBuffer",
      "return_type": "void",
      "params": [
        {
          "name": "width",
          "type": "int"
        },
        {
          "name": "height",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "destroySelectionBuffer",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setPickingMethod",
      "return_type": "void",
      "params": [
        {
          "name": "method",
          "type": "PickingMethod"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "useSelectionBufferMethod",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateRay",
      "return_type": "void",
      "params": [
        {
          "name": "position",
          "type": "const sofa::type::Vec3 &"
        },
        {
          "name": "orientation",
          "type": "const sofa::type::Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleMouseEvent",
      "return_type": "void",
      "params": [
        {
          "name": "status",
          "type": "MOUSE_STATUS"
        },
        {
          "name": "button",
          "type": "MOUSE_BUTTON"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [
        {
          "name": "root",
          "type": "core::objectmodel::BaseNode *"
        }
      ],
      "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": "unload",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setColourRenderCallback",
      "return_type": "void",
      "params": [
        {
          "name": "colourRender",
          "type": "CallBackRender *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateMouse2D",
      "return_type": "void",
      "params": [
        {
          "name": "mouse",
          "type": "MousePosition"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getOperation",
      "return_type": "Operation *",
      "params": [
        {
          "name": "button",
          "type": "MOUSE_BUTTON"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "changeOperation",
      "return_type": "Operation *",
      "params": [
        {
          "name": "setting",
          "type": "sofa::component::setting::MouseButtonSetting *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "changeOperation",
      "return_type": "Operation *",
      "params": [
        {
          "name": "button",
          "type": "MOUSE_BUTTON"
        },
        {
          "name": "op",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addCallBack",
      "return_type": "void",
      "params": [
        {
          "name": "c",
          "type": "CallBackPicker *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCallBackPicker",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clearCallBacks",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findCollisionUsingBruteForce",
      "return_type": "BodyPicked",
      "params": [
        {
          "name": "origin",
          "type": "const type::Vec3 &"
        },
        {
          "name": "direction",
          "type": "const type::Vec3 &"
        },
        {
          "name": "maxLength",
          "type": "double"
        },
        {
          "name": "root",
          "type": "core::objectmodel::BaseNode *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "findCollisionUsingColourCoding",
      "return_type": "BodyPicked",
      "params": [
        {
          "name": "origin",
          "type": "const type::Vec3 &"
        },
        {
          "name": "direction",
          "type": "const type::Vec3 &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getInteraction",
      "return_type": "ComponentMouseInteraction *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getLastPicked",
      "return_type": "BodyPicked *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findCollision",
      "return_type": "BodyPicked",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findCollisionUsingPipeline",
      "return_type": "BodyPicked",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findCollisionUsingBruteForce",
      "return_type": "BodyPicked",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findCollisionUsingColourCoding",
      "return_type": "BodyPicked",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "needToCastRay",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "setCompatibleInteractor",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `PickHandler` component in the SOFA framework is designed to manage mouse interactions for picking and manipulating objects within the simulation scene. It handles ray-casting and selection buffer methods for detecting collisions between the mouse cursor and objects, enabling interactive user operations such as dragging or selecting elements.\n\n### Role and Purpose:\nThe `PickHandler` manages various aspects of user interaction with the simulated environment, including initializing a dedicated node to handle mouse interactions, updating the position and orientation of a ray that represents the mouse pointer, and finding collisions based on different methods (ray-casting or color coding). It also manages operations tied to specific mouse buttons, allowing custom behavior for each type of interaction.\n\n### Interactions with Other Components:\nThe `PickHandler` interacts with other SOFA components through its API. For instance:\n- **Mechanical Objects and Collision Models:** The component uses collision models (`MouseCollisionModel`) to detect collisions between the ray and objects in the scene, and it updates the mechanical state of objects based on user input.\n- **Node Management:** It interacts with `BaseNode` for initializing and managing a dedicated node for mouse interactions within the simulation's scenegraph hierarchy.\n- **Callbacks:** It provides mechanisms to register callback functions (`CallBackPicker`, `CallBackRender`) that can be triggered when specific events occur, such as picking an object or rendering color-coded collision results.\n\n### Practical Usage Guidance:\nThe `PickHandler` is typically used in the context of interactive simulations where user input is required. Methods like `init`, `activateRay`, and `deactivateRay` are called to set up and control mouse interaction within a scene. The component supports changing picking methods (e.g., ray-casting or selection buffer) via `setPickingMethod`. Interactions can be customized by setting specific operations for different mouse buttons using the `changeOperation` method.\n\n### Data Fields:\nThe component maintains data fields such as `mouseNode`, which is a dedicated node in the simulation scene for handling mouse interactions, and `lastPicked`, which stores information about the most recent collision detected. Additionally, it manages callback lists (`callbacks`) and operation mappings (`operations`).",
  "maths": "<maths_md_description>\nThe `PickHandler` component in the SOFA framework is primarily focused on managing interactive mouse operations within the simulation scene. It does not directly contribute to any governing equations or operators such as mass matrix (\\(M\"]), stiffness matrix (\\(K\")), internal force (\\(f_{int}\"), residual (\\(R\")), etc., which are typical in FEM simulations. Instead, its role is more focused on providing a mechanism for user interaction and collision detection between the mouse cursor (represented by a ray) and objects within the scene.\n\n### Role in the Global FEM Pipeline:\nThe `PickHandler` operates at a higher level of abstraction and does not directly participate in any core numerical or physical computations typical to an FEM simulation pipeline. It is primarily involved in handling user input, managing mouse interactions, and detecting collisions with objects within the scene. This makes it more of an I/O and interaction component rather than a computational one.\n\n### Constitutive or Kinematic Laws:\nThe `PickHandler` does not implement any constitutive laws, stress-strain relationships, or kinematic equations as these are handled by other components in SOFA, such as the mechanical models and solvers. Instead, it uses collision detection methods to determine if a ray (representing the mouse) intersects with objects in the scene.\n\n### Numerical Methods or Discretization Choices:\nThe `PickHandler` does not implement any FEM-specific discretization schemes like finite elements, shape functions, or numerical integration techniques. However, it does use different collision detection methods, such as ray-casting and color coding, to determine if a mouse interaction has occurred.\n\n### Variational / Lagrangian Mechanics Framework:\nThe `PickHandler` is not directly related to the variational or Lagrangian mechanics framework used in FEM simulations. It serves an auxiliary role by providing interactive capabilities that can be leveraged during the simulation for user interactions such as picking objects, but it does not influence the core mechanical behavior of the system.\n\n### Summary:\nThe `PickHandler` is a utility component designed to handle mouse interactions and detect collisions within the SOFA framework. It operates outside the typical FEM computational pipeline and focuses on providing a means for interactive user input in simulations. This makes it less relevant from a mathematical or physical standpoint, but crucial for interactive applications.\n</maths_md_description>",
  "abstract": "The `PickHandler` manages mouse interactions for picking and manipulating objects within the SOFA simulation scene by handling ray-casting, selection buffer methods, and collision detection.",
  "sheet": "\n# PickHandler\n\n## Overview\nThe `PickHandler` component in the SOFA framework is designed to manage mouse interactions for picking and manipulating objects within the simulation scene. It handles ray-casting and selection buffer methods for detecting collisions between the mouse cursor and objects, enabling interactive user operations such as dragging or selecting elements.\n\n## Parameters and Data\n- **mouseNode**: A dedicated node in the simulation scene for handling mouse interactions.\n- **lastPicked**: Stores information about the most recent collision detected.\n- **callbacks**: List of callback functions that can be triggered when specific events occur, such as picking an object or rendering color-coded collision results.\n\n## Dependencies and Connections\nThe `PickHandler` interacts with other SOFA components through its API. For instance:\n- **Mechanical Objects and Collision Models:** The component uses collision models (`MouseCollisionModel`) to detect collisions between the ray and objects in the scene, and it updates the mechanical state of objects based on user input.\n- **Node Management:** It interacts with `BaseNode` for initializing and managing a dedicated node for mouse interactions within the simulation's scenegraph hierarchy.\n\n## Practical Notes\nThe `PickHandler` is typically used in interactive simulations where user input is required. Methods like `init`, `activateRay`, and `deactivateRay` are called to set up and control mouse interaction within a scene. The component supports changing picking methods (e.g., ray-casting or selection buffer) via `setPickingMethod`. Interactions can be customized by setting specific operations for different mouse buttons using the `changeOperation` method."
}