.. _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** |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², deg/s²]
   * - 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)

.. 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.