pyframetree 0.3.0__py3-none-any.whl

pyframetree/__init__.py

@@ -0,0 +1,15 @@
+from .backend import gpu_available
+from .coordinate_systems import CoordinateSystem
+from .rotation import Rotation
+from .transformations import Transformation
+from .utils import X_AX, Y_AX, Z_AX
+
+__all__ = [
+    'CoordinateSystem',
+    'Rotation',
+    'Transformation',
+    'gpu_available',
+    'X_AX',
+    'Y_AX',
+    'Z_AX',
+]

pyframetree/backend.py

@@ -0,0 +1,38 @@
+"""NumPy/CuPy dispatch: arrays are processed on the device they already live on."""
+
+import importlib
+import sys
+
+import numpy as np
+
+
+def array_module(array):
+    cupy = sys.modules.get('cupy')
+    if cupy is not None and isinstance(array, cupy.ndarray):
+        return cupy
+    return np
+
+
+def to_numpy(array):
+    if array_module(array) is np:
+        return np.asarray(array)
+    return array.get()
+
+
+def float_points(points):
+    """Points as a float array of shape (..., 3), kept on their current device."""
+    xp = array_module(points)
+    points = xp.asarray(points)
+    if not np.issubdtype(points.dtype, np.floating):
+        points = points.astype(float)
+    if points.ndim == 0 or points.shape[-1] != 3:
+        raise ValueError('points must have shape (..., 3)')
+    return points
+
+
+def gpu_available():
+    try:
+        cupy = importlib.import_module('cupy')
+        return cupy.cuda.runtime.getDeviceCount() > 0
+    except Exception:
+        return False

pyframetree/coordinate_systems.py

@@ -0,0 +1,346 @@
+import numpy as np
+import quantities as q
+
+from .backend import float_points, to_numpy
+from .rotation import Rotation
+from .transformations import Transformation
+from .utils import (
+    Y_AX,
+    Z_AX,
+    axis_angle_matrix,
+    conversion_factor,
+    finite_scalar,
+    homogeneous,
+    length_unit,
+    magnitude,
+    vector3,
+)
+
+REFERENCES = ('parent', 'world', 'local')
+SPACES = ('local', 'world')
+IDENTITY = np.eye(4)
+IDENTITY.flags.writeable = False
+
+
+def _inverse(pose):
+    """Inverse of a 4x4 pose ``[[s R, t], [0, 1]]``, without a general matrix inversion."""
+    linear = pose[:3, :3]
+    inverse_linear = linear.T / (linear[:, 0] @ linear[:, 0])
+    return homogeneous(inverse_linear, -inverse_linear @ pose[:3, 3])
+
+
+class CoordinateSystem:
+    """A coordinate frame: an origin, an orientation and a uniform scale.
+
+    Frames form a tree. Each frame stores its pose relative to its parent (or
+    to the world for a root), so children and attached points follow it.
+    Its axes ``u``, ``v`` and ``w`` are always orthogonal and of equal length.
+
+    Bare numbers are read in ``unit`` (the parent's unit by default, else
+    metres); quantities may use any length unit.
+
+    Motion methods take ``relative_to='parent' | 'world' | 'local'``: their
+    arguments are coordinates in that frame. With ``inherit=False``, the
+    frame's points and children stay where they are in the world.
+    """
+
+    def __init__(
+        self, origin=(0, 0, 0), rotation=None, scale=1.0, *, parent=None, name=None, unit=None
+    ):
+        if unit is None and parent is not None:
+            self.unit, self._metres_per_unit = parent.unit, parent._metres_per_unit
+        else:
+            self.unit = length_unit(q.m if unit is None else unit)
+            self._metres_per_unit = conversion_factor(self.unit, q.m)
+        self._name = name
+        self._parent = None
+        self._children = {}
+        self._named_children = {}
+        self._points = {}
+        self._cached_parent_world = self._cached_local = self._cached_world = None
+
+        if rotation is not None and not isinstance(rotation, Rotation):
+            raise TypeError('rotation must be a Rotation')
+        scale = self._scale_factor(scale)
+        linear = np.eye(3) if rotation is None else rotation.matrix
+        self._local = homogeneous(scale * linear, self._metres(origin, 'origin'))
+        if parent is not None:
+            self.set_parent(parent, keep_world=False)
+
+    # Tree
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def parent(self):
+        return self._parent
+
+    @property
+    def children(self):
+        return tuple(self._children)
+
+    def child(self, name):
+        return self._named_children[name]
+
+    def set_parent(self, parent, *, keep_world=True):
+        """Attach this frame to ``parent``, or detach it with ``None``.
+
+        By default the frame keeps its world pose. With ``keep_world=False``
+        its current pose is reinterpreted relative to the new parent.
+        """
+        if parent is not None:
+            if not isinstance(parent, CoordinateSystem):
+                raise TypeError('parent must be a CoordinateSystem or None')
+            ancestor = parent
+            while ancestor is not None:
+                if ancestor is self:
+                    raise ValueError('a frame cannot be its own ancestor')
+                ancestor = ancestor._parent
+            sibling = parent._named_children.get(self._name)
+            if sibling is not None and sibling is not self:
+                raise ValueError(f'{parent!r} already has a child named {self._name!r}')
+
+        if keep_world:
+            world = self._world()
+            self._local = world.copy() if parent is None else _inverse(parent._world()) @ world
+        if self._parent is not None:
+            del self._parent._children[self]
+            self._parent._named_children.pop(self._name, None)
+        if parent is not None:
+            parent._children[self] = None
+            if self._name is not None:
+                parent._named_children[self._name] = self
+        self._parent = parent
+        return self
+
+    # Pose
+
+    def _world(self):
+        """World pose as a read-only 4x4 matrix in metres.
+
+        Poses are replaced, never modified in place, so a cached world pose is
+        valid while its inputs (parent world pose, local pose) are the same objects.
+        """
+        chain, frame = [], self
+        while frame is not None:
+            chain.append(frame)
+            frame = frame._parent
+        world = IDENTITY
+        for frame in reversed(chain):
+            if frame._cached_parent_world is not world or frame._cached_local is not frame._local:
+                frame._cached_parent_world, frame._cached_local = world, frame._local
+                frame._cached_world = world @ frame._local
+                frame._cached_world.flags.writeable = False
+            world = frame._cached_world
+        return world
+
+    def _parent_world(self):
+        return IDENTITY if self._parent is None else self._parent._world()
+
+    def _in_unit(self, pose):
+        if self._metres_per_unit == 1:
+            return Transformation._trusted(pose.copy(), self.unit)
+        matrix = pose.copy()
+        matrix[:3, 3] /= self._metres_per_unit
+        return Transformation._trusted(matrix, self.unit)
+
+    @property
+    def local_transform(self):
+        """Snapshot of the map from this frame's coordinates to its parent's, in ``unit``."""
+        return self._in_unit(self._local)
+
+    @property
+    def world_transform(self):
+        """Snapshot of the map from this frame's coordinates to world coordinates, in ``unit``."""
+        return self._in_unit(self._world())
+
+    @property
+    def origin(self):
+        return self._world()[:3, 3] / self._metres_per_unit * self.unit
+
+    @property
+    def scale_factor(self):
+        return float(np.cbrt(np.linalg.det(self._world()[:3, :3])))
+
+    @property
+    def rotation(self):
+        return Rotation._trusted(self._world()[:3, :3] / self.scale_factor)
+
+    @property
+    def u(self):
+        return self._world()[:3, 0].copy()
+
+    @property
+    def v(self):
+        return self._world()[:3, 1].copy()
+
+    @property
+    def w(self):
+        return self._world()[:3, 2].copy()
+
+    # Coordinates
+
+    def to_world(self, points):
+        """Convert points from this frame's coordinates to world coordinates."""
+        return self.world_transform.apply(points)
+
+    def to_local(self, points):
+        """Convert points from world coordinates to this frame's coordinates."""
+        return self._in_unit(_inverse(self._world())).apply(points)
+
+    # Motion
+
+    def translate(self, offset, *, relative_to='parent', inherit=True):
+        motion = homogeneous(np.eye(3), self._metres(offset, 'offset'))
+        return self._move(motion, relative_to, inherit)
+
+    def rotate(self, axis, angle, *, pivot=None, relative_to='parent', inherit=True):
+        """Rotate about ``axis`` through ``pivot`` (default: this frame's origin)."""
+        rotation = axis_angle_matrix(axis, angle)
+        if pivot is None:
+            pivot = self._pose_in(relative_to)[:3, 3]
+        else:
+            pivot = self._metres(pivot, 'pivot')
+        return self._move(homogeneous(rotation, pivot - rotation @ pivot), relative_to, inherit)
+
+    def scale(self, factor, *, inherit=True):
+        """Multiply the axis lengths by ``factor``, about this frame's origin."""
+        motion = homogeneous(self._scale_factor(factor) * np.eye(3))
+        return self._move(motion, 'local', inherit)
+
+    def flip(self, *, inherit=True):
+        """Reverse all three axes. This changes the frame's handedness."""
+        return self.scale(-1, inherit=inherit)
+
+    def set_position(self, position, *, relative_to='parent', inherit=True):
+        target = self._pose_in(relative_to).copy()
+        target[:3, 3] = self._metres(position, 'position')
+        return self._place(target, relative_to, inherit)
+
+    def set_spherical(self, r, theta, phi, *, relative_to='parent', inherit=True):
+        """Place the origin at (r, theta, phi), with ``w`` pointing radially outward.
+
+        ``theta`` is the polar angle from z and ``phi`` the azimuth from x.
+        ``u`` points towards increasing theta and ``v`` towards increasing phi.
+        """
+        radius = finite_scalar(r, 'r', self.unit) * self._metres_per_unit
+        if radius < 0:
+            raise ValueError('r must be nonnegative')
+        rotation = axis_angle_matrix(Z_AX, phi) @ axis_angle_matrix(Y_AX, theta)
+        scale = np.cbrt(np.linalg.det(self._pose_in(relative_to)[:3, :3]))
+        target = homogeneous(scale * rotation, radius * rotation[:, 2])
+        return self._place(target, relative_to, inherit)
+
+    def _pose_in(self, relative_to):
+        """This frame's pose, in the coordinates of the ``relative_to`` frame."""
+        if relative_to == 'parent':
+            return self._local
+        if relative_to == 'world':
+            return self._world()
+        if relative_to == 'local':
+            return IDENTITY
+        raise ValueError(f'relative_to must be one of {REFERENCES}')
+
+    def _place(self, target, relative_to, inherit):
+        """Give this frame the pose ``target``, expressed in ``relative_to`` coordinates."""
+        if relative_to == 'world':
+            target = _inverse(self._parent_world()) @ target
+        elif relative_to == 'local':
+            target = self._local @ target
+        return self._set_local(target, inherit)
+
+    def _move(self, motion, relative_to, inherit):
+        """Apply ``motion``, expressed in ``relative_to`` coordinates."""
+        return self._place(motion @ self._pose_in(relative_to), relative_to, inherit)
+
+    def _set_local(self, local, inherit):
+        if not inherit:
+            correction = _inverse(local) @ self._local
+            for child in self._children:
+                child._local = correction @ child._local
+            transform = self._in_unit(correction)
+            self._points = {label: transform.apply(value) for label, value in self._points.items()}
+        self._local = local
+        return self
+
+    def _metres(self, value, name):
+        return vector3(value, name, self.unit) * self._metres_per_unit
+
+    @staticmethod
+    def _scale_factor(value):
+        value = finite_scalar(value, 'scale')
+        if value == 0:
+            raise ValueError('scale must be nonzero')
+        return value
+
+    # Points
+
+    def add_points(self, points, label, *, space='local'):
+        """Attach a copy of ``points`` (shape ``(..., 3)``) under ``label``.
+
+        Points are stored in this frame's coordinates and unit, keeping their
+        dtype and device, and move with the frame.
+        """
+        if space not in SPACES:
+            raise ValueError(f'space must be one of {SPACES}')
+        if label in self._points:
+            raise ValueError(f'point label already exists: {label!r}')
+        if isinstance(points, (q.Quantity, list, tuple)):
+            points = magnitude(points, self.unit)
+        points = float_points(points)
+        self._points[label] = self.to_local(points) if space == 'world' else points.copy()
+
+    def remove_points(self, label):
+        """Detach the points stored under ``label`` and return them, in local coordinates."""
+        return self._points.pop(label)
+
+    def get_points(self, label, *, space='local'):
+        """A copy of the points stored under ``label``, in this frame's unit."""
+        if space not in SPACES:
+            raise ValueError(f'space must be one of {SPACES}')
+        points = self._points[label]
+        return self.to_world(points) if space == 'world' else points.copy()
+
+    @property
+    def point_labels(self):
+        return tuple(self._points)
+
+    # Display
+
+    def visualize(self, plotter=None, cmap='viridis', children=True, show_points=True):
+        """Draw the frame (and its descendants) in world coordinates with PyVista."""
+        try:
+            import pyvista as pv
+            from matplotlib import colormaps
+        except ImportError as exc:
+            raise ImportError("visualize requires pip install 'pyframetree[visualization]'") from exc
+
+        plotter = pv.Plotter() if plotter is None else plotter
+        axis_colors = colormaps[cmap](np.linspace(0, 1, 3))
+        frames = [self]
+        while frames:
+            frame = frames.pop()
+            origin = frame.origin.rescale(self.unit).magnitude
+            for axis, color in zip((frame.u, frame.v, frame.w), axis_colors):
+                plotter.add_arrows(origin, axis, color=color)
+            plotter.add_points(origin, color='black')
+            if show_points:
+                for index, label in enumerate(frame._points):
+                    points = to_numpy(frame.get_points(label, space='world'))
+                    points = points * conversion_factor(frame.unit, self.unit)
+                    if points.size:
+                        plotter.add_points(
+                            points.reshape(-1, 3),
+                            color=colormaps['tab10'](index % 10),
+                            point_size=10,
+                            render_points_as_spheres=True,
+                        )
+            if children:
+                frames.extend(reversed(frame.children))
+        return plotter
+
+    def __repr__(self):
+        name = '' if self._name is None else f'{self._name!r}, '
+        return f'CoordinateSystem({name}origin={self.origin}, scale={self.scale_factor:g})'

pyframetree/rotation.py

@@ -0,0 +1,85 @@
+import numpy as np
+import quantities as q
+
+from .utils import axis_angle_matrix
+
+
+class Rotation:
+    """An immutable 3D rotation, stored as an orthonormal 3x3 matrix.
+
+    ``a @ b`` is the rotation that applies ``b`` first, then ``a``.
+    """
+
+    def __init__(self, matrix=None):
+        matrix = np.eye(3) if matrix is None else np.array(matrix, dtype=float)
+        if matrix.shape != (3, 3) or not np.allclose(matrix.T @ matrix, np.eye(3), atol=1e-9):
+            raise ValueError('rotation matrix must be an orthonormal 3x3 matrix')
+        if np.linalg.det(matrix) < 0:
+            raise ValueError('rotation matrix must have determinant +1')
+        self._matrix = matrix
+
+    @classmethod
+    def _trusted(cls, matrix):
+        rotation = cls.__new__(cls)
+        rotation._matrix = matrix
+        return rotation
+
+    @classmethod
+    def from_axis_angle(cls, axis, angle):
+        """Right-handed rotation about ``axis``; bare angles are radians."""
+        return cls._trusted(axis_angle_matrix(axis, angle))
+
+    @classmethod
+    def from_quaternion(cls, quaternion):
+        """From a quaternion (w, x, y, z); it does not need to be normalized."""
+        quaternion = np.asarray(quaternion, dtype=float)
+        norm = np.linalg.norm(quaternion)
+        if quaternion.shape != (4,) or not np.isfinite(norm) or norm == 0:
+            raise ValueError('quaternion must be four finite numbers, not all zero')
+        w, x, y, z = quaternion / norm
+        return cls._trusted(
+            np.array(
+                [
+                    [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
+                    [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
+                    [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
+                ]
+            )
+        )
+
+    @property
+    def matrix(self):
+        return self._matrix.copy()
+
+    @property
+    def quaternion(self):
+        """The unit quaternion (w, x, y, z), with w >= 0."""
+        # Bar-Itzhack: the quaternion is the dominant eigenvector of this matrix.
+        (xx, xy, xz), (yx, yy, yz), (zx, zy, zz) = self._matrix
+        k = np.array(
+            [
+                [xx + yy + zz, zy - yz, xz - zx, yx - xy],
+                [zy - yz, xx - yy - zz, xy + yx, xz + zx],
+                [xz - zx, xy + yx, yy - xx - zz, yz + zy],
+                [yx - xy, xz + zx, yz + zy, zz - xx - yy],
+            ]
+        )
+        quaternion = np.linalg.eigh(k)[1][:, -1]
+        return quaternion if quaternion[0] >= 0 else -quaternion
+
+    def inverse(self):
+        return Rotation._trusted(self._matrix.T)
+
+    def apply(self, vectors):
+        """Rotate one vector ``(3,)`` or a batch ``(..., 3)``; quantities keep their units."""
+        if isinstance(vectors, q.Quantity):
+            return self.apply(vectors.magnitude) * vectors.units
+        return np.asarray(vectors, dtype=float) @ self._matrix.T
+
+    def __matmul__(self, other):
+        if not isinstance(other, Rotation):
+            return NotImplemented
+        return Rotation._trusted(self._matrix @ other._matrix)
+
+    def __repr__(self):
+        return f'Rotation(quaternion={self.quaternion.round(12).tolist()})'

pyframetree/transformations.py

@@ -0,0 +1,125 @@
+import numpy as np
+import quantities as q
+
+from .backend import array_module, float_points, to_numpy
+from .utils import (
+    angle_radians,
+    axis_angle_matrix,
+    conversion_factor,
+    homogeneous,
+    length_unit,
+    magnitude,
+    unit_vector,
+    vector3,
+)
+
+SHEAR_PLANES = ('xy', 'xz', 'yx', 'yz', 'zx', 'zy')
+
+
+class Transformation:
+    """An immutable affine map of 3D points, stored as a 4x4 matrix.
+
+    Distances in the matrix, and bare numbers given to it, are in ``unit``.
+    ``a @ b`` applies ``b`` first, then ``a``. Points are processed on the
+    device (NumPy or CuPy) they already live on.
+    """
+
+    def __init__(self, matrix=None, *, unit=q.m):
+        self.unit = length_unit(unit)
+        matrix = np.eye(4) if matrix is None else np.array(to_numpy(matrix), dtype=float)
+        if matrix.shape != (4, 4) or not np.all(np.isfinite(matrix)):
+            raise ValueError('matrix must be a finite 4x4 array')
+        if not np.array_equal(matrix[3], [0, 0, 0, 1]):
+            raise ValueError('matrix must be affine: its last row must be (0, 0, 0, 1)')
+        self._matrix = matrix
+
+    @classmethod
+    def _trusted(cls, matrix, unit):
+        transform = cls.__new__(cls)
+        transform._matrix, transform.unit = matrix, unit
+        return transform
+
+    @classmethod
+    def translation(cls, offset, *, unit=q.m):
+        unit = length_unit(unit)
+        return cls._trusted(homogeneous(np.eye(3), vector3(offset, 'offset', unit)), unit)
+
+    @classmethod
+    def rotation(cls, axis, angle):
+        """Right-handed rotation about ``axis`` through the origin; bare angles are radians."""
+        return cls._trusted(homogeneous(axis_angle_matrix(axis, angle)), q.m)
+
+    @classmethod
+    def scaling(cls, factors):
+        """Scale by one factor, or by three factors along x, y and z."""
+        factors = np.broadcast_to(magnitude(factors, q.dimensionless), 3)
+        return cls._trusted(homogeneous(np.diag(vector3(factors, 'factors'))), q.m)
+
+    @classmethod
+    def shear(cls, plane, angle):
+        """Shear in ``plane``: 'xy' adds tan(angle) * y to x, and so on."""
+        if plane not in SHEAR_PLANES:
+            raise ValueError(f'plane must be one of {SHEAR_PLANES}')
+        radians = angle_radians(angle)
+        if np.isclose(np.cos(radians), 0):
+            raise ValueError('shear angle must not be ±90°')
+        linear = np.eye(3)
+        linear['xyz'.index(plane[0]), 'xyz'.index(plane[1])] = np.tan(radians)
+        return cls._trusted(homogeneous(linear), q.m)
+
+    @classmethod
+    def look_at(cls, eye, target, up=(0, 1, 0), *, unit=q.m):
+        """World-to-camera map: ``eye`` goes to the origin, ``target`` onto the -z axis."""
+        unit = length_unit(unit)
+        eye = vector3(eye, 'eye', unit)
+        backward = unit_vector(eye - vector3(target, 'target', unit), 'eye - target')
+        right = unit_vector(np.cross(vector3(up, 'up'), backward), 'up × (eye - target)')
+        rows = np.array([right, np.cross(backward, right), backward])
+        return cls._trusted(homogeneous(rows, -rows @ eye), unit)
+
+    @property
+    def matrix(self):
+        return self._matrix.copy()
+
+    def as_unit(self, unit):
+        """The same physical map, with distances expressed in another unit."""
+        unit = length_unit(unit)
+        factor = conversion_factor(self.unit, unit)
+        if factor == 1:
+            return self
+        matrix = self._matrix.copy()
+        matrix[:3, 3] *= factor
+        return Transformation._trusted(matrix, unit)
+
+    def inverse(self):
+        linear = np.linalg.inv(self._matrix[:3, :3])
+        return Transformation._trusted(
+            homogeneous(linear, -linear @ self._matrix[:3, 3]), self.unit
+        )
+
+    def __matmul__(self, other):
+        if not isinstance(other, Transformation):
+            return NotImplemented
+        return Transformation._trusted(self._matrix @ other.as_unit(self.unit)._matrix, self.unit)
+
+    def apply(self, points, *, vectors=False):
+        """Transform one point ``(3,)`` or a batch ``(..., 3)``.
+
+        ``vectors=True`` skips the translation, for directions or velocities.
+        Quantities come back in their own units.
+        """
+        if isinstance(points, q.Quantity):
+            transform = self if vectors else self.as_unit(points.units)
+            return transform.apply(points.magnitude, vectors=vectors) * points.units
+        if isinstance(points, (list, tuple)):
+            points = magnitude(points, q.dimensionless if vectors else self.unit)
+
+        points = float_points(points)
+        xp = array_module(points)
+        result = points @ xp.asarray(self._matrix[:3, :3].T, dtype=points.dtype)
+        if not vectors:
+            result += xp.asarray(self._matrix[:3, 3], dtype=points.dtype)
+        return result
+
+    def __repr__(self):
+        return f'Transformation(unit={self.unit.dimensionality}, matrix=\n{self._matrix})'

pyframetree/utils.py

@@ -0,0 +1,89 @@
+"""Unit handling and input validation.
+
+``quantities`` conversions are slow (~100 µs), so conversion factors are cached.
+"""
+
+import numpy as np
+import quantities as q
+
+X_AX = np.array([1.0, 0.0, 0.0])
+Y_AX = np.array([0.0, 1.0, 0.0])
+Z_AX = np.array([0.0, 0.0, 1.0])
+
+_FACTORS = {}
+
+
+def conversion_factor(units, target):
+    """Multiply a magnitude in ``units`` by this to express it in ``target``."""
+    units, target = units.dimensionality, target.dimensionality
+    key = (frozenset(units.items()), frozenset(target.items()))
+    factor = _FACTORS.get(key)
+    if factor is None:
+        factor = _FACTORS[key] = float(q.Quantity(1.0, units).rescale(target).magnitude)
+    return factor
+
+
+def length_unit(unit):
+    if not isinstance(unit, q.Quantity):
+        unit = q.Quantity(1.0, unit).units
+    conversion_factor(unit, q.m)  # Raises for anything that is not a length.
+    return unit
+
+
+def magnitude(value, unit):
+    """Strip units: quantities are converted to ``unit``, bare numbers are taken as they are."""
+    if isinstance(value, q.Quantity):
+        return value.magnitude * conversion_factor(value, unit)
+    if isinstance(value, (list, tuple)) and any(
+        isinstance(v, (q.Quantity, list, tuple)) for v in value
+    ):
+        return np.array([magnitude(v, unit) for v in value], dtype=float)
+    return np.asarray(value, dtype=float)
+
+
+def vector3(value, name='vector', unit=q.dimensionless):
+    value = magnitude(value, unit)
+    if value.shape != (3,) or not np.all(np.isfinite(value)):
+        raise ValueError(f'{name} must be three finite numbers')
+    return value
+
+
+def unit_vector(value, name='axis'):
+    value = vector3(value, name)
+    length = np.linalg.norm(value)
+    if length == 0:
+        raise ValueError(f'{name} must be nonzero')
+    return value / length
+
+
+def finite_scalar(value, name, unit=q.dimensionless):
+    value = magnitude(value, unit)
+    if value.shape != () or not np.isfinite(value):
+        raise ValueError(f'{name} must be a finite number')
+    return float(value)
+
+
+def angle_radians(angle):
+    return finite_scalar(angle, 'angle (bare numbers are radians)', q.rad)
+
+
+def homogeneous(linear, translation=(0.0, 0.0, 0.0)):
+    matrix = np.eye(4)
+    matrix[:3, :3] = linear
+    matrix[:3, 3] = translation
+    return matrix
+
+
+def axis_angle_matrix(axis, angle):
+    """Right-handed rotation matrix about ``axis`` (Rodrigues' formula)."""
+    x, y, z = unit_vector(axis)
+    radians = angle_radians(angle)
+    c, s = np.cos(radians), np.sin(radians)
+    t = 1 - c
+    return np.array(
+        [
+            [c + x * x * t, x * y * t - z * s, x * z * t + y * s],
+            [y * x * t + z * s, c + y * y * t, y * z * t - x * s],
+            [z * x * t - y * s, z * y * t + x * s, c + z * z * t],
+        ]
+    )

pyframetree-0.3.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: pyframetree
+Version: 0.3.0
+Summary: Nested 3D coordinate frames with physical units and vectorized transformations
+Author-email: Gabriel Lefloch <gabriel.lefloch@kit.edu>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/gabs1234/QuaternionFrame
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: quantities>=0.16
+Provides-Extra: visualization
+Requires-Dist: pyvista>=0.43; extra == "visualization"
+Requires-Dist: matplotlib>=3.6; extra == "visualization"
+Dynamic: license-file
+
+# PyFrameTree
+
+Nested 3D coordinate frames and point-cloud transformations, with physical units.
+
+## Installation
+
+From the repository:
+
+```bash
+uv sync --extra visualization
+```
+
+## Usage
+
+```bash
+uv run --extra visualization python examples/simple_transform.py --show
+```
+
+```python
+from pyframetree import CoordinateSystem
+import quantities as pq
+import numpy as np
+import pyvista as pv
+```
+
+```python
+plotter = pv.Plotter()
+
+# Create a random point cloud
+N = 100
+points = np.random.rand(N, 3)
+
+# Create a reference coordinate system
+Reference = CoordinateSystem()
+
+# Create a main coordinate system
+Main = CoordinateSystem()
+
+# Create a child coordinate system
+Child = CoordinateSystem(parent=Main, name='Child')
+Child.add_points(points, 'points')
+Child.translate([2, 2, 0]*pq.m)
+Child.rotate([0, 1, 1], 30*pq.deg)
+
+Main.scale(3, inherit=False) # Scale the main coordinate system, but not its children
+Main.rotate([1, 0, 0], 30*pq.deg, inherit=True)
+
+Reference.visualize(plotter=plotter, children=False, cmap='gray')
+Main.visualize(plotter=plotter, children=False, cmap='plasma')
+Child.visualize(plotter=plotter, children=False, cmap='viridis')
+
+plotter.save_graphic('assets/frames.svg')
+```
+
+![example](assets/frames.svg)

pyframetree-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyframetree/__init__.py,sha256=Q08bYBPG2IVm-H0fuuJKdIbMEsJuFNL7lre1svUdHAU,329
+pyframetree/backend.py,sha256=-mUpDekhlam1wmAdefcheKey18o-IjLATa0C0Y6-CJY,971
+pyframetree/coordinate_systems.py,sha256=4bV_XeKJ0HLKTnt4upMj8k85JrXSNc82g1rRPkv3x0E,13489
+pyframetree/rotation.py,sha256=nIYQWDsNp5wFNdvqQYsBHqsB04GwqPNWo-aKRbWntS0,3218
+pyframetree/transformations.py,sha256=xmWaoQFEDKMqyBY4ApCQ6zD-SEIio0hukRjKgDkYrr0,4907
+pyframetree/utils.py,sha256=H05OnsFI39MATGxJ9EVa1OSEzSOzAKZiudSKAcIRJF4,2779
+pyframetree-0.3.0.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
+pyframetree-0.3.0.dist-info/METADATA,sha256=E82MRXWYUXmBqRjSihAOqld2JU3SE0YqfPiToVJo7Ao,1829
+pyframetree-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pyframetree-0.3.0.dist-info/top_level.txt,sha256=tTpwoeaLaeADigd40EzdW5zN9vg-dmwVinahYG1uGVw,12
+pyframetree-0.3.0.dist-info/RECORD,,

pyframetree-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyframetree-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyframetree-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyframetree