0
# Coordinate Systems
1

2
Comprehensive coordinate system transformations including rectangular, spherical, cylindrical, latitudinal, and various planetary coordinate systems. These functions enable conversion between different geometric representations used in space science.
3

4
## Capabilities
5

6
### Spherical Coordinates
7

8
Convert between rectangular (Cartesian) and spherical coordinate systems.
9

10
```python { .api }
11
def sphrec(r: float, colat: float, lon: float) -> ndarray:
12
    """
13
    Convert spherical coordinates to rectangular coordinates.
14
    
15
    Parameters:
16
    - r: float, distance from origin
17
    - colat: float, colatitude in radians (angle from +Z axis)
18
    - lon: float, longitude in radians
19
    
20
    Returns:
21
    ndarray: 3-element rectangular coordinate vector [x, y, z]
22
    """
23

24
def recsph(rectan: ndarray) -> Tuple[float, float, float]:
25
    """
26
    Convert rectangular coordinates to spherical coordinates.
27
    
28
    Parameters:
29
    - rectan: ndarray, 3-element rectangular coordinate vector
30
    
31
    Returns:
32
    Tuple[float, float, float]: (r, colat, lon)
33
    - r: distance from origin
34
    - colat: colatitude in radians
35
    - lon: longitude in radians
36
    """
37
```
38

39
### Latitudinal Coordinates
40

41
Convert between rectangular and latitudinal coordinate systems (latitude/longitude).
42

43
```python { .api }
44
def latrec(radius: float, lon: float, lat: float) -> ndarray:
45
    """
46
    Convert latitudinal coordinates to rectangular coordinates.
47
    
48
    Parameters:
49
    - radius: float, distance from origin
50
    - lon: float, longitude in radians
51
    - lat: float, latitude in radians
52
    
53
    Returns:
54
    ndarray: 3-element rectangular coordinate vector [x, y, z]
55
    """
56

57
def reclat(rectan: ndarray) -> Tuple[float, float, float]:
58
    """
59
    Convert rectangular coordinates to latitudinal coordinates.
60
    
61
    Parameters:
62
    - rectan: ndarray, 3-element rectangular coordinate vector
63
    
64
    Returns:
65
    Tuple[float, float, float]: (radius, lon, lat)
66
    - radius: distance from origin
67
    - lon: longitude in radians
68
    - lat: latitude in radians
69
    """
70
```
71

72
### Cylindrical Coordinates
73

74
Convert between rectangular and cylindrical coordinate systems.
75

76
```python { .api }
77
def cylrec(r: float, lon: float, z: float) -> ndarray:
78
    """
79
    Convert cylindrical coordinates to rectangular coordinates.
80
    
81
    Parameters:
82
    - r: float, radial distance from Z-axis
83
    - lon: float, longitude in radians
84
    - z: float, height above XY-plane
85
    
86
    Returns:
87
    ndarray: 3-element rectangular coordinate vector [x, y, z]
88
    """
89

90
def reccyl(rectan: ndarray) -> Tuple[float, float, float]:
91
    """
92
    Convert rectangular coordinates to cylindrical coordinates.
93
    
94
    Parameters:
95
    - rectan: ndarray, 3-element rectangular coordinate vector
96
    
97
    Returns:
98
    Tuple[float, float, float]: (r, lon, z)
99
    - r: radial distance from Z-axis
100
    - lon: longitude in radians
101
    - z: height above XY-plane
102
    """
103
```
104

105
### Coordinate System Conversions
106

107
Convert between different coordinate systems directly.
108

109
```python { .api }
110
def sphlat(r: float, colat: float, lon: float) -> Tuple[float, float, float]:
111
    """
112
    Convert spherical coordinates to latitudinal coordinates.
113
    
114
    Parameters:
115
    - r: float, distance from origin
116
    - colat: float, colatitude in radians
117
    - lon: float, longitude in radians
118
    
119
    Returns:
120
    Tuple[float, float, float]: (radius, longitude, latitude)
121
    """
122

123
def latsph(radius: float, lon: float, lat: float) -> Tuple[float, float, float]:
124
    """
125
    Convert latitudinal coordinates to spherical coordinates.
126
    
127
    Parameters:
128
    - radius: float, distance from origin
129
    - lon: float, longitude in radians
130
    - lat: float, latitude in radians
131
    
132
    Returns:
133
    Tuple[float, float, float]: (r, colatitude, longitude)
134
    """
135

136
def cyllat(r: float, lonc: float, z: float) -> Tuple[float, float, float]:
137
    """
138
    Convert cylindrical coordinates to latitudinal coordinates.
139
    
140
    Parameters:
141
    - r: float, radial distance from Z-axis
142
    - lonc: float, longitude in radians
143
    - z: float, height above XY-plane
144
    
145
    Returns:
146
    Tuple[float, float, float]: (radius, longitude, latitude)
147
    """
148

149
def latcyl(radius: float, lon: float, lat: float) -> Tuple[float, float, float]:
150
    """
151
    Convert latitudinal coordinates to cylindrical coordinates.
152
    
153
    Parameters:
154
    - radius: float, distance from origin
155
    - lon: float, longitude in radians
156
    - lat: float, latitude in radians
157
    
158
    Returns:
159
    Tuple[float, float, float]: (r, longitude, z)
160
    """
161
```
162

163
### Geodetic Coordinates
164

165
Convert between rectangular and geodetic coordinate systems for planetary surfaces.
166

167
```python { .api }
168
def georec(lon: float, lat: float, alt: float, re: float, f: float) -> ndarray:
169
    """
170
    Convert geodetic coordinates to rectangular coordinates.
171
    
172
    Parameters:
173
    - lon: float, longitude in radians
174
    - lat: float, latitude in radians  
175
    - alt: float, altitude above reference ellipsoid
176
    - re: float, equatorial radius of reference ellipsoid
177
    - f: float, flattening coefficient
178
    
179
    Returns:
180
    ndarray: 3-element rectangular coordinate vector [x, y, z]
181
    """
182

183
def recgeo(rectan: ndarray, re: float, f: float) -> Tuple[float, float, float]:
184
    """
185
    Convert rectangular coordinates to geodetic coordinates.
186
    
187
    Parameters:
188
    - rectan: ndarray, 3-element rectangular coordinate vector
189
    - re: float, equatorial radius of reference ellipsoid
190
    - f: float, flattening coefficient
191
    
192
    Returns:
193
    Tuple[float, float, float]: (lon, lat, alt)
194
    - lon: longitude in radians
195
    - lat: latitude in radians
196
    - alt: altitude above reference ellipsoid
197
    """
198
```
199

200
### Planetographic Coordinates
201

202
Convert between rectangular and planetographic coordinate systems.
203

204
```python { .api }
205
def pgrrec(body: str, lon: float, lat: float, alt: float, re: float, f: float) -> ndarray:
206
    """
207
    Convert planetographic coordinates to rectangular coordinates.
208
    
209
    Parameters:
210
    - body: str, name of central body
211
    - lon: float, longitude in radians
212
    - lat: float, latitude in radians
213
    - alt: float, altitude above reference ellipsoid
214
    - re: float, equatorial radius
215
    - f: float, flattening coefficient
216
    
217
    Returns:
218
    ndarray: 3-element rectangular coordinate vector [x, y, z]
219
    """
220

221
def recpgr(body: str, rectan: ndarray, re: float, f: float) -> Tuple[float, float, float]:
222
    """
223
    Convert rectangular coordinates to planetographic coordinates.
224
    
225
    Parameters:
226
    - body: str, name of central body
227
    - rectan: ndarray, 3-element rectangular coordinate vector
228
    - re: float, equatorial radius
229
    - f: float, flattening coefficient
230
    
231
    Returns:
232
    Tuple[float, float, float]: (lon, lat, alt)
233
    - lon: longitude in radians
234
    - lat: latitude in radians  
235
    - alt: altitude above reference ellipsoid
236
    """
237
```
238

239
### Range/RA/DEC Coordinates
240

241
Convert between rectangular and range/right ascension/declination coordinates.
242

243
```python { .api }
244
def radrec(range: float, ra: float, dec: float) -> ndarray:
245
    """
246
    Convert range, right ascension, and declination to rectangular coordinates.
247
    
248
    Parameters:
249
    - range: float, distance from origin
250
    - ra: float, right ascension in radians
251
    - dec: float, declination in radians
252
    
253
    Returns:
254
    ndarray: 3-element rectangular coordinate vector [x, y, z]
255
    """
256

257
def recrad(rectan: ndarray) -> Tuple[float, float, float]:
258
    """
259
    Convert rectangular coordinates to range, right ascension, declination.
260
    
261
    Parameters:
262
    - rectan: ndarray, 3-element rectangular coordinate vector
263
    
264
    Returns:
265
    Tuple[float, float, float]: (range, ra, dec)
266
    - range: distance from origin
267
    - ra: right ascension in radians
268
    - dec: declination in radians
269
    """
270
```
271

272
### Azimuth/Elevation Coordinates
273

274
Convert between rectangular and azimuth/elevation coordinates.
275

276
```python { .api }
277
def azlrec(r: float, az: float, el: float) -> ndarray:
278
    """
279
    Convert azimuth and elevation to rectangular coordinates.
280
    
281
    Parameters:
282
    - r: float, distance from origin
283
    - az: float, azimuth in radians
284
    - el: float, elevation in radians
285
    
286
    Returns:
287
    ndarray: 3-element rectangular coordinate vector [x, y, z]
288
    """
289

290
def recazl(rectan: ndarray, azccw: bool, elplsz: bool) -> Tuple[float, float, float]:
291
    """
292
    Convert rectangular coordinates to azimuth and elevation.
293
    
294
    Parameters:
295
    - rectan: ndarray, 3-element rectangular coordinate vector
296
    - azccw: bool, azimuth counter-clockwise flag
297
    - elplsz: bool, elevation plus Z flag
298
    
299
    Returns:
300
    Tuple[float, float, float]: (range, azimuth, elevation)
301
    - range: distance from origin
302
    - azimuth: azimuth in radians
303
    - elevation: elevation in radians
304
    """
305
```
306

307
## Common Usage Patterns
308

309
### Basic Coordinate Conversion
310
```python
311
import spiceypy as spice
312
import numpy as np
313

314
# Convert spherical to rectangular coordinates
315
r = 1000.0  # 1000 km
316
colat = spice.rpd() * 30.0  # 30 degrees colatitude
317
lon = spice.rpd() * 45.0    # 45 degrees longitude
318

319
rect_coords = spice.sphrec(r, colat, lon)
320
print(f"Rectangular: {rect_coords}")
321

322
# Convert back to spherical
323
r_back, colat_back, lon_back = spice.recsph(rect_coords)
324
print(f"Spherical: r={r_back:.1f}, colat={spice.dpr()*colat_back:.1f}°, lon={spice.dpr()*lon_back:.1f}°")
325
```
326

327
### Planetary Surface Coordinates
328
```python
329
# Convert Earth geodetic coordinates to rectangular
330
# Location: San Francisco, CA
331
lon_sf = spice.rpd() * -122.4194  # Longitude (west is negative)
332
lat_sf = spice.rpd() * 37.7749    # Latitude
333
alt_sf = 0.052                    # Altitude in km (52 meters)
334

335
# Earth parameters
336
re_earth = 6378.1366              # Equatorial radius in km
337
f_earth = 0.00335281066           # Flattening coefficient
338

339
rect_sf = spice.georec(lon_sf, lat_sf, alt_sf, re_earth, f_earth)
340
print(f"San Francisco rectangular coordinates: {rect_sf}")
341

342
# Convert back to geodetic
343
lon_back, lat_back, alt_back = spice.recgeo(rect_sf, re_earth, f_earth)
344
print(f"Geodetic: lon={spice.dpr()*lon_back:.4f}°, lat={spice.dpr()*lat_back:.4f}°, alt={alt_back*1000:.1f}m")
345
```
346

347
### Mars Surface Operations
348
```python
349
# Convert Mars planetographic coordinates to rectangular
350
# Using Olympus Mons coordinates
351
lon_olympus = spice.rpd() * -133.8  # West longitude
352
lat_olympus = spice.rpd() * 18.65   # North latitude  
353
alt_olympus = 21.9                  # Altitude in km above datum
354

355
# Mars parameters
356
re_mars = 3396.19                   # Equatorial radius in km
357
f_mars = 0.00518498                 # Flattening coefficient
358

359
rect_olympus = spice.pgrrec("MARS", lon_olympus, lat_olympus, alt_olympus, re_mars, f_mars)
360
print(f"Olympus Mons rectangular coordinates: {rect_olympus}")
361
```
362

363
### Astronomical Coordinate Conversion
364
```python
365
# Convert astronomical coordinates (RA/DEC) to rectangular
366
range_star = 50.0  # Distance in parsecs (example)
367
ra_star = spice.rpd() * 83.633     # Right ascension in degrees (Betelgeuse)
368
dec_star = spice.rpd() * 7.407     # Declination in degrees
369

370
rect_star = spice.radrec(range_star, ra_star, dec_star)
371
print(f"Star position vector: {rect_star}")
372

373
# Convert back to RA/DEC
374
range_back, ra_back, dec_back = spice.recrad(rect_star)
375
print(f"RA/DEC: RA={spice.dpr()*ra_back:.3f}°, DEC={spice.dpr()*dec_back:.3f}°, Range={range_back:.1f}")
376
```
377

378
### Vector Coordinate Analysis
379
```python
380
# Analyze a position vector in different coordinate systems
381
position = np.array([1000.0, 1500.0, 2000.0])  # km
382

383
# Spherical analysis
384
r, colat, lon = spice.recsph(position)
385
print(f"Spherical: r={r:.1f} km, colat={spice.dpr()*colat:.1f}°, lon={spice.dpr()*lon:.1f}°")
386

387
# Latitudinal analysis  
388
radius, lon_lat, lat = spice.reclat(position)
389
print(f"Latitudinal: r={radius:.1f} km, lon={spice.dpr()*lon_lat:.1f}°, lat={spice.dpr()*lat:.1f}°")
390

391
# Cylindrical analysis
392
r_cyl, lon_cyl, z_cyl = spice.reccyl(position)
393
print(f"Cylindrical: r={r_cyl:.1f} km, lon={spice.dpr()*lon_cyl:.1f}°, z={z_cyl:.1f} km")
394
```