.. _enable_alter_motion:

enable_alter_motion
------------------------------------------
The ``enable_alter_motion()`` and :ref:`alter_motion <alter_motion>` functions make it possible to alter the motion trajectory.

This function sets the configuration for the alter function and allows the input quantity of alter_motion() to be applied to the motion trajectory. Alter motion is generated in segments of iCycleTime x 10 ms. iCycleTime must be 1 to 254; see the Caution below. This function provides 2 modes (accumulation mode and increment mode). The input quantity of alter_motion() can be applied to the motion trajectory in two ways: as an accumulated value or as an increment value. In accumulation mode, the input quantity is the absolute altering amount (dX,dY,dZ,dRX,dRY,dRZ) from the current motion trajectory.

In increment mode, by contrast, the input quantity is the increment from the previous absolute altering amount. The reference coordinate can be changed through the input parameter ref. The limits on the accumulated amount and the increment amount can be set through the input parameters fLimitDpos (accumulated limit) and fLimitDposPer (increment input limit during 1 cycle). The actual alter amount is limited to these limits.

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

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

.. code-block:: cpp

    bool enable_alter_motion(int iCycleTime,
                             PATH_MODE ePathMode,
                             COORDINATE_SYSTEM eTargetRef,
                             float fLimitDpos[2],
                             float fLimitDposPer[2]) {
        return _enable_alter_motion(_rbtCtrl, iCycleTime, ePathMode, eTargetRef, fLimitDpos, fLimitDposPer);
    };

**Parameter**

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

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - iCycleTime
     - int
     - -
     - Alter motion is generated in segments of iCycleTime x 10 ms. Valid range: 1 to 254. The controller refuses 0 and 255 with an alter-motion input error.
   * - ePathMode
     - :ref:`PATH_MODE <enum_path_mode>`
     - -
     - Path interpolation mode.
   * - eTargetRef
     - :ref:`COORDINATE_SYSTEM <enum_coordinate_system>`
     - -
     - Coordinate frame in which alter motion commands are applied. |br|
       Typical values: ``COORDINATE_SYSTEM_BASE``, ``COORDINATE_SYSTEM_TOOL``.
   * - fLimitDpos
     - float[2]
     - -
     - Maximum translation limits. |br|
       [0]: Linear displacement limit (mm) |br|
       [1]: Orientation change limit (deg) |br|
       With both elements at ``-10000`` the accumulated amount is not limited.
   * - fLimitDposPer
     - float[2]
     - -
     - Limit on the alter amount per cycle. |br|
       [0]: Linear displacement limit per cycle (mm) |br|
       [1]: Orientation change limit per cycle (deg) |br|
       With both elements at ``-10000`` the amount per cycle is not limited.

**Return**

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

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

.. Caution::

   Values of ``iCycleTime`` above 255 are applied modulo 256; for example, 257 is applied as 1 (10 ms). Values whose remainder is 0 or 255 are refused with a warning. Pass only values from 1 to 254.

**Example**

.. code-block:: cpp

   // 1) Enable alter motion mode (20 x 10 ms = 200 ms cycle)
   float limitDpos[2] = {5.0f, 3.0f};       // max linear/orient displacement
   float limitDposPer[2] = {0.5f, 0.3f};    // per-cycle delta limits
   drfl.enable_alter_motion(20, PATH_MODE_DPOS, COORDINATE_SYSTEM_TOOL,
                            limitDpos, limitDposPer);

   // 2) Apply small delta adjustments while motion is running
   for (int i = 0; i < 50; ++i) {
       float delta[6] = {0.1f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};
       drfl.alter_motion(delta);
       std::this_thread::sleep_for(std::chrono::milliseconds(200));
   }

   // 3) Disable alter motion mode after fine-tuning
   drfl.disable_alter_motion();

This example demonstrates how to **activate alter motion**, apply small position corrections at each control cycle,  
and safely disable it after the fine-tuning process.  
Note that `alter_motion()` can be used only after `enable_alter_motion()` is called successfully,  
and must be executed within the configured limits for displacement and orientation.