SphericalCoordinatesBase

class astropy.coordinates.coordsystems.SphericalCoordinatesBase(*args, **kwargs)

Bases: object

Abstract superclass for all coordinate classes representing points in three dimensions.

Notes

Subclasses must implement __init__, and define the latangle and lonangle properties. They may also override the equinox property, or leave it unaltered to indicate the coordinates are equinoxless.

_initialize_latlon is provided to implement typical initialization features, and should be called from a subclass’ __init__. See the classes in astropy.coordinates.builtin_systems for examples of this.

Attributes Summary

cartesian
distance	The radial distance for this coordinate object as an Distance object.
equinox	The equinox of this system, or None to indicate no equinox specified.
isscalar	True if this coordinate contains scalar angles/distances, or False if
latangle	The latitudinal/elevation angle for these coordinates as an Angle object.
lonangle	The longitudinal/azimuthal angle for these coordinates as an Angle object.
x
y
z

Methods Summary

from_name(name)	Given a name, query the CDS name resolver to attempt to retrieve coordinate information for that object.
is_transformable_to(tosys)	Determines if this coordinate can be transformed to a particular system.
match_to_catalog_3d(catalogcoord[, nthneighbor])	Finds the nearest 3-dimensional matches of this coordinate to a set of catalog coordinates.
match_to_catalog_sky(catalogcoord[, nthneighbor])	Finds the nearest on-sky matches of this coordinate in a set of catalog coordinates.
separation(other)	Computes on-sky separation between this coordinate and another.
separation_3d(other)	Computes three dimensional separation between this coordinate and another.
to_string([style])	A string representation of the coordinates.
transform_to(tosys)	Transform this coordinate to a new system.

Attributes Documentation

cartesian

distance

The radial distance for this coordinate object as an Distance object.

If set as a tuple, the tuple will be passed into the Distance constructor.

Alternatively, this may be None, indicating an unknown/not given distance. Where necessary, this object will be interpreted as angles on the unit sphere.

equinox

The equinox of this system, or None to indicate no equinox specified.

isscalar

True if this coordinate contains scalar angles/distances, or False if they are array-like

latangle

The latitudinal/elevation angle for these coordinates as an Angle object.

Subclasses will often provide properties returning the same object, but with a name more appropriate for the particular subclass.

lonangle

The longitudinal/azimuthal angle for these coordinates as an Angle object.

Subclasses will often provide properties returning the same object, but with a name more appropriate for the particular subclass.

x

y

z

Methods Documentation

classmethod from_name(name)

Given a name, query the CDS name resolver to attempt to retrieve coordinate information for that object. The search database, sesame url, and query timeout can be set through configuration items in astropy.coordinates.name_resolve – see docstring for astropy.coordinates.name_resolve.get_icrs_coordinates for more information.

Parameters:

name : str

The name of the object to get coordinates for, e.g. m42.

Returns:

coord : SphericalCoordinatesBase

Instance of a Coordinates class, specified by the class this is called on, e.g. if Galactic.from_name('m42'), will get an instance of Galactic representing the position of M42.

is_transformable_to(tosys)

Determines if this coordinate can be transformed to a particular system.

Parameters:

tosys : class

The system to transform this coordinate into.

Returns:

transformable : bool or str

True if this can be trasnformed to tosys, False if not. The string ‘same’ if tosys is the same system as this object (i.e. no transformation is needed).

match_to_catalog_3d(catalogcoord, nthneighbor=1)

Finds the nearest 3-dimensional matches of this coordinate to a set of catalog coordinates.

This finds the 3-dimensional closest neighbor, which is only different from the on-sky distance if distance is set in this object or the catalogcoord object.

Parameters:

catalogcoord : SphericalCoordinatesBase

The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., catalogcoord.isscalar == False)

nthneighbor : int, optional

Which closest neighbor to search for. Typically 1 is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is 2, for matching a coordinate catalog against itself (1 is inappropriate because each point will find itself as the closest match).

Returns:

idx : integer array

Indecies into catalogcoord to get the matched points for each matchcoord. Shape matches this coordinate.

sep2d : Angle

The on-sky separation between the closest match for each matchcoord and the matchcoord. Shape matches matchcoord.

dist3d : Quantity

The 3D distance between the closest match for each matchcoord and the matchcoord. Shape matches this coordinate.

See also

astropy.coordinates.matching.match_coordinates_3d

Notes

This method requires scipy to be installed or it will fail.

match_to_catalog_sky(catalogcoord, nthneighbor=1)

Finds the nearest on-sky matches of this coordinate in a set of catalog coordinates.

Parameters:

catalogcoord : SphericalCoordinatesBase

The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., catalogcoord.isscalar == False)

nthneighbor : int, optional

Which closest neighbor to search for. Typically 1 is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is 2, for matching a coordinate catalog against itself (1 is inappropriate because each point will find itself as the closest match).

Returns:

idx : integer array

Indecies into catalogcoord to get the matched points for each matchcoord. Shape matches this coordinate.

sep2d : Angle

The on-sky separation between the closest match for each matchcoord and the matchcoord. Shape matches matchcoord.

dist3d : Quantity

The 3D distance between the closest match for each matchcoord and the matchcoord. Shape matches this coordinate.

See also

astropy.coordinates.matching.match_coordinates_sky

Notes

This method requires scipy to be installed or it will fail.

separation(other)

Computes on-sky separation between this coordinate and another.

Parameters:

other : SphericalCoordinatesBase

The coordinate to get the separation to.

Returns:

sep : Angle

The on-sky separation between this and the other coordinate.

Notes

The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [R2].

[R2]	http://en.wikipedia.org/wiki/Great-circle_distance

separation_3d(other)

Computes three dimensional separation between this coordinate and another.

Parameters:

other : SphericalCoordinatesBase

The coordinate system to get the distance to.

Returns:

sep : Distance

The real-space distance between these two coordinates.

Raises:

ValueError :

If this or the other coordinate do not have distances.

to_string(style=None, **kwargs)

A string representation of the coordinates.

See astropy.coordinates.Angle.to_string() for details and keyword arguments (the two angles forming the coordinates are are both astropy.coordinates.Angle instances). Keyword arguments are passed to astropy.coordinates.Angle.to_string().

Parameters:

style : {‘hmsdms’, ‘dms’, ‘decimal’, None}

The formatting specification to use. These encode the three most common ways to represent coordinates. If None is passed, the defaults for the current coordinate class is used.

kwargs :

Keyword arguments are passed to astropy.coordinates.Angle.to_string().

transform_to(tosys)

Transform this coordinate to a new system.

Parameters:

tosys : class

The system to transform this coordinate into.

Returns:

transcoord :

A new object with this coordinate represented in the tosys system.

Raises:

ValueError :

If there is no possible transformation route.