# Links, Coordinate Systems and LinkTree¶

## Link Concept¶

In the NxLib coordinate systems are implicitly defined by the concept of a *Link*. A *Link* is a Transformation
between two coordinate systems - as any other transformation in the NxLib - with the difference, that the names of the
associated coordinate systems are known to the NxLib.

## Coordinate Systems¶

Coordinate systems are either defined by a camera link or by user defined links. Each camera can store one *Link*
into a target coordinate system. The target coordinate system can either be the serial number of another camera or a
user defined coordinate system, which you can define in the Links node by providing a Transformation
between and the names of two coordinate systems.

By default, some of the NxLib’s commands use the following coordinate systems to refer to the world coordinate system (see below). Note that you can always choose the name of the target coordinate system of those commands freely.

“Workspace”if you performed a workspace calibration and did not change the default Target parameter.

“Workspace”or“Hand”if you performed a hand-eye calibration and did not change the default Target parameter.

## Link Tree¶

All links defined by a camera link or by the user defined links are internally combined into one link tree. The
following example shows how the NxLib would assemble its *LinkTree* from two camera links (blue) and five user defined
links representing a robot model (orange). The first camera “123” is mounted on the robot and moves around with it,
hence it has a static link to the robot hand. The second camera “456” is mounted somewhere in the world and has a
workspace calibration with target “Workspace”.

In case your link tree contains loops, links that are part of a loop are ignored so that cameras with links ending in a loop will use their own camera coordinate system as world coordinate system. User defined links that refer to a link that is part of a loop are not valid.

## World Coordinate System¶

The root of the link tree is called the world coordinate system. If your link tree consists of several subtrees, all
root nodes are assumed to be the world coordinate system and internally linked by an identity transformation. The world
coordinate system is always the target system of at least one link and it can either have a name or it can be the empty
string. A **named** world coordinate system can be created with a link that has a specified target system, which is
neither a camera serial nor specified in the user defined links node. The “Workspace” node in the above graph is an
example for a named world coordinate system. A **nameless** world coordinate system can be created with a link that has
an empty target system.

Whenever a camera computes 3D data, the resulting coordinates are in the world coordinate system. This is achieved by resolving the link chain from the camera to the root of the link tree by chaining the transformations along the path. The link chain stops when a world coordinate system has been reached. The result of the resolution is a Transformation from the camera to the world coordinate system. This transformation is then applied to the computed 3D data of the camera. If the camera has no link, the 3D data remains in the camera coordinate system (which at the same time is the world coordinate system).

Applying this to the above example, “Workspace” is the world coordinate system and both cameras “123” and “456” will compute 3D data in the coordinate system “Workspace”. If the robot model would not have been specified and “123” would still be linked to “Hand”, its 3D data would be in the “Hand” coordinate system. Note that the link from “RobotOrigin” to “Workspace” has to be specified, otherwise “RobotOrigin” would be considered the world coordinate system for “123”.