.. _alter_motion:

alter_motion
------------------------------------------
This function applies an **incremental adjustment** to the active motion trajectory  
after :ref:`enable_alter_motion <enable_alter_motion>` has been successfully activated.  
It allows fine control of the robot’s end-effector position and orientation in real time  
by sending small delta pose values at each control cycle.

Each call to `alter_motion()` modifies the current trajectory based on the provided `fTargetPos` offsets.  
The input values correspond to **X, Y, Z, Rx, Ry, Rz** displacements and rotations,  
which are interpreted according to the reference frame configured in `enable_alter_motion()`.

This function is available in **M2.4 version or higher**.

**Definition** |br|
``DRFLEx.h`` within class `CDRFLEx`, public section

.. code-block:: cpp

    bool alter_motion(float fTargetPos[NUM_TASK]) {
        return _alter_motion(_rbtCtrl, fTargetPos);
    };

**Parameter**

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

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - fTargetPos
     - float[6]
     - -
     - Array representing incremental motion values for the current cycle. |br|
       Order: **[X, Y, Z, Rx, Ry, Rz]** |br|
       Units: **mm** for translation, **deg** for rotation.

**Return**

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

   * - **Value**
     - **Description**
   * - 0
     - The robot is in a fault state, or the offset could not be sent.
   * - 1
     - The offset was sent, or alter motion is not enabled and nothing was sent.

**Example**

.. code-block:: cpp

   std::atomic<bool> g_bRunAlter(true);

   // Thread sending small incremental poses until asked to stop
   void ThreadFunc() {
       float delta[6] = {1.0f, 0.0f, 0.0f, 1.0f, 0.0f, 0.0f};  // ΔX=1mm, ΔRx=1° per cycle
       while (g_bRunAlter) {
           drfl.alter_motion(delta);
           std::this_thread::sleep_for(std::chrono::milliseconds(200));  // one 200 ms cycle
       }
   }

   // 1) Enable alter motion mode (20 x 10 ms = 200 ms cycle)
   float limitDpos[2] = {50.0f, 90.0f};
   float limitDposPer[2] = {5.0f, 50.0f};
   drfl.enable_alter_motion(20, PATH_MODE_DPOS, COORDINATE_SYSTEM_BASE,
                            limitDpos, limitDposPer);

   // 2) Start an asynchronous motion to alter (200 mm along X at 50 mm/s, about 4 s)
   float target[6] = {200.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};
   float vel[2] = {50.0f, 30.0f};
   float acc[2] = {100.0f, 60.0f};
   drfl.amovel(target, vel, acc, 0.f, MOVE_MODE_RELATIVE);

   // 3) Start the user thread; main makes no other drfl calls while it runs
   std::thread th(ThreadFunc);

   // 4) Let it run while the motion is active to apply incremental corrections
   std::this_thread::sleep_for(std::chrono::seconds(3));

   // 5) Stop the thread, then disable alter motion mode
   g_bRunAlter = false;
   th.join();
   drfl.disable_alter_motion();

**Caution**

- Call :ref:`enable_alter_motion <enable_alter_motion>` before ``alter_motion()``; while alter motion is not enabled, ``alter_motion()`` sends nothing and still returns true, so a true return does not confirm that the offset was applied.  
- Calls on one CDRFLEx object must be made one at a time: while ``alter_motion()`` is being sent periodically, make no other calls on the same object; see :ref:`Rules for callback functions <callback_rules>`.  
- The update rate must match the cycle time set in :ref:`enable_alter_motion <enable_alter_motion>`.  
- Offsets are applied only while a motion is running. Offsets sent while no motion is running are ignored; start the motion (for example with :ref:`amovel <auto_amovel>`) before sending offsets.  
- Input values follow **fixed XYZ notation**, and must not exceed configured limits (`fLimitDpos`, `fLimitDposPer`).