tessl/pypi-scikit-spatial
Spatial objects and computations based on NumPy arrays for 2D, 3D, and higher-dimensional geometric calculations.
—
Pending
basic-objects.mddocs/
Basic Spatial Objects
Fundamental building blocks including points, vectors, and collections of points. These objects form the foundation of all geometric computations and inherit full NumPy array functionality, making them subclasses of numpy.ndarray.
Capabilities
Point
Represents a single point in N-dimensional space. Points support distance calculations and visualization while inheriting all NumPy array operations.
class Point(np.ndarray):
"""
A point in N-dimensional space.
Parameters:
- array: array-like, coordinates of the point
"""
def __init__(self, array): ...
@property
def dimension(self) -> int:
"""Return the dimension of the point."""
def distance_point(self, other) -> np.float64:
"""
Calculate Euclidean distance to another point.
Parameters:
- other: array-like, another point
Returns:
Euclidean distance between points
"""
def set_dimension(self, dim) -> 'Point':
"""
Set dimension by padding with zeros if needed.
Parameters:
- dim: int, target dimension
Returns:
Point with specified dimension
"""
def plot_2d(self, ax_2d, **kwargs):
"""
Plot point in 2D.
Parameters:
- ax_2d: matplotlib Axes, 2D plotting axes
- **kwargs: additional keywords passed to scatter
"""
def plot_3d(self, ax_3d, **kwargs):
"""
Plot point in 3D.
Parameters:
- ax_3d: matplotlib Axes3D, 3D plotting axes
- **kwargs: additional keywords passed to scatter
"""
def plotter(self, **kwargs):
"""Return plotting function for matplotlib integration."""
def to_array(self) -> np.ndarray:
"""Convert to regular numpy array."""
def is_close(self, other, **kwargs) -> bool:
"""Check if arrays are close using numpy.allclose."""
def is_equal(self, other) -> bool:
"""Check if arrays are exactly equal."""
def round(self, decimals=0):
"""Round array values to given precision."""Usage Example:
from skspatial.objects import Point
# Create points from lists or arrays
p1 = Point([1, 2, 3])
p2 = Point([4, 5, 6])
# Use NumPy functionality
print(p1.size) # 3
print(p1.mean()) # 2.0
# Use spatial methods
distance = p1.distance_point(p2)
print(distance) # 5.196152422706632
# Set dimension
p1_2d = p1.set_dimension(2) # Point([1, 2])Vector
Represents a vector in N-dimensional space with specialized vector operations including cross products, dot products, angles, and projections.
class Vector(np.ndarray):
"""
A vector in N-dimensional space.
Parameters:
- array: array-like, components of the vector
"""
def __init__(self, array): ...
@classmethod
def from_points(cls, point_a, point_b) -> 'Vector':
"""
Create vector from two points.
Parameters:
- point_a: array-like, start point
- point_b: array-like, end point
Returns:
Vector from point_a to point_b
"""
@property
def dimension(self) -> int:
"""Return the dimension of the vector."""
def norm(self, **kwargs) -> np.float64:
"""
Return the norm (magnitude) of the vector.
Parameters:
- **kwargs: additional keywords passed to numpy.linalg.norm
Returns:
Norm of the vector
"""
def unit(self) -> 'Vector':
"""
Return the unit vector in the same direction.
Returns:
Unit vector with magnitude 1
"""
def is_zero(self, **kwargs) -> bool:
"""
Check if vector is zero vector.
Parameters:
- **kwargs: additional keywords passed to math.isclose
Returns:
True if vector is close to zero
"""
def cross(self, other) -> 'Vector':
"""
Compute cross product with another vector.
Parameters:
- other: array-like, another vector
Returns:
Cross product vector
"""
def cosine_similarity(self, other) -> np.float64:
"""
Compute cosine similarity with another vector.
Parameters:
- other: array-like, another vector
Returns:
Cosine similarity (-1 to 1)
"""
def angle_between(self, other) -> float:
"""
Compute angle between vectors in radians.
Parameters:
- other: array-like, another vector
Returns:
Angle in radians (0 to π)
"""
def angle_signed(self, other) -> float:
"""
Compute signed angle for 2D vectors.
Parameters:
- other: array-like, another 2D vector
Returns:
Signed angle in radians (-π to π)
"""
def is_perpendicular(self, other, **kwargs) -> bool:
"""
Check if perpendicular to another vector.
Parameters:
- other: array-like, another vector
- **kwargs: additional keywords passed to math.isclose
Returns:
True if vectors are perpendicular
"""
def is_parallel(self, other, **kwargs) -> bool:
"""
Check if parallel to another vector.
Parameters:
- other: array-like, another vector
- **kwargs: additional keywords passed to math.isclose
Returns:
True if vectors are parallel
"""
def scalar_projection(self, other) -> np.float64:
"""
Compute scalar projection onto another vector.
Parameters:
- other: array-like, vector to project onto
Returns:
Scalar projection value
"""
def project_vector(self, other) -> 'Vector':
"""
Compute vector projection onto another vector.
Parameters:
- other: array-like, vector to project onto
Returns:
Projected vector
"""
def plot_2d(self, ax_2d, point=(0, 0), scalar=1, **kwargs):
"""
Plot vector in 2D starting from a point.
Parameters:
- ax_2d: matplotlib Axes, 2D plotting axes
- point: array-like, starting point (default: origin)
- scalar: float, scaling factor (default: 1)
- **kwargs: additional keywords passed to plot
"""
def plot_3d(self, ax_3d, point=(0, 0, 0), scalar=1, **kwargs):
"""
Plot vector in 3D starting from a point.
Parameters:
- ax_3d: matplotlib Axes3D, 3D plotting axes
- point: array-like, starting point (default: origin)
- scalar: float, scaling factor (default: 1)
- **kwargs: additional keywords passed to plot
"""
def side_vector(self, other) -> int:
"""
Find side of vector where another vector lies (2D only).
Parameters:
- other: array-like, another 2D vector
Returns:
1 if other is to the left, -1 if to the right, 0 if collinear
"""
def angle_signed_3d(self, other, direction_positive) -> float:
"""
Compute signed angle between 3D vectors using reference direction.
Parameters:
- other: array-like, another 3D vector
- direction_positive: array-like, reference direction for positive angles
Returns:
Signed angle in radians (-π to π)
"""
def different_direction(self, **kwargs) -> 'Vector':
"""
Return a simple vector in different direction.
Useful for finding perpendicular vectors or generating test vectors.
Parameters:
- **kwargs: additional keywords passed to numpy functions
Returns:
Vector in a different direction from the current vector
"""
def side_vector(self, other) -> int:
"""
Find which side of this vector another vector is on (2D only).
Parameters:
- other: array-like, another 2D vector
Returns:
-1, 0, or 1 indicating left side, on line, or right side
"""
def angle_signed_3d(self, other, direction_positive) -> float:
"""
Compute signed angle between 3D vectors using a positive direction.
Parameters:
- other: array-like, another 3D vector
- direction_positive: array-like, vector defining positive rotation direction
Returns:
Signed angle in radians
"""
def set_dimension(self, dim) -> 'Vector':
"""
Set dimension by padding with zeros if needed.
Parameters:
- dim: int, target dimension
Returns:
Vector with specified dimension
"""
def to_array(self) -> np.ndarray:
"""Convert to regular numpy array."""
def is_close(self, other, **kwargs) -> bool:
"""Check if arrays are close using numpy.allclose."""
def is_equal(self, other) -> bool:
"""Check if arrays are exactly equal."""
def round(self, decimals=0):
"""Round array values to given precision."""
def plotter(self, **kwargs):
"""Return plotting function for matplotlib integration."""Usage Example:
from skspatial.objects import Vector, Point
# Create vectors
v1 = Vector([1, 0, 0])
v2 = Vector([0, 1, 0])
# Create from points
v3 = Vector.from_points([0, 0, 0], [3, 4, 0])
# Vector operations
magnitude = v3.norm() # 5.0
unit_v3 = v3.unit() # Vector([0.6, 0.8, 0.0])
# Cross product
cross = v1.cross(v2) # Vector([0, 0, 1])
# Angle between vectors
angle = v1.angle_between(v2) # π/2 radians (90 degrees)
# Check relationships
is_perp = v1.is_perpendicular(v2) # True
is_par = v1.is_parallel(v2) # False
# 2D-specific methods
v2d_1 = Vector([1, 0])
v2d_2 = Vector([0, 1])
side = v2d_1.side_vector(v2d_2) # 1 (left side)
# 3D signed angle with reference direction
v3d_1 = Vector([1, 0, 0])
v3d_2 = Vector([0, 1, 0])
ref_dir = Vector([0, 0, 1])
signed_angle_3d = v3d_1.angle_signed_3d(v3d_2, ref_dir) # π/2 radians
# Generate different direction vector
diff_v = v1.different_direction() # Vector in different directionPoints
Represents a collection of N points in D-dimensional space as an (N×D) array. Provides methods for analyzing point sets including centroids, collinearity, and coplanarity tests.
class Points(np.ndarray):
"""
A collection of points in N-dimensional space.
Parameters:
- points: array-like, (N, D) array of N points with dimension D
"""
def __init__(self, points): ...
@property
def dimension(self) -> int:
"""Return the dimension of the points."""
def unique(self) -> 'Points':
"""
Return unique points.
Returns:
Points with duplicates removed
"""
def centroid(self) -> Point:
"""
Return the centroid of all points.
Returns:
Point representing the centroid
"""
def mean_center(self, return_centroid=False):
"""
Mean-center points around origin.
Parameters:
- return_centroid: bool, if True return centroid used
Returns:
Mean-centered points, optionally with centroid
"""
def normalize_distance(self) -> 'Points':
"""
Normalize distances from origin.
Returns:
Points with normalized distances
"""
def affine_rank(self, **kwargs) -> np.int64:
"""
Return the affine rank of points.
Parameters:
- **kwargs: additional keywords passed to numpy.linalg.matrix_rank
Returns:
Affine rank of the point set
"""
def are_concurrent(self, **kwargs) -> bool:
"""
Check if all points are the same.
Parameters:
- **kwargs: additional keywords passed to numpy.allclose
Returns:
True if all points are concurrent
"""
def are_collinear(self, **kwargs) -> bool:
"""
Check if points are collinear.
Parameters:
- **kwargs: additional keywords passed to numpy.linalg.matrix_rank
Returns:
True if points lie on a line
"""
def are_coplanar(self, **kwargs) -> bool:
"""
Check if points are coplanar.
Parameters:
- **kwargs: additional keywords passed to numpy.linalg.matrix_rank
Returns:
True if points lie on a plane
"""
def set_dimension(self, dim) -> 'Points':
"""
Set dimension by padding with zeros if needed.
Parameters:
- dim: int, target dimension
Returns:
Points with specified dimension
"""
def plot_2d(self, ax_2d, **kwargs):
"""
Plot points in 2D.
Parameters:
- ax_2d: matplotlib Axes, 2D plotting axes
- **kwargs: additional keywords passed to scatter
"""
def plot_3d(self, ax_3d, **kwargs):
"""
Plot points in 3D.
Parameters:
- ax_3d: matplotlib Axes3D, 3D plotting axes
- **kwargs: additional keywords passed to scatter
"""
def to_array(self) -> np.ndarray:
"""Convert to regular numpy array."""
def is_close(self, other, **kwargs) -> bool:
"""Check if arrays are close using numpy.allclose."""
def is_equal(self, other) -> bool:
"""Check if arrays are exactly equal."""
def round(self, decimals=0):
"""Round array values to given precision."""
def plotter(self, **kwargs):
"""Return plotting function for matplotlib integration."""Usage Example:
from skspatial.objects import Points
# Create collection of points
points = Points([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
# Analyze point set
centroid = points.centroid() # Point([4, 5, 6])
are_collinear = points.are_collinear() # True
# Working with 2D points
points_2d = Points([[0, 0], [1, 1], [2, 2], [3, 4]])
are_collinear_2d = points_2d.are_collinear() # False
# Check coplanarity for 3D points
points_3d = Points([[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]])
are_coplanar = points_3d.are_coplanar() # TrueInstall with Tessl CLI
npx tessl i tessl/pypi-scikit-spatial