ktk.geometry.create_transform_series

create_transform_series(matrices=None, *, angles=None, seq=None, degrees=False, quaternions=None, scalar_first=False, x=None, y=None, z=None, xy=None, xz=None, yz=None, positions=None, length=None)

Create an Nx4x4 transform series from multiple input forms.

Matrix input form

If the input is a series of 3x3 rotation matrices or 4x4 homogeneous transforms, use this form:

ktk.geometry.to_transform_series(
    matrices: ArrayLike,
    *,
    positions: ArrayLike | None = None,
    length: int | None = None,
    ) -> np.ndarray

Angle input form

If the input is a series of Euler/cardan angles, use this form:

ktk.geometry.to_transform_series(
    *,
    angles: ArrayLike,
    seq: str,
    degrees: bool = False,
    positions: ArrayLike | None = None,
    length: int | None = None,
    ) -> np.ndarray

Quaternion input form

If the input is a series of quaternions, use this form:

ktk.geometry.to_transform_series(
    *,
    quaternions: ArrayLike,
    scalar_first: bool = False,
    positions: ArrayLike | None = None,
    length: int | None = None,
    ) -> np.ndarray

Vector input form (using cross-product)

To create transform series that represent a local coordinate system based on the cross product of different vectors, use this form, where one of {x, y, z} and one of {xy, xz, yz} must be defined:

ktk.geometry.to_transform_series(
    *,
    x: ArrayLike | None = None,
    y: ArrayLike | None = None,
    z: ArrayLike | None = None,
    xy: ArrayLike | None = None,
    xz: ArrayLike | None = None,
    yz: ArrayLike | None = None,
    positions: ArrayLike | None = None,
    length: int | None = None,
    ) -> np.ndarray

With this input form, x, y or z sets the first axis of the local coordinate system. Then, xy, xz or yz forms a plane with the first vector; the second axis is the cross product of both vectors (perpendicular to this plane). Finally, the third axis is the cross product of the two first axes.

Parameters:

• matrices (ArrayLike | None) – Used in the matrix input form. Nx3x3 series or rotations or Nx4x4 series of homogeneous transforms.

• angles (ArrayLike | None) – Used in the angles input form. Series of angles, either of shape (N,) or (N, 1) for rotations around only one axis, or (N, 2) or (N, 3) for rotations around consecutive axes.

• seq (str | None) – Used in the angles input form. Specifies the sequence of axes for successive rotations. Up to 3 characters belonging to {“X”, “Y”, “Z”} for intrinsic rotations (moving axes), or {“x”, “y”, “z”} for extrinsic rotations (fixed axes). Extrinsic and intrinsic rotations cannot be mixed in one function call.

• degrees (bool) – Used in the angles input form. Optional. If True, then the given angles are in degrees, otherwise they are in radians. Default is False (radians).

• quaternions (ArrayLike | None) – Used in the quaternions input form. Nx4 series of quaternions.

• scalar_first (bool) – Used in the quaternions input form. Optional. If True, the quaternion order is (w, x, y, z). If False, the quaternion order is (x, y, z, w). Default is False.

• x (ArrayLike | None) – Used in the vector input form. Define either x, y or z. A series of N vectors (Nx4) that define the {x|y|z} axis of the frames to be created.

• y (ArrayLike | None) – Used in the vector input form. Define either x, y or z. A series of N vectors (Nx4) that define the {x|y|z} axis of the frames to be created.

• z (ArrayLike | None) – Used in the vector input form. Define either x, y or z. A series of N vectors (Nx4) that define the {x|y|z} axis of the frames to be created.

• xy (ArrayLike | None) – Used in the vector input form. Only if x or y is specified. A series of N vectors (Nx4) in the xy plane, to create z using (x cross xy) or (xy cross y). Choose vectors that point roughly in the +x or +y direction.

• xz (ArrayLike | None) – Used in the vector input form. Only if x or z is specified. A series of N vectors (Nx4) in the xz plane, to create y using (xz cross x) or (z cross xz). Choose vectors that point roughly in the +x or +z direction.

• yz (ArrayLike | None) – Used in the vector input form. Only if y or z is specified. A series of N vectors (Nx4) in the yz plane, to create x using (y cross yz) or (yz cross z). Choose vectors that point roughly in the +y or +z direction.

• positions (ArrayLike | None) – Optional. An Nx2, Nx3 or Nx4 point series that defines the position component (fourth column) of the transforms. Default value is [[0.0, 0.0, 0.0, 1.0]]. If the input is an Nx4x4 frame series and therefore already has positions, then the existing positions are kept unless positions is specified.

• length (int | None) – Optional. The number of samples in the resulting series. If there is only one sample in the original array, this one sample will be duplicated to match length. Otherwise, an error is raised if the input array does not match length.

Returns:

An Nx4x4 transform series.

Return type:

np.ndarray

Examples

Matrix input

Convert a 2x3x3 rotation matrix series and a 1x4 position series to an 2x4x4 homogeneous transform series:

>>> positions = [[0.5, 0.6, 0.7]]
>>> rotations = [[[ 1.,  0.,  0.],
...              [ 0.,  1.,  0.],
...              [ 0.,  0.,  1.]],
...             [[ 1.,  0.,  0.],
...              [ 0.,  0., -1.],
...              [ 0.,  1.,  0.]]]
>>> ktk.geometry.create_transform_series(rotations, positions=positions)
array([[[ 1. ,  0. ,  0. ,  0.5],
        [ 0. ,  1. ,  0. ,  0.6],
        [ 0. ,  0. ,  1. ,  0.7],
        [ 0. ,  0. ,  0. ,  1. ]],

       [[ 1. ,  0. ,  0. ,  0.5],
        [ 0. ,  0. , -1. ,  0.6],
        [ 0. ,  1. ,  0. ,  0.7],
        [ 0. ,  0. ,  0. ,  1. ]]])

Angle input

Create a series of two homogeneous transforms that rotates 0, then 90 degrees around x:

>>> ktk.geometry.create_transform_series(angles=[0, 90], seq="x", degrees=True)
array([[[ 1.,  0.,  0.,  0.],
        [ 0.,  1.,  0.,  0.],
        [ 0.,  0.,  1.,  0.],
        [ 0.,  0.,  0.,  1.]],

       [[ 1.,  0.,  0.,  0.],
        [ 0.,  0., -1.,  0.],
        [ 0.,  1.,  0.,  0.],
        [ 0.,  0.,  0.,  1.]]])