{
  "name": "ClipPlane",
  "main": {
    "name": "ClipPlane",
    "namespace": "sofa::gl::component::rendering3d",
    "module": "Sofa.GL.Component.Rendering3D",
    "include": "sofa/gl/component/rendering3d/ClipPlane.h",
    "doc": "Define arbitrary clipping plane into OpenGL.",
    "inherits": [
      "VisualModel"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "position",
        "type": "sofa::type::Vec3",
        "xmlname": "position",
        "help": "Point crossed by the clipping plane"
      },
      {
        "name": "normal",
        "type": "sofa::type::Vec3",
        "xmlname": "normal",
        "help": "Normal of the clipping plane, pointing toward the clipped region"
      },
      {
        "name": "id",
        "type": "int",
        "xmlname": "id",
        "help": "Clipping plane OpenGL ID"
      },
      {
        "name": "active",
        "type": "bool",
        "xmlname": "active",
        "help": "Control whether the clipping plane should be applied or not"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "checkDataValues",
        "return_type": "sofa::core::objectmodel::ComponentState",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "reinit",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "fwdDraw",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "core::visual::VisualParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "bwdDraw",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "core::visual::VisualParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The **ClipPlane** is a component in the SOFA framework that defines an arbitrary clipping plane for OpenGL rendering, allowing users to visually slice or clip parts of a 3D scene. It inherits from `VisualModel` and is part of the `Sofa.GL.Component.Rendering3D` module.\n\n### Role and Purpose\nThe primary role of **ClipPlane** is to enhance visual clarity by enabling selective clipping in OpenGL scenes, which can be particularly useful for medical simulations where internal structures need to be examined.\n\n### Interactions with Other Components\n- **VisualModel**: The `ClipPlane` inherits from this class, meaning it integrates seamlessly within the visualization pipeline of SOFA. It interacts with other visual components and models through the `fwdDraw` and `bwdDraw` methods which handle forward and backward drawing operations.\n- **OpenGL Integration**: By setting up OpenGL clipping planes, `ClipPlane` communicates directly with the graphics card to apply real-time clipping effects during rendering.\n\n### Practical Usage Guidance\n- **Data Fields**:\n  - `position`: Specifies a point crossed by the clipping plane (type: `sofa::type::Vec3`).\n  - `normal`: Represents the normal vector of the clipping plane, pointing towards the region that will be clipped out (type: `sofa::type::Vec3`).\n  - `id`: An OpenGL ID associated with this particular clipping plane (type: `int`).\n  - `active`: A boolean flag to control whether the clipping effect should be active or not (type: `bool`).\n\n### Methods\n- **checkDataValues**: Ensures that the data fields are valid.\n- **init** and **reinit**: Initialization methods for setting up the component.\n- **fwdDraw** and **bwdDraw**: Handle drawing operations in forward and backward passes, respectively."
  },
  "maths": {
    "maths": "The **ClipPlane** is a component within the SOFA framework designed to define an arbitrary clipping plane in OpenGL for visual rendering purposes. It serves as a tool to enhance visual clarity by selectively slicing or clipping parts of a 3D scene, which can be particularly useful for medical simulations where internal structures need detailed examination.\n\n### Governing Equations and Operators\nThe **ClipPlane** does not directly contribute to the governing equations typically associated with FEM simulation (e.g., mass matrix M, stiffness matrix K, or internal force $f_{\text{int}}$). Instead, it operates at the level of OpenGL rendering by defining a clipping plane equation that determines which parts of the 3D scene are rendered and which are not. The plane is defined by its normal vector $\\mathbf{n}$ and a point $\\mathbf{p}_0$ on the plane. The equation for this plane in the global coordinate system can be written as:\n\n\begin{equation}\n\\mathbf{n} \\cdot (\\mathbf{x} - \\mathbf{p}_0) = 0,\n\\end{equation}\nwhere $\\mathbf{x}$ is any point on the plane. Any point $\\mathbf{x}$ in space that satisfies this equation lies on the clipping plane, while points not satisfying it are either on one side of the plane or the other.\n\n### Constitutive and Kinematic Laws\nThe **ClipPlane** does not involve constitutive or kinematic laws typically associated with FEM. It operates purely at a rendering level by applying OpenGL clipping planes to selectively hide parts of the scene based on user-defined parameters (position and normal).\n\n### Role in Global FEM Pipeline\nIn terms of the global FEM pipeline, **ClipPlane** does not contribute directly to the assembly, time integration, nonlinear solve, linear solve, constraint handling, or mapping. Instead, it functions as a post-processing tool that enhances visual clarity by selectively clipping parts of the rendered 3D scene.\n\n### Numerical Methods and Discretization Choices\nThe **ClipPlane** leverages OpenGL's built-in support for clipping planes to perform real-time rendering operations. It does not employ any numerical methods or discretizations typically associated with FEM. The primary discretization choices are related to the OpenGL rendering pipeline, such as setting up the plane parameters (position and normal) that determine which parts of the scene will be visible.\n\n### Variational / Lagrangian Mechanics Framework\nThe **ClipPlane** does not fit into the broader variational or Lagrangian mechanics framework associated with FEM simulation. It operates at a purely visual level, enhancing the user's ability to interactively examine different aspects of the 3D scene by selectively clipping regions."
  },
  "summary": {
    "abstract": "ClipPlane defines an arbitrary clipping plane in OpenGL to selectively clip parts of a 3D scene for enhanced visual clarity.",
    "sheet": "# ClipPlane\n\n**Overview:**\nClipPlane is a rendering component that defines an arbitrary clipping plane in OpenGL. It inherits from `VisualModel` and integrates into the visualization pipeline by controlling which parts of the 3D scene are rendered.\n\n**Parameters and Data:*\n- **position**: Specifies a point crossed by the clipping plane (type: `sofa::type::Vec3`).\n- **normal**: Represents the normal vector of the clipping plane, pointing towards the region that will be clipped out (type: `sofa::type::Vec3`).\n- **id**: An OpenGL ID associated with this particular clipping plane (type: `int`).\n- **active**: A boolean flag to control whether the clipping effect should be active or not (type: `bool`).\n\n**Dependencies and Connections:**\nClipPlane inherits from `VisualModel` and interacts with other visual components through drawing methods (`fwdDraw`, `bwdDraw`). It communicates directly with OpenGL for real-time rendering operations.\n\n**Practical Notes:**\nThe clipping plane equation is defined by its normal vector \\(\\mathbf{n}\\) and a point \\(\\mathbf{p}_0\\) on the plane. The equation can be written as: \n\\[\\mathbf{n} \\cdot (\\mathbf{x} - \\mathbf{p}_0) = 0,\\]\nwhere \\(\\mathbf{x}\\) is any point in space. Points satisfying this equation lie on the clipping plane; others are either visible or clipped based on their position relative to the normal vector."
  }
}