You're reading the documentation for an older, but still supported version (1.33.4).
For information on the latest version, please have a look at 1.33.5.

calc_coord

This function computes a new user Cartesian coordinate system by using up to 4 input poses (fTargetPos1-fTargetPos4) and an input mode (nInputMode). The reference system is defined by eTargetRef. This feature is available in controller firmware M2.5 or higher.

Depending on the number of input points and the mode, the algorithm determines the X-, Y-, and Z-axis directions as follows:

• 1 point (`nCnt = 1`) → The coordinate system is identical to the pose of fTargetPos1.

• 2 points (`nCnt = 2`) - nInputMode = 0: X-axis runs from x1 to x2. Z-axis is the current Tool-Z direction projected onto the plane orthogonal to the X-axis. The origin is x1. - nInputMode = 1: Z-axis is defined based on the Z direction of x1, orthogonalized against the X-axis.

• 3 points (`nCnt = 3`) → X-axis is defined by x1 → x2, Z-axis by the cross product of (x2 - x1) and (x3 - x1).

• 4 points (`nCnt = 4`) → Same as the 3-point definition, but uses the 4th point for orientation refinement.

Definition
DRFLEx.h within class CDRFLEx, public section

LPROBOT_POSE calc_coord(
    unsigned short nCnt,
    unsigned short nInputMode,
    COORDINATE_SYSTEM eTargetRef,
    float fTargetPos1[NUM_TASK],
    float fTargetPos2[NUM_TASK],
    float fTargetPos3[NUM_TASK],
    float fTargetPos4[NUM_TASK]
) {
    return _calc_coord(_rbtCtrl, nCnt, nInputMode, eTargetRef, fTargetPos1, fTargetPos2, fTargetPos3, fTargetPos4);
};

Parameter

Parameter Name	Data Type	Default Value	Description
nCnt	unsigned short		Number of input task poses (1-4).
nInputMode	unsigned short		Mode selector (valid only when `nCnt = 2`) 0: Z-axis defined by current tool direction 1: Z-axis defined by X1’s Z direction
eTargetRef	COORDINATE_SYSTEM		Reference coordinate system for calculation.
fTargetPos1	float[6]		Task-space pose of point #1.
fTargetPos2	float[6]		Task-space pose of point #2.
fTargetPos3	float[6]		Task-space pose of point #3.
fTargetPos4	float[6]		Task-space pose of point #4 (optional).

Return

Value	Description
LPROBOT_POSE	The resulting coordinate system (origin and orientation) expressed as a pose structure.

Note

This call waits for the controller to answer.

The returned pointer refers to storage in the CDRFLEx object that other DRFL calls and every reconnect reuse; copy the structure before making another DRFL call. The 3-argument ikin returns its result in storage shared by all CDRFLEx objects in the process instead; see ikin. Except for get_user_home, the pointer is never NULL; do not use a NULL check to detect failure.

Example

float pos1[6] = { 200.f, 30.f, 150.f, 0.f, 0.f, 0.f };
float pos2[6] = { 300.f, 30.f, 150.f, 0.f, 0.f, 0.f };
float pos3[6] = { 300.f, 80.f, 150.f, 0.f, 0.f, 45.f };
float pos4[6] = { 200.f, 80.f, 150.f, 0.f, 0.f, 0.f };

LPROBOT_POSE new_user = drfl.calc_coord(
    4,                     // use 4 points
    0,                     // mode 0
    COORDINATE_SYSTEM_BASE,
    pos1, pos2, pos3, pos4
);

for (int i = 0; i < NUM_TASK; ++i)
    printf("%.1f\n", new_user->_fPosition[i]);

This example calculates a new coordinate system using four task-space poses, returns the result in new_user, and prints the calculated origin and axes. It is commonly used to define User Frames or perform 3-point plane calibration.