Back

Spiral

sofa::component::engine::generate::Spiral
DataEngine
Doc (from source)

Engine turning on spiral any topological model. This class turns on spiral any topological model

Abstract (AI generated)

The `Spiral` component transforms any topological model into a spiral configuration based on a curvature factor, modifying the positions of degrees of freedom.

Metadata
module
Sofa.Component.Engine.Generate
namespace
sofa::component::engine::generate
include
sofa/component/engine/generate/Spiral.h
inherits
  • DataEngine
templates
  • sofa::defaulttype::Vec3Types
description

The `Spiral` component in the SOFA framework is an engine that transforms any topological model into a spiral configuration based on given parameters. It does not directly contribute to the governing equations or operators such as mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, residual $R$, etc., but rather modifies the positions of the degrees of freedom ($DOFs$) in a way that they follow a spiral path controlled by a curvature factor. This transformation can be useful for generating specific deformations or patterns in simulations involving topological models.

Transformation Process:

  • Governing Transformation Equations:

The Spiral component applies a transformation to the input position coordinates $\mathbf{x}_0$ (rest positions) of the degrees of freedom, resulting in new position coordinates $\mathbf{x}$ that follow a spiral path. The transformation process involves the following steps:

  1. Rest Position Coordinates ($f_X0$): The rest position coordinates are represented as $\mathbf{x}_0$, where each element $x_{0,i} \in \mathbb{R}^3$ corresponds to the initial position of a degree of freedom.
  2. Curvature Factor ($curvature$): The curvature factor, denoted as $A$, controls how tightly or loosely the spiral is formed. This parameter influences the shape and spacing of the spiral.
  3. Spiral Path Calculation: For each rest position coordinate $x_{0,i} = (t_0, y_0, z_0)$:

The transformation uses a mathematical formulation to compute the new coordinates based on the given curvature factor. Specifically, it calculates the arc length $l$ and solves for the parameter $t$ using an iterative method until convergence:

egin{align*} l &= |t_0| \\[5pt] A &= \texttt{curvature.getValue()} \\[5pt] t &= \sqrt{l} \\[5pt] t &= t - \frac{A/2 (t \sqrt{1+t^2} + \text{asinh}(t)) - l}{A \sqrt{1+t^2}} p_{\text{new},i} &= \left( A t \cos(t), A t \sin(t), z_0 \right) \\[5pt] n &= (-A \sin(t) - At \cos(t), A \cos(t) - At \sin(t), 0) \\[5pt] v_{\text{new},i} &= p_{\text{new},i} + n y_0 p_{\text{final}, i} &= v_{\text{new},i} p_{\text{final}, i}^{x, y, z} = \begin{cases} ( r \cos(a), r \sin(a), x_{0,i}.z) \\ a = t \\ r = A t \end{cases} & \text{if } t_0 > 0 \\ ( -r \cos(a), -r \sin(a), x_{0,i}.z) \\ a = t \\ r = -A t p_{\text{final}, i}^{x, y, z} &= p_{\text{new},i} p_{\text{final}} &= \{p_{\text{final},1}, p_{\text{final},2}, \ldots, p_{\text{final},N}\} p_{\text{final}} &= \left\{ (r_i \cos(a_i), r_i \sin(a_i), z_0) \right\}_{i=1}^N a_i &= t_i \\ r_i = A t_i & t_{i+1} &= t_i - \frac{A/2 (t_i \sqrt{1+t_i^2} + \text{asinh}(t_i)) - l}{A \sqrt{1+t_i^2}} \\[5pt] p &= a(t) = A t \\ n_{\text{normalized}} = \frac{n}{|n|} v &= p + n y_0 p_{\text{final}, i} &= v_{i, x, y, z} = (r_i \cos(a_i), r_i \sin(a_i), z_0) \\ a_i = t_i \\ r_i = A t_i p_{\text{final}} &= \left\{ p_{\text{final},i} \right\}_{i=1}^N t &= \sqrt{l} p_{\text{new}, i} &= (A t_i \cos(t), A t_i \sin(t), z_0) \\ t = t - \frac{A/2 (t \sqrt{1+t^2} + \text{asinh}(t)) - l}{A \sqrt{1+t^2}} p_{\text{final}, i}^{x, y, z} &= p_{\text{new},i} n &= (-A \sin(t) - At \cos(t), A \cos(t) - At \sin(t), 0) a_i = t_i \\ r_i = A t_i p_{\text{final}} &= \left\{ (r_i \cos(a_i), r_i \sin(a_i), z_0) \right\}_{i=1}^N n_{\text{normalized}} &= \frac{n}{|n|} v_{\text{new}, i} &= p_{\text{new}, i} + n y_0 \\ v_{\text{new},i}^{x,y,z} = (r_i \cos(a_i) - A \sin(t) - At \cos(t), r_i \sin(a_i) + A \cos(t) - At \sin(t), z_0) p_{\text{final}} &= \left\{ v_{\text{new}, i} \right\}_{i=1}^N t_{i+1} &= t_i - \frac{A/2 (t_i \sqrt{1+t_i^2} + \text{asinh}(t_i)) - l}{A \sqrt{1+t_i^2}} \\[5pt] p_{\text{final}, i}^{x,y,z} &= p_{\text{new},i} p_{\text{final}} &= \left\{ (r_i \cos(a_i), r_i \sin(a_i), z_0) \right\}_{i=1}^N \\ a_i = t_i \\ r_i = A t_i a_i &= t_i \\ r_i = A t_i p_{\text{final}, i}^{x,y,z} &= (r_i \cos(a_i), r_i \sin(a_i), z_0) \\ a_i = t_i \\ r_i = A t_i t &= \sqrt{l} p_{\text{new},i} &= (A t_i \cos(t), A t_i \sin(t), z_0) a_i &= t_i \\ r_i = A t_i p_{\text{final}, i}^{x,y,z} &= p_{\text{new},i} t_{i+1} &= t - \frac{A/2 (t \sqrt{1+t^2} + \text{asinh}(t)) - l}{A \sqrt{1+t^2}} \\[5pt] p_{\text{final}, i}^{x,y,z} &= p_{\text{new},i} a_i &= t_i \\ r_i = A t_i p_{\text{final}, i}^{x,y,z} &= (r_i \cos(a_i), r_i \sin(a_i), z_0) \\ a_i = t_i \\ r_i = A t_i p_{\text{new}} &= \left\{ p_{\text{new},i} \right\}_{i=1}^N p_{\text{final}} &= \left\{ (r_i \cos(a_i), r_i \sin(a_i), z_0) \right\}_{i=1}^N \\ a_i = t_i \\ r_i = A t_i

Role in the Global FEM Pipeline:

  • The `Spiral` component fits into the broader variational / Lagrangian mechanics framework by providing a transformation that can be used as an input to other components within the simulation pipeline.

Specifically:

  1. The rest position coordinates ($f_X0$) and new positions ($f_X$) are computed during the `doUpdate` method, which is called in the simulation loop. The transformation does not directly contribute to the stiffness matrix $K$, mass matrix $M$, internal force $f_{int}$, or residual $R$. Instead, it modifies the position coordinates that can be used by other components such as force fields and constraints.
  2. There is no direct contribution to the governing equations of motion, constitutive laws, or constraint handling. The Spiral component's primary role is to provide a transformation for the positions of degrees of freedom, which can then be utilized in subsequent stages of the FEM simulation pipeline.
Data Fields
NameTypeDefaultHelp
f_X0 VecCoord Rest position coordinates of the degrees of freedom
f_X VecCoord Position coordinates of the degrees of freedom
curvature Real Spiral curvature factor
Methods
void init () virtual
void reinit () virtual
void doUpdate () virtual
void draw (const core::visual::VisualParams * vparams) virtual 
{
  "name": "Spiral",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/Spiral.h",
  "doc": "Engine turning on spiral any topological model.\n\nThis class turns on spiral any topological model",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_X0",
      "type": "VecCoord",
      "xmlname": "rest_position",
      "help": "Rest position coordinates of the degrees of freedom"
    },
    {
      "name": "f_X",
      "type": "VecCoord",
      "xmlname": "position",
      "help": "Position coordinates of the degrees of freedom"
    },
    {
      "name": "curvature",
      "type": "Real",
      "xmlname": "curvature",
      "help": "Spiral curvature factor"
    }
  ],
  "links": [],
  "methods": [
    {
      "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": "doUpdate",
      "return_type": "void",
      "params": [],
      "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": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `Spiral` component in the SOFA framework is an engine that transforms any topological model into a spiral configuration based on given parameters. It inherits from `DataEngine`, which allows it to handle data and perform computations within the SOFA simulation pipeline.\n\n**Role and Purpose**: The primary role of the Spiral component is to modify the positions of the degrees of freedom in a way that they follow a spiral path, controlled by a curvature factor. This transformation can be useful for generating specific deformations or patterns in simulations involving topological models.\n\n**Interactions with Other Components**: The Spiral engine interacts primarily through its input and output data fields. It receives the rest position coordinates (`f_X0`) of the degrees of freedom and outputs their new positions (`f_X`). Additionally, it uses a `curvature` parameter to control how tightly or loosely the spiral is formed.\n\n**Practical Usage Guidance**: The Spiral component should be used when you need to deform a topological model into a spiral shape. Users must provide the rest positions of the degrees of freedom and can adjust the curvature factor to achieve the desired deformation. This component does not directly interact with other components beyond its input and output data fields, but it can be integrated into larger simulation setups where such transformations are required.",
  "maths": "<p>The `Spiral` component in the SOFA framework is an engine that transforms any topological model into a spiral configuration based on given parameters. It does not directly contribute to the governing equations or operators such as mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, residual $R$, etc., but rather modifies the positions of the degrees of freedom ($DOFs$) in a way that they follow a spiral path controlled by a curvature factor. This transformation can be useful for generating specific deformations or patterns in simulations involving topological models.</p>\n\n<p><strong>Transformation Process:</strong></p>\n\n<ul>\n\t<li><em>Governing Transformation Equations:</em></li>\n</ul>\n\n<p>The Spiral component applies a transformation to the input position coordinates $\\mathbf{x}_0$ (rest positions) of the degrees of freedom, resulting in new position coordinates $\\mathbf{x}$ that follow a spiral path. The transformation process involves the following steps:</p>\n\n<ol>\n\t<li><strong>Rest Position Coordinates ($f_X0$):</strong> The rest position coordinates are represented as $\\mathbf{x}_0$, where each element $x_{0,i} \\in \\mathbb{R}^3$ corresponds to the initial position of a degree of freedom.</li>\n\t<li><strong>Curvature Factor ($curvature$):</strong> The curvature factor, denoted as $A$, controls how tightly or loosely the spiral is formed. This parameter influences the shape and spacing of the spiral.</li>\n\t<li><strong>Spiral Path Calculation:</strong> For each rest position coordinate $x_{0,i} = (t_0, y_0, z_0)$:</li>\n</ol>\n\n<p>The transformation uses a mathematical formulation to compute the new coordinates based on the given curvature factor. Specifically, it calculates the arc length $l$ and solves for the parameter $t$ using an iterative method until convergence:</p>\n\n\begin{align*}\n\tl &= |t_0| \\\\[5pt]\n\tA &amp;= \\texttt{curvature.getValue()} \\\\[5pt]\n\tt &= \\sqrt{l} \\\\[5pt]\n\nt &amp;= t - \\frac{A/2 (t \\sqrt{1+t^2} + \\text{asinh}(t)) - l}{A \\sqrt{1+t^2}}\n\tp_{\\text{new},i} &= \\left( A t \\cos(t), A t \\sin(t), z_0 \\right) \\\\[5pt]\n\tn &amp;= (-A \\sin(t) - At \\cos(t), A \\cos(t) - At \\sin(t), 0) \\\\[5pt]\n\tv_{\\text{new},i} &= p_{\\text{new},i} + n y_0\n\tp_{\\text{final}, i} &amp;= v_{\\text{new},i}\n\tp_{\\text{final}, i}^{x, y, z} = \\begin{cases}\n\t( r \\cos(a), r \\sin(a), x_{0,i}.z) \\\\ a = t \\\\ r = A t\n\t\\end{cases} &amp; \\text{if } t_0 > 0 \\\\ ( -r \\cos(a), -r \\sin(a), x_{0,i}.z) \\\\ a = t \\\\ r = -A t\n\tp_{\\text{final}, i}^{x, y, z} &= p_{\\text{new},i}\n\t\n\tp_{\\text{final}} &amp;= \\{p_{\\text{final},1}, p_{\\text{final},2}, \\ldots, p_{\\text{final},N}\\}\n\tp_{\\text{final}} &amp;= \\left\\{ (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\right\\}_{i=1}^N\n\t\n\ta_i &amp;= t_i \\\\ r_i = A t_i\n\t&\n\t\n\tt_{i+1} &= t_i - \\frac{A/2 (t_i \\sqrt{1+t_i^2} + \\text{asinh}(t_i)) - l}{A \\sqrt{1+t_i^2}} \\\\[5pt]\n\t\n\tp &amp;= a(t) = A t \\\\ n_{\\text{normalized}} = \\frac{n}{|n|}\n\t\n\tv &amp;= p + n y_0\n\t\n\tp_{\\text{final}, i} &= v_{i, x, y, z} = (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\\\ a_i = t_i \\\\ r_i = A t_i\n\tp_{\\text{final}} &amp;= \\left\\{ p_{\\text{final},i} \\right\\}_{i=1}^N\n\t\n\tt &amp;= \\sqrt{l}\n\tp_{\\text{new}, i} &amp;= (A t_i \\cos(t), A t_i \\sin(t), z_0) \\\\ t = t - \\frac{A/2 (t \\sqrt{1+t^2} + \\text{asinh}(t)) - l}{A \\sqrt{1+t^2}}\n\t\n\tp_{\\text{final}, i}^{x, y, z} &= p_{\\text{new},i}\n\tn &amp;= (-A \\sin(t) - At \\cos(t), A \\cos(t) - At \\sin(t), 0)\n\t\n\ta_i = t_i \\\\ r_i = A t_i\n\tp_{\\text{final}} &amp;= \\left\\{ (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\right\\}_{i=1}^N\n\tn_{\\text{normalized}} &= \\frac{n}{|n|}\n\t\n\tv_{\\text{new}, i} &amp;= p_{\\text{new}, i} + n y_0 \\\\ v_{\\text{new},i}^{x,y,z} = (r_i \\cos(a_i) - A \\sin(t) - At \\cos(t), r_i \\sin(a_i) + A \\cos(t) - At \\sin(t), z_0)\n\tp_{\\text{final}} &amp;= \\left\\{ v_{\\text{new}, i} \\right\\}_{i=1}^N\n\t\n\tt_{i+1} &= t_i - \\frac{A/2 (t_i \\sqrt{1+t_i^2} + \\text{asinh}(t_i)) - l}{A \\sqrt{1+t_i^2}} \\\\[5pt]\n\tp_{\\text{final}, i}^{x,y,z} &amp;= p_{\\text{new},i}\n\t\n\tp_{\\text{final}} &amp;= \\left\\{ (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\right\\}_{i=1}^N \\\\ a_i = t_i \\\\ r_i = A t_i\n\t\n\ta_i &= t_i \\\\ r_i = A t_i\n\tp_{\\text{final}, i}^{x,y,z} &amp;= (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\\\ a_i = t_i \\\\ r_i = A t_i\n\t\n\tt &= \\sqrt{l}\n\tp_{\\text{new},i} &amp;= (A t_i \\cos(t), A t_i \\sin(t), z_0)\n\t\n\ta_i &= t_i \\\\ r_i = A t_i\n\tp_{\\text{final}, i}^{x,y,z} &amp;= p_{\\text{new},i}\n\t\n\tt_{i+1} &amp;= t - \\frac{A/2 (t \\sqrt{1+t^2} + \\text{asinh}(t)) - l}{A \\sqrt{1+t^2}} \\\\[5pt]\n\tp_{\\text{final}, i}^{x,y,z} &amp;= p_{\\text{new},i}\n\t\n\ta_i &= t_i \\\\ r_i = A t_i\n\tp_{\\text{final}, i}^{x,y,z} &amp;= (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\\\ a_i = t_i \\\\ r_i = A t_i\n\t\n\tp_{\\text{new}} &amp;= \\left\\{ p_{\\text{new},i} \\right\\}_{i=1}^N\n\t\n\tp_{\\text{final}} &amp;= \\left\\{ (r_i \\cos(a_i), r_i \\sin(a_i), z_0) \\right\\}_{i=1}^N \\\\ a_i = t_i \\\\ r_i = A t_i\n</align*>\n\n<p><strong>Role in the Global FEM Pipeline:</strong></p>\n\n<ul>\n\t<li>The `Spiral` component fits into the broader variational / Lagrangian mechanics framework by providing a transformation that can be used as an input to other components within the simulation pipeline.</li>\n</ul>\n\n<p><em>Specifically:</em></p>\n\n<ol>\n\t<li>The rest position coordinates ($f_X0$) and new positions ($f_X$) are computed during the `doUpdate` method, which is called in the simulation loop. The transformation does not directly contribute to the stiffness matrix $K$, mass matrix $M$, internal force $f_{int}$, or residual $R$. Instead, it modifies the position coordinates that can be used by other components such as force fields and constraints.</li>\n\t<li>There is no direct contribution to the governing equations of motion, constitutive laws, or constraint handling. The Spiral component's primary role is to provide a transformation for the positions of degrees of freedom, which can then be utilized in subsequent stages of the FEM simulation pipeline.</li>\n</ol>",
  "abstract": "The `Spiral` component transforms any topological model into a spiral configuration based on a curvature factor, modifying the positions of degrees of freedom.",
  "sheet": "# Spiral\n\n## Overview\nThe `Spiral` component is an engine that modifies position coordinates to form a spiral path. It inherits from `DataEngine`, enabling it to handle data and computations within SOFA simulations.\n\n## Parameters and Data\n- **f_X0**: Rest position coordinates of the degrees of freedom (`VecCoord`).\n- **f_X**: Position coordinates of the degrees of freedom after transformation (`VecCoord`).\n- **curvature**: Spiral curvature factor (`Real`), controlling how tightly or loosely the spiral is formed.\n\n## Practical Notes\nThe `Spiral` component should be used when a topological model needs to be deformed into a spiral shape. Users must provide rest positions and can adjust the curvature factor for desired deformation. This component does not directly interact with other components beyond its input and output data fields."
}