{
  "name": "ConicalForceField",
  "main": {
    "name": "ConicalForceField",
    "namespace": "sofa::component::mechanicalload",
    "module": "Sofa.Component.MechanicalLoad",
    "include": "sofa/component/mechanicalload/ConicalForceField.h",
    "doc": "Outward repulsion applied by a cone geometry.",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "data",
        "type": "DataTypes"
      },
      {
        "name": "coneCenter",
        "type": "Coord",
        "xmlname": "coneCenter",
        "help": "cone center"
      },
      {
        "name": "coneHeight",
        "type": "Coord",
        "xmlname": "coneHeight",
        "help": "cone height"
      },
      {
        "name": "coneAngle",
        "type": "Real",
        "xmlname": "coneAngle",
        "help": "cone angle"
      },
      {
        "name": "stiffness",
        "type": "Real",
        "xmlname": "stiffness",
        "help": "force stiffness"
      },
      {
        "name": "damping",
        "type": "Real",
        "xmlname": "damping",
        "help": "force damping"
      },
      {
        "name": "color",
        "type": "sofa::type::RGBAColor",
        "xmlname": "color",
        "help": "cone color. (default=0.0,0.0,0.0,1.0,1.0)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "setCone",
        "return_type": "void",
        "params": [
          {
            "name": "center",
            "type": "const Coord &"
          },
          {
            "name": "height",
            "type": "Coord"
          },
          {
            "name": "angle",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setStiffness",
        "return_type": "void",
        "params": [
          {
            "name": "stiff",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDamping",
        "return_type": "void",
        "params": [
          {
            "name": "damp",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "dataF",
            "type": "DataVecDeriv &"
          },
          {
            "name": "dataX",
            "type": "const DataVecCoord &"
          },
          {
            "name": "dataV",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addDForce",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "datadF",
            "type": "DataVecDeriv &"
          },
          {
            "name": "datadX",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "core::behavior::StiffnessMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildDampingMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "core::behavior::DampingMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateStiffness",
        "return_type": "void",
        "params": [
          {
            "name": "x",
            "type": "const VecCoord &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isIn",
        "return_type": "bool",
        "params": [
          {
            "name": "p",
            "type": "Coord"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "title": "Conical Force Field Component",
    "description": "The Conical Force Field is a force field in the SOFA physics engine that applies outward repulsion based on a cone geometry. This component can be used to model forces emanating from or acting against a conical shape, which can be useful for simulating scenarios where objects are influenced by a conically-shaped boundary or region.\n\n### Key Features and Functionality:\n- **Cone Geometry**: The force field is defined based on a cone with user-defined center position (`coneCenter`), height direction and magnitude (`coneHeight`), and apex angle (`coneAngle`).\n- **Force Parameters**: Users can set the stiffness and damping coefficients of the repulsive forces applied by the cone.\n- **Visualization**: The component provides a method to visualize the cone geometry using a specified color for visualization purposes within the simulation environment.\n- **Contact Points Management**: It maintains an internal list (`contacts`) of points where interactions with the force field occur, each storing an index, normal vector, and position.\n- **Interaction Methods**: Provides methods such as `addForce` and `addDForce` to calculate and apply forces to particles within the simulation. Additionally, it implements `buildStiffnessMatrix` for stiffness matrix calculation relevant to the force field's influence.\n\n### Usage:\nThe Conical Force Field is particularly useful in simulations where objects need to be influenced or repelled by a conically-shaped boundary, such as simulating wind forces emanating from a cone or modeling how particles interact with funnel-like shapes. The ability to set stiffness and damping allows for customization of the force field's behavior depending on specific simulation requirements.\n\n### Customization:\nThe component is templated (`ConicalForceField<DataTypes>`) to allow its usage with different data types, such as 3D vector types, enabling flexibility in how positions and forces are represented within the SOFA framework. Additionally, it can be extended by overriding the `ConicalForceFieldInternalData` class for additional storage or specialized behavior.",
    "parameters": [
      {
        "name": "coneCenter",
        "description": "The center position of the cone's base from which the repulsive force emanates.",
        "type": "Coord"
      },
      {
        "name": "coneHeight",
        "description": "Direction and magnitude vector representing the height of the cone, defining its orientation and length.",
        "type": "Coord"
      },
      {
        "name": "coneAngle",
        "description": "The apex angle of the cone in degrees which defines how wide the repulsive area is.",
        "type": "Real"
      },
      {
        "name": "stiffness",
        "description": "Coefficient that determines the strength or intensity of the repulsion force applied by the cone.",
        "type": "Real"
      },
      {
        "name": "damping",
        "description": "Damping coefficient which influences how quickly the effect of the force diminishes over time or distance.",
        "type": "Real"
      },
      {
        "name": "color",
        "description": "Color used for visualizing the cone geometry in the simulation environment. (default: 0.0, 0.0, 0.0, 1.0)",
        "type": "RGBAColor"
      }
    ],
    "methods": [
      {
        "name": "setCone",
        "description": "Sets the center position, height vector and apex angle of the cone.",
        "parameters": [
          {
            "name": "center",
            "type": "Coord"
          },
          {
            "name": "height",
            "type": "Coord"
          },
          {
            "name": "angle",
            "type": "Real"
          }
        ]
      },
      {
        "name": "setStiffness",
        "description": "Changes the stiffness coefficient which defines how strong the repulsion force is.",
        "parameters": [
          {
            "name": "stiff",
            "type": "Real"
          }
        ]
      },
      {
        "name": "setDamping",
        "description": "Modifies the damping coefficient to control how quickly or slowly the effects of the force field diminish.",
        "parameters": [
          {
            "name": "damp",
            "type": "Real"
          }
        ]
      }
    ]
  },
  "maths": {
    "maths": "### Mathematical Description of Conical Force Field\n\n#### Geometry Definition:\n- **Cone Center:** The center of the cone is defined by a position vector \\( C = (x_c, y_c, z_c) \\).\n- **Cone Height and Apex Angle:** The height direction of the cone is given by a unit vector \\( \textbf{h} \\). The apex angle \\(\theta\\) defines the spread of the cone.\n\n#### Interaction with Particles:\nThe force field interacts with particles within its geometry, applying repulsive forces. Consider a particle at position \\(\textbf{p}\\).\n\n1. **Distance Calculation:** Compute the vector from the center of the cone to the particle's position, \\( \textbf{r} = \textbf{p} - C \\). The distance is given by:\n   \\[ d = |\textbf{r}| \\]\n2. **Projection onto Cone Axis:** Find the projection of \\(\textbf{r}\\) along the cone's height vector, \\( \textbf{h} \\):\n   \\[ h_{proj} = (\textbf{r} \bullet \textbf{h}) \textbf{h} \\]\n3. **Radial Distance:** The radial distance from the axis of the cone to the particle is given by:\n   \\[ r_{rad} = |\textbf{r} - h_{proj}| \\]\n4. **Condition for Interaction: If the radial distance and height projection satisfy the cone's geometry, i.e.,\n   \\[ \tan(\theta/2) \times |h_{proj}| > r_{rad}, \\] then the particle is within the cone.\n\n#### Force Calculation:\n- **Repulsion Force:** When a particle is inside the cone, a repulsive force is applied to push it out. The direction of this force can be along the normal vector at the point of interaction on the conical surface or along the radial distance from the axis.\n- **Normal Vector:** The normal vector \\(\textbf{n}\\) at the particle's position relative to the cone’s surface can be approximated as:\n   \\[ \textbf{n} = \frac{\textbf{r}}{d} - \tan(\theta/2) \times \frac{h_{proj}}{|h_{proj}|^2} \\]\n- **Force Magnitude:** The magnitude of the force is influenced by stiffness and damping coefficients, denoted as \\( k_s \\) (stiffness) and \\( k_d \\) (damping). Assuming a velocity vector \\(\textbf{v}\\), the total repulsive force can be written as:\n   \\[ \textbf{F} = -k_s (\textbf{r}_{proj}) \times \textbf{n} - k_d |\textbf{v}| \\]\n\n#### Visualization:\nThe cone geometry is visualized using a specified color. The visualization method provides an intuitive representation of the force field’s influence area.\n\n#### Contact Points Management:\n- **Contact List:** The component maintains an internal list (`contacts`) containing indices, normal vectors, and positions where interactions with the force field occur.\n- **Contact Calculation:** Each contact point is calculated based on particle position and cone geometry constraints.\n\n### Summary:\nThe Conical Force Field applies repulsive forces to particles within a defined conical region. The interaction forces are computed based on the geometric relationship between particles and the cone, with stiffness and damping parameters influencing their magnitude. This component provides both physical interactions and visualization capabilities for simulations involving conically-shaped boundaries or regions."
  },
  "summary": {
    "abstract": "The ConicalForceField applies outward repulsive forces based on a conical geometry defined by its center, height, angle, stiffness, and damping parameters.",
    "sheet": "# ConicalForceField\n\n## Overview\nThe ConicalForceField is a force field in the SOFA framework that applies outward repulsion to particles within a specified conical region. It inherits from `ForceField` and operates by defining a cone geometry with user-specified center, height, angle, stiffness, and damping parameters.\n\n## Mathematical Model\n### Geometry Definition\n- **Cone Center:** The center of the cone is defined by a position vector \\( C = (x_c, y_c, z_c) \\).\n- **Cone Height and Apex Angle:** The height direction of the cone is given by a unit vector \\( \\mathbf{h} \\). The apex angle \\(\\theta\\) defines the spread of the cone.\n\n### Interaction with Particles\nThe force field interacts with particles within its geometry, applying repulsive forces. Consider a particle at position \\(\\mathbf{p}\\).\n1. **Distance Calculation:** Compute the vector from the center of the cone to the particle's position, \\( \\mathbf{r} = \\mathbf{p} - C \\). The distance is given by:\n   \\[ d = |\\mathbf{r}| \\]\n2. **Projection onto Cone Axis:** Find the projection of \\(\\mathbf{r}\\) along the cone's height vector, \\( \\mathbf{h} \\):\n   \\[ h_{proj} = (\\mathbf{r} \\cdot \\mathbf{h}) \\mathbf{h} \\]\n3. **Radial Distance:** The radial distance from the axis of the cone to the particle is given by:\n   \\[ r_{rad} = |\\mathbf{r} - h_{proj}| \\]\n4. **Condition for Interaction:** If the radial distance and height projection satisfy the cone's geometry, i.e.,\n   \\[ \\tan(\\theta/2) \\times |h_{proj}| > r_{rad}, \\] then the particle is within the cone.\n\n### Force Calculation\n- **Repulsion Force:** When a particle is inside the cone, a repulsive force is applied to push it out. The direction of this force can be along the normal vector at the point of interaction on the conical surface or along the radial distance from the axis.\n- **Normal Vector:** The normal vector \\(\\mathbf{n}\\) at the particle's position relative to the cone’s surface can be approximated as:\n   \\[ \\mathbf{n} = \\frac{\\mathbf{r}}{d} - \\tan(\\theta/2) \\times \\frac{h_{proj}}{|h_{proj}|^2} \\]\n- **Force Magnitude:** The magnitude of the force is influenced by stiffness and damping coefficients, denoted as \\( k_s \\) (stiffness) and \\( k_d \\) (damping). Assuming a velocity vector \\(\\mathbf{v}\\), the total repulsive force can be written as:\n   \\[ \\mathbf{F} = -k_s (r_{proj}) \\times \\mathbf{n} - k_d |\\mathbf{v}| \\]\n\n## Parameters and Data\n- **coneCenter:** Cone center position (`Coord`)\n- **coneHeight:** Cone height direction and magnitude (`Coord`)\n- **coneAngle:** Apex angle of the cone (`Real`)\n- **stiffness:** Force stiffness coefficient (`Real`, default: not specified)\n- **damping:** Force damping coefficient (`Real`, default: not specified)\n- **color:** Visualization color for the cone geometry (`RGBAColor`, default: `0.0, 0.0, 0.0, 1.0`)"
  }
}