.. _auto_move_spiral:

move_spiral (Auto Mode)
------------------------------------------

This function executes a **spiral trajectory** motion in which the robot’s radius gradually increases in the **radial direction**  
while moving in parallel with a **rotating spiral** along the **axial direction**.  
The path is formed on a plane perpendicular to the selected axis (`eTaskAxis`) and the spiral expands outward  
until it reaches the specified maximum radius and length.

.. figure:: /tutorials/images/mode/movespiral_overview.png
   :alt: movespiral
   :width: 80%
   :align: center

.. raw:: html
      
   <br>


**Definition (Maximum Radius / Length)** |br|
``DRFLEx.h`` within class `CDRFLEx`, public section (line 803)

.. code-block:: cpp

   bool move_spiral(TASK_AXIS eTaskAxis,
                    float fRevolution,
                    float fMaximuRadius,
                    float fMaximumLength,
                    float fTargetVel[2],
                    float fTargetAcc[2],
                    float fTargetTime = 0.f,
                    MOVE_REFERENCE eMoveReference = MOVE_REFERENCE_TOOL) {
       return _move_spiral(_rbtCtrl, eTaskAxis, fRevolution, fMaximuRadius,
                           fMaximumLength, fTargetVel, fTargetAcc,
                           fTargetTime, eMoveReference);
   };

**Parameter**

.. list-table::
   :widths: 22 20 18 40
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - eTaskAxis
     - :ref:`TASK_AXIS <enum_task_axis>`
     - -
     - Axis perpendicular to the spiral surface |br|
       (defines rotation plane for the spiral path)
   * - fRevolution
     - float
     - -
     - Total number of spiral revolutions [rev > 0]
   * - fMaximuRadius
     - float
     - -
     - Final spiral radius [mm]
   * - fMaximumLength
     - float
     - -
     - Linear distance moved along the spiral axis [mm] |br|
       (negative value = reverse direction)
   * - fTargetVel
     - float[2]
     - -
     - Linear and angular velocity [mm/s, deg/s]
   * - fTargetAcc
     - float[2]
     - -
     - Linear and angular acceleration [mm/s\ :sup:`2`, deg/s\ :sup:`2`]
   * - fTargetTime
     - float
     - 0.0
     - Total execution time [sec]
   * - eMoveReference
     - :ref:`MOVE_REFERENCE <enum_move_reference>`
     - ``MOVE_REFERENCE_TOOL``
     - Coordinate reference frame for spiral motion (BASE / TOOL)

----

**Definition (Target Position)** |br|
``DRFLEx.h`` within class `CDRFLEx`, public section (line 804)

.. code-block:: cpp

   bool move_spiral(TASK_AXIS eTaskAxis,
                    float fRevolution,
                    float fTargetPos[3],
                    float fTargetVel[2],
                    float fTargetAcc[2],
                    float fTargetTime = 0.f,
                    MOVE_REFERENCE eMoveReference = MOVE_REFERENCE_TOOL,
                    MOVE_MODE eMoveMode = MOVE_MODE_ABSOLUTE,
                    SPIRAL_DIR eSpiralDir = DR_SPIRAL_OUTWARD,
                    ROT_DIR eRotDir = DR_ROT_FORWARD) {
       return _move_spiral_ex(_rbtCtrl, eTaskAxis, fRevolution, fTargetPos,
                              fTargetVel, fTargetAcc, fTargetTime, eMoveReference,
                              eMoveMode, eSpiralDir, eRotDir);
   };

This overload defines the spiral endpoint using **X, Y, Z coordinates** instead of maximum radius
and length. It also adds control over **spiral direction**, **rotation direction**, and **move mode**
(absolute/relative). It internally calls ``_move_spiral_ex`` instead of ``_move_spiral``.

**Parameter**

.. list-table::
   :widths: 22 20 18 40
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - eTaskAxis
     - :ref:`TASK_AXIS <enum_task_axis>`
     - -
     - Axis perpendicular to the spiral surface |br|
       (defines rotation plane for the spiral path)
   * - fRevolution
     - float
     - -
     - Total number of spiral revolutions [rev > 0]
   * - fTargetPos
     - float[3]
     - -
     - Target point as X, Y, Z coordinates [mm] |br|
       (replaces fMaximuRadius / fMaximumLength)
   * - fTargetVel
     - float[2]
     - -
     - Linear and angular velocity [mm/s, deg/s]
   * - fTargetAcc
     - float[2]
     - -
     - Linear and angular acceleration [mm/s\ :sup:`2`, deg/s\ :sup:`2`]
   * - fTargetTime
     - float
     - 0.0
     - Total execution time [sec]
   * - eMoveReference
     - :ref:`MOVE_REFERENCE <enum_move_reference>`
     - ``MOVE_REFERENCE_TOOL``
     - Coordinate reference frame for spiral motion (BASE / TOOL)
   * - eMoveMode
     - :ref:`MOVE_MODE <enum_move_mode>`
     - ``MOVE_MODE_ABSOLUTE``
     - Movement basis (absolute or relative)
   * - eSpiralDir
     - :ref:`SPIRAL_DIR <enum_spiral_dir>`
     - ``DR_SPIRAL_OUTWARD``
     - Radial direction of the spiral |br|
       ``DR_SPIRAL_OUTWARD``: expand outward from center |br|
       ``DR_SPIRAL_INWARD``: contract inward toward target
   * - eRotDir
     - :ref:`ROT_DIR <enum_rot_dir>`
     - ``DR_ROT_FORWARD``
     - Rotation direction along the axis |br|
       ``DR_ROT_FORWARD``: forward rotation (+) |br|
       ``DR_ROT_REVERSE``: reverse rotation (-)

.. Note::

  - ``fRevolution`` sets the **number of rotations** in the spiral trajectory.  
  - ``fMaximuRadius`` defines the **final radius** of the spiral.  
  - ``fMaximumLength`` specifies the **distance traveled along the spiral axis**,  
    with negative values moving in the opposite axial direction.  
  - ``fTargetVel`` and ``fTargetAcc`` control the linear and angular speed profiles.  
  - When ``fTargetTime`` is provided, motion is timed and velocity/acceleration are ignored.  
  - ``eTaskAxis`` selects which plane the spiral lies on (e.g., `TASK_AXIS_Z` for XY-plane spirals).  
  - ``eMoveReference`` defines the reference frame (BASE or TOOL).  
  - This function does **not support online blending** with other motion commands.

  .. figure:: /tutorials/images/mode/movespiral_overview2.png
   :alt: movespiral_overview2
   :width: 80%
   :align: center

  .. raw:: html
        
    <br>

.. Caution:: 

  - If the rotating acceleration generated by the spiral exceeds a safe limit,  
    the system may trigger an error for protection.  
    Reduce ``fTargetVel``, ``fTargetAcc``, or ``fTargetTime`` accordingly.

**Return**

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - **Value**
     - **Description**
   * - 0
     - Error
   * - 1
     - Success

**Example**

.. code-block:: cpp

   // Perform a spiral motion along the TOOL-Z axis
   float rev = 3;       // 3 full rotations
   float rmax = 30;     // Maximum radius: 30 mm
   float lmax = 50;     // Moves 50 mm in Z-axis direction
   float tvel[2] = {50, 50};    // Linear/Angular velocity
   float tacc[2] = {100, 100};  // Linear/Angular acceleration

   drfl.move_spiral(TASK_AXIS_Z, rev, rmax, lmax, tvel, tacc);
   // Moves the robot in a spiral expanding outward (radius 30 mm)
   // while ascending 50 mm along the Z-axis over 3 turns.

This command is commonly used for polishing, surface scanning, or coating applications  
where a smooth helical trajectory with radial expansion is required.