Frame

class hazy.frame.Frame(parent: Frame | None = None, name: str | None = None)[source]

Bases: object

Hierarchical reference frame with transformation tracking.

Frames support accumulation of transformations (translation, rotation, scaling) and provide cached transformation matrices for efficient repeated calculations.

Transformations are applied in S→R→T order (Scale, Rotation, Translation) when converting from local to parent coordinates.

parent: Parent frame in hierarchy (None for root frames)

name: Human-readable frame identifier

batch_transform_points_global(points: NDArray[np.floating]) → NDArray[np.floating][source]

Batch transform an array of points from this coordinate system to global.

Homogeneous coordinate (w=1) will be added automatically.

Parameters:: points – Array of 3D points, will be reshaped to (N, 3)
Returns:: Points transformed to global space

Examples

>>> frame = Frame().translate(x=1.0)
>>> points = np.array([[0, 0, 0], [1, 0, 0]])
>>> frame.batch_transform_points_global(points)

batch_transform_vectors_global(vectors: NDArray[np.floating]) → NDArray[np.floating][source]

Batch transform an array of vectors from this coordinate system to global.

Homogeneous coordinate (w=0) will be added automatically.

Parameters:: vectors – Array of 3D vectors, will be reshaped to (N, 3)
Returns:: Vectors transformed to global space

Examples

>>> frame = Frame().translate(x=1.0)
>>> vectors = np.array([[1, 0, 0], [0, 1, 0]])
>>> frame.batch_transform_vectors_global(vectors)

clear_all_transforms() → Self[source]

Clear all transformations.

Returns:: Self for method chaining

clear_rotations() → Self[source]

Clear all rotations.

Returns:: Self for method chaining

clear_scalings() → Self[source]

Clear all scalings.

Returns:: Self for method chaining

clear_translations() → Self[source]

Clear all translations.

Returns:: Self for method chaining

property combined_rotation: Rotation: Combined rotation from all accumulated rotations.

property combined_scale: NDArray[np.floating]: Combined scaling matrix from all accumulated scalings.

property combined_translation: NDArray[np.floating]: Combined translation vector from all accumulated translations.

freeze() → Self[source]

Freeze frame to prevent further modifications.

Returns:: Self for method chaining

Examples

>>> frame = Frame().translate(x=1.0).freeze()
>>> frame.translate(x=2.0)  # Raises RuntimeError

make_child(name: str | None = None) → Frame[source]

Creates a frame with this frame as its parent.

Parameters:: name – Optional name for the child frame
Returns:: New child frame

Example

>>> root = Frame.make_root(name="world")
>>> child = root.make_child(name="child")

classmethod make_root(name: str | None = None) → Frame[source]

Create a root frame (frame without parent).

Parameters:: name – Optional name for the root frame
Returns:: New root frame

Example

>>> root = Frame.make_root(name="world")
>>> robot = root.make_child(name="robot")

property origin: Point: Origin point (0, 0, 0) in this frame.

property origin_global: Point: Origin point transformed to global frame.

point(x: float, y: float, z: float) → Point[source]

point(x: ArrayLike) → Point

Create point in this frame.

Parameters:

x – X-coordinate or array-like [x, y, z]
y – Y-coordinate (required if x is scalar)
z – Z-coordinate (required if x is scalar)

Returns:

Point in this frame

Examples

>>> frame.point(1.0, 2.0, 3.0)
>>> frame.point([1, 2, 3])
>>> frame.point(np.array([1, 2, 3]))

property root: Frame

Get the root frame of this hierarchy.

Returns:: Root frame (self if no parent, otherwise traverses up to root)

rotate(rotation: ArrayLike) → Self[source]

Add rotation matrix to frame.

Parameters:: rotation – 3x3 rotation matrix
Returns:: Self for method chaining

Examples

>>> frame = Frame()
>>> R = np.eye(3)  # Identity rotation
>>> frame.rotate(R)

rotate_euler(*, x: float = 0.0, y: float = 0.0, z: float = 0.0, seq: Literal['xyz', 'xzy', 'yzx', 'yxz', 'zxy', 'zyx'] = 'xyz', degrees: bool = False) → Self[source]

Add Euler angle rotation to frame.

Parameters:

x – Rotation around x-axis
y – Rotation around y-axis
z – Rotation around z-axis
seq – Rotation sequence (default: xyz)
degrees – If True, angles are in degrees, otherwise radians

Returns:

Self for method chaining

Examples

>>> frame = Frame()
>>> frame.rotate_euler(z=90, degrees=True)
>>> frame.rotate_euler(y=np.pi) # default radians
>>> frame.rotate_euler(x=30, y=45, z=60, seq="zyx", degrees=True)

rotate_quaternion(quaternion: ArrayLike, *, scalar_first: bool = False) → Self[source]

Add quaternion rotation to frame.

Parameters:

quaternion – (4,) or (N, 4) array describing rotation with quaternion
scalar_first – Whether the scalar is the first or last element of the quaternion

Returns:

Self for method chaining

Examples

>>> frame = Frame()
>>> frame.rotate_quaternion([0, 0, 0, 1])  # Identity, scalar last
>>> frame.rotate_quaternion(
        [1, 0, 0, 0], scalar_first=True
    )  # Identity, scalar first

scale(x: float) → Self[source]

scale(x: Sequence[float]) → Self

scale(x: float, y: float, z: float) → Self

Add scaling to frame.

Parameters:

x – Uniform scale factor, x-axis scale, or (x, y, z) array
y – Y-axis scale (not allowed if x is array)
z – Z-axis scale (not allowed if x is array)

Returns:

Self for method chaining

Examples

>>> frame = Frame()
>>> frame.scale(2.0)  # Uniform scaling
>>> frame.scale(1.0, 2.0, 3.0)  # Per-axis scaling
>>> frame.scale([1.0, 2.0, 3.0])  # Array input

property transform_from_global: NDArray[np.floating]

4x4 transformation matrix from global frame to this frame.

Returns:: Inverse of transform_to_global

property transform_from_parent: NDArray[np.floating]

4x4 homogeneous transformation matrix from parent to local frame.

Returns:: Inverse of transform_to_parent

transform_to(target: Frame) → NDArray[np.floating][source]

Compute transformation matrix from this frame to target frame.

Parameters:: target – Target reference frame
Returns:: 4x4 transformation matrix from self to target
Raises:: RuntimeError – If frames belong to different hierarchies (different roots)

Examples

>>> world = Frame.make_root("world")
>>> camera = world.make_child("camera").translate(z=5.0)
>>> T = camera.transform_to(world)

property transform_to_global: NDArray[np.floating]

4x4 transformation matrix from this frame to global frame.

Recursively composes transformations through parent hierarchy. Results are cached for performance.

Returns:: 4x4 transformation matrix

property transform_to_parent: NDArray[np.floating]

4x4 homogeneous transformation matrix from local to parent frame.

Transformations are applied in S→R→T order (Scale, Rotation, Translation). Results are cached for performance.

Returns:: 4x4 transformation matrix (copy to prevent modification)

translate(x: float, y: float, z: float) → Self[source]

translate(x: Sequence[float]) → Self

translate(*, x: float = 0.0, y: float = 0.0, z: float = 0.0) → Self

Add translation to frame.

Parameters:

x – Translation along x-axis or (x, y, z) array
y – Translation along y-axis (not allowed if x is array)
z – Translation along z-axis (not allowed if x is array)

Returns:

Self for method chaining

Examples

>>> frame = Frame()
>>> frame.translate(x=1.0, y=2.0, z=3.0)
>>> frame.translate([1.0, 2.0, 3.0])

unfreeze() → Self[source]

Unfreeze frame to allow modifications.

Returns:: Self for method chaining

vector(x: float, y: float, z: float) → Vector[source]

vector(x: ArrayLike) → Vector

Create vector in this frame.

Parameters:

x – X-coordinate or array-like [x, y, z]
y – Y-coordinate (required if x is scalar)
z – Z-coordinate (required if x is scalar)

Returns:

Vector in this frame

Examples

>>> frame.vector(1.0, 2.0, 3.0)
>>> frame.vector([1, 2, 3])
>>> frame.vector(np.array([1, 2, 3]))

property x_axis: Vector: Unit vector along the x-axis in this frame.

property x_axis_global: Vector: Unit vector along the x-axis transformed to global frame.

property y_axis: Vector: Unit vector along the y-axis in this frame.

property y_axis_global: Vector: Unit vector along the y-axis transformed to global frame.

property z_axis: Vector: Unit vector along the z-axis in this frame.

property z_axis_global: Vector: Unit vector along the z-axis transformed to global frame.

property Frame.name: str: Name of this frame.

property Frame.parent: Frame | None: Reference to the parent of this frame. If this is a root frame parent is None.