Coordinate Systems

Certain movement operations provided by this library allow the specification of a coordinate system in which the motion is executed. Coordinate systems may be predefined such as the robot coordinate system, tool coordinate system, or camera coordinate system or they may be defined by the user. User-defined coordinate systems offer flexibility and can represent arbitrary frames of reference. These may be static or dynamic; in the latter case, they can be updated or manipulated at runtime to reflect changing conditions or inputs.

New coordinate systems are defined by a pose that is expressed relative to the robot coordinate system.

The joint coordinate system is a special case as it is defined in joint space rather than Cartesian space. Manipulating the joint coordinate system is rarely necessary and is therefore not supported.

Note

Manipulating coordinate systems is currently only supported for robots within the Victor Robot Behavior Group.

Available coordinate systems for robots with Victor behavior are:

class CSVictor(value)

An enum representing the coordinate systems for robots with Victor behavior.

ROBOT = 1

TOOL = 2

CAMERA = 3

USER1 = 4

USER2 = 5

USER3 = 6

USER4 = 7

USER5 = 8

USER6 = 9

USER7 = 10

USER8 = 11

USER9 = 12

USER10 = 13

USER11 = 14

USER12 = 15

USER13 = 16

USER14 = 17

USER15 = 18

USER16 = 19

Reading a Coordinate System

In order to get the origin of a user configured coordinate system as CartesianPose in robot coordinates use the get_cs_origin_v() method. Note that reading non user defined coordinate systems is not supported.

usercs_1_origin = robot.get_cs_origin_v(CSVictor.USER1)

Manipulating a Coordinate System

Manipulating coordinate systems is possible with the set_cs_origin_v() method. The coordinate system to manipulate as well as the the origin must be provided as arguments.

robot.set_cs_origin_v(CSVictor.USER1, HOME)

Full Example of Handling Coordinate Systems

The following example shows a simple application in which a coordinate system is manipulated.

Coordinate System example

"""A simple example on how to manipulate coordinate systems."""

import math
from collections.abc import Iterable
from math import radians
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    CartesianPose,
    CartesianTargetVictor,
    CoordinateSystemVictorTrait,
    CSVictor,
    GetTcpPoseTrait,
    JointPose,
    LifecycleTrait,
    MovePTPTrait,
    MovePTPVictorTrait,
    VorausErrorHandler,
    VorausIndustrialRobotArm,
    configure_logging,
)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401

HOME = JointPose().from_list(
    [radians(d) for d in [10, -120, 120, -100, -100, -10]]
)
FLAT = JointPose().from_list([radians(d) for d in [1, -1, 1, -1, -1, -1]])


@runtime_checkable
class _RequiredRobotTraits(
    CoordinateSystemVictorTrait,
    GetTcpPoseTrait,
    MovePTPTrait,
    MovePTPVictorTrait,
    LifecycleTrait,
    Protocol,
): ...


def _assert_poses_are_almost_equal(
    pose1: Iterable, pose2: Iterable
) -> None:
    assert all(
        math.isclose(v1, v2) for v1, v2 in zip(pose1, pose2, strict=True)
    )


def run_my_application(robot: _RequiredRobotTraits) -> None:
    """Example application."""
    robot.enable()
    # Get the home pose as Cartesian pose
    robot.move_ptp(HOME).result()
    home_cartesian = robot.get_tcp_pose()

    robot.move_ptp(FLAT).result()

    # Set the USERCS1 at the home pose
    robot.set_cs_origin_v(CSVictor.USER1, HOME)

    # Move to the origin of USERCS1
    robot.move_ptp_v(
        CartesianTargetVictor(CartesianPose(), CSVictor.USER1)
    ).result()

    # Assert that the origin of USERCS1 is indeed the home pose
    usercs_1_origin = robot.get_cs_origin_v(CSVictor.USER1)
    _assert_poses_are_almost_equal(home_cartesian, usercs_1_origin)

    # Assert that by driving to the origin of USERCS1 we reached
    # the home pose
    current_tcp_pose = robot.get_tcp_pose()
    _assert_poses_are_almost_equal(home_cartesian, current_tcp_pose)


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    error_handler = VorausErrorHandler()
    with robot.connect(host=VORAUS_CORE_HOST, port=VORAUS_CORE_PORT):
        run_my_application(robot)

Definition of the Coordinate System Methods

The coordinate system manipulation is defined in the CoordinateSystemVictorTrait:

CoordinateSystemVictorTrait

protocol CoordinateSystemVictorTrait

Trait to configure coordinate systems for Victor robots.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod set_cs_origin_v(cs, new_origin)

Define the origin of a specific coordinate system.

It is valid for robots with Victor behavior.

Parameters:

cs (CSVictor) – The coordinate system to set. Predefined non-user CS can not be set and are not allowed.
new_origin (JointPose | CartesianPose | CartesianTargetVictor) – The desired pose for the new origin. CartesianPose is interpreted in RobotCS. CartesianTargetVictor uses the defined CS.

Raises:

AttributeError – Setting non-user CS is not allowed. This exception will change to a ‘ValueError’ in the next major release. Consider using except (ValueError, AttributeError): when specifying exception handlers.

Return type:

None

abstractmethod get_cs_origin_v(cs)

Get the origin of a coordinate system.

It is valid for robots with Victor behavior.

Parameters:: cs (CSVictor) – The coordinate system of which the origin should be read. Predefined non-user CS can not be read.
Raises:: AttributeError – Reading non-user CS is not supported. This exception will change to a ‘ValueError’ in the next major release. Consider using except (ValueError, AttributeError): when specifying exception handlers.
Return type:: CartesianPose
Returns:: The Cartesian pose of the origin of the desired coordinate system in robot CS

Jogging

Pause and Continue