0
# Coordinates
1

2
Conversions between different coordinate systems for position representation including Cartesian, cylindrical, and spherical coordinates with bidirectional conversion support.
3

4
## Capabilities
5

6
### Cartesian Coordinate Conversions
7

8
Conversions from Cartesian (x, y, z) coordinates to other systems.
9

10
```python { .api }
11
def cylindrical_from_cartesian(p):
12
    """
13
    Convert Cartesian coordinates to cylindrical coordinates.
14
    
15
    Parameters:
16
    - p: array-like, shape (..., 3) - Cartesian coordinates (x, y, z)
17
    
18
    Returns:
19
    - q: array, shape (..., 3) - Cylindrical coordinates (rho, phi, z)
20
    """
21

22
def spherical_from_cartesian(p):
23
    """
24
    Convert Cartesian coordinates to spherical coordinates.
25
    
26
    Parameters:
27
    - p: array-like, shape (..., 3) - Cartesian coordinates (x, y, z)
28
    
29
    Returns:
30
    - q: array, shape (..., 3) - Spherical coordinates (rho, theta, phi)
31
    """
32
```
33

34
### Cylindrical Coordinate Conversions
35

36
Conversions from cylindrical (rho, phi, z) coordinates to other systems.
37

38
```python { .api }
39
def cartesian_from_cylindrical(p):
40
    """
41
    Convert cylindrical coordinates to Cartesian coordinates.
42
    
43
    Parameters:
44
    - p: array-like, shape (..., 3) - Cylindrical coordinates (rho, phi, z)
45
        - rho: radial distance from z-axis
46
        - phi: azimuth angle in radians
47
        - z: height along z-axis
48
    
49
    Returns:
50
    - q: array, shape (..., 3) - Cartesian coordinates (x, y, z)
51
    """
52

53
def spherical_from_cylindrical(p):
54
    """
55
    Convert cylindrical coordinates to spherical coordinates.
56
    
57
    Parameters:
58
    - p: array-like, shape (..., 3) - Cylindrical coordinates (rho, phi, z)
59
    
60
    Returns:
61
    - q: array, shape (..., 3) - Spherical coordinates (rho, theta, phi)
62
    """
63
```
64

65
### Spherical Coordinate Conversions
66

67
Conversions from spherical (rho, theta, phi) coordinates to other systems.
68

69
```python { .api }
70
def cartesian_from_spherical(p):
71
    """
72
    Convert spherical coordinates to Cartesian coordinates.
73
    
74
    Parameters:
75
    - p: array-like, shape (..., 3) - Spherical coordinates (rho, theta, phi)
76
        - rho: radial distance from origin
77
        - theta: polar angle from positive z-axis (0 to π)
78
        - phi: azimuth angle in x-y plane from positive x-axis
79
    
80
    Returns:
81
    - q: array, shape (..., 3) - Cartesian coordinates (x, y, z)
82
    """
83

84
def cylindrical_from_spherical(p):
85
    """
86
    Convert spherical coordinates to cylindrical coordinates.
87
    
88
    Parameters:
89
    - p: array-like, shape (..., 3) - Spherical coordinates (rho, theta, phi)
90
    
91
    Returns:
92
    - q: array, shape (..., 3) - Cylindrical coordinates (rho, phi, z)
93
    """
94
```
95

96
## Usage Examples
97

98
### Basic Coordinate Conversions
99

100
```python
101
import numpy as np
102
import pytransform3d.coordinates as pco
103

104
# Define points in Cartesian coordinates
105
cartesian_points = np.array([
106
    [1, 0, 0],      # x-axis
107
    [0, 1, 0],      # y-axis  
108
    [0, 0, 1],      # z-axis
109
    [1, 1, 1],      # diagonal
110
])
111

112
print("Original Cartesian coordinates:")
113
print(cartesian_points)
114

115
# Convert to cylindrical
116
cylindrical = pco.cylindrical_from_cartesian(cartesian_points)
117
print("\nCylindrical coordinates (rho, phi, z):")
118
print(cylindrical)
119

120
# Convert to spherical
121
spherical = pco.spherical_from_cartesian(cartesian_points)
122
print("\nSpherical coordinates (rho, theta, phi):")
123
print(spherical)
124

125
# Verify round-trip conversion
126
cartesian_recovered = pco.cartesian_from_spherical(spherical)
127
print("\nRecovered Cartesian coordinates:")
128
print(cartesian_recovered)
129
print(f"Conversion error: {np.max(np.abs(cartesian_points - cartesian_recovered))}")
130
```
131

132
### Working with Arrays
133

134
```python
135
import numpy as np
136
import pytransform3d.coordinates as pco
137

138
# Create grid of points
139
x = np.linspace(-2, 2, 5)
140
y = np.linspace(-2, 2, 5) 
141
z = np.linspace(0, 2, 3)
142

143
# Create meshgrid
144
X, Y, Z = np.meshgrid(x, y, z)
145
cartesian_grid = np.stack([X.flatten(), Y.flatten(), Z.flatten()], axis=1)
146

147
print(f"Grid shape: {cartesian_grid.shape}")
148

149
# Convert entire grid to cylindrical coordinates
150
cylindrical_grid = pco.cylindrical_from_cartesian(cartesian_grid)
151

152
# Extract components
153
rho = cylindrical_grid[:, 0]
154
phi = cylindrical_grid[:, 1] 
155
z_cyl = cylindrical_grid[:, 2]
156

157
print(f"Radial distances range: {rho.min():.3f} to {rho.max():.3f}")
158
print(f"Azimuth angles range: {phi.min():.3f} to {phi.max():.3f} radians")
159
print(f"Heights range: {z_cyl.min():.3f} to {z_cyl.max():.3f}")
160
```
161

162
### Cross-System Conversions
163

164
```python
165
import numpy as np
166
import pytransform3d.coordinates as pco
167

168
# Define point in cylindrical coordinates
169
cylindrical_point = np.array([2.0, np.pi/4, 1.0])  # rho=2, phi=45°, z=1
170
print(f"Cylindrical: rho={cylindrical_point[0]}, phi={cylindrical_point[1]:.3f}, z={cylindrical_point[2]}")
171

172
# Convert cylindrical -> cartesian -> spherical
173
cartesian = pco.cartesian_from_cylindrical(cylindrical_point)
174
spherical = pco.spherical_from_cartesian(cartesian)
175

176
print(f"Cartesian: x={cartesian[0]:.3f}, y={cartesian[1]:.3f}, z={cartesian[2]:.3f}")
177
print(f"Spherical: rho={spherical[0]:.3f}, theta={spherical[1]:.3f}, phi={spherical[2]:.3f}")
178

179
# Direct cylindrical -> spherical conversion
180
spherical_direct = pco.spherical_from_cylindrical(cylindrical_point)
181
print(f"Direct conversion: rho={spherical_direct[0]:.3f}, theta={spherical_direct[1]:.3f}, phi={spherical_direct[2]:.3f}")
182

183
# Verify both paths give same result
184
print(f"Conversion difference: {np.max(np.abs(spherical - spherical_direct))}")
185
```
186

187
### Coordinate System Visualization
188

189
```python
190
import numpy as np
191
import matplotlib.pyplot as plt
192
import pytransform3d.coordinates as pco
193

194
# Generate points on sphere in spherical coordinates
195
n_points = 1000
196
rho = 1.0  # unit sphere
197
theta = np.random.uniform(0, np.pi, n_points)  # polar angle
198
phi = np.random.uniform(0, 2*np.pi, n_points)  # azimuth angle
199

200
spherical_points = np.column_stack([np.full(n_points, rho), theta, phi])
201

202
# Convert to Cartesian for plotting  
203
cartesian_points = pco.cartesian_from_spherical(spherical_points)
204

205
# Plot 3D scatter
206
fig = plt.figure(figsize=(12, 4))
207

208
# Cartesian view
209
ax1 = fig.add_subplot(131, projection='3d')
210
ax1.scatter(cartesian_points[:, 0], cartesian_points[:, 1], cartesian_points[:, 2], 
211
           c=theta, cmap='viridis', s=1)
212
ax1.set_title('Cartesian View')
213
ax1.set_xlabel('X')
214
ax1.set_ylabel('Y')
215
ax1.set_zlabel('Z')
216

217
# Cylindrical projection (top view)
218
cylindrical_points = pco.cylindrical_from_cartesian(cartesian_points)
219
ax2 = fig.add_subplot(132)
220
ax2.scatter(cylindrical_points[:, 0] * np.cos(cylindrical_points[:, 1]), 
221
           cylindrical_points[:, 0] * np.sin(cylindrical_points[:, 1]),
222
           c=cylindrical_points[:, 2], cmap='plasma', s=1)
223
ax2.set_title('Cylindrical Projection')
224
ax2.set_xlabel('Rho * cos(phi)')
225
ax2.set_ylabel('Rho * sin(phi)')
226
ax2.set_aspect('equal')
227

228
# Spherical coordinates plot
229
ax3 = fig.add_subplot(133)
230
ax3.scatter(phi, theta, c=rho, s=1)
231
ax3.set_title('Spherical Coordinates')
232
ax3.set_xlabel('Phi (azimuth)')
233
ax3.set_ylabel('Theta (polar)')
234

235
plt.tight_layout()
236
plt.show()
237
```