0
# Coordinate Systems
1
2
Comprehensive celestial coordinate system framework with transformations between reference frames, sky coordinate matching, and integration with observational astronomy.
3
4
## Core Imports
5
6
```python
7
from astropy.coordinates import SkyCoord
8
from astropy.coordinates import ICRS, Galactic, FK5, AltAz
9
from astropy.coordinates import EarthLocation
10
from astropy.coordinates import get_body, get_sun, get_moon
11
from astropy.coordinates import match_coordinates_sky, search_around_sky
12
```
13
14
## Capabilities
15
16
### High-Level Sky Coordinates
17
18
High-level interface for celestial coordinates with automatic frame transformations, coordinate matching, and observational astronomy integration.
19
20
```python { .api }
21
class SkyCoord:
22
"""
23
High-level representation of celestial coordinates.
24
25
Parameters:
26
- *args: coordinate values (ra, dec) or (lon, lat) etc.
27
- frame: coordinate frame (ICRS, Galactic, etc.)
28
- unit: units for coordinates
29
- **kwargs: frame-specific attributes
30
"""
31
def __init__(self, *args, frame=None, unit=None, **kwargs): ...
32
33
def transform_to(self, frame):
34
"""
35
Transform to another coordinate frame.
36
37
Parameters:
38
- frame: target frame class or instance
39
40
Returns:
41
SkyCoord: coordinates in new frame
42
"""
43
44
def match_to_catalog_sky(self, catalogcoord, nthneighbor=1):
45
"""
46
Match coordinates to catalog coordinates.
47
48
Parameters:
49
- catalogcoord: catalog coordinates to match against
50
- nthneighbor: which neighbor to find (1=closest)
51
52
Returns:
53
tuple: (indices, separations, distances_3d)
54
"""
55
56
def search_around_sky(self, searchcoord, seplimit):
57
"""
58
Search for coordinates within angular separation limit.
59
60
Parameters:
61
- searchcoord: coordinates to search around
62
- seplimit: maximum angular separation
63
64
Returns:
65
tuple: (indices_coords, indices_search, separations, distances_3d)
66
"""
67
68
def separation(self, other):
69
"""Angular separation to other coordinates."""
70
71
def separation_3d(self, other):
72
"""3D distance to other coordinates."""
73
74
def position_angle(self, other):
75
"""Position angle to other coordinates."""
76
77
def directional_offset_by(self, position_angle, separation):
78
"""Offset coordinates by position angle and separation."""
79
80
@property
81
def ra(self):
82
"""Right ascension."""
83
84
@property
85
def dec(self):
86
"""Declination."""
87
88
@property
89
def distance(self):
90
"""Distance (if available)."""
91
92
@property
93
def pm_ra_cosdec(self):
94
"""Proper motion in RA (including cos(dec) factor)."""
95
96
@property
97
def pm_dec(self):
98
"""Proper motion in declination."""
99
100
@property
101
def radial_velocity(self):
102
"""Radial velocity."""
103
```
104
105
### Coordinate Frames
106
107
Built-in coordinate reference frames for celestial coordinates with support for epochs, equinoxes, and observational parameters.
108
109
```python { .api }
110
class BaseCoordinateFrame:
111
"""Base class for coordinate reference frames."""
112
def __init__(self, *args, **kwargs): ...
113
114
def transform_to(self, frame):
115
"""Transform to another frame."""
116
117
@property
118
def spherical(self):
119
"""Spherical representation."""
120
121
@property
122
def cartesian(self):
123
"""Cartesian representation."""
124
125
# Equatorial coordinate systems
126
class ICRS(BaseCoordinateFrame):
127
"""International Celestial Reference System."""
128
129
class FK5(BaseCoordinateFrame):
130
"""Fifth Fundamental Catalogue system."""
131
def __init__(self, equinox=None, obstime=None): ...
132
133
class FK4(BaseCoordinateFrame):
134
"""Fourth Fundamental Catalogue system."""
135
def __init__(self, equinox=None, obstime=None): ...
136
137
class FK4NoETerms(BaseCoordinateFrame):
138
"""FK4 coordinates without E-terms of aberration."""
139
140
# Galactic coordinates
141
class Galactic(BaseCoordinateFrame):
142
"""Galactic coordinate system."""
143
144
class Supergalactic(BaseCoordinateFrame):
145
"""Supergalactic coordinate system."""
146
147
# Horizontal coordinates
148
class AltAz(BaseCoordinateFrame):
149
"""Altitude-Azimuth coordinate system."""
150
def __init__(self, obstime=None, location=None, pressure=None, temperature=None): ...
151
152
# Geocentric and heliocentric systems
153
class Gcrs(BaseCoordinateFrame):
154
"""Geocentric Celestial Reference System."""
155
def __init__(self, obstime=None, obsgeoloc=None, obsgeovel=None): ...
156
157
class CIRS(BaseCoordinateFrame):
158
"""Celestial Intermediate Reference System."""
159
160
class ITRS(BaseCoordinateFrame):
161
"""International Terrestrial Reference System."""
162
163
class HCRS(BaseCoordinateFrame):
164
"""Heliocentric Celestial Reference System."""
165
166
# Local Standard of Rest frames
167
class LSR(BaseCoordinateFrame):
168
"""Local Standard of Rest frame."""
169
def __init__(self, v_bary=None): ...
170
171
class LSRK(BaseCoordinateFrame):
172
"""Kinematic Local Standard of Rest."""
173
174
class LSRD(BaseCoordinateFrame):
175
"""Dynamic Local Standard of Rest."""
176
177
class GalacticLSR(BaseCoordinateFrame):
178
"""Galactic Local Standard of Rest."""
179
```
180
181
### Coordinate Representations
182
183
Different mathematical representations for coordinates (spherical, cartesian, cylindrical) with conversion utilities.
184
185
```python { .api }
186
class BaseRepresentation:
187
"""Base class for coordinate representations."""
188
def __init__(self): ...
189
190
def to_cartesian(self):
191
"""Convert to Cartesian representation."""
192
193
@classmethod
194
def from_cartesian(cls, cart):
195
"""Create from Cartesian coordinates."""
196
197
class SphericalRepresentation(BaseRepresentation):
198
"""
199
Spherical coordinates (longitude, latitude, distance).
200
201
Parameters:
202
- lon: longitude coordinate
203
- lat: latitude coordinate
204
- distance: radial distance (optional)
205
"""
206
def __init__(self, lon, lat, distance=None): ...
207
208
class UnitSphericalRepresentation(BaseRepresentation):
209
"""Unit sphere coordinates (longitude, latitude only)."""
210
def __init__(self, lon, lat): ...
211
212
class CartesianRepresentation(BaseRepresentation):
213
"""
214
Cartesian coordinates (x, y, z).
215
216
Parameters:
217
- x, y, z: Cartesian coordinate components
218
"""
219
def __init__(self, x, y, z): ...
220
221
def norm(self):
222
"""Magnitude of position vector."""
223
224
def dot(self, other):
225
"""Dot product with another vector."""
226
227
def cross(self, other):
228
"""Cross product with another vector."""
229
230
class CylindricalRepresentation(BaseRepresentation):
231
"""Cylindrical coordinates (rho, phi, z)."""
232
def __init__(self, rho, phi, z): ...
233
234
class PhysicsSphericalRepresentation(BaseRepresentation):
235
"""Physics convention spherical coordinates (r, theta, phi)."""
236
def __init__(self, r, theta, phi): ...
237
238
# Conversion utilities
239
def cartesian_to_spherical(x, y, z):
240
"""Convert Cartesian to spherical coordinates."""
241
242
def spherical_to_cartesian(r, lat, lon):
243
"""Convert spherical to Cartesian coordinates."""
244
```
245
246
### Angles and Angular Quantities
247
248
Specialized angle classes with parsing support, range constraints, and astronomical coordinate handling.
249
250
```python { .api }
251
class Angle:
252
"""
253
General angle class with unit support and string parsing.
254
255
Parameters:
256
- angle: numerical value or string representation
257
- unit: angle unit (degree, radian, hourangle, etc.)
258
"""
259
def __init__(self, angle, unit=None): ...
260
261
def to(self, unit):
262
"""Convert to different angular unit."""
263
264
def wrap_at(self, wrap_angle):
265
"""Wrap angle to specified range."""
266
267
@property
268
def degree(self):
269
"""Angle in degrees."""
270
271
@property
272
def radian(self):
273
"""Angle in radians."""
274
275
@property
276
def hourangle(self):
277
"""Angle in hour angles (15 degrees)."""
278
279
@property
280
def hms(self):
281
"""Hours, minutes, seconds tuple."""
282
283
@property
284
def dms(self):
285
"""Degrees, minutes, seconds tuple."""
286
287
class Longitude(Angle):
288
"""
289
Longitude angle constrained to [0°, 360°).
290
291
Parameters:
292
- angle: longitude value
293
- unit: angular unit
294
- wrap_angle: wrapping reference angle
295
"""
296
def __init__(self, angle, unit=None, wrap_angle=None): ...
297
298
class Latitude(Angle):
299
"""
300
Latitude angle constrained to [-90°, +90°].
301
302
Parameters:
303
- angle: latitude value
304
- unit: angular unit
305
"""
306
def __init__(self, angle, unit=None): ...
307
```
308
309
### Distance and 3D Coordinates
310
311
Distance measurements with parallax and redshift support, enabling full 3D coordinate transformations.
312
313
```python { .api }
314
class Distance:
315
"""
316
Distance measurement with unit support and astronomical conversions.
317
318
Parameters:
319
- distance: distance value
320
- unit: distance unit
321
- parallax: parallax angle (alternative specification)
322
- distmod: distance modulus (alternative specification)
323
- z: redshift (alternative specification, requires cosmology)
324
"""
325
def __init__(self, distance=None, unit=None, parallax=None, distmod=None, z=None): ...
326
327
def to(self, unit):
328
"""Convert to different distance unit."""
329
330
@property
331
def parallax(self):
332
"""Parallax angle corresponding to distance."""
333
334
@property
335
def distmod(self):
336
"""Distance modulus."""
337
338
@property
339
def z(self):
340
"""Cosmological redshift (if applicable)."""
341
```
342
343
### Earth Locations and Observatories
344
345
Earth location support for observational astronomy calculations including site coordinates and observatory databases.
346
347
```python { .api }
348
class EarthLocation:
349
"""
350
Location on Earth's surface for astronomical observations.
351
352
Parameters:
353
- lat: geodetic latitude
354
- lon: longitude
355
- height: height above reference ellipsoid
356
- x, y, z: geocentric Cartesian coordinates (alternative)
357
"""
358
def __init__(self, lat=None, lon=None, height=None, x=None, y=None, z=None): ...
359
360
@classmethod
361
def from_geocentric(cls, x, y, z, unit=None):
362
"""Create from geocentric coordinates."""
363
364
@classmethod
365
def of_site(cls, site_name):
366
"""
367
Create from observatory name.
368
369
Parameters:
370
- site_name: name of observatory (e.g., 'Keck', 'VLT')
371
"""
372
373
@classmethod
374
def get_site_names(cls):
375
"""Get list of available observatory site names."""
376
377
def to_geocentric(self):
378
"""Convert to geocentric coordinates."""
379
380
def get_itrs(self, obstime=None):
381
"""Get ITRS coordinates at given time."""
382
```
383
384
### Solar System Objects
385
386
Functions for obtaining coordinates of solar system objects including planets, the Moon, and the Sun.
387
388
```python { .api }
389
def get_body(body, time, location=None, ephemeris=None):
390
"""
391
Get coordinates of solar system body.
392
393
Parameters:
394
- body: name of body ('sun', 'moon', 'mercury', etc.)
395
- time: observation time
396
- location: observer location (EarthLocation)
397
- ephemeris: ephemeris to use ('builtin', 'de430', etc.)
398
399
Returns:
400
SkyCoord: coordinates of the body
401
"""
402
403
def get_moon(time, location=None, ephemeris=None):
404
"""Get Moon coordinates."""
405
406
def get_sun(time):
407
"""Get Sun coordinates."""
408
409
def solar_system_ephemeris():
410
"""Context manager for setting default ephemeris."""
411
```
412
413
### Coordinate Matching and Searching
414
415
Utilities for matching coordinate catalogs and searching for nearby objects with optimized algorithms.
416
417
```python { .api }
418
def match_coordinates_3d(matchcoord, catalogcoord, nthneighbor=1):
419
"""
420
Match coordinates in 3D space.
421
422
Parameters:
423
- matchcoord: coordinates to match
424
- catalogcoord: catalog coordinates
425
- nthneighbor: which neighbor to return
426
427
Returns:
428
tuple: (indices, separations, distances_3d)
429
"""
430
431
def match_coordinates_sky(matchcoord, catalogcoord, nthneighbor=1):
432
"""Match coordinates on the sky (2D angular matching)."""
433
434
def search_around_3d(coords1, coords2, distlimit):
435
"""
436
Search for coordinates within 3D distance limit.
437
438
Parameters:
439
- coords1, coords2: coordinate arrays
440
- distlimit: maximum 3D distance
441
442
Returns:
443
tuple: (indices_1, indices_2, distances_3d)
444
"""
445
446
def search_around_sky(coords1, coords2, seplimit):
447
"""Search for coordinates within angular separation limit."""
448
```
449
450
### Name Resolution
451
452
Coordinate lookup by astronomical object names using online databases.
453
454
```python { .api }
455
def get_icrs_coordinates(name):
456
"""
457
Resolve object name to ICRS coordinates.
458
459
Parameters:
460
- name: astronomical object name
461
462
Returns:
463
SkyCoord: ICRS coordinates of the object
464
"""
465
466
class NameResolveError(Exception):
467
"""Exception raised when name resolution fails."""
468
```
469
470
## Usage Examples
471
472
### Basic Coordinate Creation and Transformation
473
474
```python
475
from astropy.coordinates import SkyCoord
476
import astropy.units as u
477
478
# Create coordinates
479
c = SkyCoord(ra=10.625*u.degree, dec=41.2*u.degree, frame='icrs')
480
481
# Transform between frames
482
c_galactic = c.galactic
483
c_fk5 = c.transform_to('fk5')
484
485
print(f"ICRS: RA={c.ra}, Dec={c.dec}")
486
print(f"Galactic: l={c_galactic.l}, b={c_galactic.b}")
487
print(f"FK5: RA={c_fk5.ra}, Dec={c_fk5.dec}")
488
```
489
490
### Coordinate Arrays and Matching
491
492
```python
493
import numpy as np
494
495
# Create coordinate arrays
496
ra = np.random.uniform(0, 360, 1000) * u.degree
497
dec = np.random.uniform(-90, 90, 1000) * u.degree
498
catalog = SkyCoord(ra=ra, dec=dec)
499
500
# Single target coordinate
501
target = SkyCoord(ra=180*u.degree, dec=45*u.degree)
502
503
# Find closest match
504
idx, sep2d, sep3d = target.match_to_catalog_sky(catalog)
505
closest_star = catalog[idx]
506
507
print(f"Closest star at separation: {sep2d.to(u.arcsec)}")
508
```
509
510
### Observational Astronomy
511
512
```python
513
from astropy.coordinates import EarthLocation, AltAz, get_sun
514
from astropy.time import Time
515
516
# Set up observatory
517
location = EarthLocation.of_site('Keck')
518
time = Time('2023-08-15 10:00:00')
519
520
# Get Sun coordinates
521
sun = get_sun(time)
522
523
# Transform to horizontal coordinates
524
sun_altaz = sun.transform_to(AltAz(obstime=time, location=location))
525
526
print(f"Sun altitude: {sun_altaz.alt}")
527
print(f"Sun azimuth: {sun_altaz.az}")
528
```
529
530
### Proper Motion and 3D Coordinates
531
532
```python
533
# Star with proper motion and parallax
534
star = SkyCoord(
535
ra=83.8221*u.degree, dec=-5.3911*u.degree,
536
distance=Distance(parallax=768.5*u.mas),
537
pm_ra_cosdec=28.87*u.mas/u.yr,
538
pm_dec=11.31*u.mas/u.yr,
539
radial_velocity=-17.8*u.km/u.s,
540
obstime=Time('J2000')
541
)
542
543
# Apply proper motion to current epoch
544
star_now = star.apply_space_motion(new_obstime=Time.now())
545
546
print(f"Current position: RA={star_now.ra}, Dec={star_now.dec}")
547
print(f"3D distance: {star.distance}")
548
```
549
550
### Custom Coordinate Frames
551
552
```python
553
from astropy.coordinates import frame_transform_graph
554
555
# Define custom frame transformation
556
@frame_transform_graph.transform(StaticMatrixTransform, CustomFrame, ICRS)
557
def custom_to_icrs():
558
# Define transformation matrix
559
return rotation_matrix
560
561
# Use custom frame
562
coords_custom = SkyCoord(10*u.degree, 20*u.degree, frame=CustomFrame)
563
coords_icrs = coords_custom.transform_to(ICRS)
564
```