1# -*- coding: utf-8 -*-
2# Licensed under a 3-clause BSD style license - see LICENSE.rst
3
4from astropy import units as u
5from astropy.utils.decorators import format_doc
6from astropy.coordinates.angles import Angle
7from astropy.coordinates import representation as r
8from astropy.coordinates.baseframe import BaseCoordinateFrame, RepresentationMapping, base_doc
9
10# these are needed for defining the NGP
11from .fk5 import FK5
12from .fk4 import FK4NoETerms
13
14__all__ = ['Galactic']
15
16
17doc_components = """
18    l : `~astropy.coordinates.Angle`, optional, keyword-only
19        The Galactic longitude for this object (``b`` must also be given and
20        ``representation`` must be None).
21    b : `~astropy.coordinates.Angle`, optional, keyword-only
22        The Galactic latitude for this object (``l`` must also be given and
23        ``representation`` must be None).
24    distance : `~astropy.units.Quantity` ['length'], optional, keyword-only
25        The Distance for this object along the line-of-sight.
26
27    pm_l_cosb : `~astropy.units.Quantity` ['angular speed'], optional, keyword-only
28        The proper motion in Galactic longitude (including the ``cos(b)`` term)
29        for this object (``pm_b`` must also be given).
30    pm_b : `~astropy.units.Quantity` ['angular speed'], optional, keyword-only
31        The proper motion in Galactic latitude for this object (``pm_l_cosb``
32        must also be given).
33    radial_velocity : `~astropy.units.Quantity` ['speed'], optional, keyword-only
34        The radial velocity of this object.
35"""
36
37doc_footer = """
38    Notes
39    -----
40    .. [1] Blaauw, A.; Gum, C. S.; Pawsey, J. L.; Westerhout, G. (1960), "The
41       new I.A.U. system of galactic coordinates (1958 revision),"
42       `MNRAS, Vol 121, pp.123 <https://ui.adsabs.harvard.edu/abs/1960MNRAS.121..123B>`_.
43"""
44
45
46@format_doc(base_doc, components=doc_components, footer=doc_footer)
47class Galactic(BaseCoordinateFrame):
48    """
49    A coordinate or frame in the Galactic coordinate system.
50
51    This frame is used in a variety of Galactic contexts because it has as its
52    x-y plane the plane of the Milky Way.  The positive x direction (i.e., the
53    l=0, b=0 direction) points to the center of the Milky Way and the z-axis
54    points toward the North Galactic Pole (following the IAU's 1958 definition
55    [1]_). However, unlike the `~astropy.coordinates.Galactocentric` frame, the
56    *origin* of this frame in 3D space is the solar system barycenter, not
57    the center of the Milky Way.
58    """
59
60    frame_specific_representation_info = {
61        r.SphericalRepresentation: [
62            RepresentationMapping('lon', 'l'),
63            RepresentationMapping('lat', 'b')
64        ],
65        r.CartesianRepresentation: [
66            RepresentationMapping('x', 'u'),
67            RepresentationMapping('y', 'v'),
68            RepresentationMapping('z', 'w')
69        ],
70        r.CartesianDifferential: [
71            RepresentationMapping('d_x', 'U', u.km/u.s),
72            RepresentationMapping('d_y', 'V', u.km/u.s),
73            RepresentationMapping('d_z', 'W', u.km/u.s)
74        ]
75    }
76
77    default_representation = r.SphericalRepresentation
78    default_differential = r.SphericalCosLatDifferential
79
80    # North galactic pole and zeropoint of l in FK4/FK5 coordinates. Needed for
81    # transformations to/from FK4/5
82
83    # These are from the IAU's definition of galactic coordinates
84    _ngp_B1950 = FK4NoETerms(ra=192.25*u.degree, dec=27.4*u.degree)
85    _lon0_B1950 = Angle(123, u.degree)
86
87    # These are *not* from Reid & Brunthaler 2004 - instead, they were
88    # derived by doing:
89    #
90    # >>> FK4NoETerms(ra=192.25*u.degree, dec=27.4*u.degree).transform_to(FK5())
91    #
92    # This gives better consistency with other codes than using the values
93    # from Reid & Brunthaler 2004 and the best self-consistency between FK5
94    # -> Galactic and FK5 -> FK4 -> Galactic. The lon0 angle was found by
95    # optimizing the self-consistency.
96    _ngp_J2000 = FK5(ra=192.8594812065348*u.degree, dec=27.12825118085622*u.degree)
97    _lon0_J2000 = Angle(122.9319185680026, u.degree)
98