{
  "name": "FixedPlaneProjectiveConstraint",
  "main": {
    "name": "FixedPlaneProjectiveConstraint",
    "namespace": "sofa::component::constraint::projective",
    "module": "Sofa.Component.Constraint.Projective",
    "include": "sofa/component/constraint/projective/FixedPlaneProjectiveConstraint.h",
    "doc": "Project particles on a given plane.",
    "inherits": [
      "ProjectiveConstraintSet"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types",
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_direction",
        "type": "Coord",
        "xmlname": "direction",
        "help": "normal direction of the plane"
      },
      {
        "name": "d_dmin",
        "type": "Real",
        "xmlname": "dmin",
        "help": "Minimum plane distance from the origin"
      },
      {
        "name": "d_dmax",
        "type": "Real",
        "xmlname": "dmax",
        "help": "Maximum plane distance from the origin"
      },
      {
        "name": "data",
        "type": "DataTypes"
      }
    ],
    "links": [
      {
        "name": "l_topology",
        "target": "BaseMeshTopology",
        "kind": "single",
        "xmlname": "topology",
        "help": "link to the topology container"
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectResponse",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "resData",
            "type": "DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectVelocity",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "vData",
            "type": "DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectPosition",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "xData",
            "type": "DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "M",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "offset",
            "type": "unsigned int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "projectJacobianMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "cData",
            "type": "DataMatrixDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyConstraint",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "matrix",
            "type": "const MultiMatrixAccessor *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyConstraint",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "vect",
            "type": "BaseVector *"
          },
          {
            "name": "matrix",
            "type": "const MultiMatrixAccessor *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyConstraint",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "sofa::core::behavior::ZeroDirichletCondition *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDirection",
        "return_type": "void",
        "params": [
          {
            "name": "dir",
            "type": "Coord"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "selectVerticesAlongPlane",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDminAndDmax",
        "return_type": "void",
        "params": [
          {
            "name": "_dmin",
            "type": "const Real"
          },
          {
            "name": "_dmax",
            "type": "const Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addConstraint",
        "return_type": "void",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeConstraint",
        "return_type": "void",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isPointInPlane",
        "return_type": "bool",
        "params": [
          {
            "name": "p",
            "type": "const Coord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "Fixed Plane Projective Constraint",
    "description": "The Fixed Plane Projective Constraint is a constraint model in SOFA (Simulation Open-Framework Architecture) that restricts the movement of particles to lie within a defined plane or between two parallel planes. This component is part of the projective constraints set, which means it projects the forces and positions onto a subspace defined by the constraint.",
    "parameters": [
      {
        "name": "d_direction",
        "description": "The normal direction vector of the defining plane.",
        "type": "Coord"
      },
      {
        "name": "d_dmin",
        "description": "Minimum distance from the origin to define one parallel plane when selecting vertices between two planes. Used only if setDminAndDmax is called.",
        "type": "Real"
      },
      {
        "name": "d_dmax",
        "description": "Maximum distance from the origin to define another parallel plane when selecting vertices between two planes. Used only if setDminAndDmax is called.",
        "type": "Real"
      }
    ],
    "methods": [
      {
        "name": "init()",
        "description": "Initializes the constraint, linking it with the topology component and setting up topological changes support."
      },
      {
        "name": "draw(vparams)",
        "description": "Draws the constrained points in the visualization."
      },
      {
        "name": "projectResponse(mparams, resData)",
        "description": "Projects the response onto the plane."
      },
      {
        "name": "projectVelocity(mparams, vData)",
        "description": "Projects the velocity vectors of particles onto the plane."
      },
      {
        "name": "projectPosition(mparams, xData)",
        "description": "Projects the positions of particles onto the plane."
      },
      {
        "name": "setDirection(dir)",
        "description": "Sets the normal direction vector for the plane constraint."
      },
      {
        "name": "selectVerticesAlongPlane()",
        "description": "Selects vertices based on their position relative to the defined plane or planes, adding them as constrained points if they lie within the specified range."
      },
      {
        "name": "setDminAndDmax(dmin, dmax)",
        "description": "Sets the minimum and maximum distances from the origin for defining two parallel planes between which particles will be selected as constrained points."
      },
      {
        "name": "addConstraint(index)",
        "description": "Adds a vertex to the set of constrained points."
      },
      {
        "name": "removeConstraint(index)",
        "description": "Removes a vertex from the set of constrained points."
      }
    ]
  },
  "maths": {
    "maths": "## Mathematical and Physical Description of Fixed Plane Projective Constraint\n\n### Overview\nThe Fixed Plane Projective Constraint is a constraint mechanism designed to restrict the movement of particles within a defined plane or between two parallel planes. This constraint is part of the SOFA (Simulation Open-Framework Architecture) framework, which is widely used for real-time physics simulation and modeling.\n\n### Mathematical Formulation\n\n1. **Constraint Definition**: \nThe plane in question can be mathematically defined using its normal vector \\(\\mathbf{n}\\), which is a unit vector perpendicular to the plane, and an offset value \\(d_0\\). The equation of the plane is given by:\n   \\[\n   \\mathbf{n}^T \\cdot (\\mathbf{p} - \\mathbf{p}_0) = 0\n   \\]\n   where \\(\n   \\\n   mathbf{p}_0\n   \\\n   \\\n   ) is any point on the plane. If we consider a fixed origin, then the offset \\(d_0\\) can be expressed as:\n   \\[\n   d_0 = \\mathbf{n}^T \\cdot \\mathbf{p}_0\n   \\]\n   The equation of the plane becomes:\n   \\[\n   \\mathbf{n}^T \\cdot \\mathbf{p} = d_0\n   \\]\n\n2. **Parallel Planes**: \nThe constraint can also be extended to restrict particles between two parallel planes with offsets \\(d_{\\text{min}}\\) and \\(d_{\\text{max}}\\). The mathematical condition for a point \\(\n   \\\n   mathbf{p}\n   \\\n   \\\n   ) to lie within the region defined by these two planes is:\n   \\[\n   d_{\\text{min}} < \\mathbf{n}^T \\cdot \\mathbf{p} < d_{\\text{max}}\n   \\]\n\n3. **Projection Operation**: \nThe constraint enforces this condition through a projection operation on the particle positions and forces. Given a position vector \\(\n   \\\n   mathbf{x}\n   \\\n   \\\n   ), the projected position \\(\\mathbf{x}^\\prime\\) is computed such that it satisfies the constraint equation. The projection can be formulated as:\n   \\[\n   \\mathbf{x}^\\prime = \\mathbf{x} - (\\mathbf{n}^T \\cdot \\mathbf{x} - d_0) \\cdot \\mathbf{n}\n   \\]\n   This ensures that the projected position \\(\n   \\\n   mathbf{x}^\\prime\n   \\\n   \\\n   ) lies on the defined plane.\n\n4. **Force Projection**: \nThe constraint also projects forces to enforce the movement within the specified plane or region. Given a force vector \\(\\mathbf{f}\\), the projected force \\(\n   \\\n   mathbf{f}^\\prime\n   \\\n   \\\n   ) is computed such that it aligns with the constraint direction:\n   \\[\n   \\mathbf{f}^\\prime = \\mathbf{f} - (\\mathbf{n}^T \\cdot \\mathbf{f}) \\cdot \\mathbf{n}\n   \\]\n\n### Physical Interpretation\n1. **Movement Restriction**: \nThe constraint ensures that the particles are restricted to move along a plane or within a region defined by two parallel planes. This can be used in simulations where certain physical constraints need to be imposed, such as restricting motion of objects to specific surfaces or regions.\n\n2. **Energy Conservation**: \nBy projecting both positions and forces onto the constraint space, the system conserves energy while enforcing the geometric restrictions. The projection operation ensures that any movement violating the plane condition is corrected in a physically consistent manner.\n\n3. **Numerical Stability**: \nThe use of projective constraints helps maintain numerical stability during simulations by ensuring that particles do not move outside the defined regions due to numerical errors or approximations.\n\n### Implementation Details\n- **Initialization**: The constraint can be initialized with specific parameters such as normal vector \\(\n   \\\n   mathbf{n}\n   \\\n   \\\n   ) and offsets \\(d_{\\text{min}}\\) and \\(d_{\\text{max}}\\).\n- **Selection of Vertices**: The system can dynamically select vertices that lie within the defined region, ensuring that only relevant particles are constrained.\n\nThis mathematical formulation provides a robust framework for enforcing geometric constraints in real-time simulations."
  },
  "summary": {
    "abstract": "The `FixedPlaneProjectiveConstraint` projects particles onto a specified plane or between two parallel planes using normal vector and distance parameters.",
    "sheet": "# FixedPlaneProjectiveConstraint\n\n## Mathematical Model\n\nThe constraint enforces that particles lie on a defined plane with normal vector \\(\\mathbf{n}\\) and offset distances \\(d_{\\text{min}}\\) and \\(d_{\\text{max}}\\). The projection operation for position \\(\\mathbf{x}\\) is given by:\n\n\begin{equation}\n    \\mathbf{x}^\\prime = \\mathbf{x} - (\\mathbf{n}^T \\cdot \\mathbf{x} - d_0) \\cdot \\mathbf{n},\n\\end{equation}\nwhere \\(d_0\\) is the offset of the plane. For forces, the projection operation ensures alignment with the constraint direction:\n\n\begin{equation}\n    \\mathbf{f}^\\prime = \\mathbf{f} - (\\mathbf{n}^T \\cdot \\mathbf{f}) \\cdot \\mathbf{n}.\n\\end{equation}\n\n## Parameters and Data\n\n- **direction**: Normal direction of the plane (`Coord` type).\n- **dmin**: Minimum plane distance from the origin (`Real` type).\n- **dmax**: Maximum plane distance from the origin (`Real` type).\n\n## Practical Notes\n\nThe constraint ensures numerical stability by projecting positions and forces onto the defined plane or region, preventing particles from moving outside specified boundaries."
  }
}