3. robodk Module

This section is the reference of the robodk module. This module includes the Mat class to represent transformations in 3D. The robodk module is a robotics toolbox for Python, based on Peter Corke’s Robotics Toolbox (regarding pose transformations): http://petercorke.com/Robotics_Toolbox.html.

The following page provides a brief overview of the RoboDK API for Python:
https://www.robodk.com/offline-programming


A summary regarding the RoboDK API is available in the documentation: https://robodk.com/doc/en/RoboDK-API.html

3.1. Example

The following example uses the robodk and robolink libraries to move a robot.

from robolink import *              # import the robolink library (bridge with RoboDK)
from robodk import *                # import the robodk library (robotics toolbox)

RDK = Robolink()                    # establish a link with the simulator
robot = RDK.Item('KUKA KR210')      # retrieve the robot by name
robot.setJoints([0,90,-90,0,0,0])   # set the robot to the home position

target = robot.Pose()               # retrieve the current target as a pose (position of the active tool with respect to the active reference frame)
xyzabc = Pose_2_KUKA(target)        # Convert the 4x4 pose matrix to XYZABC position and orientation angles (mm and deg)

x,y,z,a,b,c = xyzabc                # Calculate a new pose based on the previous pose
xyzabc2 = [x,y,z+50,a,b,c+45]
target2 = KUKA_2_Pose(xyzabc2)      # Convert the XYZABC array to a pose (4x4 matrix)

robot.MoveJ(target2)                # Make a linear move to the calculated position

The following macro shows a basic example to move a robot along a hexagonal path:
/RoboDK/Library/SampleOfflineProgramming.py.

More examples are available in the Examples section.

3.2. robodk Module

robodk.Adept_2_Pose(xyzrpw)

Converts an Adept XYZRPW target to a pose (4x4 matrix)

robodk.Comau_2_Pose(xyzrpw)

Converts a Comau XYZRPW target to a pose (4x4 matrix), the same representation required by PDL Comau programs.

robodk.DateCreated(filepath, stringformat=False)

Returns the time that a file was modified

robodk.DateModified(filepath, stringformat=False)

Returns the time that a file was modified

robodk.DirExists(folder)

Returns true if the folder exists

robodk.FileExists(file)

Returns true if the file exists

robodk.KUKA_2_Pose(xyzrpw)

Converts a KUKA XYZABC target to a pose (4x4 matrix), required by KUKA KRC controllers.

robodk.LoadList(strfile, separator=', ', codec='utf-8')

Load data from a CSV file or a TXT file to a list of numbers

Example:


csvdata = LoadList(strfile, ‘,’) values = [] for i in range(len(csvdata)):

print(csvdata[i]) values.append(csvdata[i])
robodk.LoadMat(strfile, separator=', ')

Load data from a CSV file or a TXT file to a Mat Matrix

See also

LoadList()

class robodk.Mat(rows=None, ncols=None)

Mat is a matrix object. The main purpose of this object is to represent a pose in the 3D space (position and orientation).

A pose is a 4x4 matrix that represents the position and orientation of one reference frame with respect to another one, in the 3D space.

Poses are commonly used in robotics to place objects, reference frames and targets with respect to each other.

Example:

from robolink import *                  # import the robolink library
from robodk import *                    # import the robodk library

RDK = Robolink()                        # connect to the RoboDK API
robot  = RDK.Item('', ITEM_TYPE_ROBOT)  # Retrieve a robot available in RoboDK
#target  = RDK.Item('Target 1')         # Retrieve a target (example)


pose = robot.Pose()                     # retrieve the current robot position as a pose (position of the active tool with respect to the active reference frame)
# target = target.Pose()                # the same can be applied to targets (taught position)

# Read the 4x4 pose matrix as [X,Y,Z , A,B,C] Euler representation (mm and deg): same representation as KUKA robots
XYZABC = Pose_2_KUKA(target)
print(XYZABC)

# Read the 4x4 pose matrix as [X,Y,Z, q1,q2,q3,q4] quaternion representation (position in mm and orientation in quaternion): same representation as ABB robots (RAPID programming)
xyzq1234 = Pose_2_ABB(target)
print(xyzq1234)

# Read the 4x4 pose matrix as [X,Y,Z, u,v,w] representation (position in mm and orientation vector in radians): same representation as Universal Robots
xyzuvw = Pose_2_UR(target)
print(xyzuvw)

x,y,z,a,b,c = XYZABC                    # Use the KUKA representation (for example) and calculate a new pose based on the previous pose
XYZABC2 = [x,y,z+50,a,b,c+45]
pose2 = KUKA_2_Pose(XYZABC2)            # Convert the XYZABC array to a pose (4x4 matrix)

robot.MoveJ(pose2)                      # Make a joint move to the new position
# target.setPose(pose2)                  # We can also update the pose to targets, tools, reference frames, objects, ...
Offset(x, y, z, rx=0, ry=0, rz=0)

Calculates a relative target with respect to the reference frame coordinates. X,Y,Z are in mm, W,P,R are in degrees.

Pos()

Returns the position of a pose (assumes that a 4x4 homogeneous matrix is being used)

RelTool(x, y, z, rx=0, ry=0, rz=0)

Calculates a target relative with respect to the tool coordinates. X,Y,Z are in mm, W,P,R are in degrees. The behavior of this function is the same as ABB’s RAPID RelTool command.

SaveMat(strfile)

Save Mat Matrix to a CSV or TXT file

VX()

Returns the X vector of a pose (assumes that a 4x4 homogeneous matrix is being used)

VY()

Returns the Y vector of a pose (assumes that a 4x4 homogeneous matrix is being used)

VZ()

Returns the Z vector of a pose (assumes that a 4x4 homogeneous matrix is being used)

catH(mat2)

Concatenate with another matrix (horizontal concatenation)

catV(mat2)

Concatenate with another matrix (vertical concatenation)

eye(m=4)

Make identity matrix of size (mxm)

invH()

Calculates the inverse of a homogeneous matrix

isHomogeneous()

returns 1 if it is a Homogeneous matrix

list()

Returns the first column of the matrix as a list

list2()

Returns the matrix as list of lists (one list per column)

setPos(newpos)

Sets the XYZ position of a pose (assumes that a 4x4 homogeneous matrix is being used)

setVX(v_xyz)

Sets the VX vector of a pose, which is the first column of a homogeneous matrix (assumes that a 4x4 homogeneous matrix is being used)

setVY(v_xyz)

Sets the VY vector of a pose, which is the first column of a homogeneous matrix (assumes that a 4x4 homogeneous matrix is being used)

setVZ(v_xyz)

Sets the VZ vector of a pose, which is the first column of a homogeneous matrix (assumes that a 4x4 homogeneous matrix is being used)

size(dim=None)

Returns the size of a matrix (m,n). Dim can be set to 0 to return m (rows) or 1 to return n (columns)

tolist()

Returns the first column of the matrix as a list

tr()

Returns the transpose of the matrix

exception robodk.MatrixError

An exception class for Matrix

robodk.Motoman_2_Pose(xyzwpr)

Converts a Motoman target to a pose (4x4 matrix)

robodk.Nachi_2_Pose(xyzwpr)

Converts a Nachi XYZRPW target to a pose (4x4 matrix)

robodk.Offset(target_pose, x, y, z, rx=0, ry=0, rz=0)

Calculates a relative target with respect to the reference frame coordinates. X,Y,Z are in mm, RX,RY,RZ are in degrees.

Parameters:
  • x (float) – translation along the Reference X axis (mm)
  • y (float) – translation along the Reference Y axis (mm)
  • z (float) – translation along the Reference Z axis (mm)
  • rx (float) – rotation around the Reference X axis (deg) (optional)
  • ry (float) – rotation around the Reference Y axis (deg) (optional)
  • rz (float) – rotation around the Reference Z axis (deg) (optional)
robodk.Pose_2_ABB(H)

Converts a pose to an ABB target (using quaternion representation).

Parameters:H (Mat) – pose
robodk.Pose_2_Adept(H)

Converts a pose to an Adept target

Parameters:H (Mat) – pose
robodk.Pose_2_Comau(H)

Converts a pose to a Comau target, the same representation required by PDL Comau programs.

Parameters:H (Mat) – pose
robodk.Pose_2_Fanuc(H)

Converts a pose (4x4 matrix) to a Fanuc XYZWPR target

Parameters:H (Mat) – pose
robodk.Pose_2_KUKA(H)

Converts a pose (4x4 matrix) to an XYZABC KUKA target (Euler angles), required by KUKA KRC controllers.

Parameters:H (Mat) – pose
robodk.Pose_2_Motoman(H)

Converts a pose (4x4 matrix) to a Motoman XYZWPR target

Parameters:H (Mat) – pose
robodk.Pose_2_Nachi(pose)

Converts a pose to a Nachi XYZRPW target

Parameters:pose (Mat) – pose
robodk.Pose_2_Staubli(H)

Converts a pose (4x4 matrix) to a Staubli XYZWPR target

Parameters:H (Mat) – pose
robodk.Pose_2_TxyzRxyz(H)

Converts a pose to a 6-value target as [x,y,z,rx,ry,rz] so that H = transl(x,y,z)*rotx(rx)*roty(ry)*rotz(rz).

Parameters:H (Mat) – pose
robodk.Pose_2_UR(pose)

Calculate the p[x,y,z,u,v,w] position with rotation vector for a pose target. This is the same format required by Universal Robot controllers.

robodk.RelTool(target_pose, x, y, z, rx=0, ry=0, rz=0)

Calculates a relative target with respect to the tool coordinates. This procedure has exactly the same behavior as ABB’s RelTool instruction. X,Y,Z are in mm, W,P,R are in degrees.

Parameters:
  • x (float) – translation along the Tool X axis (mm)
  • y (float) – translation along the Tool Y axis (mm)
  • z (float) – translation along the Tool Z axis (mm)
  • rx (float) – rotation around the Tool X axis (deg) (optional)
  • ry (float) – rotation around the Tool Y axis (deg) (optional)
  • rz (float) – rotation around the Tool Z axis (deg) (optional)
robodk.RemoveDirFTP(ftp, path)

Recursively delete a directory tree on a remote server.

robodk.RemoveFileFTP(ftp, filepath)

Delete a file on a remote server.

robodk.TxyzRxyz_2_Pose(xyzrpw)

Calculates the pose from the position and euler angles ([x,y,z,rx,ry,rz] array)

Parameters:xyzrpw (list of float) – [x,y,z,rx,ry,rz] in mm and radians

The result is the same as calling: H = transl(x,y,z)*rotx(rx)*roty(ry)*rotz(rz)

robodk.UR_2_Pose(xyzwpr)

Calculate the pose target given a p[x,y,z,u,v,w] cartesian target with rotation vector. This is the same format required by Universal Robot controllers.

robodk.UploadDirFTP(localpath, server_ip, remote_path, username, password)

Upload a folder to a robot through FTP recursively

robodk.UploadFTP(program, robot_ip, remote_path, ftp_user, ftp_pass)

Upload a program or a list of programs to the robot through FTP provided the connection parameters

robodk.UploadFileFTP(file_path_name, server_ip, remote_path, username, password)

Upload a file to a robot through FTP

robodk.acos(value)

Returns the arc cosinus in radians

robodk.add3(a, b)

Adds two 3D vectors c=a+b

robodk.angle3(a, b)

Returns the angle in radians of two 3D vectors

robodk.angles_2_joints(jin, type)

Converts the angles between links into the robot motor space depending on the type of the robot.

robodk.asin(value)

Returns the arc sinus in radians

robodk.atan2(y, x)

Returns angle of a 2D coordinate in the XY plane

robodk.catH(mat1, mat2)

Concatenate 2 matrices (horizontal concatenation)

robodk.catV(mat1, mat2)

Concatenate 2 matrices (vertical concatenation)

robodk.cos(value)

Returns the cosinus of an angle in radians

robodk.cross(a, b)

Returns the cross product of two 3D vectors

robodk.dh(rz, tx=None, tz=None, rx=None)

Returns the Denavit-Hartenberg 4x4 matrix for a robot link. calling dh(rz,tx,tz,rx) is the same as using rotz(rz)*transl(tx,0,tx)*rotx(rx) calling dh(rz,tx,tz,rx) is the same as calling dh([rz,tx,tz,rx])

robodk.dhm(rx, tx=None, tz=None, rz=None)

Returns the Denavit-Hartenberg Modified 4x4 matrix for a robot link (Craig 1986).

calling dhm(rx,tx,tz,rz) is the same as using rotx(rx)*transl(tx,0,tx)*rotz(rz)

calling dhm(rx,tx,tz,rz) is the same as calling dhm([rx,tx,tz,rz])

robodk.distance(a, b)

Calculates the distance between two points

robodk.dot(a, b)

Returns the dot product of two 3D vectors

robodk.eye(size=4)

Returns the identity matrix

T(t_x, t_y, t_z) = \begin{bmatrix} 1 & 0 & 0 & 0 \\
0 & 1 & 0 & 0 \\
0 & 0 & 1 & 0 \\
0 & 0 & 0 & 1
\end{bmatrix}

Parameters:size (int) – square matrix size (4 by default)
robodk.fitPlane(points)

Best fits a plane to a cloud of points

robodk.getBaseName(filepath)

Returns the file name and extension of a file path

robodk.getFileDir(filepath)

Returns the directory of a file path

robodk.getFileName(filepath)

Returns the file name (with no extension) of a file path

robodk.getOpenFile(path_preference='C:/RoboDK/Library/')

Pop up a file dialog window to select a file to open.

robodk.getSaveFile(path_preference='C:/RoboDK/Library/', strfile='file.txt', strtitle='Save file as ...')

Pop up a file dialog window to select a file to save.

robodk.intersect_line_2_plane(pline, vline, pplane, vplane)

Calculates the intersection betweeen a line and a plane

robodk.invH(matrix)

Returns the inverse of a homogeneous matrix

Parameters:matrix (Mat) – pose
robodk.joints_2_angles(jin, type)

Converts the robot encoders into angles between links depending on the type of the robot.

robodk.mbox(msg, b1='OK', b2='Cancel', frame=True, t=False, entry=None)

Create an instance of MessageBox, and get data back from the user.

Parameters:
  • msg (str) – string to be displayed
  • b1 (str, tuple) – left button text, or a tuple (<text for button>, <to return on press>)
  • b2 (str, tuple) – right button text, or a tuple (<text for button>, <to return on press>)
  • frame (bool) – include a standard outerframe: True or False
  • t (int, float) – time in seconds (int or float) until the msgbox automatically closes
  • entry (None, bool, str) – include an entry widget that will provide its contents returned. Provide text to fill the box

Example:


name = mbox(‘Enter your name’, entry=True) name = mbox(‘Enter your name’, entry=’default’) if name:

print(“Value: ” + name)

value = mbox(‘Male or female?’, (‘male’, ‘m’), (‘female’, ‘f’)) mbox(‘Process done’)

robodk.mult3(v, d)

Multiplies a 3D vector to a scalar

robodk.name_2_id(str_name_id)

Returns the number of a numbered object. For example: “Frame 3” returns 3

robodk.norm(p)

Returns the norm of a 3D vector

robodk.normalize3(a)

Returns the unitary vector

robodk.pause(seconds)

Pause in seconds

Parameters:pause (float) – time in seconds
robodk.point_Zaxis_2_pose(point, zaxis, yaxis_hint1=[0, 0, 1], yaxis_hint2=[0, 1, 1])

Returns a pose given the origin as a point, a Z axis and a preferred orientation for the Y axis

robodk.pose_2_quaternion(Ti)

Returns the quaternion orientation vector of a pose (4x4 matrix)

Parameters:Ti (Mat) – pose
robodk.pose_2_xyzrpw(H)

Calculates the equivalent position and euler angles ([x,y,z,r,p,w] array) of the given pose according to the following operation:

Parameters:H (Mat) – pose
Returns:[x,y,z,w,p,r] in mm and deg

Uses the following order: transl(x,y,z)*rotz(w*pi/180)*roty(p*pi/180)*rotx(r*pi/180)

robodk.pose_angle(pose)

Returns the angle in radians of a 4x4 matrix pose

Parameters:pose (Mat) – pose
robodk.pose_angle_between(pose1, pose2)

Returns the angle in radians between two poses (4x4 matrix pose)

robodk.print_pose_ABB(pose)

Displays an ABB RAPID target (the same way it is displayed in IRC5 controllers).

Parameters:pose (Mat) – pose
robodk.proj_pt_2_line(point, paxe, vaxe)

Projects a point to a line

robodk.proj_pt_2_plane(point, planepoint, planeABC)

Projects a point to a plane

robodk.quaternion_2_pose(qin)

Returns the pose orientation matrix (4x4 matrix) from a quaternion orientation vector

robodk.rotx(rx)

Returns a rotation matrix around the X axis

R_x(\theta) = \begin{bmatrix} 1 & 0 & 0 & 0 \\
0 & c_\theta & -s_\theta & 0 \\
0 & s_\theta & c_\theta & 0 \\
0 & 0 & 0 & 1
\end{bmatrix}

Parameters:rx (float) – rotation around X axis in radians

See also

transl(), roty(), roty()

robodk.roty(ry)

Returns a rotation matrix around the Y axis

R_y(\theta) = \begin{bmatrix} c_\theta & 0 & s_\theta & 0 \\
0 & 1 & 0 & 0 \\
-s_\theta & 0 & c_\theta & 0 \\
0 & 0 & 0 & 1
\end{bmatrix}

Parameters:ry (float) – rotation around Y axis in radians

See also

transl(), rotx(), rotz()

robodk.rotz(rz)

Returns a rotation matrix around the Z axis

R_x(\theta) = \begin{bmatrix} c_\theta & -s_\theta & 0 & 0 \\
s_\theta & c_\theta & 0 & 0 \\
0 & 0 & 1 & 0 \\
0 & 0 & 0 & 1
\end{bmatrix}

Parameters:ry (float) – rotation around Y axis in radians

See also

transl(), rotx(), roty()

robodk.searchfiles(pattern='C:\\RoboDK\\Library\\*.rdk')

List the files in a directory with a given extension

robodk.sin(value)

Returns the sinus of an angle in radians

robodk.size(matrix, dim=None)

Returns the size of a matrix (m,n). Dim can be set to 0 to return m (rows) or 1 to return n (columns)

Parameters:
  • matrix (Mat) – pose
  • dim (int) – dimension
robodk.sqrt(value)

Returns the square root of a value

robodk.subs3(a, b)

Subtracts two 3D vectors c=a-b

robodk.tic()

Start a stopwatch timer

robodk.toc()

Read the stopwatch timer

robodk.tr(matrix)

Returns the transpose of the matrix

Parameters:matrix (Mat) – pose
robodk.transl(tx, ty=None, tz=None)

Returns a translation matrix

T(t_x, t_y, t_z) = \begin{bmatrix} 1 & 0 & 0 & t_x \\
0 & 1 & 0 & t_y \\
0 & 0 & 1 & t_z \\
0 & 0 & 0 & 1
\end{bmatrix}

Parameters:
  • tx (float) – translation along the X axis
  • ty (float) – translation along the Y axis
  • tz (float) – translation along the Z axis

See also

rotx(), roty(), rotz()

robodk.xyzrpw_2_pose(xyzrpw)

Calculates the pose from the position and euler angles ([x,y,z,r,p,w] array) The result is the same as calling: H = transl(x,y,z)*rotz(w*pi/180)*roty(p*pi/180)*rotx(r*pi/180)