Geometry¤
Differentiable geometric primitives written in JAX, used by the goals and constraints to measure an equilibrium state.
Vectors¤
length_vector(u: Float[Array, 3]) -> Float[Array, 1]
Calculate the length of a vector.
Parameters:
-
u(Float[Array, 3]) –The vector.
Returns:
-
length(Float[Array, 1]) –The Euclidean length of the vector.
length_vector_sqrd(u: Float[Array, 3]) -> Float[Array, 1]
Calculate the squared length of a vector.
Parameters:
-
u(Float[Array, 3]) –The vector.
Returns:
-
length(Float[Array, 1]) –The squared Euclidean length of the vector.
normalize_vector(u: Float[Array, 3], safe_nan: bool = True) -> Float[Array, 3]
Scale a vector such that it has a unit length.
Parameters:
-
u(Float[Array, 3]) –The vector to normalize.
-
safe_nan(bool, default:True) –If True, replace nan entries by zeroes before normalizing.
Returns:
-
vector(Float[Array, 3]) –The unit-length vector.
Notes
If safe_nan is True, any nan values in the input vector are replaced by zeroes. The function will return a zero vector if the input vector is a zero vector or if all its elements are nan.
vector_unitized(u: Float[Array, 3]) -> Float[Array, 3]
Scale a vector such that it has a unit length.
Parameters:
-
u(Float[Array, 3]) –The vector to normalize.
Returns:
-
vector(Float[Array, 3]) –The unit-length vector.
Notes
Unlike normalize_vector, this helper does not guard against zero-length or nan input, so it divides by the raw vector length.
subtract_vectors(u: Float[Array, 3], v: Float[Array, 3]) -> Float[Array, 3]
Subtract two vectors.
Parameters:
-
u(Float[Array, 3]) –The vector to subtract from.
-
v(Float[Array, 3]) –The vector to subtract.
Returns:
-
vector(Float[Array, 3]) –The difference u - v.
vector_projection(u: Float[Array, 3], v: Float[Array, 3]) -> Float[Array, 3]
Calculates the orthogonal projection of u onto v.
Parameters:
-
u(Float[Array, 3]) –The vector to project.
-
v(Float[Array, 3]) –The vector to project onto.
Returns:
-
projection(Float[Array, 3]) –The component of u parallel to v.
cosine_vectors(u: Float[Array, 3], v: Float[Array, 3]) -> Float[Array, '']
Compute the signed cosine of the angle between two vectors.
Parameters:
-
u(Float[Array, 3]) –The first vector.
-
v(Float[Array, 3]) –The second vector.
Returns:
-
cosine(Float[Array, '']) –The cosine of the angle, in the range [-1, 1].
angle_vectors(u: Float[Array, 3], v: Float[Array, 3], deg: bool = False) -> Float[Array, '']
Compute the smallest angle between two vectors.
Parameters:
-
u(Float[Array, 3]) –The first vector.
-
v(Float[Array, 3]) –The second vector.
-
deg(bool, default:False) –If True, return the angle in degrees instead of radians.
Returns:
-
angle(Float[Array, '']) –The smallest angle between the vectors.
Notes
The cosine is clipped to [-1, 1] before the arccosine, whose value and gradient are singular when the vectors are parallel: in floating point the cosine of two parallel vectors can overshoot 1 by a few ulps.
line_vector(line: Float[Array, '2 3'], normalized: bool = True) -> Float[Array, 3]
Calculate the (normalized) vector formed by the difference of the line end points.
Parameters:
-
line(Float[Array, '2 3']) –The line, as its two end points.
-
normalized(bool, default:True) –If True, scale the vector to unit length.
Returns:
-
vector(Float[Array, 3]) –The vector from the first end point to the second.
Points and distances¤
distance_point_point_sqrd(u: Float[Array, 3], v: Float[Array, 3]) -> Float[Array, '']
Calculate the square of the distance between two points.
Parameters:
-
u(Float[Array, 3]) –The first point.
-
v(Float[Array, 3]) –The second point.
Returns:
-
distance(Float[Array, '']) –The squared Euclidean distance between the points.
closest_point_on_line(point: Float[Array, 3], line: Float[Array, '2 3']) -> Float[Array, 3]
Computes the closest location on a line to a supplied point.
Parameters:
-
point(Float[Array, 3]) –The query point.
-
line(Float[Array, '2 3']) –The line, as its two end points.
Returns:
-
point(Float[Array, 3]) –The orthogonal projection of the query point onto the infinite line.
closest_point_on_segment(point: Float[Array, 3], segment: Float[Array, '2 3']) -> Float[Array, 3]
Calculate the closest location on a segment to an input point.
Parameters:
-
point(Float[Array, 3]) –The query point.
-
segment(Float[Array, '2 3']) –The segment, as its two end points.
Returns:
-
point(Float[Array, 3]) –The closest location on the segment, clamped to its end points.
closest_point_on_plane(point: Float[Array, 3], plane: Float[Array, '2 3']) -> Float[Array, 3]
Computes the closest location on a plane to a supplied point.
Parameters:
-
point(Float[Array, 3]) –The query point.
-
plane(Float[Array, '2 3']) –The plane, as its origin and normal.
Returns:
-
point(Float[Array, 3]) –The orthogonal projection of the query point onto the plane.
colinearity_points(points: Float[Array, 'points 3']) -> Float[Array, '']
Calculate the colinearity of a sequence of points.
Parameters:
-
points(Float[Array, 'points 3']) –The ordered sequence of points.
Returns:
-
colinearity(Float[Array, '']) –The colinearity energy, zero when the points are colinear.
Notes
Colinearity is defined as length-normalized fairness energy: E = sum_i ||e_i - e_{i-1}||^2 / (0.5 * (||e_{i-1}||^2 + ||e_i||^2)) where e_i = points[i+1] - points[i].
The normalization makes this energy less sensitive to local point spacing than a raw second-difference energy. A colinearity of 0.0 indicates that the points are colinear (i.e., they lie on a straight line). The result is normalized by the number of interior vertices so it is invariant to problem size.
curvature_points(points: Float[Array, 'points 3']) -> Float[Array, '']
Compute the curvature (turning) energy of a sequence of points.
Penalizes changes in direction between consecutive edges. Scale-invariant.
Parameters:
-
points(Float[Array, 'points 3']) –The ordered sequence of points.
Returns:
-
energy(Float[Array, '']) –The turning energy, zero when the points are colinear.
Notes
Curvature is defined as raw turning energy: E = sum_i ||t_i - t_{i-1}||^2 / (num_points - 2) where t_i is the unit tangent vector. Energy depends only on turn angles, not on edge lengths, so it is scale-invariant.
curvature_point_polygon(point: Float[Array, 3], polygon: Float[Array, 'points 3']) -> Float[Array, '']
Compute the discrete curvature at a point based on a polygon surrounding it.
The discrete curvature of a node equals 2 * pi - sum(alphas).
TODO: divide return value by tributary area of point.
Parameters:
-
point(Float[Array, 3]) –The central point at which the curvature is evaluated.
-
polygon(Float[Array, 'points 3']) –The ring of points surrounding the central point.
Returns:
-
curvature(Float[Array, '']) –The discrete curvature at the central point.
Notes
Alphas is the list of angles between each pair of successive edges as the outward vectors from the node.
Polygons¤
area_polygon(polygon: Float[Array, 'points 3']) -> Float[Array, '']
Computes the area of a polygon.
Parameters:
-
polygon(Float[Array, 'points 3']) –The polygon, as a sequence of at least three unique points.
Returns:
-
area(Float[Array, '']) –The area of the polygon.
area_triangle(triangle: Float[Array, '3 3']) -> Float[Array, '']
Calculate the area of a triangle.
Parameters:
-
triangle(Float[Array, '3 3']) –The triangle, as exactly three points.
Returns:
-
area(Float[Array, '']) –The area of the triangle.
normal_polygon(polygon: Float[Array, 'points 3'], unitized: bool = True) -> Float[Array, 3]
Computes the normal of a closed polygon.
Parameters:
-
polygon(Float[Array, 'points 3']) –The polygon, as a sequence of at least three unique points.
-
unitized(bool, default:True) –If True, scale the normal to unit length.
Returns:
-
normal(Float[Array, 3]) –The polygon normal.
Notes
The polygon points are referenced to their centroid before the cross products. For a closed loop the reference point telescopes out of the summed cross products, so the normal is unchanged analytically, but the centering avoids the catastrophic cancellation that crossing large absolute coordinates incurs far away from the origin.
Rows that contain nan values are excluded from the centroid and drop the two cross-product terms they touch, so the direction of the normal survives nan padding but its magnitude does not.
normal_triangle(triangle: Float[Array, '3 3'], unitize: bool = False) -> Float[Array, 3]
Computes the normal vector of a triangle.
Parameters:
-
triangle(Float[Array, '3 3']) –The triangle, as exactly three points.
-
unitize(bool, default:False) –If True, scale the normal to unit length.
Returns:
-
normal(Float[Array, 3]) –The triangle normal.
angles_polygon(polygon: Float[Array, 'points 3'], deg: bool = False) -> Float[Array, points]
Calculate the internal angles of a polygon.
Parameters:
-
polygon(Float[Array, 'points 3']) –The polygon, as a sequence of at least three points.
-
deg(bool, default:False) –If True, return the angles in degrees instead of radians.
Returns:
-
angles(Float[Array, points]) –The internal angle at each polygon vertex.
cosines_angles_polygon(polygon: Float[Array, 'points 3']) -> Float[Array, points]
Calculate the internal angle cosines of a polygon.
Parameters:
-
polygon(Float[Array, 'points 3']) –The polygon, as a sequence of at least three points.
Returns:
-
cosines(Float[Array, points]) –The cosine of the internal angle at each polygon vertex.
planarity_polygon(polygon: Float[Array, 'points 3']) -> Float[Array, '']
Calculate the planarity of a polygon.
Parameters:
-
polygon(Float[Array, 'points 3']) –The polygon, as a sequence of at least three points.
Returns:
-
planarity(Float[Array, '']) –The planarity energy, zero when the polygon is planar.
Notes
The planarity of a polygon is calculated as the sum of the absolute dot product between the polygon's unitized normal vector and its unitized edge vectors.
planarity_triangle(triangle: Float[Array, '3 3']) -> Float[Array, '']
Calculate the planarity of a triangle.
Parameters:
-
triangle(Float[Array, '3 3']) –The triangle, as exactly three points.
Returns:
-
planarity(Float[Array, '']) –The planarity energy, always zero for a triangle.
Local coordinate systems¤
line_lcs(line: Float[Array, '2 3']) -> Float[Array, '3 3']
Returns the local coordinate system (LCS) of a line.
Parameters:
-
line(Float[Array, '2 3']) –The line, as its two end points.
Returns:
-
lcs(Float[Array, '3 3']) –The orthonormal basis, as its stacked U, V, and W axes.
Notes
The LCS is a 3D orthonormal basis formed by unit vectors U, V, and W. The orthonormal basis is constructed using the following convention:
- The U axis is the unit vector of the coordinate difference of the line end points.
- The V axis is the cross product of U and the global Z axis. If the V axis is parallel to Z, then V becomes the cross product of U and the global Y axis.
- The W axis is the cross product of U and V.
polygon_lcs(polygon: Float[Array, 'points 3']) -> Float[Array, '3 3']
Returns the local coordinate system (LCS) of a polygon.
Parameters:
-
polygon(Float[Array, 'points 3']) –The polygon, as a sequence of at least three points.
Returns:
-
lcs(Float[Array, '3 3']) –The orthonormal basis, as its stacked U, V, and W axes.
Notes
The LCS is a 3D orthonormal basis formed by unit vectors U, V, and W. The orthonormal basis is constructed using the following convention:
- The W axis is the unitized polygon normal.
- The V axis is the cross product of W and the global X axis. If W is parallel to X, then V becomes the cross product of W and the global Y axis.
- The U axis is the cross product of W and V, sign-aligned so it points away from the reference axis used for V.