coordsys

namespace nin {
    template <coordsys_traits CT> class coordsys;
}

coordsys is the base class for all coordinate systems, regardless of the backend. It provides the minimum functionality common to every coordinate system:

  • Identity: two coordinate systems are equal only if they share the same backend object.

  • Tree traversal: tf_to_WCS() and tf_from_WCS() walk the kinematic tree to compute raw transformation data relative to WCS.

  • Linked copies: linked_copy() creates a second handle to the same backend so that coord_value, coord_cloud, and bridges can hold a reference to a coordinate system that tracks the original.

  • Origin queries: origin() and origin_to() express the coordinate system’s origin as a value or quantity.

Copying a coordsys clones its backend, producing an independent coordinate system. The copy is not equal to the original — it is a new object with the same initial state. To create a reference copy that is equal, use linked_copy().

Nested types

Type Definition

coordsys_traits

CT

quantity_type

CT::quantity_type

value_type

coord_value<CT>

tf_data_type

CT::tf_data_type

Member functions

(Constructor)

coordsys()

(1)

coordsys(WCS_t)

(2)

coordsys(coordsys const& copy)

(3)

coordsys(coordsys && move)

(4)

  • (1)-(2) Default and WCS constructors. Create a coordinate system at the world origin with no backend. coordsys(WCS_t) is a named alias for the default constructor — both produce a WCS-rooted coordinate system.

  • (3) Copy constructor. Clones the backend, creating an independent coordinate system. The lock state is not preserved: a copy of a locked coordsys starts unlocked.

  • (4) Move constructor.

operator =

assignment

coordsys & operator =(coordsys const& copy)

(1)

coordsys & operator =(coordsys && move)

(2)

  • (1) Copy assignment. Clones the backend (same semantics as the copy constructor). The lock state is not preserved.

  • (2) Move assignment.

operator ==

identity comparison

bool operator ==(coordsys const& rhs) const

(1)

Returns true if *this and rhs share the same backend object (pointer equality). Two independently constructed coordinate systems with identical parameters are not equal. Use linked_copy() to obtain a copy that compares equal.

tf_to_WCS

transformation to the world coordinate system

tf_data_type tf_to_WCS(unsigned hop_limit = 1024) const

(1)

Returns the raw transformation data from *this to WCS by traversing the kinematic tree. Throws hop_limit_exceeded_error (a std::runtime_error) if the tree traversal exceeds hop_limit hops. This typically indicates a cyclic coordinate system graph.

The shown default 1024 is the value of the project-wide constant pos_offset_default_hop_limit, which can be overridden by defining the POS_OFFSET_DEFAULT_HOP_LIMIT macro before the ninbot.pos module is built.

tf_from_WCS

transformation from the world coordinate system

tf_data_type tf_from_WCS(unsigned hop_limit = 1024) const

(1)

Returns the raw transformation data from WCS to *this. Equivalent to CT::invert_tf(tf_to_WCS(hop_limit)).

linked_copy

creates a linked copy

coordsys linked_copy() const

(1)

Returns a new coordsys that shares the same backend pointer. The returned object compares equal to *this. Mutations through one handle (e.g. moving the coordinate system) are visible through the other.

origin

origin point of this coordinate system

value_type origin() const

(1)

Returns the origin of this coordinate system as a coord_value in *this. The quantity is default-constructed (zero for numeric types).

origin_to

origin expressed in another coordinate system

quantity_type origin_to(coordsys inCS) const

(1)

Shortcut for mapCS(*this, inCS)(quantity_type{}). Returns the origin of *this expressed in inCS as a raw quantity.

lock

cache the result of tf_to_WCS()

void lock()

(1)

Computes tf_to_WCS() once and stores the result. While locked, every subsequent call to tf_to_WCS() returns the cached value without traversing the parent chain. The lock state is not preserved by copy or copy-assignment: a copy of a locked coordsys starts unlocked.

coordsys satisfies the Lockable named requirement, so std::unique_lock can be used for exception-safe locking:

{
    std::unique_lock lock {cs};
    coord_tf tf = mapCS(cs_a, cs_b);  // traversal stops at cs
}  // cs unlocked here

unlock

clear the cached tf_to_WCS() value

void unlock()

(1)

Clears the cache set by lock(). Subsequent calls to tf_to_WCS() resume full tree traversal.