0
# scikit-spatial
1

2
A comprehensive Python library providing spatial objects and computations based on NumPy arrays. The library enables developers to work with geometric objects and perform complex spatial calculations in 2D, 3D, and higher-dimensional spaces with robust numerical computing capabilities.
3

4
## Package Information
5

6
- **Package Name**: scikit-spatial
7
- **Language**: Python
8
- **Installation**: `pip install scikit-spatial`
9
- **Optional Plotting Support**: `pip install 'scikit-spatial[plotting]'`
10

11
## Core Imports
12

13
```python
14
from skspatial.objects import Point, Vector, Line, Plane, Points
15
```
16

17
Common patterns for importing spatial objects:
18

19
```python
20
from skspatial.objects import (
21
    Point, Vector, Points, Line, LineSegment, 
22
    Plane, Circle, Sphere, Triangle, Cylinder
23
)
24
```
25

26
For measurement and transformation functions:
27

28
```python
29
from skspatial.measurement import area_triangle, volume_tetrahedron, area_signed
30
from skspatial.transformation import transform_coordinates
31
from skspatial.plotting import plot_2d, plot_3d
32
```
33

34
## Basic Usage
35

36
```python
37
from skspatial.objects import Point, Vector, Line, Plane
38

39
# Create spatial objects from array-like data
40
point = Point([1, 2, 3])
41
vector = Vector([0, 1, 0])
42
line = Line(point=[0, 0, 0], direction=[1, 1, 0])
43

44
# Objects inherit from NumPy arrays
45
print(vector.size)  # 3
46
print(vector.mean())  # 1.0
47

48
# Use specialized spatial methods
49
unit_vector = vector.unit()
50
print(unit_vector.norm())  # 1.0
51

52
# Project point onto line
53
projected = line.project_point([5, 6, 7])
54
print(projected)  # Point([5.5, 5.5, 0.0])
55

56
# Create plane from three points
57
plane = Plane.from_points([0, 0, 0], [1, 0, 0], [0, 1, 0])
58
print(plane.normal)  # Vector([0, 0, 1])
59

60
# Intersection operations
61
intersection = plane.intersect_line(line)
62
print(intersection)  # Point([0, 0, 0])
63
```
64

65
## Architecture
66

67
scikit-spatial is built on a foundational principle: **spatial objects as NumPy arrays**. Every spatial object inherits from `numpy.ndarray`, providing full NumPy functionality while adding specialized spatial methods. This design enables seamless integration with the NumPy ecosystem while maintaining geometric semantics.
68

69
**Key Design Elements:**
70

71
- **Array-Based Objects**: Point, Vector, and Points are direct subclasses of NumPy ndarray
72
- **Geometric Primitives**: Line, Plane, Circle, Sphere, Triangle, Cylinder built on Point/Vector foundations
73
- **Inheritance Hierarchy**: Base classes provide shared functionality (plotting, array operations, spatial computations)
74
- **NumPy Integration**: All spatial computations leverage NumPy's optimized linear algebra operations
75
- **Matplotlib Visualization**: Built-in plotting support for 2D and 3D visualization
76

77
This architecture distinguishes scikit-spatial from symbolic geometry libraries by prioritizing numerical computation performance and NumPy ecosystem compatibility.
78

79
## Capabilities
80

81
### Basic Spatial Objects
82

83
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.
84

85
```python { .api }
86
class Point(np.ndarray):
87
    def __init__(self, array): ...
88
    def distance_point(self, other) -> np.float64: ...
89
    def plot_2d(self, ax_2d, **kwargs): ...
90
    def plot_3d(self, ax_3d, **kwargs): ...
91

92
class Vector(np.ndarray):
93
    def __init__(self, array): ...
94
    @classmethod
95
    def from_points(cls, point_a, point_b) -> 'Vector': ...
96
    def norm(self, **kwargs) -> np.float64: ...
97
    def unit(self) -> 'Vector': ...
98
    def cross(self, other) -> 'Vector': ...
99
    def angle_between(self, other) -> float: ...
100

101
class Points(np.ndarray):
102
    def __init__(self, points): ...
103
    def centroid(self) -> Point: ...
104
    def are_collinear(self, **kwargs) -> bool: ...
105
    def are_coplanar(self, **kwargs) -> bool: ...
106
```
107

108
[Basic Spatial Objects](./basic-objects.md)
109

110
### Linear Geometry
111

112
Lines, line segments, and planes with comprehensive geometric operations including projections, intersections, and distance calculations. Supports both infinite geometric objects and bounded segments.
113

114
```python { .api }
115
class Line:
116
    def __init__(self, point, direction): ...
117
    @classmethod
118
    def from_points(cls, point_a, point_b) -> 'Line': ...
119
    @classmethod
120
    def best_fit(cls, points, **kwargs) -> 'Line': ...
121
    def project_point(self, point) -> Point: ...
122
    def intersect_line(self, other, **kwargs) -> Point: ...
123
    def distance_point(self, point) -> np.float64: ...
124

125
class Plane:
126
    def __init__(self, point, normal): ...
127
    @classmethod
128
    def from_points(cls, point_a, point_b, point_c, **kwargs) -> 'Plane': ...
129
    @classmethod
130
    def best_fit(cls, points, **kwargs) -> 'Plane': ...
131
    def intersect_line(self, line, **kwargs) -> Point: ...
132
    def intersect_plane(self, other, **kwargs) -> Line: ...
133
```
134

135
[Linear Geometry](./linear-geometry.md)
136

137
### Curved Geometry
138

139
Circles, spheres, and cylinders with specialized methods for curved surface computations, intersections, and volume calculations.
140

141
```python { .api }
142
class Circle:
143
    def __init__(self, point, radius): ...
144
    @classmethod
145
    def from_points(cls, point_a, point_b, point_c, **kwargs) -> 'Circle': ...
146
    def area(self) -> float: ...
147
    def circumference(self) -> float: ...
148
    def intersect_line(self, line) -> Tuple[Point, Point]: ...
149

150
class Sphere:
151
    def __init__(self, point, radius): ...
152
    def volume(self) -> float: ...
153
    def surface_area(self) -> float: ...
154
    def intersect_line(self, line) -> Tuple[Point, Point]: ...
155

156
class Cylinder:
157
    def __init__(self, point, vector, radius): ...
158
    def volume(self) -> np.float64: ...
159
    def surface_area(self) -> np.float64: ...
160
```
161

162
[Curved Geometry](./curved-geometry.md)
163

164
### Measurement and Analysis
165

166
Standalone functions for computing geometric properties including areas, volumes, triangle analysis, and spatial relationships.
167

168
```python { .api }
169
def area_triangle(point_a, point_b, point_c) -> np.float64: ...
170
def volume_tetrahedron(point_a, point_b, point_c, point_d) -> np.float64: ...
171
def area_signed(points) -> float: ...
172

173
class Triangle:
174
    def __init__(self, point_a, point_b, point_c): ...
175
    def area(self) -> np.float64: ...
176
    def perimeter(self) -> np.float64: ...
177
    def classify(self, **kwargs) -> str: ...
178
    def is_right(self, **kwargs) -> bool: ...
179
```
180

181
[Measurement and Analysis](./measurement.md)
182

183
### Coordinate Transformations and Plotting  
184

185
Coordinate system transformations and comprehensive matplotlib-based visualization support for both 2D and 3D plotting.
186

187
```python { .api }
188
def transform_coordinates(points, point_origin, vectors_basis) -> np.ndarray: ...
189
def plot_2d(*plotters) -> Tuple: ...
190
def plot_3d(*plotters) -> Tuple: ...
191
```
192

193
[Transformations and Plotting](./transforms-plotting.md)
194

195
## Types
196

197
```python { .api }
198
from typing import Union, Sequence, Tuple
199
import numpy as np
200

201
array_like = Union[np.ndarray, Sequence]
202
```