R3::basic_translation

namespace nin::R3 {
    template <std::floating_point T>
    struct basic_translation;

    using translation = basic_translation<double>;
}

A 3D translation transformation. It shifts coordinates by (Δx, Δy, Δz) expressed as length quantities. Translations are composable, invertible and callable on basic_position_qty. Translations are transformations and cannot be associated to coordinate systems the way that position quantities can do.

The type alias R3::translation is provided for R3::basic_translation<double>.

Data members

Member Type

Δx

units::length_v<T>

Δy

units::length_v<T>

Δz

units::length_v<T>

Nested types

Type Definition

arithmetic_type

T

unit_type

units::length_v<T>

value_type

length

reference

length &

const_reference

length const&

size_type

std::size_t

difference_type

std::ptrdiff_t

iterator

forward iterator over the three components

const_iterator

const forward iterator over the three components

Member functions

(Constructor)

basic_translation()

(1)

basic_translation(length Δx0, length Δy0 = {}, length Δz0 = {})

(2)

  • (1) Default constructor. All components are zero.

  • (2) Component constructor.

Example
import ninbot;
using namespace nin;
int main() {
    R3::translation tran_0;                          // (0, 0, 0) (m)
    R3::translation tran_1 = {10_cm, 20_cm, 5_cm};   // (0.1, 0.2, 0.05) (m)
}

invert

inverts the translation in place

basic_translation & invert()

(1)

Inverts the transformation by negating all components.

Returns a reference to *this.

Example
import ninbot;
using namespace nin;
int main() {
    R3::translation tran = {10_cm, 20_cm, 5_cm};
    tran.invert();     // tran = (-10, -20, -5) (cm)
}

operator()

applies the translation to a point quantity

basic_position_qty<T> operator () (R3::basic_position_qty<T>)

(1)

Returns a new position quantity obtained by adding the translation to the input argument component-wise.

Example
import ninbot;
using namespace nin;
int main() {
    R3::point_qty   pt = {1_m, 2_m, 3_m};
    R3::translation tran = {10_cm, 20_cm, 0_m};
    R3::point_qty   pt2 = tran(pt);     // pt2 = (1.1, 2.2, 3) (m)
}

operator[]

component access by index

length & operator [] (size_type index)

(1)

length const& operator [] (size_type index) const

(2)

Index 0 returns Δx; index 1 returns Δy; any other index returns Δz.

begin, cbegin

iterator to the first component

iterator begin()

(1)

const_iterator begin() const

(2)

const_iterator cbegin() const

(3)

Returns an iterator to the Δx component.

Example
import ninbot;
using namespace nin;
int main() {
    R3::translation tran = {10_cm, 20_cm, 5_cm};
    for (units::length component : tran)
        { /* iterates over Δx, Δy, then Δz */ }
}

end, cend

sentinel

iterator end()

(1)

const_iterator end() const

(2)

const_iterator cend() const

(3)

Returns a sentinel for iterating over the components.

Example
import ninbot;
using namespace nin;
int main() {
    R3::translation tran = {10_cm, 20_cm, 5_cm};
    for (units::length component : tran)
        { /* iterates over Δx, Δy, then Δz */ }
}

size

number of components

static size_type size()

(1)

Returns 3.

max_size

maximum number of components

static size_type max_size()

(1)

Returns 3.

empty

whether the container holds no components

static bool empty()

(1)

Returns false.

operator==

equality comparison

friend bool operator == (basic_translation, basic_translation)

(1)

Componentwise equality.

Non-member functions

inv

inverse translation

basic_translation<T> inv(basic_translation<T>)

(1)

Returns the inverted translation of the argument.

Example
import ninbot;
using namespace nin;
int main() {
    R3::translation tran  = {10_cm, 20_cm, 5_cm};
    R3::translation trani = inv(tran);     // trani = (-10, -20, -5) (cm)
}

compose

composes two translations

basic_translation<T> compose(lhs, rhs)

(1)

Returns the translation whose effect is the composition of the two translations. Composition of translations is commutative.

Example
import ninbot;
using namespace nin;
int main() {
    R3::translation tran1 = {10_cm,  0_m,  3_m };
    R3::translation tran2 = { 0_m,  20_cm, 3_m };
    R3::translation tran  = compose(tran1, tran2);     // tran = (10, 20, 600) (cm)
}

std::formatter<>

STL overload for the std::format and std::print families.

std::format("{:<format-spec>}", t)

(1)

Adds a specialization of std::formatter that formats the three components in the order Δx, Δy, Δz.

The <format-spec> syntax is

[<float-spec>] [ "_" [<unit>] ] [ "|" <separator> ]

with the following rules:

  • <float-spec> — anything before the first _ or | is forwarded verbatim to the STL formatter for floating points and applied to formatting each component.

  • <unit> — the text between and | (or the end of the spec) selects the unit used both for the displayed values and the trailing unit label. When the is present but <unit> is empty, the unit label is suppressed and magnitudes are formatted in SI units.

  • Parentheses — when the format-spec contains no | separator, the output is wrapped in parentheses.

  • Separator — the text after | is placed between the components. The is not required in order to specify a separator: when is omitted, the trailing unit label is the default SI label (e.g. ` (m)), and parentheses are dropped as soon as `| is present. When neither _ nor | is given, <separator> defaults to ", ".

Example
import ninbot;
#include <print>
int main() {
    nin::R3::translation t = {1.5_m, 2.0_m, 300_mm};
    std::println("{}", t);                    // "(1.5, 2, 0.3) (m)"
    std::println("{:_}", t);                  // "(1.5, 2, 0.3)"
    std::println("{:|, }", t);                // "1.5, 2, 0.3 (m)"
    std::println("{:.2f| }", t);              // "1.50 2.00 0.30 (m)"
    std::println("{:_m|, }", t);              // "1.5, 2, 0.3 (m)"
    std::println("{:.2f_m}", t);              // "(1.50, 2.00, 0.30) (m)"
    std::println("{:.2f_m|; }", t);           // "1.50; 2.00; 0.30 (m)"
    std::println("({:.3f_cm| - })", t);       // "(150.000 - 200.000 - 30.000 (cm))"
    std::println("{:.2f_|, } m",    t);       // "1.50, 2.00, 0.30 m"
}