Prjprm

class astropy.wcs.Prjprm

Bases: object

Class that contains information needed to project or deproject native spherical coordinates. It consists of certain members that must be set by the user (given) and others that are set by the WCSLIB routines (returned). Some of the latter are supplied for informational purposes and others are for internal use only.

Attributes Summary

bounds

Controls bounds checking.

category

Read-only. Projection category matching the value of the relevant wcs module constants:

code

Three-letter projection code defined by the FITS standard.

conformal

Read-only. True if the projection is conformal.

divergent

Read-only. True if the projection diverges in latitude.

equiareal

Read-only. True if the projection is equal area.

global_projection

Read-only. True if the projection can represent the whole sphere in a finite, non-overlapped mapping.

m

Read-only. Intermediate integer value (used only for the ZPN and HPX projections).

n

Read-only. Intermediate integer value (used only for the ZPN and HPX projections).

name

Read-only. Long name of the projection.

phi0

The native longitude, \(\phi_0\) (in degrees) of the reference point, i.e. the point (x,y) = (0,0).

pv

Projection parameters.

pvrange

Read-only. Range of projection parameter indices: 100 times the first allowed index plus the number of parameters, e.g.

r0

The radius of the generating sphere for the projection, a linear scaling parameter.

simplezen

Read-only. True if the projection is a radially-symmetric zenithal projection.

theta0

the native latitude, \(\theta_0\) (in degrees) of the reference point, i.e. the point (x,y) = (0,0).

w

Read-only. Intermediate floating-point values derived from the projection parameters, cached here to save recomputation.

x0

Read-only. The offset in x used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

y0

Read-only. The offset in y used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

Methods Summary

get_pvi

Set/Get projection parameters for specific index.

prjs2x

Project native spherical coordinates \((\phi,\theta)\) to Cartesian (x,y) coordinates in the plane of projection.

prjx2s

Deproject Cartesian (x,y) coordinates in the plane of projection to native spherical coordinates \((\phi,\theta)\).

set

This method sets up a Prjprm object according to information supplied within it.

set_pvi

Set/Get projection parameters for specific index.

Attributes Documentation

bounds

Controls bounds checking. If bounds&1 then enable strict bounds checking for the spherical-to-Cartesian (s2x) transformation for the AZP, SZP, TAN, SIN, ZPN, and COP projections. If bounds&2 then enable strict bounds checking for the Cartesian-to-spherical transformation (x2s) for the HPX and XPH projections. If bounds&4 then the Cartesian- to-spherical transformations (x2s) will invoke WCSLIB’s prjbchk() to perform bounds checking on the computed native coordinates, with a tolerance set to suit each projection. bounds is set to 7 during initialization by default which enables all checks. Zero it to disable all checking.

It is not necessary to reset the Prjprm struct (via Prjprm.set()) when bounds is changed.

category

Read-only. Projection category matching the value of the relevant wcs module constants:

PRJ_ZENITHAL, PRJ_CYLINDRICAL, PRJ_PSEUDOCYLINDRICAL, PRJ_CONVENTIONAL, PRJ_CONIC, PRJ_POLYCONIC, PRJ_QUADCUBE, and PRJ_HEALPIX.

code

Three-letter projection code defined by the FITS standard.

conformal

Read-only. True if the projection is conformal.

divergent

Read-only. True if the projection diverges in latitude.

equiareal

Read-only. True if the projection is equal area.

global_projection

Read-only. True if the projection can represent the whole sphere in a finite, non-overlapped mapping.

m

Read-only. Intermediate integer value (used only for the ZPN and HPX projections).

n

Read-only. Intermediate integer value (used only for the ZPN and HPX projections).

name

Read-only. Long name of the projection.

phi0

The native longitude, \(\phi_0\) (in degrees) of the reference point, i.e. the point (x,y) = (0,0). If undefined the initialization routine will set this to a projection-specific default.

pv

Projection parameters. These correspond to the PVi_ma keywords in FITS, so pv[0] is PVi_0a, pv[1] is PVi_1a, etc., where i denotes the latitude-like axis. Many projections use pv[1] (PVi_1a), some also use pv[2] (PVi_2a) and SZP uses pv[3] (PVi_3a). ZPN is currently the only projection that uses any of the others.

When setting pv values using lists or numpy.ndarray, elements set to None will be left unchanged while those set to numpy.nan will be set to WCSLIB’s UNDEFINED special value. For efficiency purposes, if supplied list or numpy.ndarray is shorter than the length of the pv member, then remaining values in pv will be left unchanged.

Note

When retrieving pv, a copy of the prjprm.pv array is returned. Modifying this array values will not modify underlying WCSLIB’s prjprm.pv data.

pvrange

Read-only. Range of projection parameter indices: 100 times the first allowed index plus the number of parameters, e.g. TAN is 0 (no parameters), SZP is 103 (1 to 3), and ZPN is 30 (0 to 29).

r0

The radius of the generating sphere for the projection, a linear scaling parameter. If this is zero, it will be reset to its default value of \(180^\circ/\pi\) (the value for FITS WCS).

simplezen

Read-only. True if the projection is a radially-symmetric zenithal projection.

theta0

the native latitude, \(\theta_0\) (in degrees) of the reference point, i.e. the point (x,y) = (0,0). If undefined the initialization routine will set this to a projection-specific default.

w

Read-only. Intermediate floating-point values derived from the projection parameters, cached here to save recomputation.

Note

When retrieving w, a copy of the prjprm.w array is returned. Modifying this array values will not modify underlying WCSLIB’s prjprm.w data.

x0

Read-only. The offset in x used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

y0

Read-only. The offset in y used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

Methods Documentation

get_pvi()

Set/Get projection parameters for specific index. These correspond to the PVi_ma keywords in FITS, so pv[0] is PVi_0a, pv[1] is PVi_1a, etc., where i denotes the latitude-like axis. Many projections use pv[1] (PVi_1a), some also use pv[2] (PVi_2a) and SZP uses pv[3] (PVi_3a). ZPN is currently the only projection that uses any of the others.

Setting a pvi value to None will reset the corresponding WCSLIB’s prjprm.pv element to the default value as set by WCSLIB’s prjini().

Setting a pvi value to numpy.nan will set the corresponding WCSLIB’s prjprm.pv element to WCSLIB’s UNDEFINED special value.

prjs2x()

Project native spherical coordinates \((\phi,\theta)\) to Cartesian (x,y) coordinates in the plane of projection.

The projection is that specified by Prjprm.code.

Parameters:
phinumpy.ndarray

Array corresponding to the longitude \(\phi\) of the projected point in native spherical coordinates (in degrees).

thetanumpy.ndarray

Array corresponding to the longitude \(\theta\) of the projected point in native spherical coordinatess (in degrees). Values corresponding to invalid \((\phi, \theta)\) coordinates are set to numpy.nan.

Returns:
x, ypython:tuple of numpy.ndarray

Projected coordinates.

Raises:
MemoryError

Null prjprm pointer passed to WCSLIB routines.

InvalidPrjParametersError

Invalid projection parameters.

prjx2s()

Deproject Cartesian (x,y) coordinates in the plane of projection to native spherical coordinates \((\phi,\theta)\).

The projection is that specified by Prjprm.code.

Parameters:
x, ynumpy.ndarray

Arrays corresponding to the first (x) and second (y) projected coordinates.

Returns:
phi, thetapython:tuple of numpy.ndarray

Longitude and latitude \((\phi,\theta)\) of the projected point in native spherical coordinates (in degrees). Values corresponding to invalid (x,y) coordinates are set to numpy.nan.

Raises:
MemoryError

Null prjprm pointer passed to WCSLIB routines.

InvalidPrjParametersError

Invalid projection parameters.

set()

This method sets up a Prjprm object according to information supplied within it.

Note that this routine need not be called directly; it will be invoked by prjx2s and prjs2x if Prjprm.flag is anything other than a predefined magic value.

The one important property of set() is that the projection code must be defined in the Prjprm in order for set() to identify the required projection.

Raises:
MemoryError

Null prjprm pointer passed to WCSLIB routines.

InvalidPrjParametersError

Invalid projection parameters.

InvalidCoordinateError

One or more of the (x,y) or (lon,lat) coordinates were invalid.

set_pvi()

Set/Get projection parameters for specific index. These correspond to the PVi_ma keywords in FITS, so pv[0] is PVi_0a, pv[1] is PVi_1a, etc., where i denotes the latitude-like axis. Many projections use pv[1] (PVi_1a), some also use pv[2] (PVi_2a) and SZP uses pv[3] (PVi_3a). ZPN is currently the only projection that uses any of the others.

Setting a pvi value to None will reset the corresponding WCSLIB’s prjprm.pv element to the default value as set by WCSLIB’s prjini().

Setting a pvi value to numpy.nan will set the corresponding WCSLIB’s prjprm.pv element to WCSLIB’s UNDEFINED special value.