0
# Transformations and Plotting
1

2
Coordinate system transformations and comprehensive matplotlib-based visualization support for both 2D and 3D plotting of spatial objects.
3

4
## Capabilities
5

6
### Coordinate Transformations
7

8
Transform points between different coordinate systems using custom origins and basis vectors.
9

10
```python { .api }
11
def transform_coordinates(points, point_origin, vectors_basis) -> np.ndarray:
12
    """
13
    Transform points into a new coordinate system.
14
    
15
    Parameters:
16
    - points: array-like, (N, D) array of N points with dimension D
17
    - point_origin: array-like, (D,) origin of the new coordinate system
18
    - vectors_basis: sequence, basis vectors of the new coordinate system
19
                     Sequence of N_bases vectors, each with D elements
20
    
21
    Returns:
22
    (N, N_bases) array of coordinates in the new coordinate system
23
    
24
    Examples:
25
    Transform 2D points using standard and diagonal basis:
26
    >>> points = [[1, 2], [3, 4], [5, 6]]
27
    >>> vectors_basis = [[1, 0], [1, 1]]
28
    >>> transform_coordinates(points, [0, 0], vectors_basis)
29
    array([[ 1,  3],
30
           [ 3,  7], 
31
           [ 5, 11]])
32
    
33
    Transform 3D points to 2D coordinate system:
34
    >>> points = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
35
    >>> vectors_basis = [[1, 0, 0], [-1, 1, 0]]
36
    >>> transform_coordinates(points, [0, 0, 0], vectors_basis)
37
    array([[1, 1],
38
           [4, 1],
39
           [7, 1]])
40
    """
41
```
42

43
**Usage Example:**
44
```python
45
from skspatial.transformation import transform_coordinates
46
import numpy as np
47

48
# Transform 2D points to rotated coordinate system
49
points = [[1, 0], [0, 1], [1, 1]]
50
angle = np.pi / 4  # 45 degrees
51
rotation_basis = [
52
    [np.cos(angle), np.sin(angle)],    # Rotated x-axis
53
    [-np.sin(angle), np.cos(angle)]    # Rotated y-axis
54
]
55
transformed = transform_coordinates(points, [0, 0], rotation_basis)
56

57
# Transform 3D points to plane coordinate system
58
points_3d = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
59
plane_origin = [0, 0, 0]
60
plane_basis = [
61
    [1, 0, 0],  # x-direction in plane
62
    [0, 1, 0]   # y-direction in plane
63
]
64
plane_coords = transform_coordinates(points_3d, plane_origin, plane_basis)
65
```
66

67
### 2D and 3D Plotting
68

69
Comprehensive matplotlib-based visualization supporting all spatial objects with customizable styling and multiple object plotting.
70

71
```python { .api }
72
def plot_2d(*plotters) -> Tuple:
73
    """
74
    Plot multiple spatial objects in 2D.
75
    
76
    Parameters:
77
    - *plotters: sequence of plotter functions from spatial objects
78
    
79
    Returns:
80
    Tuple (fig, ax) containing matplotlib Figure and Axes objects
81
    
82
    Examples:
83
    Plot multiple objects together:
84
    >>> from skspatial.objects import Point, Line
85
    >>> from skspatial.plotting import plot_2d
86
    >>> point = Point([1, 2])
87
    >>> line = Line([0, 0], [1, 1])
88
    >>> fig, ax = plot_2d(
89
    ...     point.plotter(color='red', s=100),
90
    ...     line.plotter(t_2=3, color='blue')
91
    ... )
92
    """
93

94
def plot_3d(*plotters) -> Tuple:
95
    """
96
    Plot multiple spatial objects in 3D.
97
    
98
    Parameters:
99
    - *plotters: sequence of plotter functions from spatial objects
100
    
101
    Returns:
102
    Tuple (fig, ax) containing matplotlib Figure and Axes3D objects
103
    
104
    Examples:
105
    Plot 3D objects together:
106
    >>> from skspatial.objects import Point, Plane, Sphere
107
    >>> from skspatial.plotting import plot_3d
108
    >>> point = Point([1, 2, 3])
109
    >>> plane = Plane([0, 0, 0], [0, 0, 1])
110
    >>> sphere = Sphere([0, 0, 0], 2)
111
    >>> fig, ax = plot_3d(
112
    ...     point.plotter(color='red', s=100),
113
    ...     plane.plotter(alpha=0.3),
114
    ...     sphere.plotter(alpha=0.5, color='blue')
115
    ... )
116
    """
117
```
118

119
### Spatial Object Plotting Methods
120

121
All spatial objects provide plotting capabilities through consistent interfaces for 2D and 3D visualization.
122

123
```python { .api }
124
# Common plotting interface for all spatial objects
125
class SpatialObject:
126
    def plotter(self, **kwargs):
127
        """
128
        Return plotting function for matplotlib integration.
129
        
130
        Parameters:
131
        - **kwargs: styling keywords passed to matplotlib functions
132
        
133
        Returns:
134
        Plotting function that can be used with plot_2d/plot_3d
135
        """
136
    
137
    def plot_2d(self, ax_2d, **kwargs):
138
        """
139
        Plot object directly on 2D matplotlib axes.
140
        
141
        Parameters:
142
        - ax_2d: matplotlib Axes, 2D plotting axes
143
        - **kwargs: styling keywords passed to matplotlib functions
144
        """
145
    
146
    def plot_3d(self, ax_3d, **kwargs):
147
        """
148
        Plot object directly on 3D matplotlib axes.
149
        
150
        Parameters:
151
        - ax_3d: matplotlib Axes3D, 3D plotting axes
152
        - **kwargs: styling keywords passed to matplotlib functions
153
        """
154
```
155

156
### Object-Specific Plotting Parameters
157

158
Different spatial objects support specialized plotting parameters:
159

160
```python { .api }
161
# Point plotting
162
Point.plot_2d(ax_2d, s=50, c='red', alpha=0.7, **kwargs)
163
Point.plot_3d(ax_3d, s=50, c='red', alpha=0.7, **kwargs)
164

165
# Vector plotting (with origin and scaling)
166
Vector.plot_2d(ax_2d, point=(0, 0), scalar=1, color='blue', **kwargs)
167
Vector.plot_3d(ax_3d, point=(0, 0, 0), scalar=1, color='blue', **kwargs)
168

169
# Line plotting (with parameter range)
170
Line.plot_2d(ax_2d, t_1=0, t_2=1, color='green', linewidth=2, **kwargs)
171
Line.plot_3d(ax_3d, t_1=0, t_2=1, color='green', linewidth=2, **kwargs)
172

173
# Plane plotting (with limits)
174
Plane.plot_3d(ax_3d, lims_x=(-5, 5), lims_y=(-5, 5), alpha=0.3, **kwargs)
175

176
# Circle plotting
177
Circle.plot_2d(ax_2d, fill=False, edgecolor='red', linewidth=2, **kwargs)
178

179
# Sphere plotting (with discretization)
180
Sphere.plot_3d(ax_3d, n_angles=30, alpha=0.5, color='blue', **kwargs)
181

182
# Cylinder plotting (with discretization)
183
Cylinder.plot_3d(ax_3d, n_along_axis=100, n_angles=30, alpha=0.7, **kwargs)
184

185
# Triangle plotting (with part selection)
186
Triangle.plot_2d(ax_2d, part='points', s=50, c='red', **kwargs)
187
Triangle.plot_3d(ax_3d, part='edges', color='black', linewidth=1, **kwargs)
188
```
189

190
**Usage Examples:**
191

192
```python
193
from skspatial.objects import Point, Vector, Line, Plane, Circle, Sphere
194
from skspatial.plotting import plot_2d, plot_3d
195
import matplotlib.pyplot as plt
196

197
# 2D plotting example
198
point = Point([1, 2])
199
vector = Vector([2, 1])
200
line = Line([0, 0], [1, 1])
201
circle = Circle([0, 0], 3)
202

203
fig, ax = plot_2d(
204
    point.plotter(s=100, c='red', label='Point'),
205
    vector.plotter(point=[1, 2], scalar=1.5, color='blue', label='Vector'),
206
    line.plotter(t_1=-2, t_2=4, color='green', label='Line'),
207
    circle.plotter(fill=False, edgecolor='purple', linewidth=2, label='Circle')
208
)
209
ax.set_aspect('equal')
210
ax.legend()
211
ax.grid(True)
212
plt.show()
213

214
# 3D plotting example
215
point_3d = Point([1, 2, 3])
216
plane = Plane([0, 0, 0], [0, 0, 1])
217
sphere = Sphere([2, 2, 2], 1.5)
218
line_3d = Line([0, 0, 0], [1, 1, 1])
219

220
fig, ax = plot_3d(
221
    point_3d.plotter(s=100, c='red', label='Point'),
222
    plane.plotter(lims_x=(-3, 3), lims_y=(-3, 3), alpha=0.3, color='gray'),
223
    sphere.plotter(alpha=0.6, color='blue', label='Sphere'),
224
    line_3d.plotter(t_1=0, t_2=3, color='green', linewidth=3, label='Line')
225
)
226
ax.set_xlabel('X')
227
ax.set_ylabel('Y') 
228
ax.set_zlabel('Z')
229
ax.legend()
230
plt.show()
231

232
# Direct plotting on existing axes
233
fig = plt.figure(figsize=(12, 5))
234

235
# 2D subplot
236
ax1 = fig.add_subplot(1, 2, 1)
237
point.plot_2d(ax1, s=100, c='red')
238
circle.plot_2d(ax1, fill=False, edgecolor='blue', linewidth=2)
239
ax1.set_aspect('equal')
240
ax1.grid(True)
241
ax1.set_title('2D Plot')
242

243
# 3D subplot  
244
ax2 = fig.add_subplot(1, 2, 2, projection='3d')
245
point_3d.plot_3d(ax2, s=100, c='red')
246
sphere.plot_3d(ax2, alpha=0.5, color='blue')
247
ax2.set_title('3D Plot')
248

249
plt.tight_layout()
250
plt.show()
251

252
# Animation example (plotting objects at different times)
253
import numpy as np
254

255
fig, ax = plt.subplots()
256

257
# Animate a point moving along a line
258
line = Line([0, 0], [1, 1])
259
t_values = np.linspace(0, 5, 50)
260

261
for t in t_values:
262
    ax.clear()
263
    
264
    # Plot the line
265
    line.plot_2d(ax, t_1=0, t_2=5, color='blue', alpha=0.5)
266
    
267
    # Plot point at current position
268
    current_point = line.to_point(t)
269
    current_point.plot_2d(ax, s=100, c='red')
270
    
271
    ax.set_xlim(-1, 6)
272
    ax.set_ylim(-1, 6)
273
    ax.set_aspect('equal')
274
    ax.grid(True)
275
    ax.set_title(f'Point at t={t:.1f}')
276
    
277
    plt.pause(0.1)
278

279
plt.show()
280
```
281

282
### Integration with NumPy and Scientific Python
283

284
The plotting system integrates seamlessly with NumPy arrays and other scientific Python libraries:
285

286
```python
287
import numpy as np
288
from skspatial.objects import Points, Line, Plane
289
from skspatial.plotting import plot_3d
290

291
# Generate random point cloud
292
np.random.seed(42)
293
points_array = np.random.randn(100, 3)
294
points = Points(points_array)
295

296
# Fit geometric objects to data
297
line_fit = Line.best_fit(points_array)
298
plane_fit = Plane.best_fit(points_array)
299

300
# Visualize data and fitted objects
301
fig, ax = plot_3d(
302
    points.plotter(s=30, c='gray', alpha=0.6, label='Data'),
303
    line_fit.plotter(t_1=-3, t_2=3, color='red', linewidth=3, label='Best Fit Line'),
304
    plane_fit.plotter(lims_x=(-3, 3), lims_y=(-3, 3), alpha=0.3, color='blue', label='Best Fit Plane')
305
)
306
ax.legend()
307
ax.set_title('Geometric Fitting Visualization')
308
plt.show()
309
```