Spatial Type Construction
=========================

The spatial types support common 3D geometry operations locally. They do not
require a client connection.

Build orientations with :class:`~olo.spatial.Quaternion` from roll-pitch-yaw
angles or axis-angle rotations, then compose them into
:class:`~olo.spatial.Pose` and :class:`~olo.spatial.Transform` values. 4x4
homogeneous matrices round-trip through the SDK types.

.. tab-set::
    :sync-group: sdk-language

    .. tab-item:: Python
        :sync: python

        The Python spatial types are immutable dataclasses. Roll-pitch-yaw
        angles are in radians using xyz extrinsic order.

        .. literalinclude:: scripts/spatial-math.py
           :language: python

        .. note::

           For heavier spatial algebra (Jacobians, trajectory interpolation,
           etc.), convert to a 4x4 matrix and use a dedicated library such as
           `spatialmath-python <https://pypi.org/project/spatialmath-python/>`_:

           .. code-block:: python

              import math
              from spatialmath import SE3

              from olo.spatial import Point, Pose, Quaternion

              pose = Pose(
                  position=Point(x=0.4, y=0.0, z=0.3),
                  orientation=Quaternion.from_rpy(0.0, math.radians(15), 0.0),
              )
              se3 = SE3(pose.matrix())
              print(se3)

    .. tab-item:: TypeScript
        :sync: typescript

        The TypeScript spatial types are dependency-free classes. Roll-pitch-yaw
        angles are in radians using xyz extrinsic order.

        .. literalinclude:: scripts/spatial-math.ts
           :language: typescript