9.2. Expressing series of numbers, points, vectors, and transforms in Kinetics Toolkit

In Kinetics Toolkit, numbers, points, vectors, and transforms are expressed as series, where the first dimension of any series corresponds to time. This is emphasized in the following examples:

9.2.1. Series of numbers (float, int)

Since a float or an integer has no dimension, a series of N floats or integers has one dimension of length N:

[x(t0), x(t1), x(t2), ...]

9.2.2. Series of points

Since a point has four coordinates (x, y, z, 1), then a series of N points has a shape of (N, 4):

[
    [x(t0), y(t0), z(t0), 1.0],
    [x(t1), y(t1), z(t1), 1.0],
    [x(t2), y(t2), z(t2), 1.0],
    [ ... ,  ... ,  ... , ...],
]

import kineticstoolkit.lab as ktk

ktk.geometry.create_point_series(
    x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0]
)

array([[1., 4., 7., 1.],
       [2., 5., 8., 1.],
       [3., 6., 9., 1.]])

9.2.3. Series of vectors

Since a vector has four coordinates (x, y, z, 0), a series of N vectors has a shape of (N, 4):

[
    [x(t0), y(t0), z(t0), 0.0],
    [x(t1), y(t1), z(t1), 0.0],
    [x(t2), y(t2), z(t2), 0.0],
    [ ... ,  ... ,  ... , ...],
]

The function ktk.geometry.create_vector_series creates such vector series:

ktk.geometry.create_vector_series(
    x=[1.0, 2.0, 3.0], y=[4.0, 5.0, 6.0], z=[7.0, 8.0, 9.0]
)

array([[1., 4., 7., 0.],
       [2., 5., 8., 0.],
       [3., 6., 9., 0.]])

9.2.4. Series of transforms

Since a transform has a shape of (4, 4), then a series of N frames has a shape of (N, 4, 4):

[
    [
        [R00(t0), R01(t0), R02(t0), px(t0)],
        [R10(t0), R11(t0), R12(t0), py(t0)],
        [R20(t0), R21(t0), R22(t0), pz(t0)],
        [    0.0,     0.0,     0.0,    1.0],
    ],
    [
        [R00(t1), R01(t1), R02(t1), px(t1)],
        [R10(t1), R11(t1), R12(t1), py(t1)],
        [R20(t1), R21(t1), R22(t1), pz(t1)],
        [    0.0,     0.0,     0.0,    1.0],
    ],
    ...
]

9.2.5. Series of point clouds

We can express M points together as an array of shape (4, M):

\[\begin{split} \begin{bmatrix} x_0 & x_1 & x_2 & ... \\ y_0 & y_1 & y_2 & ... \\ z_0 & z_1 & z_2 & ... \\ 1 & 1 & 1 & ... \end{bmatrix} \end{split}\]

Therefore, a series of N point clouds has a shape of (N, 4, M):

[
    [
        [x0(t0), x1(t0), x2(t0), ...],
        [y0(t0), y1(t0), y2(t0), ...],
        [z0(t0), z1(t0), z2(t0), ...],
        [   1.0,    1.0,    1.0, ...],
    ],
    [
        [x0(t1), x1(t1), x2(t1), ...],
        [y0(t1), y1(t1), y2(t1), ...],
        [z0(t1), z1(t1), z2(t1), ...],
        [   1.0,    1.0,    1.0, ...],
    ],
    ...
]

The same applies to series of vector clouds.

9.2.6. Time-invariant coordinates

Always ensure that the first dimension of any array is reserved to time, even for coordinates that do not vary in time. For example, the vector \([1, 2, 3, 0]\) must be expressed as [[1.0, 2.0, 3.0, 0.0]] (note the double brackets). Expressing it as [1.0, 2.0, 3.0, 0.0] (single brackets) would mean a series of 4 floats instead of one time-invariant vector.

A quick way to convert a constant array to a series is to use np.newaxis:

one_vector = np.array([1.0, 2.0, 3.0, 0.0])
series_of_one_vector = one_vector[np.newaxis]