Points

Lightweight 2‑D / 3‑D point and vector type shared across the pybosl2 geometry layer

Lightweight 2‑D / 3‑D point and vector type shared across the pybosl2 geometry layer.

Provides Point (mutable, x/y/optional z) with elementwise arithmetic and numpy integration. Vector is a backward-compatible alias for Point.

class pybosl2.points.Point(x=0.0, y=None, z=None)[source]

Bases: Sequence[float]

A mutable 2‑D or 3‑D point and vector.

Inherits from Sequence for compatibility with functions that accept Sequence[float].

If z is None the point is 2‑D (is_2d returns True); a concrete z makes it a 3‑D point. Supports iteration, indexing, len(), elementwise arithmetic (returning Point), and np.asarray().

Examples

from pybosl2 import Point

p2 = Point(10.0, 20.0)
assert p2.is_2d
assert len(p2) == 2

p3 = Point(10.0, 20.0, 5.0)
assert not p3.is_2d
assert len(p3) == 3
Parameters:
x : float

y : float

z : float | None

x : float
y : float
z : float | None = None
property is_2d : bool

True when z is None (a 2‑D point).

copy()[source]

Return a copy of this point.

Return type:

Point

dot(other)[source]

Dot product with another vector (2‑D or 3‑D).

Parameters:
other : Sequence[float] | ndarray

The point to compare or combine with.

Return type:

float

cross(other)[source]

Cross product with another 3‑D vector, returning a Point.

Parameters:
other : Sequence[float] | ndarray

The point to compare or combine with.

Raises:

ValueError – If this point is 2‑D (cross product requires 3‑D vectors).

Return type:

Point

classmethod from_seq(seq)[source]

Create a Point from any array-like sequence of 2 or 3 values.

Parameters:
seq : Sequence[float] | ndarray

A sequence, list, tuple, or ndarray of [x, y] or [x, y, z].

Returns:

A new Point.

Raises:

ValueError – If the sequence has fewer than 2 or more than 3 elements.

Return type:

Point

astuple()[source]

Return the point as a (x, y) or (x, y, z) tuple.

Return type:

tuple[float, float] | tuple[float, float, float]

tolist()[source]

Return the point as a [x, y] or [x, y, z] list.

Return type:

list[float]

property norm : float

Euclidean length of the vector from origin to this point.

to_3d(z=0.0)[source]

Return a 3‑D copy with the given z.

For a 2‑D point this adds the Z coordinate. For a 3‑D point this returns a copy with z replaced (unless z equals self.z).

Parameters:
z : float

Z coordinate to give a 2-D point when lifting it to 3-D.

Return type:

Point

normalized(error=None)[source]

Normalize this vector to unit length, returning a new Point.

If it has (near) zero length, returns error if given, else raises ValueError.

Parameters:
error : Point | Sequence[float] | ndarray | None

Raise on a degenerate input rather than returning a fallback.

Return type:

Point

angle(other)[source]

Angle between this vector and other in radians.

The result is always in the range [0, pi].

Parameters:
other : Point

The point to compare or combine with.

Return type:

float

axis(other)[source]

Return the axis vector (cross product) and angle between this vector and other.

Requires 3-D vectors.

Parameters:
other : Point

The point to compare or combine with.

Return type:

tuple[list[float], float]

bisect(other)[source]

Return a unit vector that bisects the minor angle between this vector and other.

Returns None if they are directly opposite.

Parameters:
other : Point

The point to compare or combine with.

Return type:

Point | None

closest(points)[source]

Return the index of the closest point in points to this point.

Parameters:
points : Sequence[Point]

The points to operate on.

Return type:

int

furthest(points)[source]

Return the index of the furthest point in points from this point.

Parameters:
points : Sequence[Point]

The points to operate on.

Return type:

int

pybosl2.points.PointLike : TypeAlias = pybosl2.points.Point | collections.abc.Sequence[float] | NDArray[numpy.float64]

What a parameter meaning “one point” accepts (PLAN T-4, the point-shaped twin of PathLike): a Point, the plain list or tuple a caller writes, or a NumPy array. Normalise on the first line of the body with Point(x) or np.asarray(x, dtype=float).

Typing such a parameter np.ndarray is the defect this exists to stop: it rejected Bezier.begin([0, 0], 45) – which is what the docstring examples write, and what any caller writes – while accepting only the form the library happens to hand back.

Declared here rather than at the top of the module so its value can be a real expression: as a string it is a forward reference the linter cannot see through, and the NDArray import it needs gets pruned as unused.

pybosl2.points.Vector

alias of Point