POS Library Basic Notions

The notions explained in this section are essential in understanding how the POS Library works. More information and examples are available in the reference and tutorial pages.

The typical workflow for coordinate calculations is:

  1. Define the coordinate systems involved.

  2. Generate a transformation function from the current state of the hierarchy.

  3. Apply the transformation to a coordinate.

Key notions

Coordinates

Coordinate quantities and values

A coordinate quantity is a set of values describing a position, orientation, or other spatial quantity. Without context, it is just a measure: it only acquires meaning when associated with a coordinate system.

A coordinate value pairs the two, defining how those values map to the physical world.

Use quantities when computing or manipulating the raw numbers — arithmetic, interpolation, serialisation. Use values when the connection to the physical world must be preserved — transforming to another system, calculating distances.

Coordinate systems

A coordinate system is an abstract object that is used as reference to any associated coordinates. Multiple coordinate systems can coexist, each with its own origin and axes. The same physical point has different coordinate values in different coordinate systems.

Other frameworks call coordinate systems frames and relate them by parent-relative positions. Ninbot uses the broader term coordinate system, relating them by transformation functions instead, which supports general coordinate spaces where the notion of relative position does not apply.

Transformation functions

A coordinate transformation function converts the representation of coordinates from one coordinate system to another. It does not change the physical coordinates: only its numerical representation (the quantity). Transformation functions are optimized for performance. The downside is that after creating one, it cannot be modified.

Additional notions

The World Coordinate System

The World Coordinate System (nin::WCS) is the fixed root of the kinematic tree, or the reference against which all transformations are ultimately resolved. It is equivalent to a default-constructed coordinate system and can be used anywhere a coordinate system is expected.

mapCS

mapCS() is a factory of coordinate transformation functions between any two coordinate systems. It queries the coordinate systems for the necessary data, which may involve recursively traversing a kinematic chain or even accessing the network. For this reason, mapCS() is a potentially slow function.

The member functions map_to() and origin_to() are convenience functions of values and systems respectively that call mapCS() and invoke the transformation in one go. These functions discard the transformation function immediately after invoking it, so they are only recommended for one-shot coordinate transformations.

Coordinate clouds

Coordinate clouds are similar to values, but they hold a collection of quantities rather than a single one.

There are two flavors: The dynamic-extent clouds store the quantities in `std::vector`s, whereas fixed-size clouds use `std::array`s.

Backends

TODO

A coordinate system backend is the implementation object that gives a coordinate system its behaviour. Every coordinate system owns a backend, which is responsible for computing the transformation toward the World Coordinate System when mapCS() queries it.

The library provides built-in backends for the most common cases — child coordinate systems with a fixed offset, and live systems whose pose is read from an external source such as a physics engine.

The backend is an implementation detail of the coordinate system. Users interact exclusively with the coordsys object and never touch the backend directly, unless they are authoring a new backend.

Bridges

Coordinate bridges connect different coordinate spaces via conversion functions, allowing mapCS() to build transformation functions that cross boundaries of coordinate spaces.

For example, a bridge between Cartesian space and joint space uses forward kinematics to convert from joint coordinates to Cartesian coordinates, and inverse kinematics for the reverse direction.