{
  "name": "CylinderCollisionModel",
  "main": {
    "name": "CylinderCollisionModel",
    "namespace": "sofa::component::collision::geometry",
    "module": "Sofa.Component.Collision.Geometry",
    "include": "sofa/component/collision/geometry/CylinderCollisionModel.h",
    "doc": "Collision model which represents a set of rigid cylinders.\n\nCylinderModel templated by RigidTypes (frames), direction is given by Y direction of the frame.",
    "inherits": [
      "CollisionModel"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types"
    ],
    "data_fields": [
      {
        "name": "d_cylinder_radii",
        "type": "VecReal",
        "xmlname": "radii",
        "help": "Radius of each cylinder"
      },
      {
        "name": "d_cylinder_heights",
        "type": "VecReal",
        "xmlname": "heights",
        "help": "The cylinder heights"
      },
      {
        "name": "d_cylinder_local_axes",
        "type": "VecAxisCoord"
      },
      {
        "name": "d_default_radius",
        "type": "Real",
        "xmlname": "defaultRadius",
        "help": "The default radius"
      },
      {
        "name": "d_default_height",
        "type": "Real",
        "xmlname": "defaultHeight",
        "help": "The default height"
      },
      {
        "name": "d_default_local_axis",
        "type": "Coord",
        "xmlname": "defaultLocalAxis",
        "help": "The default local axis cylinder is modeled around"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resize",
        "return_type": "void",
        "params": [
          {
            "name": "size",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeBoundingTree",
        "return_type": "void",
        "params": [
          {
            "name": "maxDepth",
            "type": "int"
          }
        ],
        "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 *"
          },
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getMechanicalState",
        "return_type": "core::behavior::MechanicalState<DataTypes> *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "radius",
        "return_type": "Real",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "center",
        "return_type": "const Coord &",
        "params": [
          {
            "name": "i",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "axis",
        "return_type": "Coord",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "local_axis",
        "return_type": "Coord",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "orientation",
        "return_type": "const sofa::type::Quat<SReal>",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "height",
        "return_type": "Real",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "point1",
        "return_type": "Coord",
        "params": [
          {
            "name": "i",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "point2",
        "return_type": "Coord",
        "params": [
          {
            "name": "i",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "defaultRadius",
        "return_type": "Real",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "velocity",
        "return_type": "const Coord &",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "writeRadii",
        "return_type": "Data<VecReal> &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "writeHeights",
        "return_type": "Data<VecReal> &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "writeLocalAxes",
        "return_type": "Data<VecAxisCoord> &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "CylinderCollisionModel",
    "description": "This component represents a collection of cylinders in the simulation, used for collision detection and visual representation. Each cylinder is defined by its center position, radius, height, and orientation axis.",
    "parameters": [
      {
        "name": "radii",
        "description": "A vector specifying the radius of each cylinder.",
        "type": "Real[]",
        "default_value": "",
        "data_type": "VecReal"
      },
      {
        "name": "heights",
        "description": "A vector specifying the height of each cylinder.",
        "type": "Real[]",
        "default_value": "",
        "data_type": "VecReal"
      },
      {
        "name": "defaultRadius",
        "description": "The default radius used when the radii array does not specify a value for a particular cylinder.",
        "type": "Real",
        "default_value": "0.5",
        "data_type": "Real"
      },
      {
        "name": "defaultHeight",
        "description": "The default height used when the heights array does not specify a value for a particular cylinder.",
        "type": "Real",
        "default_value": "2",
        "data_type": "Real"
      },
      {
        "name": "defaultLocalAxis",
        "description": "The default orientation axis used to define the direction of each cylinder. The cylinder will be oriented along this vector.",
        "type": "Vec3",
        "default_value": "[0, 1, 0]",
        "data_type": "Vec3"
      }
    ],
    "methods": [
      {
        "name": "resize",
        "description": "Resizes the CylinderCollisionModel to accommodate a new number of cylinders.",
        "parameters": [
          "size (integer)"
        ]
      },
      {
        "name": "init",
        "description": "Initializes the CylinderCollisionModel, linking it to the mechanical state and setting its size based on the number of elements in the rigid mechanical model."
      },
      {
        "name": "computeBoundingTree",
        "description": "Computes the bounding tree for collision detection using a cube approximation of each cylinder.",
        "parameters": [
          "maxDepth (integer)"
        ]
      },
      {
        "name": "draw",
        "description": "Renders the specified cylinder in the scene during visualization.",
        "parameters": [
          "vparams (VisualParams)",
          "i (index of the cylinder)"
        ]
      }
    ],
    "relationships": [
      {
        "name": "MechanicalState",
        "type": "dependency",
        "description": "This component requires a Rigid Mechanical Model to define the positions and orientations of each cylinder."
      }
    ],
    "usage_examples": [
      "Example: Define a CylinderCollisionModel with custom radii, heights and axes:",
      "<CylinderCollisionModel name='my_cylinders' radii='[0.5, 1]' heights='[2, 3]' defaultLocalAxis='[1, 0, 0]'></CylinderCollisionModel>"
    ],
    "notes": "The CylinderCollisionModel uses a cube approximation for collision detection to improve performance. The actual cylinder geometry is only used for visualization."
  },
  "maths": {
    "maths": "## Mathematical and Physical Description of the Cylinder Component in SOFA\n\n### Overview\nThe Cylinder Component in SOFA is a specialized model for representing cylindrical objects within a physical simulation. Each cylinder is defined by its center position, radius, height, and orientation axis. The cylinders are used for both collision detection and visual representation.\n\n### Mathematical Representation\n#### Parameters:\n- **Center Position ($\\mathbf{c}$)**: This vector $\\mathbf{c} = (c_x, c_y, c_z)$ represents the central point of the cylinder in 3D space.\n- **Radius ($r$)**: The radius of the cylinder is denoted by $r$. It defines the width of the cylindrical cross-section perpendicular to its axis.\n- **Height ($h$)**: The height $h$ of the cylinder extends along its central axis. \n- **Orientation Axis ($\\mathbf{a}$)**: This vector $\\mathbf{a} = (a_x, a_y, a_z)$ represents the orientation direction of the cylinder’s central axis.\n\n#### Points on Cylinder Surface:\nThe surface points $(x,y,z)$ of a cylindrical object can be described parametrically as follows:\n\\[ x = c_x + r \\cos(\\theta) \\]\n\\[ y = c_y + r \\sin(\\theta) \\]\n\\[ z = c_z + t \\cdot h/2 \\]\nwhere $\\theta$ ranges from 0 to $2\\pi$ (defining the circular cross-section), and $t$ ranges from -1 to 1, defining the height along the axis.\n\n#### Bounding Box:\nThe bounding box for each cylinder is calculated by considering the radius $r$, half-height ($h/2$), and orientation vector $\\mathbf{a}$. The minimum $(minVec)$ and maximum $(maxVec)$ vectors of the bounding box are given as follows:\n- Calculate the axis-aligned points along the height direction:\n  \\[ p_1 = c + (h/2) \\cdot a \\]\n  \\[ p_2 = c - (h/2) \\cdot a \\]\n- For each dimension $dim$ in $(x, y, z)$:\n  \\[ minVec(dim) = \\min(p1(dim), p2(dim)) - r \\]\n  \\[ maxVec(dim) = \\max(p1(dim), p2(dim)) + r \\]\nThe bounding box is then defined by these $minVec$ and $maxVec$ vectors, facilitating efficient collision detection.\n\n### Physical Representation\nThe physical properties of the cylinder include its position in space, velocity (if applicable for moving objects), and orientation. These are stored as part of a Rigid Mechanical Model in SOFA.\n- **Position**: Each cylinder’s center is represented using the position vector $\\mathbf{c}$ within the mechanical model.\n- **Orientation**: The orientation of the cylinder’s central axis can be expressed by a quaternion, which allows for smooth and efficient rotation operations.\n\n#### Collision Detection:\nThe bounding box (computed as described above) plays a crucial role in collision detection. For each cylinder, its bounding box is checked against other objects' bounding boxes to determine potential collisions. If the bounding boxes intersect, more detailed checks can be performed using the actual cylindrical geometry.\n\n### Visualization\nThe cylinders are visualized using their center position $\\mathbf{c}$, radius $r$, and height $h$. The visualization function draws each cylinder by rendering it along its axis defined by $\\mathbf{a}$. The color of each cylinder can be customized as needed for the simulation environment.\n\n### Initialization and Resizing:\nThe cylinders are initialized based on a given number of rigid bodies in the mechanical model. During initialization, default values for radius, height, and orientation are assigned if not explicitly provided. The component dynamically resizes to accommodate changes in the number of objects within the mechanical model.\n\n### Application:\nThe Cylinder Component is particularly useful in simulations where cylindrical shapes need precise collision detection and visualization. This includes applications ranging from industrial robotics to medical simulations where cylindrical structures represent pipes, bones, or similar components."
  },
  "summary": {
    "abstract": "Represents a set of rigid cylinders for collision detection in SOFA simulations, defining each cylinder by its center position, radius, height, and orientation axis.",
    "sheet": "# CylinderCollisionModel\n\n**Overview**\nCylinderCollisionModel is a specialized component that represents a collection of rigid cylinders used for collision detection. Each cylinder is defined by its center position, radius, height, and orientation axis.\n\n**Parameters and Data**\nThe significant data fields exposed by the component are:\n- **radii**: Radius of each cylinder (`VecReal`)\n- **heights**: The cylinder heights (`VecReal`)\n- **defaultRadius**: Default radius for cylinders (`Real`, default: 1.0)\n- **defaultHeight**: Default height for cylinders (`Real`, default: 1.0)\n- **defaultLocalAxis**: Default local axis around which the cylinder is modeled (`Coord`, default: (0, 1, 0))\n\n**Dependencies and Connections**\nThe CylinderCollisionModel typically requires a mechanical model to define the positions of the cylinders and exchanges data with other collision models for detecting collisions.\n"
  }
}