Geom3 Module

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

Aabb3

A class representing an axis-aligned bounding box in 3D 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, Aabb3 objects will be retrieved from other engeom objects which use them internally, such as Curve3 and Mesh entities. However, they can also be created and manipulated directly.

center property

Get the center point of the AABB.

Returns:

Type	Description
Point3	the center point of the AABB.

extent property

The extent of the box (equivalent to self.max - self.min).

Returns:

Type	Description
Vector3	A vector representing the extent of the box.

max property

Get the maximum point of the AABB.

Returns:

Type	Description
Point3	the maximum point of the AABB.

min property

Get the minimum point of the AABB.

Returns:

Type	Description
Point3	the minimum point of the AABB.

__init__(x_min, y_min, z_min, x_max, y_max, z_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 box.	required
y_min	float	the minimum y coordinate of the box.	required
z_min	float	the minimum z coordinate of the box.	required
x_max	float	the maximum x coordinate of the box.	required
y_max	float	the maximum y coordinate of the box.	required
z_max	float	the maximum z coordinate of the box.	required

at_point(x, y, z, w, h=None, l=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
z	float	The z-coordinate of the center of the AABB.	required
w	float	The width (x extent) of the AABB.	required
h	float | None	The height (y extent) of the AABB. If not provided, it will have the same value as the width.	None
l	float | None	The length (z extent) of the AABB. If not provided, it will have the same value as the width.	None

Returns:

Type	Description
Aabb3	A new axis aligned bounding box 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
Aabb3	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
Aabb3	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
Aabb3	a new AABB object with the shrunk bounds.

Curve3

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

Note

Because this curve is a simplicial 1-complex in 3D space it cannot divide space the way a Curve2 can in 2D space. As a result, it lacks the concept of left/right or inside/outside, and so does not have all the same features that exist in the 2D curve class.

points property

Will return an immutable view of the vertices of the mesh as a numpy array of shape (n, 3).

Returns:

Type	Description
NDArray[float]	a numpy array of shape (n, 3) containing the vertices of the mesh.

__init__(vertices, tol=1e-06)

Create a curve from a set of vertices. The vertices should be a numpy array of shape (n, 3).

Parameters:

Name	Type	Description	Default
vertices	NDArray[float]	a numpy array of shape (n, 3) containing the vertices of the curve.	required
tol	float	the inherent tolerance of the curve; points closer than this distance will be considered the same.	1e-06

at_back()

Return a station at the back of the curve. This is equivalent to calling at_length(length).

Returns:

Type	Description
CurveStation3	a CurveStation3 object representing the station at the back of the curve.

at_closest_to_point(point)

Return a station along the curve at the closest point to the given point. The station will be the point on the curve that is closest to the given point.

Parameters:

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

Returns:

Type	Description
CurveStation3	a CurveStation3 object representing the station along the curve.

at_fraction(fraction)

Return a station along the curve at the given fraction of the length of the curve. If the fraction is greater than 1 or less than 0, an error will be raised.

Parameters:

Name	Type	Description	Default
fraction	float	the fraction of the length of the curve to return the station at.	required

Returns:

Type	Description
CurveStation3	a CurveStation3 object representing the station along the curve.

at_front()

Return a station at the front of the curve. This is equivalent to calling at_length(0).

Returns:

Type	Description
CurveStation3	a CurveStation3 object representing the station at the front of the curve.

at_length(length)

Return a station along the curve at the given length. The length is measured from the start of the curve to the station. If the length is greater than the length of the curve or less than 0, an error will be raised.

Parameters:

Name	Type	Description	Default
length	float	the length along the curve to return the station at.	required

Returns:

Type	Description
CurveStation3	a CurveStation3 object representing the station along the curve.

clone()

Will return a copy of the curve. This is a copy of the data, so modifying the returned curve will not modify the original curve.

Returns:

Type	Description
Curve3	a copy of the curve.

length()

Return the total length of the curve in the units of the vertices.

Returns:

Type	Description
float	the length of the curve.

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
Curve3	a new curve object with the resampled vertices.

simplify(tolerance)

Simplify the curve using the Ramer-Douglas-Peucker algorithm. This will remove vertices from the curve that are within the given tolerance of the line between the previous and next vertices.

Parameters:

Name	Type	Description	Default
tolerance	float	the tolerance to use when simplifying the curve.	required

Returns:

Type	Description
Curve3	a new curve object with the simplified vertices.

transformed_by(iso)

Transform the curve by an isometry. This will return a new curve object with the transformed vertices.

Parameters:

Name	Type	Description	Default
iso	Iso3	the isometry to transform the curve by.	required

Returns:

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

CurveStation3

A class representing a station along a curve in 3D 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 Curve3 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
Vector3	the direction vector of the curve at the station.

direction_point property

A SurfacePoint3 object representing the point on the curve and the curve's tangent/direction vector.

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.

point property

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

Returns:

Type	Description
Point3	the point in 3D world space

FaceFilterHandle

A class that acts as a handle to a filtering (selection/deselection) operation of faces on a mesh.

A filtering operation is started using the face_select_all or face_select_none methods on a Mesh object, and then further filtering operations can be done on the handle to select or deselect faces based on various criteria.

Once finished, the handle can be finalized into a list of the final indices of the triangles that passed the filter, or used to directly create a new mesh containing only the filtered triangles.

collect()

Finalize the handle by collecting the final indices of the triangles that passed the filter.

Returns:

Type	Description
List[int]	a list of the final indices of the triangles that passed the filter.

create_mesh()

Create a new mesh from the filtered triangles. This will build a new mesh object containing only the triangles (and their respective vertices) that are still retained in the filter.

Returns:

Type	Description
Mesh	a new mesh object containing only the filtered triangles.

facing(x, y, z, angle, mode)

Add, remove, or keep only the faces whose normals are facing a given direction within a certain angle tolerance.

This method will alter the filter handle object in place and return self to allow for the use of a fluent-like interface if desired.

Parameters:

Name	Type	Description	Default
x	float	the x component of the direction to check against	required
y	float	the y component of the direction to check against	required
z	float	the z component of the direction to check against	required
angle	float	the maximum angle in radians between the face normal and the filter direction	required
mode	SelectOp	the operation to perform on the faces, one of SelectOp.Add, SelectOp.Remove, or SelectOp.Keep	required

Returns:

Type	Description
FaceFilterHandle	the altered filter handle object

near_mesh(other, all_points, distance_tol, mode, planar_tol=None, angle_tol=None)

Add, remove, or keep only the faces that are within a certain distance of their closest projection onto another mesh. The distance can require that all three vertices of the triangle are within the tolerance, or just one.

There are two additional optional tolerances that can be applied.

1. A planar tolerance, which checks the distance of the vertex projected onto the plane of the reference mesh triangle and looks at how far it is from the projection point. This is useful to filter out triangles that go past the edge of the reference mesh.

2. An angle tolerance, which checks the angle between the normal of the current triangle and the normal of the reference triangle. This is useful to filter out triangles that are not facing the same direction as the reference mesh.

Parameters:

Name	Type	Description	Default
other	Mesh	the mesh to use as a reference	required
all_points	bool	if True, all points of the triangle must be within the tolerance, if False, only one point	required
distance_tol	float	the maximum distance between the triangle and its projection onto the reference mesh	required
mode	SelectOp	the operation to perform on the faces, one of SelectOp.Add, SelectOp.Remove, or SelectOp.Keep	required
planar_tol	float | None	the maximum in-plane distance between the triangle and its projection onto the reference mesh	None
angle_tol	float | None	the maximum angle between the normals of the triangle and the reference mesh	None

Iso3

A class representing an isometry in 3D space. An isometry is a transformation that preserves distances and angles, and is also sometimes known as a rigid body transformation. It is composed of a translation and a rotation, with the rotation part being internally represented by a unit quaternion.

Iso3 objects can be used to transform 3D points, vectors, surface points, other isometries, and a few other types of objects. They can also be inverted and decomposed.

__init__(matrix)

Attempt to create an isometry from a 4x4 matrix in the form of a numpy array. If the matrix is not a valid isometry (it is not orthogonal, it has scale or shear, etc.), an exception will be raised.

Use this method if you explicitly have a known matrix to convert to an isometry, otherwise consider using a composition of the from_translation and from_rotation methods.

Parameters:

Name	Type	Description	Default
matrix	NDArray[float]	a numpy array of shape (4, 4) containing the matrix representation of the isometry.	required

__matmul__(other)

Multiply another object by the isometry, transforming it and returning a new object of the same type.

Parameters:

Name	Type	Description	Default
other	Transformable3	an object of one of the transformable types	required

Returns:

Type	Description
Transformable3	a new object of the same type as the input object, transformed by the isometry.

as_numpy()

Return a copy of the 4x4 matrix representation of the isometry.

flip_around_x()

Return a new isometry that flips the isometry 180° around the x-axis. The origin of the isometry will be preserved, but the y and z axes will point in the opposite directions.

Returns:

Type	Description
Iso3	a new isometry that is the result of the flip.

flip_around_y()

Return a new isometry that flips the isometry 180° around the y-axis. The origin of the isometry will be preserved, but the x and z axes will point in the opposite directions.

Returns:

Type	Description
Iso3	a new isometry that is the result of the flip.

flip_around_z()

Return a new isometry that flips the isometry 180° around the z-axis. The origin of the isometry will be preserved, but the x and y axes will point in the opposite directions.

Returns:

Type	Description
Iso3	a new isometry that is the result of the flip.

from_rotation(angle, ax, ay, az) staticmethod

Create an isometry representing a rotation around an axis defined by a vector direction and the origin. The components of the direction will be automatically normalized before the rotation applied.

When looking down the axis of rotation (the axis is pointing towards the observer), the rotation will be counter-clockwise.

Parameters:

Name	Type	Description	Default
angle	float	the angle to rotate by in radians.	required
ax	float	the x component of the rotation axis.	required
ay	float	the y component of the rotation axis.	required
az	float	the z component of the rotation axis.	required

Returns:

Type	Description
Iso3	the isometry representing the rotation.

from_translation(x, y, z) staticmethod

Create an isometry representing a translation by the specified x, y, and z components.

Parameters:

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

Returns:

Type	Description
Iso3	an isometry containing only a translation component

identity() staticmethod

Return the identity isometry.

inverse()

Get the inverse of the isometry. The inverse is the isometry that will undo the transformation of the original isometry, or the isometry that when applied to the original isometry will return 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 Point3 objects.

Parameters:

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

Returns:

Type	Description
NDArray[float]	a numpy array of shape (N, 3) 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 Vector3 objects.

Parameters:

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

Returns:

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

Mesh

A class holding an unstructured, 3-dimensional mesh of triangles.

aabb property

Get the axis-aligned bounding box of the mesh.

faces property

Will return an immutable view of the triangles of the mesh as a numpy array of shape (m, 3).

Returns:

Type	Description
NDArray[uint32]	a numpy array of shape (m, 3) containing the triangles of the mesh.

vertices property

Will return an immutable view of the vertices of the mesh as a numpy array of shape (n, 3).

Returns:

Type	Description
NDArray[float]	a numpy array of shape (n, 3) containing the vertices of the mesh.

__init__(vertices, faces, merge_duplicates=False, delete_degenerate=False)

Create an engeom mesh from vertices and triangles. The vertices should be a numpy array of shape (n, 3), while the triangles should be a numpy array of shape (m, 3) containing the indices of the vertices that make up each triangle. The triangles should be specified in counter-clockwise order when looking at the triangle from the front/outside.

Tip

If you get an error TypeError: argument 'faces': 'ndarray' object cannot be converted to 'PyArray<T, D>', make sure to convert the faces array to an unsigned integer type, e.g. numpy.uint32.

Parameters:

Name	Type	Description	Default
vertices	NDArray[float]	a numpy array of shape (n, 3) containing the vertices of the mesh.	required
faces	NDArray[uint32]	a numpy array of shape (m, 3) containing the triangles of the mesh, should be uint.	required
merge_duplicates	bool	merge duplicate vertices and triangles	False
delete_degenerate	bool	delete degenerate triangles	False

append(other)

Append another mesh to this mesh. This will add the vertices and triangles from the other mesh to this mesh, changing this one and leaving the other one unmodified.

The merge_duplicates and delete_degenerate flags will control whether to merge duplicate vertices/triangles and delete degenerate triangles when appending the mesh.

Parameters:

Name	Type	Description	Default
other	Mesh	the mesh to append to this mesh, will not be modified in this operation	required

boundary_first_flatten()

This method will perform a conformal mapping of the mesh to the XY plane using the boundary-first flattening algorithm developed by Crane et al. This mapping attempts to preserve angles from the original mesh to the flattened mesh, and is useful for applications such as texture mapping or transformation to an image/raster space for analysis.

There are a number of limitations to this method based on the implementation:

• There can be no non-manifold edges in the mesh. Non-manifold edges are edges that have more than two faces connected to them. If there are non-manifold edges, the method will raise an exception.

• There must be a single patch (sets of faces connected by common edges) in the mesh. If there are multiple patches, the method will raise an exception.

• There can be only one boundary loop in the mesh, meaning that there can be no holes. If there are holes, the method will raise an exception.

The method will return a numpy array of shape (n, 2) containing the flattened vertices of the mesh in the XY plane. There is no specific orientation or position guarantee to the output vertices, so they may need to be transformed, scaled, and/or rotated to fit a specific application.

The 2D vertices in the output will be in the exact same order as those in the mesh and will have a 1:1 correspondence by index, meaning that the faces array from the mesh also describes the triangles in the flattened output.

Returns:

Type	Description
NDArray[float]	a numpy array of shape (n, 2) containing the flattened vertices of the mesh.

cloned()

Will return a copy of the mesh. This is a copy of the data, so modifying the returned mesh will not modify the original mesh.

Returns:

Type	Description
Mesh	an independent copy of the mesh.

create_from_indices(indices)

Create a new mesh from a list of triangle indices. This will build a new mesh object containing only the triangles (and their respective vertices) identified by the given list of indices. Do not allow duplicate indices in the list.

Parameters:

Name	Type	Description	Default
indices	List[int]	the triangle indices to include in the new mesh	required

Returns:

Type	Description
Mesh	a new mesh object containing only the specified triangles

deviation(points, mode)

Calculate the deviation between a set of points and their respective closest points on the mesh surface. There are two possible modes of computing the distance, specified using the DeviationMode enum. The two modes are essentially the same except for how they treat points which are beyond the edge of the closest face.

• DeviationMode.Point: The deviation is calculated as the direct distance from the test point to the closest point on the face.

• DeviationMode.Plane: The deviation is calculated as the distance from the test point to the plane of the face on which the closest point lies. This allows for points that are slightly beyond the edge of the closest face to have a deviation which would be the same as if the edge of the face extended to beyond the test point.

In both cases, the deviation will be positive if the point is outside the surface and negative if the point is inside the surface.

This is a means of efficiently calculating the deviation of a large number of points from a mesh surface. For a single point, the measure_point_deviation method will provide a Distance3 result, which is more suitable for visualization and reporting.

Parameters:

Name	Type	Description	Default
points	NDArray[float]	a numpy array of shape (n, 3) containing the points to calculate the deviation for.	required
mode	DeviationMode	the mode to calculate the deviation in.	required

Returns:

Type	Description
NDArray[float]	a numpy array of shape (n, ) containing the deviation for each point.

face_select_all()

Start a filter operation on the faces of the mesh beginning with all faces selected. This will return a filter object that can be used to further add or remove faces from the selection.

Returns:

Type	Description
FaceFilterHandle	a filter object for the triangles of the mesh.

face_select_none()

Start a filter operation on the faces of the mesh beginning with no faces selected. This will return a filter object that can be used to further add or remove faces from the selection.

Returns:

Type	Description
FaceFilterHandle	a filter object for the triangles of the mesh.

load_stl(path, merge_duplicates=False, delete_degenerate=False) staticmethod

Load a mesh from an STL file. This will return a new mesh object containing the vertices and triangles from the file. Optional parameters can be used to control the behavior of the loader when handling duplicate vertices/ triangles and degenerate triangles.

Note

The STL loader will automatically merge duplicate vertices due to the extreme redundancy of the STL format, but the merge_duplicates flag will control whether to merge vertices when new meshes are appended to the existing mesh.

Parameters:

Name	Type	Description	Default
path	str | Path	the path to the STL file to load.	required
merge_duplicates	bool	merge duplicate vertices and triangles. If None, the default behavior is to do nothing	False
delete_degenerate	bool	delete degenerate triangles. If None, the default behavior is to do nothing	False

Returns:

Type	Description
Mesh	the mesh object containing the data from the file.

measure_point_deviation(x, y, z, dist_mode)

Compute the deviation of a point from this mesh's surface and return it as a measurement object.

The deviation is the distance from the point to its closest projection onto the mesh using the specified distance mode. The direction of the measurement is the direction between the point and the projection, flipped so that it points in the same direction as the mesh surface normal.

If the distance is less than a very small floating point epsilon, the direction will be taken directly from the mesh surface normal.

The first point .a of the measurement is the point on the mesh, and the second point .b is the test point that was given as an argument.

There are two possible modes of computing the distance, specified using the DeviationMode enum. The two modes are essentially the same except for how they treat points which are beyond the edge of the closest face.

• DeviationMode.Point: The deviation is calculated as the direct distance from the test point to the closest point on the face.

• DeviationMode.Plane: The deviation is calculated as the distance from the test point to the plane of the face on which the closest point lies. This allows for points that are slightly beyond the edge of the closest face to have a deviation which would be the same as if the edge of the face extended to beyond the test point.

In both cases, the deviation will be positive if the point is outside the surface and negative if the point is inside the surface.

This method is appropriate for measuring the deviation at a few points of interest, returning a rich object that contains features to aid in visualization or analysis. For bulk measurement of large numbers of points, use the deviation method instead.

Parameters:

Name	Type	Description	Default
x	float	the x component of the point to measure	required
y	float	the y component of the point to measure	required
z	float	the z component of the point to measure	required
dist_mode	DeviationMode	the deviation mode to use	required

Returns:

Type	Description
Distance3	a Distance3 object containing the deviation measurement

sample_poisson(radius)

Sample the surface of the mesh using a Poisson disk sampling algorithm. This will return a numpy array of points and their normals that are approximately evenly distributed across the surface of the mesh. The radius parameter controls the minimum distance between points.

Internally, this algorithm will first re-sample each triangle of the mesh with a dense array of points at a maximum distance of radius/2, before applying a random poisson disk sampling algorithm to thin the resampled points. This means that the output points are not based on the mesh vertices, so large triangles will not be under-represented and small triangles will not be over-represented.

Parameters:

Name	Type	Description	Default
radius	float	the minimum distance between points.	required

Returns:

Type	Description
NDArray[float]	a numpy array of shape (n, 6) containing the sampled points.

section(plane, tol=None)

Calculate and return the intersection curves between the mesh and a plane.

Parameters:

Name	Type	Description	Default
plane	Plane3	The plane to intersect the mesh with.	required
tol	float | None	The curve tolerance to use when constructing the intersection curves. See the Curve3 class initializer for more information on the tolerance parameter.	None

Returns:

Type	Description
List[Curve3]	a list of Curve3 objects representing the intersection curves.

separate_patches()

Separate the mesh into connected patches. This will return a list of new mesh objects, each containing one connected patch of the original mesh. These objects will be clones of the original mesh, so modifying them will have no effect on the original mesh.

Returns:

Type	Description
List[Mesh]	a list of new mesh objects containing the connected patches.

split(plane)

Split the mesh by a plane. The plane will divide the mesh into two possible parts and return them as two new objects. If the part lies entirely on one side of the plane, the other part will be None.

Parameters:

Name	Type	Description	Default
plane	Plane3	the plane to split the mesh by.	required

Returns:

Type	Description
Tuple[Mesh | None, Mesh | None]	a tuple of two optional meshes, the first being that on the negative side of the plane, the second being that on the positive side of the plane.

surface_closest_to(x, y, z)

Find the closest point on the surface of the mesh to a given point in space, returning the point and normal in the form of a SurfacePoint3 object.

Parameters:

Name	Type	Description	Default
x	float	the x coordinate of the point to find the closest point to	required
y	float	the y coordinate of the point to find the closest point to	required
z	float	the z coordinate of the point to find the closest point to	required

Returns:

Type	Description
SurfacePoint3	a SurfacePoint3 object containing the closest point and normal

transform_by(iso)

Transforms the vertices of the mesh by an isometry. This will modify the mesh in place. Any copies made of the vertices will no longer match the mesh after this operation.

Parameters:

Name	Type	Description	Default
iso	Iso3	the isometry to transform the mesh by.	required

write_stl(path)

Write the mesh to an STL file. This will write the vertices and triangles of the mesh to the file in binary format.

Parameters:

Name	Type	Description	Default
path	str | Path	the path to the STL file to write.	required

Plane3

A class representing a plane in 3D space. The plane is represented by a unit normal vector and a distance from the origin along the normal vector.

__init__(a, b, c, d)

Create a plane from the equation ax + by + cz + d = 0.

Parameters:

Name	Type	Description	Default
a	float	the x value of the unit normal vector.	required
b	float	the y value of the unit normal vector.	required
c	float	the z value of the unit normal vector.	required
d	float	the distance from the origin along the normal vector.	required

inverted_normal()

Return a new plane with the normal vector inverted.

Returns:

Type	Description
Plane3	a new plane with the inverted normal vector.

project_point(point)

Project a point onto the plane. The projected point will be the closest point on the plane to the input point.

Parameters:

Name	Type	Description	Default
point	Point3	the point to project.	required

Returns:

Type	Description
Point3	the projected point.

signed_distance_to_point(point)

Calculate the signed distance from the plane to a point. The distance will be positive if the point is on the same side of the plane as the normal vector, and negative if the point is on the opposite side.

Parameters:

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

Returns:

Type	Description
float	the signed distance from the plane to the point.

Point3

Bases: Iterable[float]

A class representing a point in 3D space. The point is represented by its x, y, and z coordinates. It is iterable and will yield the x, y, and z coordinates in that order, allowing the Python unpacking operator * to be used to compensate for the lack of function overloading in other parts of the library.

A point supports a number of mathematical operations, including addition and subtraction with vectors, subtraction with other points, and scaling by a scalar value. It also supports transformation by isometry.

Points have different semantics than vectors when it comes to transformations and some mathematical operations. Be sure to use the type which matches the conceptual use of the object in your code.

coords property

Get the coordinates of the point as a Vector3 object.

Returns:

Type	Description
Vector3	a Vector3 object

x property

Get the x coordinate of the point as a floating point value.

y property

Get the y coordinate of the point as a floating point value.

z property

Get the z coordinate of the point as a floating point value.

__add__(other)

Add a vector to a point to get a new point.

Parameters:

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

Returns:

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

__init__(x, y, z)

Create a point in 3D space by specifying the x, y, and z coordinates.

Parameters:

Name	Type	Description	Default
x	float	the x coordinate of the point	required
y	float	the y coordinate of the point	required
z	float	the z coordinate of the point	required

__mul__(other)

Multiply the coordinates of the point by a scalar value.

Parameters:

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

Returns:

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

__neg__()

Invert the point by negating all of its components.

Returns:

Type	Description
Point3	a new point in which the x, y, and z components are negated

__rmul__(other)

Multiply the coordinates of the point 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	the scalar value to multiply the point by.	required

Returns:

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

__sub__(other)

Subtract a vector from a point to get a new point, or subtract a point from a point to get a new vector.

Parameters:

Name	Type	Description	Default
other	PointOrVector3	the other point or vector to subtract from this point.	required

Returns:

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

__truediv__(other)

Divide the coordinates of the point by a scalar value.

Parameters:

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

Returns:

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

as_numpy()

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

SurfacePoint3

This class is used to represent a surface point in 3D 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 Vector3 object.

Returns:

Type	Description
Vector3	a Vector3 object

point property

Get the coordinates of the point as a Point3 object.

Returns:

Type	Description
Point3	a Point3 object

__init__(x, y, z, nx, ny, nz)

Create a surface point in 3D space by specifying the x, y, and z coordinates of the point, as well as the x, y, and z components of the normal vector. The normal components will be normalized before being stored, so they do not need to be scaled to unit length before being passed to this constructor.

Parameters:

Name	Type	Description	Default
x	float	the x coordinate of the point	required
y	float	the y coordinate of the point	required
z	float	the z coordinate of the point	required
nx	float	the x component of the normal vector (will be normalized after construction)	required
ny	float	the y component of the normal vector (will be normalized after construction)	required
nz	float	the z component of the normal vector (will be normalized after construction)	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		required

Returns:

Type	Description
SurfacePoint3

__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		required

Returns:

Type	Description
SurfacePoint3

__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		required

Returns:

Type	Description
SurfacePoint3

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
Point3	the point at the distance along the normal.

get_plane()

Get the plane defined by the surface point.

Returns:

Type	Description
Plane3	the plane defined by the surface point.

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	Point3	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	Point3	the point to calculate the projection of.	required

Returns:

Type	Description
Point3	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
SurfacePoint3	a new surface point with the inverted 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	Point3	the point to calculate the projection of.	required

Returns:

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

SvdBasis3

A class which creates a set of orthonormal basis vectors from a set of points in 3D 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, 3) 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()

Return the standard deviations of the basis vectors.

Returns:

Type	Description
NDArray[float]	a numpy array of shape (3, ) containing the standard deviations of the basis vectors.

basis_variances()

Return the variances of the basis vectors.

Returns:

Type	Description
NDArray[float]	a numpy array of shape (3, ) containing the variances of the basis vectors.

largest()

Return the largest normalized basis vector.

Returns:

Type	Description
Vector3	a Vector3 object containing the largest basis 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 maximum rank is 3, which indicates that the point set cannot be reduced to a lower dimension.

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()

Return the smallest normalized basis vector.

Returns:

Type	Description
Vector3	a Vector3 object containing the smallest basis vector.

to_iso3()

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 in an arbitrary plane, transforming the original points by this isometry will move the points such that all points lie on the XY plane.

Returns:

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

Vector3

Bases: Iterable[float]

A class representing a vector in 3D space. The vector is represented by its x, y, and z components. It is iterable and will yield the x, y, and z components in that order, allowing the Python unpacking operator * to be used to compensate for the lack of function overloading in other parts of the library.

A vector supports a number of mathematical operations, including addition, subtraction, scalar multiplication, dot and cross products, and normalization. It also supports transformation by isometry.

Vectors have different semantics than points when it comes to transformations and some mathematical operations. Be sure to use the type which matches the conceptual use of the object in your code.

x property

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

y property

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

z property

Get the z component of the vector as a floating point value.

__add__(other)

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

Parameters:

Name	Type	Description	Default
other	PointOrVector3	the other vector or point to add to this vector.	required

Returns:

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

__init__(x, y, z)

Create a vector in 3D space by specifying the x, y, and z components.

Parameters:

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

__mul__(other)

Multiply the vector by a scalar value.

Parameters:

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

Returns:

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

__neg__()

Invert the vector by negating all of its components.

Returns:

Type	Description
Vector3	a new vector in which the x, y, and z 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	the scalar value to multiply the vector by.	required

Returns:

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

__sub__(other)

Subtract another vector from this vector.

Parameters:

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

Returns:

Type	Description
Vector3	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	the scalar value to divide the vector by.	required

Returns:

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

angle_to(other)

Calculate the smallest angle between this vector and another vector and return it in radians.

Parameters:

Name	Type	Description	Default
other	Vector3	the other vector to calculate the angle to.	required

Returns:

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

as_numpy()

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

cross(other)

Calculate the cross product of this vector with another vector.

Parameters:

Name	Type	Description	Default
other	Vector3	the other vector to calculate the cross product with.	required

Returns:

Type	Description
Vector3	the cross product of the two vectors.

dot(other)

Calculate the dot product of this vector with another vector.

Parameters:

Name	Type	Description	Default
other	Vector3	the other vector to calculate the dot product with.	required

Returns:

Type	Description
float	the dot product of the two vectors.

norm()

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

Returns:

Type	Description
float	the length of the vector as a floating point value.

normalized()

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

Returns:

Type	Description
Vector3	a new vector that has unit length