Geom2 Module

This module contains a number of classes and functions for working with 2D geometry. These range from fundamental primitives like points and vectors up to complex items like polylines.

Aabb2

A class representing an axis-aligned bounding box in 2D space. The bounding box is defined by a minimum point and a maximum point, which are the lower-left and upper-right corners of the box, respectively.

Bounding boxes are typically used for accelerating intersection and distance queries and are used internally inside the Rust language engeom library for this purpose. However, they have other useful applications and so are exposed here in the Python API.

Typically, Aabb2 objects will be retrieved from other engeom objects which use them internally, such as curves, circles, arcs, etc. However, they can also be created and manipulated directly.

center property

Get the center point of the AABB.

Returns:

Type	Description
Point2	the center point of the AABB.

extent property

Get the extent of the AABB.

Returns:

Type	Description
Vector2	the extent of the AABB.

max property

Get the maximum point of the AABB.

Returns:

Type	Description
Point2	the maximum point of the AABB.

min property

Get the minimum point of the AABB.

Returns:

Type	Description
Point2	the minimum point of the AABB.

__init__(x_min, y_min, x_max, y_max)

Create an axis-aligned bounding box from the minimum and maximum coordinates.

Parameters:

Name	Type	Description	Default
x_min	float	the minimum x-coordinate of the AABB	required
y_min	float	the minimum y-coordinate of the AABB	required
x_max	float	the maximum x-coordinate of the AABB	required
y_max	float	the maximum y-coordinate of the AABB	required

at_point(x, y, w, h=None) staticmethod

Create an AABB centered at a point with a given width and height.

Parameters:

Name	Type	Description	Default
x	float	the x-coordinate of the center of the AABB.	required
y	float	the y-coordinate of the center of the AABB.	required
w	float	the width of the AABB.	required
h	float | None	the height of the AABB. If not provided, the AABB will be square.	None

Returns:

Type	Description
Aabb2	a new AABB object.

expand(d)

Expand the AABB by a given distance in all directions. The resulting height and width will be increased by 2 * d.

Parameters:

Name	Type	Description	Default
d	float	the distance to expand the AABB by.	required

Returns:

Type	Description
Aabb2	a new AABB object with the expanded bounds.

from_points(points) staticmethod

Create an AABB that bounds a set of points. If the point array is empty or the wrong shape, an error will be thrown.

Parameters:

Name	Type	Description	Default
points	NDArray[float]	a numpy array of shape (N, 2) containing the points to bound	required

Returns:

Type	Description
Aabb2	a new AABB object

shrink(d)

Shrink the AABB by a given distance in all directions. The resulting height and width will be decreased by 2 * d.

Parameters:

Name	Type	Description	Default
d	float	the distance to shrink the AABB by.	required

Returns:

Type	Description
Aabb2	a new AABB object with the shrunk bounds.

Arc2

An arc in 2D space. The arc is defined by a center point, a radius, a start angle, and a sweep angle.

• The center point and the radius define the circle of which the arc is part.

• The start angle is the angle in radians from the positive x-axis to the point where the arc begins. A positive value is a counter-clockwise rotation, so a start angle of \(\pi / 2\) would start the arc at the top \(y=r\) of the circle.

• The sweep angle is the angle in radians that the arc covers, beginning at the starting point. A positive value is a counter-clockwise rotation, a negative value is clockwise.

aabb property

Get the axis-aligned bounding box of the arc.

Returns:

Type	Description
Aabb2	the axis-aligned bounding box of the arc.

center property

Get the center point of the arc.

Returns:

Type	Description
Point2	the center of the arc.

end_point property

Get the end point of the arc.

Returns:

Type	Description
Point2	the end point of the arc.

r property

Get the radius of the arc

Returns:

Type	Description
float	the radius of the arc

start property

Get the start angle of the arc, in radians.

Returns:

Type	Description
float	the start angle of the arc in radians.

start_point property

Get the start point of the arc.

Returns:

Type	Description
Point2	the start point of the arc.

sweep property

Get the sweep angle of the arc, in radians.

Returns:

Type	Description
float	the sweep angle of the arc in radians.

x property

Get the x-coordinate of the center of the arc.

Returns:

Type	Description
float	the x-coordinate of the arc center.

y property

Get the y-coordinate of the center of the arc.

Returns:

Type	Description
float	the y-coordinate of the arc center

__init__(x, y, r, start_radians, sweep_radians)

Create an arc from the given center point, radius, start angle, and sweep angle.

Parameters:

Name	Type	Description	Default
x	float	the x-coordinate of the center of the arc.	required
y	float	the y-coordinate of the center of the arc.	required
r	float	the radius of the arc.	required
start_radians	float	the start angle of the arc in radians, which is the angle from the positive x-axis to the starting point of the arc. A positive value is a counter-clockwise rotation.	required
sweep_radians	float	the sweep angle of the arc in radians, which is the angle that the arc covers, beginning at the starting point. A positive value is a counter-clockwise rotation, a negative value is clockwise.	required

Circle2

A class representing a circle in 2D space. The circle is defined by a center point and a radius.

aabb property

Get the axis-aligned bounding box of the circle.

Returns:

Type	Description
Aabb2	the axis-aligned bounding box of the circle.

center property

Get the Point2 at the center of the circle.

Returns:

Type	Description
Point2	the center of the circle.

r property

Get the radius of the circle.

Returns:

Type	Description
float	the radius of the circle.

x property

Get the x-coordinate of the circle.

Returns:

Type	Description
float	the x-coordinate of the circle.

y property

Get the y-coordinate of the circle.

Returns:

Type	Description
float	the y-coordinate of the circle.

__init__(x, y, r)

Create a circle from the given center point and radius.

Parameters:

Name	Type	Description	Default
x	float	the x-coordinate of the center of the circle.	required
y	float	the y-coordinate of the center of the circle.	required
r	float	the radius of the circle.	required

Curve2

A class representing a curve in 2D space. The curve is defined by a set of vertices and the line segments between them (also known as a polyline).

Because the curve is in 2D space, it also has a concept of a surface normal direction, which is orthogonal to the tangent direction of the curve at any point. This normal direction allows a Curve2 to represent a 2D manifold surface boundary, defining the concepts of inside and outside. It is commonly used to represent the surface of a solid body in a 2D cross-section.

Additionally, the Curve2 object can be used to represent closed regions by connecting the first and last vertices and allowing the curve to be treated as a closed loop. This lets the Curve2 also represent closed polygons.

is_closed property

Check if the curve is closed.

Returns:

Type	Description
bool	True if the curve is closed, False otherwise.

points property

Get the points of the curve.

Returns:

Type	Description
NDArray[float]	a numpy array of shape (N, 2) representing the points of the curve.

__init__(vertices, normals=None, tol=1e-06, force_closed=False, hull_ccw=False)

Create a 2d curve from a set of vertices and some additional options.

It's important to note that in 2d, a curve has a concept of a normal direction, built from the concept of inside/outside defined through the winding order of the vertices. This extra information can allow a 2d curve to model a manifold surface.

There are three ways to specify the winding order of the vertices:

1. Control it manually by passing the vertices array with the rows already organized so that an exterior surface is counter-clockwise.

2. If the vertices represent an exterior shape, pass hull_ccw=True to have the constructor automatically check the winding order and reverse it if point ordering in the convex hull does not match ordering in the original array.

3. Pass a normals array the same size as the vertices array, where the normals are non-zero vectors pointed in the "outside" direction at each point. The constructor will reverse the winding if the majority of normals do not point in the same direction as the winding.

Parameters:

Name	Type	Description	Default
vertices	NDArray[float]	a numpy array of shape (N, 2) representing the vertices of the curve.	required
normals	NDArray[float] | None	an optional numpy array of shape (N, 2) representing the normals of the curve associated with each vertex.	None
tol	float	a tolerance value for the curve. If not provided, a default value of 1e-6 is used. This is the distance at which two points are considered to be the same.	1e-06
force_closed	bool	If True, the curve will be closed even if the first and last points are not the same, which will be done by adding a new point at the end of the array that is the same as the first point.	False
hull_ccw	bool	If True, the constructor will check the winding order of the vertices and reverse it if the convex hull of the points is not in the same order as the original array. This will do nothing if the normals parameter is provided.	False

at_back()

Get the station at the back of the curve.

Returns:

Type	Description
CurveStation2	the station at the back of the curve.

at_closest_to_point(point)

Get the station on the curve that is closest to a given point.

Parameters:

Name	Type	Description	Default
point	Point2	the point to find the closest station to.	required

Returns:

Type	Description
CurveStation2	the station on the curve that is closest to the given point.

at_fraction(fraction)

Get the station at a given fraction of the length of the curve. Will throw a ValueError if the fraction is less than zero or greater than one.

Parameters:

Name	Type	Description	Default
fraction	float	the fraction of the length of the curve.	required

Returns:

Type	Description
CurveStation2	the station at the given fraction.

at_front()

Get the station at the front of the curve.

Returns:

Type	Description
CurveStation2	the station at the front of the curve.

at_length(length)

Get the station at a given length along the curve. Will throw a ValueError if the length is less than zero or greater than the length of the curve.

Parameters:

Name	Type	Description	Default
length	float	the length along the curve.	required

Returns:

Type	Description
CurveStation2	the station at the given length.

between_lengths(l0, l1)

Attempt to get a new curve cut between two lengths along the curve. If the lengths are not valid, a ValueError will be thrown.

If the curve is closed, the lengths will be wrapped around the curve. If the curve is not closed, the value of l0 must be less than l1. In either case, the lengths must be within the bounds of the curve.

Parameters:

Name	Type	Description	Default
l0	float	the start length.	required
l1	float	the end length.	required

Returns:

Type	Description
Curve2	a new curve between the two lengths.

between_lengths_by_control(a, b, control)

Attempt to get a new curve cut between two lengths along the curve, with a control point that will be used to determine which side of the curve to keep. This is primarily helpful on closed curves when you can find a length (usually via use of the at_closest_to_point method) that is on the side of the curve you want to keep.

If the lengths are not valid, a ValueError will be thrown.

Parameters:

Name	Type	Description	Default
a	float	the first length along the curve to cut	required
b	float	the second length along the curve to cut	required
control	float	a length along the curve that is on a point in the portion of the result that you want to keep	required

Returns:

Type	Description
Curve2	a new curve between the two lengths

length()

Get the total length of the curve as a scalar value.

Returns:

Type	Description
float	the length of the curve.

make_hull()

Get the vertices of a convex hull of the curve, in counter-clockwise order.

Returns:

Type	Description
NDArray[int]	a numpy array of shape (N, 2) representing the convex hull of the curve.

max_distance_in_direction(surf_point)

Find the maximum scalar projection of all vertices of the curve onto a surface point.

Parameters:

Name	Type	Description	Default
surf_point	SurfacePoint2	the direction to find the furthest point in.	required

Returns:

Type	Description
float	the maximum scalar projection of all vertices of the curve onto a surface point.

max_point_in_direction(direction)

Find the point on the curve that is furthest in a given direction.

Parameters:

Name	Type	Description	Default
direction	Vector2	the direction to find the furthest point in.	required

Returns:

Type	Description
Tuple[int, Point2]	a tuple of the index of the point and the point itself.

resample(resample)

Resample the curve using the given resampling method. The resampling method can be one of the following:

• Resample.ByCount(count: int): resample the curve to have the given number of points.
• Resample.BySpacing(distance: float): resample the curve to have points spaced by the given distance.
• Resample.ByMaxSpacing(distance: float): resample the curve to have points spaced by a maximum distance.

Parameters:

Name	Type	Description	Default
resample	ResampleEnum	the resampling method to use.	required

Returns:

Type	Description
Curve2	a new curve object with the resampled vertices.

reversed()

Reverse the curve and return a new curve.

Returns:

Type	Description
Curve2	a new curve with the vertices in reverse order.

simplify(tol)

Simplify the curve using the Ramer-Douglas-Peucker algorithm.

Parameters:

Name	Type	Description	Default
tol	float	the tolerance to use for simplification.	required

Returns:

Type	Description
Curve2	a new curve with the simplified points.

to_3d()

Convert the curve to a 3D curve by adding a z-coordinate of 0 to all points.

Returns:

Type	Description
Curve3	a new Curve3 object representing the curve in 3D space.

transformed_by(transform)

Transform the curve by the given transform and return a new curve.

Parameters:

Name	Type	Description	Default
transform	Iso2	the transform to apply to the curve.	required

Returns:

Type	Description
Curve2	a new curve object with the transformed vertices.

trim_back(length)

Remove the back of the curve by a given length and return a new curve.

Parameters:

Name	Type	Description	Default
length	float	the length to trim from the back of the curve.	required

Returns:

Type	Description
Curve2	a new curve with the back trimmed by the given length.

trim_front(length)

Remove the front of the curve by a given length and return a new curve.

Parameters:

Name	Type	Description	Default
length	float	the length to trim from the front of the curve.	required

Returns:

Type	Description
Curve2	a new curve with the front trimmed by the given length.

CurveStation2

A class representing a station along a curve in 2D space. The station is represented by a point on the curve, a tangent (direction) vector, and a length along the curve.

These are created as the result of position finding operations on Curve2 objects.

direction property

Get the direction vector of the curve at the location of the station. This is the tangent vector of the curve, and is typically the direction from the previous vertex to the next vertex.

Returns:

Type	Description
Vector2	the direction vector of the curve at the station.

direction_point property

Get the combined point and direction vector of the curve at the location of the station, returned as a SurfacePoint2 object.

Returns:

Type	Description
SurfacePoint2	the combined point and direction vector of the curve at the station.

index property

Get the index of the previous vertex on the curve, at or before the station.

Returns:

Type	Description
int	the index of the previous vertex on the curve.

length_along property

Get the length along the curve to the station, starting at the first vertex of the curve.

Returns:

Type	Description
float	the length along the curve to the station.

normal property

Get the normal vector of the curve at the location of the station. This is the vector that is orthogonal to the direction vector, and is the direction vector at the station rotated by -90 degrees. When the curve represents a manifold surface, this vector represents the direction of the surface normal.

Returns:

Type	Description
Vector2	the surface normal vector of the curve at the station.

point property

Get the point in 2D world space where the station is located.

Returns:

Type	Description
Point2	the point in 2D world space.

surface_point property

Get the combined point and normal vector of the curve at the location of the station, returned as a SurfacePoint2 object.

Returns:

Type	Description
SurfacePoint2	the combined point and normal vector of the curve at the station.

Iso2

A class representing an isometry in 2D space. An isometry is a transformation that preserves distances and angles, also sometimes known as a rigid body transformation. It is composed of a translation and a rotation.

Iso2 objects can be used to transform points, vectors, surface points, other isometries, and a number of other 2D geometric constructs.

__init__(tx, ty, r)

Create an isometry from a translation and a rotation. The translation is represented by the x and y components of the translation vector. The rotation is represented by the angle in radians, and will be a rotation around the origin of the coordinate system.

In convention with typical transformation matrices, transforming by an isometry constructed this way is the equivalent of first rotating by the angle r and then translating by the vector (tx, ty).

Parameters:

Name	Type	Description	Default
tx	float	the x component of the translation vector.	required
ty	float	the y component of the translation vector.	required
r	float	the angle of rotation in radians around the origin, where a positive value is a counter-clockwise rotation.	required

__matmul__(other)

Transform a point, vector, or other transformable object by the isometry using the matrix multiplication operator. The transform must be on the right side of the operator, and the object being transformed must be on the left side. This is the equivalent of multiplying the object by the isometry matrix.

When composing multiple isometries together, remember that the order of operations is reversed. For example, if you have isometries A, B, and C, and you want to compose them together such that they are the equivalent of first applying A, then B, then C, you would write D = C @ B @ A.

Parameters:

Name	Type	Description	Default
other	Transformable2	the object to transform.	required

Returns:

Type	Description
Transformable2	an object of the same type as the input, transformed by the isometry.

as_numpy()

Create a numpy array of shape (3, 3) from the isometry.

identity() staticmethod

Create the identity isometry.

inverse()

Get the inverse of the isometry, which is the isometry that undoes the transformation of the original isometry, or the isometry that when composed with the original isometry produces the identity isometry.

transform_points(points)

Transform an array of points using the isometry. The semantics of transforming points are such that the full matrix is applied, first rotating the point around the origin and then translating it by the translation vector.

To transform vectors, use the transform_vectors method instead.

This is an efficient way to transform a large number of points at once, rather than using the @ operator individually on a large number of Point2 objects.

Parameters:

Name	Type	Description	Default
points	NDArray[float]	a numpy array of shape (N, 2)	required

Returns:

Type	Description
NDArray[float]	a numpy array of shape (N, 2) containing the transformed points in the same order as the input.

transform_vectors(vectors)

Transform an array of vectors using the isometry. The semantics of transforming vectors are such that only the rotation matrix is applied, and the translation vector is not used. The vectors retain their original magnitude, but their direction is rotated by the isometry.

To transform points, use the transform_points method instead.

This is an efficient way to transform a large number of vectors at once, rather than using the @ operator individually on a large number of Vector2 objects.

Parameters:

Name	Type	Description	Default
vectors	NDArray[float]	a numpy array of shape (N, 2)	required

Returns:

Type	Description
NDArray[float]	a numpy array of shape (N, 2) containing the transformed vectors in the same order as the input.

Point2

Bases: Iterable[float]

A class representing a point in 2D space. The point contains an x and y component. It is iterable and will yield the x and y components in order, allowing the Python unpacking operator * to be used to compensate for the lack of function overloading through some other parts of the library.

A point has different semantics than a vector when it comes to transformations and some mathematical operations.

coords property

Get the coordinates of the point as a Vector2 object.

Returns:

Type	Description
Vector2	a Vector2 object with the same x and y components as the point.

x property

Access the x component of the point as a floating point value.

y property

Access the y component of the point as a floating point value.

__add__(other)

Add a vector to this point.

Parameters:

Name	Type	Description	Default
other	Vector2	the vector to add to the point.	required

Returns:

Type	Description
Vector2	a new point that is the result of the addition.

__init__(x, y)

Create a 2D point from the given x and y components.

Parameters:

Name	Type	Description	Default
x	float	the x component of the point.	required
y	float	the y component of the point.	required

__mul__(other)

Multiply the point's x and y components by a scalar value, returning a new point.

Parameters:

Name	Type	Description	Default
other	float	the scalar value to multiply the point by.	required

Returns:

Type	Description
Point2	a new point that is the result of the multiplication.

__neg__()

Invert the point by negating the x and y components.

Returns:

Type	Description
Point2	a new point in which the x and y components are negated.

__rmul__(other)

Multiply the point's x and y components by a scalar value, returning a new point. This allows the scalar to be on the left side of the multiplication.

Parameters:

Name	Type	Description	Default
other		the scalar value to multiply the point by.	required

Returns:

Type	Description
Point2	a new point that is the result of the multiplication.

__sub__(other)

Subtract a point or vector from this point. Subtracting a point from a point will return a new vector, while subtracting a vector from a point will return a new point.

Parameters:

Name	Type	Description	Default
other	PointOrVec2	a point or vector to subtract from the point.	required

Returns:

Type	Description
PointOrVec2	a new point or vector that is the result of the subtraction.

__truediv__(other)

Divide the point's x and y components by a scalar value, returning a new point.

Parameters:

Name	Type	Description	Default
other		the scalar value to divide the point by.	required

Returns:

Type	Description
Point2	a new point that is the result of the division.

as_numpy()

Create a numpy array of shape (2, ) from the point.

SurfacePoint2

This class is used to represent a surface point in 2D space.

Surface points are a composite structure that consist of a point in space and a normal direction. Conceptually, they come from metrology as a means of representing a point on the surface of an object along with the normal direction of the surface at that point. However, they are also isomorphic with the concept of a ray or a parameterized line with a direction of unit length, and can be used in that way as well.

normal property

Get the normal of the point as a Vector2 object.

Returns:

Type	Description
Vector2	a Vector2 object

point property

Get the coordinates of the point as a Point2 object.

Returns:

Type	Description
Point2	a Point2 object

__init__(x, y, nx, ny)

Create a surface point from the given x and y components and the normal vector components. The normal vector components will be normalized automatically upon creation. If the normal vector is the zero vector, an exception will be thrown.

Parameters:

Name	Type	Description	Default
x	float	the x component of the point.	required
y	float	the y component of the point.	required
nx	float	the x component of the normal vector.	required
ny	float	the y component of the normal vector.	required

__mul__(other)

Multiply the position of the surface point by a scalar value. The normal vector is not affected unless the scalar is negative, in which case the normal vector is inverted.

Parameters:

Name	Type	Description	Default
other	float	the scalar value to multiply the position by.	required

Returns:

Type	Description
SurfacePoint2	a new surface point with the position multiplied by the scalar.

__neg__()

Invert both the position AND the normal vector of the surface point.

__rmul__(other)

Multiply the position of the surface point by a scalar value. The normal vector is not affected unless the scalar is negative, in which case the normal vector is inverted.

Parameters:

Name	Type	Description	Default
other	float	the scalar value to multiply the position by.	required

Returns:

Type	Description
SurfacePoint2	a new surface point with the position multiplied by the scalar.

__truediv__(other)

Divide the position of the surface point by a scalar value. The normal vector is not affected unless the scalar is negative, in which case the normal vector is inverted.

Parameters:

Name	Type	Description	Default
other	float	the scalar value to divide the position by.	required

Returns:

Type	Description
SurfacePoint2	a new surface point with the position divided by the scalar.

at_distance(distance)

Get the point at a distance along the normal from the surface point.

Parameters:

Name	Type	Description	Default
distance	float	the distance to move along the normal.	required

Returns:

Type	Description
Point2	the point at the distance along the normal.

planar_distance(point)

Calculate the planar (non-normal) distance between the surface point and a point. This is complementary to the scalar projection. A point is projected onto the plane defined by the position and normal of the surface point, and the distance between the surface point position and the projected point is returned. The value will always be positive.

Parameters:

Name	Type	Description	Default
point	Point2	the point to calculate the distance to.	required

Returns:

Type	Description
float	the planar distance between the surface point and the point.

projection(point)

Calculate the projection of a point onto the axis defined by the surface point position and direction.

Parameters:

Name	Type	Description	Default
point	Point2	the point to calculate the projection of.	required

Returns:

Type	Description
Point2	the projection of the point onto the plane.

reversed()

Return a new surface point with the normal vector inverted, but the position unchanged.

Returns:

Type	Description
SurfacePoint2	a new surface point with the inverted normal vector.

rot_normal(angle)

Rotate the normal vector of the surface point by a given angle in radians and return a new surface point. The position of the surface point is not affected. The angle is positive for counter-clockwise rotation and negative for clockwise rotation.

Parameters:

Name	Type	Description	Default
angle	float	the angle to rotate the normal vector by.	required

Returns:

Type	Description
SurfacePoint2	a new surface point with the rotated normal vector.

scalar_projection(point)

Calculate the scalar projection of a point onto the axis defined by the surface point position and direction. Positive values indicate that the point is in the normal direction from the surface point, while negative values indicate that the point is in the opposite direction.

Parameters:

Name	Type	Description	Default
point	Point2	the point to calculate the projection of.	required

Returns:

Type	Description
float	the scalar projection of the point onto the normal.

shift_orthogonal(distance)

Shift the surface point by a distance orthogonal to the normal vector. The direction of travel is the surface point's normal vector rotated 90 degrees clockwise. For instance, if the normal vector is (0, 1), a positive distance will move the point to the right and a negative distance will move the point to the left.

Parameters:

Name	Type	Description	Default
distance	float	the distance to shift the surface point.	required

Returns:

Type	Description
SurfacePoint2	a new surface point shifted by the given distance.

SvdBasis2

A class which creates a set of orthonormal basis vectors from a set of points in 2D space. The basis is created using a singular value decomposition of the points, and is very similar to the statistical concept of principal component analysis.

The basis can be used to determine the rank of the point set, the variance of the points along the basis vectors, and to extract an isometry that will transform points from the world space to the basis space. It is useful for orienting unknown point sets in a consistent way, for finding best-fit lines or planes, and for other similar tasks.

__init__(points, weights=None)

Create a basis from a set of points. The basis will be calculated using a singular value decomposition of the points.

Parameters:

Name	Type	Description	Default
points	NDArray[float]	a numpy array of shape (n, 2) containing the points to calculate the basis from.	required
weights	NDArray[float] | None	a numpy array of shape (n,) containing the weights of the points. If None, all points will be weighted equally.	None

basis_stdevs()

Get the standard deviation of the points along the singular vectors.

Returns:

Type	Description
NDArray[float]	a numpy array of the standard deviation of the points along the singular vectors.

basis_variances()

Get the variance of the points along the singular vectors.

Returns:

Type	Description
NDArray[float]	a numpy array of the variance of the points along the singular vectors.

largest()

Get the largest singular vector of the basis.

Returns:

Type	Description
Vector2	the largest singular vector.

rank(tol)

Retrieve the rank of the decomposition by counting the number of singular values that are greater than the provided tolerance. A rank of 0 indicates that all singular values are less than the tolerance, and thus the point set is essentially a single point. A rank of 1 indicates that the point set is essentially a line. A rank of 2 indicates that the point set exists roughly in a plane.

The singular values do not directly have a clear physical meaning. They are square roots of the variance multiplied by the number of points used to compute the basis. Thus, they can be interpreted in relation to each other, and when they are very small.

This method should be used either when you know roughly what a cutoff tolerance for the problem you're working on should be, or when you know the cutoff value should be very small. Otherwise, consider examining the standard deviations of the basis vectors instead, as they will be easier to interpret (basis_stdevs()).

Parameters:

Name	Type	Description	Default
tol	float	the tolerance to use when determining the rank.	required

Returns:

Type	Description
int	the rank of the decomposition.

smallest()

Get the smallest singular vector of the basis.

Returns:

Type	Description
Vector2	the smallest singular vector.

to_iso2()

Produce an isometry which will transform from the world space to the basis space.

For example, if the basis is created from a set of points that lie roughly on an arbitrary line, multiplying original points by this isometry will move the points such that all points are aligned with the x-axis.

Returns:

Type	Description
Iso2	the isometry that transforms from the world space to the basis space.

Vector2

Bases: Iterable[float]

A class representing a vector in 2D space. The vector contains an x and y component. It is iterable and will yield the x and y components in order, allowing the Python unpacking operator * to be used to compensate for the lack of function overloading through some other parts of the library.

A vector has different semantics than a point when it comes to transformations and some mathematical operations.

x property

Access the x component of the vector as a floating point value.

y property

Access the y component of the vector as a floating point value.

__add__(other)

Add a vector to a point or another vector. Adding a vector to a point will return a new point, while adding a vector to a vector will return a new vector.

Parameters:

Name	Type	Description	Default
other	PointOrVec2	a point or vector to add to the vector.	required

Returns:

Type	Description
PointOrVec2	a new point or vector that is the result of the addition.

__init__(x, y)

Create a 2D vector from the given x and y components.

Parameters:

Name	Type	Description	Default
x	float	the x component of the vector.	required
y	float	the y component of the vector.	required

__mul__(other)

Multiply the vector by a scalar value.

Parameters:

Name	Type	Description	Default
other	float	a scalar value to multiply the vector by.	required

Returns:

Type	Description
Vector2	a new vector that is the result of the multiplication.

__neg__()

Invert the vector by negating the x and y components.

Returns:

Type	Description
Vector2	a new vector in which the x and y components are negated.

__rmul__(other)

Multiply the vector by a scalar value. This allows the scalar to be on the left side of the multiplication operator.

Parameters:

Name	Type	Description	Default
other	float	a scalar value to multiply the vector by.	required

Returns:

Type	Description
Vector2	a new vector that is the result of the multiplication.

__sub__(other)

Subtract a vector from this vector.

Parameters:

Name	Type	Description	Default
other	Vector2	the vector to subtract from this vector.	required

Returns:

Type	Description
Vector2	a new vector that is the result of the subtraction.

__truediv__(other)

Divide the vector by a scalar value.

Parameters:

Name	Type	Description	Default
other	float	a scalar value to divide the vector by.	required

Returns:

Type	Description
Vector2	a new vector that is the result of the division.

angle_to(other)

Compute the smallest angle between two vectors and return it in radians.

Parameters:

Name	Type	Description	Default
other	Vector2	the vector to compute the angle to.	required

Returns:

Type	Description
float	the angle between the two vectors in radians.

as_numpy()

Create a numpy array of shape (2, ) from the vector.

cross(other)

Compute the cross product of two vectors.

Parameters:

Name	Type	Description	Default
other	Vector2	the vector to compute the cross product with.	required

Returns:

Type	Description
float	the scalar cross product of the two vectors.

dot(other)

Compute the dot product of two vectors. The result is a scalar value.

Parameters:

Name	Type	Description	Default
other	Vector2	the vector to compute the dot product with.	required

Returns:

Type	Description
float	the scalar dot product of the two vectors.

norm()

Compute the Euclidian norm (aka magnitude, length) of the vector.

normalized()

Return a normalized version of the vector. The normalized vector will have the same direction as the original vector, but with a magnitude of 1.