SphericalProjection

class sofia_redux.scan.coordinate_systems.projection.spherical_projection.SphericalProjection

Bases: Projection2D

Initialize a spherical projection.

A forward spherical projection takes a set of spherical coordinates, converting them from a celestial pole to a native pole, and usually returns offsets from a given reference wrt a native reference. The exact details will vary by projection model. A deprojection is the reverse operation, where a set of offsets is converted back to spherical coordinates.

Attributes Summary

celestial_pole	Return the celestial pole of the spherical projection.
full_circle
native_pole	Return the native pole of the spherical projection.
native_reference	Return the native reference position of the spherical projection.
pi
reference	Return the reference position of the spherical projection.
registry
right_angle

Methods Summary

acos(value)	Return the inverse cosine of a given value.
asin(value)	Return the inverse sine of a given value.
calculate_celestial_pole()	Calculate the celestial pole.
copy()	Return a copy of the spherical projection.
create_registry()	Create the lookup registry for spherical projections.
deproject(offsets[, coordinates])	Convert projection offsets to spherical coordinates.
edit_header(header[, alt])	Edit a FITS header with the projection information.
for_name(name)	Retrieve a projection instance for a given name.
get_coordinate_instance()	Return a coordinate instance relevant to the projection.
get_latitude_parameter_prefix()	Return the latitude parameter string prefix.
get_longitude_parameter_prefix()	Return the longitude parameter string prefix.
get_offsets(theta, phi[, offsets])	Get the offsets given theta and phi.
get_phi_theta(offset[, phi_theta])	Return the phi_theta coordinates.
get_reference()	Return the reference position.
is_right_angle_pole()	Return whether the pole is a right angle pole.
offset_to_xy_radians(offset)	Return the x, y coordinates of an offset as radian quantities.
parse_header(header[, alt])	Parse and apply a FITS header to the projection.
phi_theta_to_radians(phi, theta)	Convert phi and theta to radian quantities.
project(coordinates[, projected])	Convert coordinates into projection offsets.
register(projection)	Register a projection into the registry.
set_celestial_pole(celestial_pole)	Set the celestial pole of the spherical projection.
set_default_native_pole()	Set the native pole to the default value.
set_default_pole()	Set the default pole of the spherical projection.
set_native_pole(native_pole)	Set the native pole of the spherical projection.
set_native_pole_latitude(native_pole_latitude)	Set the native pole latitude for the spherical projection.
set_native_reference(reference)	Set the native reference for the spherical projection.
set_reference(value)	Set the reference position.

Attributes Documentation

celestial_pole

Return the celestial pole of the spherical projection.

Returns:

SphericalCoordinates

full_circle = <Quantity 360. deg>

native_pole

Return the native pole of the spherical projection.

Returns:

SphericalCoordinates

native_reference

Return the native reference position of the spherical projection.

Returns:

SphericalCoordinates

pi = <Quantity 3.14159265 rad>

reference

Return the reference position of the spherical projection.

Returns:

SphericalCoordinates

registry = None

right_angle = <Quantity 90. deg>

Methods Documentation

classmethod acos(value)

Return the inverse cosine of a given value.

This a wrapper around the np.arccos() function to convert values from units.Quantity to floats if applicable, and then bound all values between -1 <= x <= 1 before performing the inverse cosine operation. The result will always be return as a units.Quantity in radians.

Parameters:

valueunits.Quantity or float or numpy.ndarray

Returns:

angleunits.Quantity

The angle in radians.

classmethod asin(value)

Return the inverse sine of a given value.

This a wrapper around the np.arcsin() function to convert values from units.Quantity to floats if applicable, and then bound all values between -1 <= x <= 1 before performing the inverse sine operation. The result will always be return as a units.Quantity in radians.

Parameters:

valueunits.Quantity or float or numpy.ndarray

Returns:

angleunits.Quantity

The angle in radians.

calculate_celestial_pole()

Calculate the celestial pole.

Calculates the celestial pole based on the projection reference position coordinate. There are cases when either a northern or southern celestial pole may exist as solutions, and the select_solution attribute can be set to “northern” or “southern” to always return this pole. If select_solution is defined as something else, such as “nearest” (default), then the solution closest to the native pole will be set.

Returns:

None

copy()

Return a copy of the spherical projection.

Returns:

SphericalProjection

classmethod create_registry()

Create the lookup registry for spherical projections.

The SphericalProjection registry is a dictionary of the form {name: class} where “name” may be the FITS CTYPE projection designation (uppercase), the explicit name of the projection (lowercase), or the lowercase name of the class. For example, the Gnomonic projection class will be returned as a value for the keys “TAN”, “gnomonic”, or “gnomonicprojection”. Spaces may be used to specify a compound projection name. For example, “cylindrical equal area”.

Returns:

None

deproject(offsets, coordinates=None)

Convert projection offsets to spherical coordinates.

Reverse projection (deprojection) is the process of converting projection offsets to coordinates about a native pole, proceeded by a transformation to the celestial pole. The exact details on how native coordinates are derived vary by projection type.

Note, if no celestial pole has been defined, it will default to LON/LAT coordinates of (0, 0).

Parameters:

offsetsCoordinate2D

The projected offsets to deproject to coordinates.

coordinatesSphericalCoordinates, optional

The output deprojected coordinates. Will default to a fresh set of SphericalCoordinates if not provided.

Returns:

coordinatesSphericalCoordinates or Coordinates2D

The deprojected coordinates.

edit_header(header, alt='')

Edit a FITS header with the projection information.

Parameters:

headerfits.Header

The FITS header to edit.

altstr, optional

The alternate FITS system.

Returns:

None

classmethod for_name(name)

Retrieve a projection instance for a given name.

Parameters:

namestr

The name of the projection to retrieve.

Returns:

SphericalProjection

An initialized spherical projection of the requested type.

get_coordinate_instance()

Return a coordinate instance relevant to the projection.

Returns:

coordinatesSphericalCoordinates

get_latitude_parameter_prefix()

Return the latitude parameter string prefix.

Returns:

str

get_longitude_parameter_prefix()

Return the longitude parameter string prefix.

Returns:

str

abstract get_offsets(theta, phi, offsets=None)

Get the offsets given theta and phi.

Takes the theta (latitude) and phi (longitude) coordinates about the celestial pole and converts them to offsets from a reference position.

Parameters:

thetaunits.Quantity

The theta angle.

phiunits.Quantity

The phi angle.

offsetsCoordinate2D, optional

An optional coordinate system in which to place the results.

Returns:

offsetsCoordinate2D

abstract get_phi_theta(offset, phi_theta=None)

Return the phi_theta coordinates.

The phi and theta coordinates refer to the inverse projection (deprojection) of projected offsets about the native pole. phi is the deprojected longitude, and theta is the deprojected latitude of the offsets.

Parameters:

offsetCoordinate2D

phi_thetaSphericalCoordinates, optional

An optional output coordinate system in which to place the results.

Returns:

coordinatesSphericalCoordinates

get_reference()

Return the reference position.

Returns:

referenceSphericalCoordinates

is_right_angle_pole()

Return whether the pole is a right angle pole.

A right-angle pole is when the native latitude of the celestial pole is equal to 90 degrees.

Returns:

bool

classmethod offset_to_xy_radians(offset)

Return the x, y coordinates of an offset as radian quantities.

Parameters:

offsetCoordinate2D

Returns:

x, yunits.Quantity, units.Quantity

parse_header(header, alt='')

Parse and apply a FITS header to the projection.

Parameters:

headerfits.Header

The FITS header to parse.

altstr, optional

The alternate FITS system.

Returns:

None

classmethod phi_theta_to_radians(phi, theta)

Convert phi and theta to radian quantities.

Parameters:

phifloat or units.Quantity

The phi (longitude) parameter.

thetafloat or units.Quantity

the theta (latitude) parameter.

Returns:

phi, thetaunits.Quantity, units.Quantity

phi and theta as radian quantities.

project(coordinates, projected=None)

Convert coordinates into projection offsets.

Forward projection consists of first converting coordinates from their celestial pole to the native pole of the spherical projection. The resultant output from the projection are generally the offsets of these transformed coordinates from a given reference position, although the exact definition of an offset may depend on the type of projection.

Note that if no celestial pole has been defined, it will default to (0, 0) LON/LAT coordinates.

Parameters:

coordinatesSphericalCoordinates

The coordinates to project.

projectedCoordinate2D, optional

The output coordinates. Will be created if not supplied.

Returns:

offsetsCoordinate2D

The projected coordinate offsets using the native spherical pole from a native reference.

classmethod register(projection)

Register a projection into the registry.

Any given spherical projection will be registered using the uppercase FITS ID, the lowercase projection name, and the lowercase class name.

Parameters:

projectionSphericalProjection

A SphericalProjection subclass instance.

Returns:

None

set_celestial_pole(celestial_pole)

Set the celestial pole of the spherical projection.

Parameters:

celestial_poleSphericalCoordinates

Returns:

None

set_default_native_pole()

Set the native pole to the default value.

The default native pole longitude will be set to 0 degrees if the projection reference latitude is greater than or equal to the projection native reference latitude (0 by default). Otherwise, it will be set to 180 degrees. Any user native pole will be overwritten during this process.

Returns:

None

set_default_pole()

Set the default pole of the spherical projection.

Returns:

None

set_native_pole(native_pole)

Set the native pole of the spherical projection.

If set, the native pole will persist each time a new reference position is given. Otherwise, the native pole will default to either (0, 90) or (180, 90) LON/LAT degrees based on whether the reference latitude is >= or < the native reference latitude.

Parameters:

native_poleSphericalCoordinates

Returns:

None

set_native_pole_latitude(native_pole_latitude)

Set the native pole latitude for the spherical projection.

The native pole latitude will only be set if it is in the range -90 <= latitude <= 90 degrees. Otherwise, it will remain fixed, but the selected solution for calculating the celestial pole will change to “northern” if greater than zero, or “southern” if less than zero.

Parameters:

native_pole_latitudeunits.Quantity

Returns:

None

set_native_reference(reference)

Set the native reference for the spherical projection.

Parameters:

referenceSphericalCoordinates

Returns:

None

set_reference(value)

Set the reference position.

Setting a reference position will also result in calculation of a celestial pole for the projection. If a native pole has not been defined by the user, a default will be set at this point.

Parameters:

valueSphericalCoordinates

Returns:

None