coord-api-test.py

# -*- coding: utf-8 -*-

from astropy import coordinates as coords
from astropy import units as u
import astropy.time

J2001 = astropy.time.Time('J2001',scale='utc')


#<---------------------------"High-level" class-------------------------------->
# The "high-level" class is intended to wrap the lower-level classes in such a
# way that they can be round-tripped, as well as providing a variety of
# convenience functionality.  This document is not intended to show *all* of the
# possible high-level functionality, rather how the high-level classes are
# initialized and interact with the low-level classes

# this creates an object that contains an `ICRS` low-level class, initialized
# identically to the first ICRS example further up.

# NOT YET
# sc = coords.SkyCoordinate(coords.SphericalRepresentation(lon=8*u.hour, lat=5*u.deg, distance=1*u.kpc), system='icrs')


# Other representations and `system` keywords delegate to the appropriate
# low-level class. The already-existing registry for user-defined coordinates
# will be used by `SkyCoordinate` to figure out what various the `system`
# keyword actually means.

# they can also be initialized using the preferred representation names
sc = coords.SkyCoordinate(ra=8*u.hour, dec=5*u.deg, system='icrs')
sc = coords.SkyCoordinate(l=120*u.deg, b=5*u.deg, system='galactic')

# High-level classes can also be initialized directly from low-level objects
sc = coords.SkyCoordinate(coords.ICRS(ra=8*u.hour, dec=5*u.deg))
# The next example raises an error because the high-level class must always
# have position data
try:
    sc = coords.SkyCoordinate(coords.FK5(equinox=J2001))  # raises ValueError
except TypeError:
    print('pass')
else:
    raise ValueError

# similarly, the low-level object can always be accessed

# NOT YET
# assert str(scoords.frame) == '<ICRS RA=120.000 deg, Dec=5.00000 deg>'

# Should (eventually) support a variety of possible complex string formats
sc = coords.SkyCoordinate('8h00m00s +5d00m00.0s', system='icrs')
# In the next example, the unit is only needed b/c units are ambiguous.  In
# general, we *never* accept ambiguity
sc = coords.SkyCoordinate('8:00:00 +5:00:00.0', unit=(u.hour, u.deg), system='icrs')

# The next one would yield length-2 array coordinates, because of the comma

# NOT YET
# sc = coords.SkyCoordinate(['8h 5d', '2°5\'12.3" 0.3rad'], system='icrs')

# It should also interpret common designation styles as a coordinate
# NOT YET
# sc = coords.SkyCoordinate('SDSS J123456.89-012345.6', system='icrs')

# the string representation can be inherited from the low-level class.

# NOT YET
# assert str(sc) == '<SkyCoordinate (ICRS) RA=120.000 deg, Dec=5.00000 deg>'

# but it should also be possible to provide formats for outputting to strings,
# similar to `Time`.  This can be added right away or at a later date.

# transformation is done the same as for low-level classes, which it delegates to

# NOT YET
# scfk5_j2001 = scoords.transform_to(coords.FK5(equinox=J2001))

if False:
    # the key difference is that the high-level class remembers frame information
    # necessary for round-tripping, unlike the low-level classes:
    sc1 = coords.SkyCoordinate(ra=8*u.hour, dec=5*u.deg, equinox=J2001, system='fk5')
    sc2 = sc1.transform_to(coords.ICRS)
    # The next assertion succeeds, but it doesn't mean anything for ICRS, as ICRS
    # isn't defined in terms of an equinox
    assert sc2.equinox == J2001
    # But it *is* necessary once we transform to FK5
    sc3 = sc2.transform_to(coords.FK5)
    assert sc3.equinox == J2001
    assert sc1.ra == sc3.ra
    # Note that this did *not* work in the low-level class example shown above,
    # because the ICRS low-level class does not store `equinox`.


# `SkyCoordinate` will also include the attribute-style access that is in the
# v0.2/0.3 coordinate objects.  This will *not* be in the low-level classes
sc = coords.SkyCoordinate(ra=8*u.hour, dec=5*u.deg, system='icrs')
scgal = sc.galactic
assert str(scgal) == '<SkyCoordinate Galactic l=216.31707 deg, b=17.51990 deg>'


# the existing `from_name` and `match_to_catalog_*` methods will be moved to the
# high-level class as convenience functionality.

if False:
    m31icrs = SkyCoordinate.from_name('M31', system='icrs')
    assert str(m31icrs) == '<SkyCoordinate (ICRS) RA=10.68471 deg, Dec=41.26875 deg>'

    cat1 = SkyCoordinate(ra=1*u.hr, dec=2*u.deg, distance=3*u.kpc)
    cat2 = SkyCoordinate(ra=1*u.hr, dec=2*u.deg, distance=3*u.kpc)
    idx2, sep2d, dist3d = cat1.match_to_catalog_sky(cat2)
    idx2, sep2d, dist3d = cat1.match_to_catalog_3d(cat2)


    # additional convenience functionality for the future should be added as methods
    # on `SkyCoordinate`, *not* the low-level classes.