{
  "name": "Edge2QuadTopologicalMapping",
  "main": {
    "name": "Edge2QuadTopologicalMapping",
    "namespace": "sofa::component::topology::mapping",
    "module": "Sofa.Component.Topology.Mapping",
    "include": "sofa/component/topology/mapping/Edge2QuadTopologicalMapping.h",
    "doc": "Topological mapping where EdgeSetTopology is converted to QuadSetTopology.\n\nThis class, called Edge2QuadTopologicalMapping, is a specific implementation of the interface TopologicalMapping where :\nINPUT TOPOLOGY = EdgeSetTopology\nOUTPUT TOPOLOGY = QuadSetTopology based on new DOFs, as the tubular skinning of INPUT TOPOLOGY.\nEdge2QuadTopologicalMapping class is templated by the pair (INPUT TOPOLOGY, OUTPUT TOPOLOGY)",
    "inherits": [
      "TopologicalMapping"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_nbPointsOnEachCircle",
        "type": "unsigned int",
        "xmlname": "nbPointsOnEachCircle",
        "help": "Discretization of created circles"
      },
      {
        "name": "d_radius",
        "type": "SReal",
        "xmlname": "radius",
        "help": "Radius of created circles in yz plan"
      },
      {
        "name": "d_radiusFocal",
        "type": "SReal",
        "xmlname": "radiusFocal",
        "help": "If greater than 0., radius in focal axis of created ellipses"
      },
      {
        "name": "d_focalAxis",
        "type": "type::Vec3",
        "xmlname": "focalAxis",
        "help": "In case of ellipses"
      },
      {
        "name": "d_flipNormals",
        "type": "bool",
        "xmlname": "flipNormals",
        "help": "Flip Normal ? (Inverse point order when creating quad)"
      }
    ],
    "links": [
      {
        "name": "l_toQuadContainer",
        "target": "QuadSetTopologyContainer",
        "kind": "single",
        "xmlname": "toQuadContainer",
        "help": "Output container storing Quads"
      },
      {
        "name": "l_toQuadModifier",
        "target": "QuadSetTopologyModifier",
        "kind": "single",
        "xmlname": "toQuadModifier",
        "help": "Output modifier handling Quads"
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateTopologicalMappingTopDown",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getFromIndex",
        "return_type": "Index",
        "params": [
          {
            "name": "ind",
            "type": "Index"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `Edge2QuadTopologicalMapping` is a specific implementation in SOFA for converting an EdgeSetTopology to a QuadSetTopology, generating new degrees-of-freedom (DOFs) as the tubular skinning of the input topology. This class inherits from `TopologicalMapping`, with the following key roles and interactions:\n\n- **Purpose**: It maps edges to quads based on input parameters such as discretization (`nbPointsOnEachCircle`), radius, focal radius, and flipping normals.\n- **Inputs**: EdgeSetTopology where each edge is treated as a segment in 3D space. The target topology (QuadSetTopology) is initialized with new DOFs that form tubular structures around these edges.\n- **Outputs**: QuadSetTopologyContainer (`l_toQuadContainer`) and QuadSetTopologyModifier (`l_toQuadModifier`). These are used to store and modify the generated quad topology.\n\n**Data Fields**:\n- `nbPointsOnEachCircle`: Discretization parameter for creating circles around each edge.\n- `radius`, `radiusFocal`, `focalAxis`: Parameters for defining the shape of created circles or ellipses.\n- `flipNormals`: Boolean to control normal orientation when creating quads.\n\n**Initialization**: The component initializes the QuadSetTopology based on the input EdgeSetTopology by generating points around each edge and forming quads. It also handles topology changes, such as adding or removing edges, and updates the quad mesh accordingly."
  },
  "maths": {
    "maths": "## Mathematical Description\n\nThe `Edge2QuadTopologicalMapping` component in SOFA is designed to map an EdgeSetTopology (which consists of a set of edges) into a QuadSetTopology (a mesh composed of quadrilateral faces). This mapping generates new degrees-of-freedom (DOFs), creating tubular structures around the original edges. The mathematical description focuses on how these tubular structures are formed and how the quads are generated from the input edges.\n\n### Input Geometry\n- **Edges**: Each edge in the EdgeSetTopology is represented as a line segment connecting two vertices, denoted by their coordinates \\( \textbf{v}_1 = (x_1, y_1, z_1) \\) and \\( \textbf{v}_2 = (x_2, y_2, z_2) \\).\n\n### Discretization of Circles or Ellipses Around Edges\n- **Discretization Parameter**: The number of points around each edge is controlled by `nbPointsOnEachCircle`, denoted as \\( n_{points} \\). This parameter determines the granularity and smoothness of the resulting tubular structure.\n- **Radius**: The radius \\( r \\) defines the size of the circular cross-section perpendicular to each edge. For an ellipse, the focal axis affects the shape along a specified direction.\n\n### Tubular Structure Generation\n1. **Direction Vector Calculation**:\n   - Compute the direction vector \\( \textbf{d} = \textbf{v}_2 - \textbf{v}_1 \\) of each edge.\n   - Normalize it to get unit vector \\( \textbf{u} = \frac{\textbf{d}}{|\textbf{d}|} \\).\n\n2. **Perpendicular Basis**:\n   - Choose an orthogonal basis \\( \textbf{n}_1, \textbf{n}_2 \\) such that they are perpendicular to each other and also perpendicular to the direction vector \\( \textbf{u} \\). For example, if the focal axis is not aligned with any coordinate axes, a cross product can be used:\n     - \\( \textbf{n}_1 = (\textbf{focalAxis} \times \textbf{u}) / |\textbf{focalAxis} \times \textbf{u}| \\)\n     - \\( \textbf{n}_2 = (\textbf{u} \times \textbf{n}_1) / |\textbf{u} \times \textbf{n}_1| \\)\n\n3. **Point Generation on Circles or Ellipses**:\n   - For each point along the edge (from \\( t=0 \\) to \\( t=1 \\), in steps of \\( 1/n_{points} \\)), generate points around it using polar coordinates for circles, and elliptical coordinates if `radiusFocal` is specified.\n     - For a circle:\n       \\[ \textbf{p}_i(t) = (1-t)\textbf{v}_1 + t\textbf{v}_2 + r (\textbf{n}_1 \times \textbf{u}) \text{cos}(2\theta_i) + r (\textbf{n}_2 \times \textbf{u}) \text{sin}(2\theta_i) \\]\n     - For an ellipse:\n       \\[ \textbf{p}_i(t) = (1-t)\textbf{v}_1 + t\textbf{v}_2 + r (\textbf{n}_1 \times \textbf{u}) \text{cos}(2\theta_i) + r_{focal} (\textbf{n}_2 \times \textbf{u}) \text{sin}(2\theta_i) \\]\n     where \\( \theta_i = 2\frac{\text{i}}{n_{points}}\times \text{PI} \\).\n\n### Quad Formation\n- **Quads Generation**: After generating points around each edge, quads are formed by connecting neighboring points along the tubular surface.\n   - Each quad is defined as a set of four vertices. For example, if two adjacent edges are \\( (\textbf{p}_i(t), \textbf{p}_{i+1}(t)) \\) and \\( (\textbf{p}_i(t+dt), \textbf{p}_{i+1}(t+dt)) \\):\n     - Quad vertices can be: \\[ Q = (\\textbf{p}_i(t), \textbf{p}_{i+1}(t), \textbf{p}_{i+1}(t + dt), \textbf{p}_i(t + dt)) \\]\n\n### Normal Orientation Control\n- **Flip Normals**: The `flipNormals` flag controls the orientation of the normals (and hence, point ordering) when creating quads. This is important for maintaining consistent surface orientation in visualization and simulation.\n\n### Topology Changes Handling\n- **Addition/Removal of Edges**: The mapping handles changes such as addition or removal of edges by generating/removing corresponding quads and updating the quad mesh accordingly to ensure consistency with the input topology changes."
  },
  "summary": {
    "abstract": "The Edge2QuadTopologicalMapping converts an EdgeSetTopology into a QuadSetTopology by generating tubular structures around edges, forming quads based on specified parameters such as discretization, radius, focal axis, and normal orientation.",
    "sheet": "# Edge2QuadTopologicalMapping\n\n## Overview\nEdge2QuadTopologicalMapping is a specific implementation of the TopologicalMapping interface that converts an EdgeSetTopology into a QuadSetTopology. It generates new degrees-of-freedom (DOFs) as tubular structures around each edge, forming quads based on input parameters such as discretization (`nbPointsOnEachCircle`), radius, focal axis, and normal orientation.\n\n## Mathematical Model\nThe `Edge2QuadTopologicalMapping` component maps an EdgeSetTopology to a QuadSetTopology by generating new DOFs that form tubular structures around the edges. The mathematical description focuses on how these tubular structures are formed and how quads are generated from the input edges.\n\n### Input Geometry\n- **Edges**: Each edge in the EdgeSetTopology is represented as a line segment connecting two vertices, denoted by their coordinates \\(\\mathbf{v}_1 = (x_1, y_1, z_1)\\) and \\(\\mathbf{v}_2 = (x_2, y_2, z_2)\\).\n\n### Discretization of Circles or Ellipses Around Edges\n- **Discretization Parameter**: The number of points around each edge is controlled by `nbPointsOnEachCircle`, denoted as \\( n_{points} \\). This parameter determines the granularity and smoothness of the resulting tubular structure.\n- **Radius**: The radius \\( r \\) defines the size of the circular cross-section perpendicular to each edge. For an ellipse, the focal axis affects the shape along a specified direction.\n\n### Tubular Structure Generation\n1. **Direction Vector Calculation**:\n   - Compute the direction vector \\(\\mathbf{d} = \\mathbf{v}_2 - \\mathbf{v}_1\\) of each edge.\n   - Normalize it to get unit vector \\(\\mathbf{u} = \\frac{\\mathbf{d}}{|\\mathbf{d}|}\\).\n\n2. **Perpendicular Basis**:\n   - Choose an orthogonal basis \\(\\mathbf{n}_1, \\mathbf{n}_2\\) such that they are perpendicular to each other and also perpendicular to the direction vector \\(\\mathbf{u}\\). For example, if the focal axis is not aligned with any coordinate axes, a cross product can be used:\n     - \\(\\mathbf{n}_1 = (\\mathbf{focalAxis} \\times \\mathbf{u}) / |\\mathbf{focalAxis} \\times \\mathbf{u}|\\)\n     - \\(\\mathbf{n}_2 = (\\mathbf{u} \\times \\mathbf{n}_1) / |\\mathbf{u} \\times \\mathbf{n}_1|\\)\n\n3. **Point Generation on Circles or Ellipses**:\n   - For each point along the edge (from \\( t=0 \\) to \\( t=1 \\), in steps of \\( 1/n_{points} \\)), generate points around it using polar coordinates for circles, and elliptical coordinates if `radiusFocal` is specified.\n     - For a circle:\n       \\[\\mathbf{p}_i(t) = (1-t)\\mathbf{v}_1 + t\\mathbf{v}_2 + r (\\mathbf{n}_1 \\times \\mathbf{u}) \\cos(2\\theta_i) + r (\\mathbf{n}_2 \\times \\mathbf{u}) \\sin(2\\theta_i)\\]\n     - For an ellipse:\n       \\[\\mathbf{p}_i(t) = (1-t)\\mathbf{v}_1 + t\\mathbf{v}_2 + r (\\mathbf{n}_1 \\times \\mathbf{u}) \\cos(2\\theta_i) + r_{focal} (\\mathbf{n}_2 \\times \\mathbf{u}) \\sin(2\\theta_i)\\]\n     where \\(\\theta_i = 2\\frac{i}{n_{points}}\\pi\\).\n\n### Quad Formation\n- **Quads Generation**: After generating points around each edge, quads are formed by connecting neighboring points along the tubular surface.\n   - Each quad is defined as a set of four vertices. For example, if two adjacent edges are \\((\\mathbf{p}_i(t), \\mathbf{p}_{i+1}(t))\\) and \\((\\mathbf{p}_i(t+dt), \\mathbf{p}_{i+1}(t+dt))\\):\n     - Quad vertices can be: \\[ Q = (\\textbf{p}_i(t), \\mathbf{p}_{i+1}(t), \\mathbf{p}_{i+1}(t + dt), \\mathbf{p}_i(t + dt)) \\]\n\n### Normal Orientation Control\n- **Flip Normals**: The `flipNormals` flag controls the orientation of the normals (and hence, point ordering) when creating quads. This is important for maintaining consistent surface orientation in visualization and simulation.\n\n## Parameters and Data\nThe significant Data fields exposed by the component are:\n- `nbPointsOnEachCircle`: Discretization parameter for creating circles around each edge.\n- `radius`, `radiusFocal`, `focalAxis`: Parameters for defining the shape of created circles or ellipses.\n- `flipNormals`: Boolean to control normal orientation when creating quads.\n\n## Dependencies and Connections\nThis component typically requires connections with QuadSetTopologyContainer (`toQuadContainer`) and QuadSetTopologyModifier (`toQuadModifier`) for output topology storage and modification."
  }
}