{
  "name": "ColourPickingVisitor",
  "main": {
    "name": "ColourPickingVisitor",
    "namespace": "sofa::gui::common",
    "module": "Sofa.GUI.Common",
    "include": "sofa/gui/common/ColourPickingVisitor.h",
    "doc": "",
    "inherits": [
      "Visitor"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "drawColourPicking",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const ColourCode"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "processCollisionModel",
        "return_type": "void",
        "params": [
          {
            "name": "node",
            "type": "simulation::Node *"
          },
          {
            "name": "",
            "type": "core::CollisionModel *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "processNodeTopDown",
        "return_type": "Result",
        "params": [
          {
            "name": "node",
            "type": "simulation::Node *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getCategoryName",
        "return_type": "const char *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `ColourPickingVisitor` is part of the SOFA GUI ecosystem and extends the `simulation::Visitor` class to facilitate colour-based picking in collision models. It is used for rendering collision models with specific RGB colour codes, which helps in identifying these models within the graphical user interface (GUI). The component supports two encoding methods: one that encodes the object's collision model and element index via colour channels, and another that encodes relative positions using barycentric weights.\n\n### Interactions with Other SOFA Components:\n- **Simulation Node**: It processes each node to find and handle collision models within the scene.\n- **Collision Models**: It interacts specifically with `TriangleCollisionModel` and `SphereCollisionModel`, rendering them with appropriate colour codes for picking purposes.\n- **GUI PickHandler**: The colour encoding is used by the GUI's pick handler to identify which object has been selected.\n\n### Practical Usage Guidance:\n- The component takes a visual parameters (`core::visual::VisualParams`) object and an encoding method (`ColourCode`), indicating how colours should be encoded (either as collision elements or relative positions).\n- It processes each collision model found within the simulation nodes, rendering them with colour codes that can later be used to identify specific elements in the scene. The `drawColourPicking` method is virtual and needs to be implemented for custom use cases.\n- Methods like `processCollisionModel`, `processTriangleModel`, and `processSphereModel` handle the rendering details for different types of collision models."
  },
  "maths": {
    "maths": "<p>The <code>ColourPickingVisitor</code> is a component in the SOFA framework that facilitates color-based picking by rendering collision models with specific RGB colour codes. This allows for the identification and selection of objects within the graphical user interface (GUI). The mathematical description involves two main encoding methods:</p>\n\n<h2 id=\"encoding-methods\">Encoding Methods</h2>\n\n<p><strong>1. Encoding Collision Elements:</strong></p>\n\n<ul>\n<li>This method encodes collision elements using colour channels to identify the model and element index.</li>\n<li>To achieve this, each triangle (in a <code>TriangleCollisionModel</code>) is assigned a unique color based on its position in the list of all triangles. The red channel encodes the index of the collision model in the scene, while the green channel encodes the index of the specific element within that model.</li>\n<li><em>Mathematical Representation:</em></li>\n<li>Let <code>r</code> be the normalized index of the collision model (i.e., <code>r = indexCollisionModel / totalCollisionModels</code>) and <code>g</code> be the normalized index of the element within that model (i.e., <code>g = indexElementWithinModel / sizeOfModel</code>). The color for each triangle is then defined as:</li>\n<li><code>C(r, g) = [r, g, 0]</code>, where <code>r, g ∈ [0,1]</code>.</li>\n</ul>\n\n<p><strong>2. Encoding Relative Positions:</strong></p>\n\n<ul>\n<li>This method encodes the relative positions of vertices in a triangle using barycentric coordinates.</li>\n<li>Barycentric coordinates <code>(α, β, γ)</code> are used to represent each vertex in a triangle as a weighted sum of its three vertices: <code>P = α * P1 + β * P2 + γ * P3</code>.</li>\n<li>The color channels (red, green, blue) are mapped to the barycentric coordinates <code>(α, β, γ)</code>, with each vertex being assigned a unique color:</li>\n<li><code>C(α, β, γ) = [1,0,0], [0,1,0], [0,0,1]</code> for vertices P1, P2, and P3 respectively.</li>\n</ul>\n\n<h2 id=\"collision-model-rendering\">Collision Model Rendering</h2>\n\n<p>The <code>ColourPickingVisitor</code> processes each collision model found within the simulation nodes:</p>\n\n<ul>\n<li><em>Triangles (Triangle Collision Models):</em></li>\n<li>For each triangle, it computes the barycentric coordinates and assigns colors based on the selected encoding method.</li>\n<li>The rendered triangles are then passed to OpenGL for drawing with specific color codes that can be later used by the GUI's pick handler to identify elements in the scene.</li>\n</ul>\n\n<ul>\n<li><em>Spheres (Sphere Collision Models):</em></li>\n<li>For spheres, it encodes only the index of the collision model if the encoding method is set for relative positions. If not, it renders each sphere with a unique color based on its position in the list.</li>\n</ul>"
  },
  "summary": {
    "abstract": "The `ColourPickingVisitor` facilitates colour-based picking by rendering collision models with unique RGB codes to identify objects in the GUI.",
    "sheet": "# ColourPickingVisitor\n\n## Overview\n\nThe `ColourPickingVisitor` is a component of the SOFA GUI ecosystem that extends the `simulation::Visitor` class. It processes each node and its collision models, rendering them with specific colour codes for picking purposes within the graphical user interface (GUI). The component supports two encoding methods: one encodes the object's collision model and element index via colour channels, while another encodes relative positions using barycentric weights.\n\n## Parameters and Data\n\nThe `ColourPickingVisitor` does not expose any significant data fields. Its functionality is driven by its methods and the parameters passed to these methods during execution.\n\n## Dependencies and Connections\n\n- **Simulation Node**: It processes each node to find and handle collision models within the scene.\n- **Collision Models**: Specifically interacts with `TriangleCollisionModel` and `SphereCollisionModel`, rendering them with appropriate colour codes for picking purposes.\n- **GUI PickHandler**: The colour encoding is used by the GUI's pick handler to identify which object has been selected."
  }
}