Geometric Primitives

Point

class hazy.Point(x: float, y: float, z: float, frame: Frame, *, w=1.0)

Bases: GeometricPrimitive

Geometric point representing position in space.

Points have homogeneous coordinate w=1, making them affected by translation.

Arithmetic semantics:

• Point - Point = Vector (displacement between positions)

• Point + Vector = Point (displace position)

• Point - Vector = Point (displace position backwards)

• Point + Point = ERROR (undefined operation)

classmethod create_nan(frame: Frame) → Point

Create point with NaN coordinates.

Parameters:

frame – Reference frame

Returns:

Point with all coordinates set to NaN

classmethod create_origin(frame: Frame) → Point

Return a point at the origin of the specified coordinate system

classmethod from_array(array: ArrayLike, frame: Frame) → Self

Create point from array with Cartesian coordinates.

Parameters:

• array – Array-like with 3 elements [x, y, z]

• frame – Reference frame

Returns:

New point (w=1 set automatically)

Raises:

ValueError – If array doesn’t have exactly 3 elements

Examples

>>> frame = Frame()
>>> p = Point.from_array([1, 2, 3], frame=frame)
>>> p = Point.from_array(np.array([1.0, 2.0, 3.0]), frame=frame)

classmethod list_from_array(points: ArrayLike, frame: Frame) → list[Point]

Create list of points from array.

Parameters:

• points – Array-like with shape (…, 3) where last dimension is coordinates

• frame – Reference frame for all points

Returns:

List of Point instances

Raises:

ValueError – If last dimension is not 3

Examples

>>> frame = Frame()
>>> points_array = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> points = Point.list_from_array(points_array, frame=frame)
>>> len(points)  # 3

Vector

class hazy.Vector(x: float, y: float, z: float, frame: Frame, *, w=0.0)

Bases: GeometricPrimitive

Geometric vector representing direction and magnitude.

Vectors have homogeneous coordinate w=0, making them invariant to translation.

Arithmetic semantics:

• Vector + Vector = Vector (combine displacements)

• Vector - Vector = Vector (difference of displacements)

• Vector + Point = Point (displace position)

• Vector - Point = ERROR (undefined operation)

cross(other: Vector) → Vector

Compute cross product with another vector.

Parameters:

other – Vector to cross with

Returns:

Vector perpendicular to both input vectors

Raises:

RuntimeError – If frames don’t match

Examples

>>> frame = Frame()
>>> v1 = frame.vector(1, 0, 0)
>>> v2 = frame.vector(0, 1, 0)
>>> v1.cross(v2)  # Vector(x=0, y=0, z=1)

dot(other: Vector) → float

Compute dot product with another vector.

Parameters:

other – Vector to dot with

Returns:

scalar dot product between both vectors

Raises:

RuntimeError – If frames don’t match

Examples

>>> frame = Frame()
>>> v1 = frame.vector(1, 2, 3)
>>> v2 = frame.vector(4, 5, 6)
>>> v1.dot(v2)  # 32.0

classmethod from_array(array: ArrayLike, frame: Frame) → Self

Create vector from array with Cartesian coordinates.

Parameters:

• array – Array-like with 3 elements [x, y, z]

• frame – Reference frame

Returns:

New vector (w=0 set automatically)

Raises:

ValueError – If array doesn’t have exactly 3 elements

Examples

>>> frame = Frame()
>>> v = Vector.from_array([1, 2, 3], frame=frame)
>>> v = Vector.from_array(np.array([1.0, 2.0, 3.0]), frame=frame)

property is_zero: bool

Check if vector has near-zero magnitude.

property magnitude: float

Euclidean length of the vector.

classmethod nan(frame: Frame) → Vector

Create vector with NaN coordinates.

Parameters:

frame – Reference frame

Returns:

Vector with all coordinates set to NaN

normalize() → Self

Normalize vector to unit length in-place.

Returns:

Self for method chaining

Raises:

RuntimeError – If vector has zero length

Examples

>>> frame = Frame()
>>> v = frame.vector(3, 4, 0)
>>> v.magnitude  # 5.0
>>> v.normalize()
>>> v.magnitude  # 1.0