Wcsprm¶

class
astropy.wcs.
Wcsprm
(header=None, key=' ', relax=False, naxis=2, keysel=0, colsel=None)¶ Bases:
object
Wcsprm
performs the core WCS transformations.Note
The members of this object correspond roughly to the key/value pairs in the FITS header. However, they are adjusted and normalized in a number of ways that make performing the WCS transformation easier. Therefore, they can not be relied upon to get the original values in the header. For that, use
astropy.io.fits.Header
directly.The FITS header parsing enforces correct FITS “keyword = value” syntax with regard to the equals sign occurring in columns 9 and 10. However, it does recognize freeformat character (NOST 1002.0, Sect. 5.2.1), integer (Sect. 5.2.3), and floatingpoint values (Sect. 5.2.4) for all keywords.
Parameters: header : An
astropy.io.fits.Header
, string, orNone
.If
None
, the object will be initialized to default values.key : str, optional
The key referring to a particular WCS transform in the header. This may be either
' '
or'A'
'Z'
and corresponds to the"a"
part of"CTYPEia"
. (key may only be provided if header is also provided.)relax : bool or int, optional
Degree of permissiveness:
False
: Recognize only FITS keywords defined by the published WCS standard.True
: Admit all recognized informal extensions of the WCS standard.int
: a bit field selecting specific extensions to accept. See Headerreading relaxation constants for details.
naxis : int, optional
The number of world coordinates axes for the object. (naxis may only be provided if header is
None
.)keysel : sequence of flag bits, optional
Vector of flag bits that may be used to restrict the keyword types considered:
WCSHDR_IMGHEAD
: Image header keywords.WCSHDR_BIMGARR
: Binary table image array.WCSHDR_PIXLIST
: Pixel list keywords.
If zero, there is no restriction. If 1, the underlying wcslib function
wcspih()
is called, rather thanwcstbh()
.colsel : sequence of int
A sequence of table column numbers used to restrict the keywords considered.
None
indicates no restriction.Raises: MemoryError
Memory allocation failed.
ValueError
Invalid key.
KeyError
Key not found in FITS header.
Attributes Summary
alt
str
Character code for alternate coordinate descriptions.axis_types
int array[naxis]
An array of fourdigit type codes for each axis.cd
double array[naxis][naxis]
TheCDi_ja
linear transformation matrix.cdelt
double array[naxis]
Coordinate increments (CDELTia
) for each coord axis.cel_offset
boolean
Is there an offset?cname
list of strings
A list of the coordinate axis names, fromCNAMEia
.colax
int array[naxis]
An array recording the column numbers for each axis in a pixel list.colnum
int
Column of FITS binary table associated with this WCS.crder
double array[naxis]
The random error in each coordinate axis,CRDERia
.crota
double array[naxis]
CROTAia
keyvalues for each coordinate axis.crpix
double array[naxis]
Coordinate reference pixels (CRPIXja
) for each pixel axis.crval
double array[naxis]
Coordinate reference values (CRVALia
) for each coordinate axis.csyer
double array[naxis]
The systematic error in the coordinate value axes,CSYERia
.ctype
list of strings[naxis]
List ofCTYPEia
keyvalues.cubeface
int
Index into thepixcrd
(pixel coordinate) array for theCUBEFACE
axis.cunit
list of astropy.UnitBase[naxis]
List ofCUNITia
keyvalues asastropy.units.UnitBase
instances.dateavg
string
Representative midpoint of the date of observation.dateobs
string
Start of the date of observation.equinox
double
The equinox associated with dynamical equatorial or ecliptic coordinate systems.imgpix_matrix
double array[2][2]
(readonly) Inverse of theCDELT
orPC
matrix.lat
int
(readonly) The index into the world coord array containing latitude values.latpole
double
The native latitude of the celestial pole,LATPOLEa
(deg).lattyp
string
(readonly) Celestial axis type for latitude.lng
int
(readonly) The index into the world coord array containing longitude values.lngtyp
string
(readonly) Celestial axis type for longitude.lonpole
double
The native longitude of the celestial pole.mjdavg
double
Modified Julian Date corresponding toDATEAVG
.mjdobs
double
Modified Julian Date corresponding toDATEOBS
.name
string
The name given to the coordinate representationWCSNAMEa
.naxis
int
(readonly) The number of axes (pixel and coordinate).obsgeo
double array[3]
Location of the observer in a standard terrestrial reference frame.pc
double array[naxis][naxis]
ThePCi_ja
(pixel coordinate) transformation matrix.phi0
double
The native latitude of the fiducial point.piximg_matrix
double array[2][2]
(readonly) Matrix containing the product of theCDELTia
diagonal matrix and thePCi_ja
matrix.radesys
string
The equatorial or ecliptic coordinate system type,RADESYSa
.restfrq
double
Rest frequency (Hz) fromRESTFRQa
.restwav
double
Rest wavelength (m) fromRESTWAVa
.spec
int
(readonly) The index containing the spectral axis values.specsys
string
Spectral reference frame (standard of rest),SPECSYSa
.ssysobs
string
Spectral reference frame.ssyssrc
string
Spectral reference frame for redshift.tab
list of Tabprm
Tabular coordinate objects.theta0
double
The native longitude of the fiducial point.velangl
double
Velocity angle.velosys
double
Relative radial velocity.velref
int
AIPS velocity code.zsource
double
The redshift,ZSOURCEa
, of the source.Methods Summary
bounds_check
(pix2world, world2pix)Enable/disable bounds checking. cdfix
()Fix erroneously omitted CDi_ja
keywords.celfix
Translates AIPSconvention celestial projection types, NCP
andGLS
.compare
(other[, cmp, tolerance])Compare two Wcsprm objects for equality. cylfix
()Fixes WCS keyvalues for malformed cylindrical projections. datfix
()Translates the old DATEOBS
date format to year2000 standard form(yyyymmddThh:mm:ss)
and derivesMJDOBS
from it if not already set.fix
([translate_units, naxis])Applies all of the corrections handled separately by datfix
,unitfix
,celfix
,spcfix
,cylfix
andcdfix
.get_cdelt
()Coordinate increments ( CDELTia
) for each coord axis.get_pc
()Returns the PC
matrix in readonly form.get_ps
()Returns PSi_ma
keywords for each i and m.get_pv
()Returns PVi_ma
keywords for each i and m.has_cd
()Returns True
ifCDi_ja
is present.has_cdi_ja
()Alias for has_cd
.has_crota
()Returns True
ifCROTAia
is present.has_crotaia
()Alias for has_crota
.has_pc
()Returns True
ifPCi_ja
is present.has_pci_ja
()Alias for has_pc
.is_unity
()Returns True
if the linear transformation matrix (cd
) is unity.mix
(mixpix, mixcel, vspan, vstep, viter, …)Given either the celestial longitude or latitude plus an element of the pixel coordinate, solves for the remaining elements by iterating on the unknown celestial coordinate element using s2p
.p2s
(pixcrd, origin)Converts pixel to world coordinates. print_contents
()Print the contents of the Wcsprm
object to stdout.s2p
(world, origin)Transforms world coordinates to pixel coordinates. set
()Sets up a WCS object for use according to information supplied within it. set_ps
(ps)Sets PSi_ma
keywords for each i and m.set_pv
(pv)Sets PVi_ma
keywords for each i and m.spcfix
()Translates AIPSconvention spectral coordinate types. sptr
(ctype[, i])Translates the spectral axis in a WCS object. sub
(axes)Extracts the coordinate description for a subimage from a WCS
object.to_header
([relax])to_header
translates a WCS object into a FITS header.unitfix
([translate_units])Translates nonstandard CUNITia
keyvalues.Attributes Documentation

alt
¶ str
Character code for alternate coordinate descriptions.For example, the
"a"
in keyword names such asCTYPEia
. This is a space character for the primary coordinate description, or one of the 26 uppercase letters, AZ.

axis_types
¶ int array[naxis]
An array of fourdigit type codes for each axis. First digit (i.e. 1000s):
 0: Nonspecific coordinate type.
 1: Stokes coordinate.
 2: Celestial coordinate (including
CUBEFACE
).  3: Spectral coordinate.
 Second digit (i.e. 100s):
 0: Linear axis.
 1: Quantized axis (
STOKES
,CUBEFACE
).  2: Nonlinear celestial axis.
 3: Nonlinear spectral axis.
 4: Logarithmic axis.
 5: Tabular axis.
 Third digit (i.e. 10s):
 0: Group number, e.g. lookup table number
 The fourth digit is used as a qualifier depending on the axis type.
 For celestial axes:
 0: Longitude coordinate.
 1: Latitude coordinate.
 2:
CUBEFACE
number.
 For lookup tables: the axis number in a multidimensional table.
 For celestial axes:
CTYPEia
in"43"
form with unrecognized algorithm code will have its type set to 1 and generate an error. First digit (i.e. 1000s):

cd
¶ double array[naxis][naxis]
TheCDi_ja
linear transformation matrix.For historical compatibility, three alternate specifications of the linear transformations are available in wcslib. The canonical
PCi_ja
withCDELTia
,CDi_ja
, and the deprecatedCROTAia
keywords. Although the latter may not formally coexist withPCi_ja
, the approach here is simply to ignore them if given in conjunction withPCi_ja
.has_pc
,has_cd
andhas_crota
can be used to determine which of these alternatives are present in the header.These alternate specifications of the linear transformation matrix are translated immediately to
PCi_ja
byset
and are nowhere visible to the lowerlevel routines. In particular,set
resetscdelt
to unity ifCDi_ja
is present (and noPCi_ja
). If noCROTAia
is associated with the latitude axis,set
reverts to a unityPCi_ja
matrix.

cdelt
¶ double array[naxis]
Coordinate increments (CDELTia
) for each coord axis.If a
CDi_ja
linear transformation matrix is present, a warning is raised andcdelt
is ignored. TheCDi_ja
matrix may be deleted by:del wcs.wcs.cd
An undefined value is represented by NaN.

cel_offset
¶ boolean
Is there an offset?If
True
, an offset will be applied to(x, y)
to force(x, y) = (0, 0)
at the fiducial point, (phi_0, theta_0). Default isFalse
.

cname
¶ list of strings
A list of the coordinate axis names, fromCNAMEia
.

colax
¶ int array[naxis]
An array recording the column numbers for each axis in a pixel list.

colnum
¶ int
Column of FITS binary table associated with this WCS.Where the coordinate representation is associated with an imagearray column in a FITS binary table, this property may be used to record the relevant column number.
It should be set to zero for an image header or pixel list.

crder
¶ double array[naxis]
The random error in each coordinate axis,CRDERia
.An undefined value is represented by NaN.

crota
¶ double array[naxis]
CROTAia
keyvalues for each coordinate axis.For historical compatibility, three alternate specifications of the linear transformations are available in wcslib. The canonical
PCi_ja
withCDELTia
,CDi_ja
, and the deprecatedCROTAia
keywords. Although the latter may not formally coexist withPCi_ja
, the approach here is simply to ignore them if given in conjunction withPCi_ja
.has_pc
,has_cd
andhas_crota
can be used to determine which of these alternatives are present in the header.These alternate specifications of the linear transformation matrix are translated immediately to
PCi_ja
byset
and are nowhere visible to the lowerlevel routines. In particular,set
resetscdelt
to unity ifCDi_ja
is present (and noPCi_ja
). If noCROTAia
is associated with the latitude axis,set
reverts to a unityPCi_ja
matrix.

crpix
¶ double array[naxis]
Coordinate reference pixels (CRPIXja
) for each pixel axis.

crval
¶ double array[naxis]
Coordinate reference values (CRVALia
) for each coordinate axis.

csyer
¶ double array[naxis]
The systematic error in the coordinate value axes,CSYERia
.An undefined value is represented by NaN.

ctype
¶ list of strings[naxis]
List ofCTYPEia
keyvalues.The
ctype
keyword values must be in upper case and there must be zero or one pair of matched celestial axis types, and zero or one spectral axis.

cubeface
¶ int
Index into thepixcrd
(pixel coordinate) array for theCUBEFACE
axis.This is used for quadcube projections where the cube faces are stored on a separate axis.
The quadcube projections (
TSC
,CSC
,QSC
) may be represented in FITS in either of two ways:The six faces may be laid out in one plane and numbered as follows:
0 4 3 2 1 4 3 2 5
Faces 2, 3 and 4 may appear on one side or the other (or both). The worldtopixel routines map faces 2, 3 and 4 to the left but the pixeltoworld routines accept them on either side.
The
COBE
convention in which the six faces are stored in a threedimensional structure using aCUBEFACE
axis indexed from 0 to 5 as above.
These routines support both methods;
set
determines which is being used by the presence or absence of aCUBEFACE
axis inctype
.p2s
ands2p
translate theCUBEFACE
axis representation to the single plane representation understood by the lowerlevel projection routines.

cunit
¶ list of astropy.UnitBase[naxis]
List ofCUNITia
keyvalues asastropy.units.UnitBase
instances.These define the units of measurement of the
CRVALia
,CDELTia
andCDi_ja
keywords.As
CUNITia
is an optional header keyword,cunit
may be left blank but otherwise is expected to contain a standard units specification as defined by WCS Paper I.unitfix
is available to translate commonly used nonstandard units specifications but this must be done as a separate step before invokingset
.For celestial axes, if
cunit
is not blank,set
useswcsunits
to parse it and scalecdelt
,crval
, andcd
to decimal degrees. It then resetscunit
to"deg"
.For spectral axes, if
cunit
is not blank,set
useswcsunits
to parse it and scalecdelt
,crval
, andcd
to SI units. It then resetscunit
accordingly.set
ignorescunit
for other coordinate types;cunit
may be used to label coordinate values.

dateavg
¶ string
Representative midpoint of the date of observation.In ISO format,
yyyymmddThh:mm:ss
.See also

dateobs
¶ string
Start of the date of observation.In ISO format,
yyyymmddThh:mm:ss
.See also

equinox
¶ double
The equinox associated with dynamical equatorial or ecliptic coordinate systems.EQUINOXa
(orEPOCH
in older headers). Not applicable to ICRS equatorial or ecliptic coordinates.An undefined value is represented by NaN.

imgpix_matrix
¶ double array[2][2]
(readonly) Inverse of theCDELT
orPC
matrix.Inverse containing the product of the
CDELTia
diagonal matrix and thePCi_ja
matrix.

lat
¶ int
(readonly) The index into the world coord array containing latitude values.

latpole
¶ double
The native latitude of the celestial pole,LATPOLEa
(deg).

lattyp
¶ string
(readonly) Celestial axis type for latitude.For example, “RA”, “DEC”, “GLON”, “GLAT”, etc. extracted from “RA–”, “DEC“, “GLON”, “GLAT”, etc. in the first four characters of
CTYPEia
but with trailing dashes removed.

lng
¶ int
(readonly) The index into the world coord array containing longitude values.

lngtyp
¶ string
(readonly) Celestial axis type for longitude.For example, “RA”, “DEC”, “GLON”, “GLAT”, etc. extracted from “RA–”, “DEC“, “GLON”, “GLAT”, etc. in the first four characters of
CTYPEia
but with trailing dashes removed.

lonpole
¶ double
The native longitude of the celestial pole.LONPOLEa
(deg).

mjdavg
¶ double
Modified Julian Date corresponding toDATEAVG
.(MJD = JD  2400000.5)
.An undefined value is represented by NaN.
See also

mjdobs
¶ double
Modified Julian Date corresponding toDATEOBS
.(MJD = JD  2400000.5)
.An undefined value is represented by NaN.
See also

name
¶ string
The name given to the coordinate representationWCSNAMEa
.

naxis
¶ int
(readonly) The number of axes (pixel and coordinate).Given by the
NAXIS
orWCSAXESa
keyvalues.The number of coordinate axes is determined at parsing time, and can not be subsequently changed.
It is determined from the highest of the following:
NAXIS
WCSAXESa
 The highest axis number in any parameterized WCS keyword. The keyvalue, as well as the keyword, must be syntactically valid otherwise it will not be considered.
If none of these keyword types is present, i.e. if the header only contains auxiliary WCS keywords for a particular coordinate representation, then no coordinate description is constructed for it.
This value may differ for different coordinate representations of the same image.

obsgeo
¶ double array[3]
Location of the observer in a standard terrestrial reference frame.OBSGEOX
,OBSGEOY
,OBSGEOZ
(in meters).An undefined value is represented by NaN.

pc
¶ double array[naxis][naxis]
ThePCi_ja
(pixel coordinate) transformation matrix.The order is:
[[PC1_1, PC1_2], [PC2_1, PC2_2]]
For historical compatibility, three alternate specifications of the linear transformations are available in wcslib. The canonical
PCi_ja
withCDELTia
,CDi_ja
, and the deprecatedCROTAia
keywords. Although the latter may not formally coexist withPCi_ja
, the approach here is simply to ignore them if given in conjunction withPCi_ja
.has_pc
,has_cd
andhas_crota
can be used to determine which of these alternatives are present in the header.These alternate specifications of the linear transformation matrix are translated immediately to
PCi_ja
byset
and are nowhere visible to the lowerlevel routines. In particular,set
resetscdelt
to unity ifCDi_ja
is present (and noPCi_ja
). If noCROTAia
is associated with the latitude axis,set
reverts to a unityPCi_ja
matrix.

phi0
¶ double
The native latitude of the fiducial point.The point whose celestial coordinates are given in
ref[1:2]
. If undefined (NaN) the initialization routine,set
, will set this to a projectionspecific default.See also

piximg_matrix
¶ double array[2][2]
(readonly) Matrix containing the product of theCDELTia
diagonal matrix and thePCi_ja
matrix.

radesys
¶ string
The equatorial or ecliptic coordinate system type,RADESYSa
.

restfrq
¶ double
Rest frequency (Hz) fromRESTFRQa
.An undefined value is represented by NaN.

restwav
¶ double
Rest wavelength (m) fromRESTWAVa
.An undefined value is represented by NaN.

spec
¶ int
(readonly) The index containing the spectral axis values.

specsys
¶ string
Spectral reference frame (standard of rest),SPECSYSa
.

ssysobs
¶ string
Spectral reference frame.The spectral reference frame in which there is no differential variation in the spectral coordinate across the fieldofview,
SSYSOBSa
.

ssyssrc
¶ string
Spectral reference frame for redshift.The spectral reference frame (standard of rest) in which the redshift was measured,
SSYSSRCa
.

tab
¶ list of Tabprm
Tabular coordinate objects.A list of tabular coordinate objects associated with this WCS.

theta0
¶ double
The native longitude of the fiducial point.The point whose celestial coordinates are given in
ref[1:2]
. If undefined (NaN) the initialization routine,set
, will set this to a projectionspecific default.See also

velangl
¶ double
Velocity angle.The angle in degrees that should be used to decompose an observed velocity into radial and transverse components.
An undefined value is represented by NaN.

velosys
¶ double
Relative radial velocity.The relative radial velocity (m/s) between the observer and the selected standard of rest in the direction of the celestial reference coordinate,
VELOSYSa
.An undefined value is represented by NaN.

velref
¶ int
AIPS velocity code.From
VELREF
keyword.

zsource
¶ double
The redshift,ZSOURCEa
, of the source.An undefined value is represented by NaN.
Methods Documentation

bounds_check
(pix2world, world2pix)¶ Enable/disable bounds checking.
Parameters: pix2world : bool, optional
world2pix : bool, optional
Notes
Note that by default (without calling
bounds_check
) strict bounds checking is enabled.

cdfix
()¶ Fix erroneously omitted
CDi_ja
keywords.Sets the diagonal element of the
CDi_ja
matrix to unity if allCDi_ja
keywords associated with a given axis were omitted. According to Paper I, if anyCDi_ja
keywords at all are given in a FITS header then those not given default to zero. This results in a singular matrix with an intersecting row and column of zeros.Returns: success : int
Returns
0
for success;1
if no change required.

celfix
()¶ Translates AIPSconvention celestial projection types,
NCP
andGLS
.Returns: success : int
Returns
0
for success;1
if no change required.

compare
(other, cmp=0, tolerance=0.0)¶ Compare two Wcsprm objects for equality.
Parameters: other : Wcsprm
The other Wcsprm object to compare to.
cmp : int, optional
A bit field controlling the strictness of the comparison. When 0, (the default), all fields must be identical.
The following constants may be or’ed together to loosen the comparison.
WCSCOMPARE_ANCILLARY
: Ignores ancillary keywords that don’t change the WCS transformation, such asDATEOBS
orEQUINOX
.WCSCOMPARE_TILING
: Ignore integral differences inCRPIXja
. This is the ‘tiling’ condition, where two WCSes cover different regions of the same map projection and align on the same map grid.WCSCOMPARE_CRPIX
: Ignore any differences at all inCRPIXja
. The two WCSes cover different regions of the same map projection but may not align on the same grid map. OverridesWCSCOMPARE_TILING
.
tolerance : float, optional
The amount of tolerance required. For example, for a value of 1e6, all floatingpoint values in the objects must be equal to the first 6 decimal places. The default value of 0.0 implies exact equality.
Returns: equal : bool

cylfix
()¶ Fixes WCS keyvalues for malformed cylindrical projections.
Returns: success : int
Returns
0
for success;1
if no change required.

datfix
()¶ Translates the old
DATEOBS
date format to year2000 standard form(yyyymmddThh:mm:ss)
and derivesMJDOBS
from it if not already set.Alternatively, if
mjdobs
is set anddateobs
isn’t, thendatfix
derivesdateobs
from it. If both are set but disagree by more than half a day thenValueError
is raised.Returns: success : int
Returns
0
for success;1
if no change required.

fix
(translate_units='', naxis=0)¶ Applies all of the corrections handled separately by
datfix
,unitfix
,celfix
,spcfix
,cylfix
andcdfix
.Parameters: translate_units : str, optional
Specify which potentially unsafe translations of nonstandard unit strings to perform. By default, performs all.
Although
"S"
is commonly used to represent seconds, its translation to"s"
is potentially unsafe since the standard recognizes"S"
formally as Siemens, however rarely that may be used. The same applies to"H"
for hours (Henry), and"D"
for days (Debye).This string controls what to do in such cases, and is caseinsensitive.
 If the string contains
"s"
, translate"S"
to"s"
.  If the string contains
"h"
, translate"H"
to"h"
.  If the string contains
"d"
, translate"D"
to"d"
.
Thus
''
doesn’t do any unsafe translations, whereas'shd'
does all of them.naxis : int array[naxis], optional
Image axis lengths. If this array is set to zero or
None
, thencylfix
will not be invoked.Returns: status : dict
 If the string contains

get_cdelt
() → double array[naxis]¶ Coordinate increments (
CDELTia
) for each coord axis.Returns the
CDELT
offsets in readonly form. Unlike thecdelt
property, this works even when the header specifies the linear transformation matrix in one of the alternativeCDi_ja
orCROTAia
forms. This is useful when you want access to the linear transformation matrix, but don’t care how it was specified in the header.

get_pc
() → double array[naxis][naxis]¶ Returns the
PC
matrix in readonly form. Unlike thepc
property, this works even when the header specifies the linear transformation matrix in one of the alternativeCDi_ja
orCROTAia
forms. This is useful when you want access to the linear transformation matrix, but don’t care how it was specified in the header.

get_ps
() → list of tuples¶ Returns
PSi_ma
keywords for each i and m.Returns: ps : list of tuples
Returned as a list of tuples of the form (i, m, value):
 i: int. Axis number, as in
PSi_ma
, (i.e. 1relative)  m: int. Parameter number, as in
PSi_ma
, (i.e. 0relative)  value: string. Parameter value.
See also
astropy.wcs.Wcsprm.set_ps
 Set
PSi_ma
values
 i: int. Axis number, as in

get_pv
() → list of tuples¶ Returns
PVi_ma
keywords for each i and m.Returns: Returned as a list of tuples of the form (i, m, value):
 i: int. Axis number, as in
PVi_ma
, (i.e. 1relative)  m: int. Parameter number, as in
PVi_ma
, (i.e. 0relative)  value: string. Parameter value.
See also
astropy.wcs.Wcsprm.set_pv
 Set
PVi_ma
values
Notes
Note that, if they were not given,
set
resets the entries forPVi_1a
,PVi_2a
,PVi_3a
, andPVi_4a
for longitude axis i to match (phi_0
,theta_0
), the native longitude and latitude of the reference point given byLONPOLEa
andLATPOLEa
. i: int. Axis number, as in

has_cd
() → bool¶ Returns
True
ifCDi_ja
is present.CDi_ja
is an alternate specification of the linear transformation matrix, maintained for historical compatibility.Matrix elements in the IRAF convention are equivalent to the product
CDi_ja = CDELTia * PCi_ja
, but the defaults differ from that of thePCi_ja
matrix. If one or moreCDi_ja
keywords are present then all unspecifiedCDi_ja
default to zero. If noCDi_ja
(orCROTAia
) keywords are present, then the header is assumed to be inPCi_ja
form whether or not anyPCi_ja
keywords are present since this results in an interpretation ofCDELTia
consistent with the original FITS specification.While
CDi_ja
may not formally coexist withPCi_ja
, it may coexist withCDELTia
andCROTAia
which are to be ignored.See also
astropy.wcs.Wcsprm.cd
 Get the raw
CDi_ja
values.

has_crota
() → bool¶ Returns
True
ifCROTAia
is present.CROTAia
is an alternate specification of the linear transformation matrix, maintained for historical compatibility.In the AIPS convention,
CROTAia
may only be associated with the latitude axis of a celestial axis pair. It specifies a rotation in the image plane that is applied after theCDELTia
; any otherCROTAia
keywords are ignored.CROTAia
may not formally coexist withPCi_ja
.CROTAia
andCDELTia
may formally coexist withCDi_ja
but if so are to be ignored.See also
astropy.wcs.Wcsprm.crota
 Get the raw
CROTAia
values

has_pc
() → bool¶ Returns
True
ifPCi_ja
is present.PCi_ja
is the recommended way to specify the linear transformation matrix.See also
astropy.wcs.Wcsprm.pc
 Get the raw
PCi_ja
values

mix
(mixpix, mixcel, vspan, vstep, viter, world, pixcrd, origin)¶ Given either the celestial longitude or latitude plus an element of the pixel coordinate, solves for the remaining elements by iterating on the unknown celestial coordinate element using
s2p
.Parameters: mixpix : int
Which element on the pixel coordinate is given.
mixcel : int
Which element of the celestial coordinate is given. If mixcel =
1
, celestial longitude is given inworld[self.lng]
, latitude returned inworld[self.lat]
. If mixcel =2
, celestial latitude is given inworld[self.lat]
, longitude returned inworld[self.lng]
.vspan : pair of floats
Solution interval for the celestial coordinate, in degrees. The ordering of the two limits is irrelevant. Longitude ranges may be specified with any convenient normalization, for example
(120,+120)
is the same as(240,480)
, except that the solution will be returned with the same normalization, i.e. lie within the interval specified.vstep : float
Step size for solution search, in degrees. If
0
, a sensible, although perhaps nonoptimal default will be used.viter : int
If a solution is not found then the step size will be halved and the search recommenced. viter controls how many times the step size is halved. The allowed range is 5  10.
world : double array[naxis]
World coordinate elements.
world[self.lng]
andworld[self.lat]
are the celestial longitude and latitude, in degrees. Which is given and which returned depends on the value of mixcel. All other elements are given. The results will be written to this array inplace.pixcrd : double array[naxis].
Pixel coordinates. The element indicated by mixpix is given and the remaining elements will be written inplace.
origin : int
Specifies the origin of pixel values. The Fortran and FITS standards use an origin of 1. Numpy and C use array indexing with origin at 0.
Returns: result : dict
Returns a dictionary with the following keys:
phi (double array[naxis])
theta (double array[naxis])
 Longitude and latitude in the native coordinate system of the projection, in degrees.
imgcrd (double array[naxis])
 Image coordinate elements.
imgcrd[self.lng]
andimgcrd[self.lat]
are the projected x and ycoordinates, in decimal degrees.
 Image coordinate elements.
world (double array[naxis])
 Another reference to the world argument passed in.
Raises: MemoryError
Memory allocation failed.
SingularMatrixError
Linear transformation matrix is singular.
InconsistentAxisTypesError
Inconsistent or unrecognized coordinate axis types.
ValueError
Invalid parameter value.
InvalidTransformError
Invalid coordinate transformation parameters.
InvalidTransformError
Illconditioned coordinate transformation parameters.
InvalidCoordinateError
Invalid world coordinate.
NoSolutionError
No solution found in the specified interval.
See also
Notes
Initially, the specified solution interval is checked to see if it’s a “crossing” interval. If it isn’t, a search is made for a crossing solution by iterating on the unknown celestial coordinate starting at the upper limit of the solution interval and decrementing by the specified step size. A crossing is indicated if the trial value of the pixel coordinate steps through the value specified. If a crossing interval is found then the solution is determined by a modified form of “regula falsi” division of the crossing interval. If no crossing interval was found within the specified solution interval then a search is made for a “noncrossing” solution as may arise from a point of tangency. The process is complicated by having to make allowance for the discontinuities that occur in all map projections.
Once one solution has been determined others may be found by subsequent invocations of
mix
with suitably restricted solution intervals.Note the circumstance that arises when the solution point lies at a native pole of a projection in which the pole is represented as a finite curve, for example the zenithals and conics. In such cases two or more valid solutions may exist but
mix
only ever returns one.Because of its generality,
mix
is very computeintensive. For computelimited applications, more efficient specialcase solvers could be written for simple projections, for example nonoblique cylindrical projections.

p2s
(pixcrd, origin)¶ Converts pixel to world coordinates.
Parameters: pixcrd : double array[ncoord][nelem]
Array of pixel coordinates.
origin : int
Specifies the origin of pixel values. The Fortran and FITS standards use an origin of 1. Numpy and C use array indexing with origin at 0.
Returns: result : dict
Returns a dictionary with the following keys:
 imgcrd: double array[ncoord][nelem]
 Array of intermediate world coordinates. For celestial axes,
imgcrd[][self.lng]
andimgcrd[][self.lat]
are the projected x, and ycoordinates, in pseudo degrees. For spectral axes,imgcrd[][self.spec]
is the intermediate spectral coordinate, in SI units.
 Array of intermediate world coordinates. For celestial axes,
 phi: double array[ncoord]
 theta: double array[ncoord]
 Longitude and latitude in the native coordinate system of the projection, in degrees.
 world: double array[ncoord][nelem]
 Array of world coordinates. For celestial axes,
world[][self.lng]
andworld[][self.lat]
are the celestial longitude and latitude, in degrees. For spectral axes,world[][self.spec]
is the intermediate spectral coordinate, in SI units.
 Array of world coordinates. For celestial axes,
 stat: int array[ncoord]
 Status return value for each coordinate.
0
for success,1+
for invalid pixel coordinate.
 Status return value for each coordinate.
Raises: MemoryError
Memory allocation failed.
SingularMatrixError
Linear transformation matrix is singular.
InconsistentAxisTypesError
Inconsistent or unrecognized coordinate axis types.
ValueError
Invalid parameter value.
ValueError
x and ycoordinate arrays are not the same size.
InvalidTransformError
Invalid coordinate transformation parameters.
InvalidTransformError
Illconditioned coordinate transformation parameters.
See also
 imgcrd: double array[ncoord][nelem]

print_contents
()¶ Print the contents of the
Wcsprm
object to stdout. Probably only useful for debugging purposes, and may be removed in the future.To get a string of the contents, use
repr
.

s2p
(world, origin)¶ Transforms world coordinates to pixel coordinates.
Parameters: world : double array[ncoord][nelem]
Array of world coordinates, in decimal degrees.
origin : int
Specifies the origin of pixel values. The Fortran and FITS standards use an origin of 1. Numpy and C use array indexing with origin at 0.
Returns: result : dict
Returns a dictionary with the following keys:
phi: double array[ncoord]
theta: double array[ncoord]
 Longitude and latitude in the native coordinate system of the projection, in degrees.
imgcrd: double array[ncoord][nelem]
 Array of intermediate world coordinates. For celestial axes,
imgcrd[][self.lng]
andimgcrd[][self.lat]
are the projected x, and ycoordinates, in pseudo “degrees”. For quadcube projections with aCUBEFACE
axis, the face number is also returned inimgcrd[][self.cubeface]
. For spectral axes,imgcrd[][self.spec]
is the intermediate spectral coordinate, in SI units.
 Array of intermediate world coordinates. For celestial axes,
pixcrd: double array[ncoord][nelem]
 Array of pixel coordinates. Pixel coordinates are zerobased.
stat: int array[ncoord]
 Status return value for each coordinate.
0
for success,1+
for invalid pixel coordinate.
 Status return value for each coordinate.
Raises: MemoryError
Memory allocation failed.
SingularMatrixError
Linear transformation matrix is singular.
InconsistentAxisTypesError
Inconsistent or unrecognized coordinate axis types.
ValueError
Invalid parameter value.
InvalidTransformError
Invalid coordinate transformation parameters.
InvalidTransformError
Illconditioned coordinate transformation parameters.
See also

set
()¶ Sets up a WCS object for use according to information supplied within it.
Note that this routine need not be called directly; it will be invoked by
p2s
ands2p
if necessary.Some attributes that are based on other attributes (such as
lattyp
onctype
) may not be correct until afterset
is called.set
strips off trailing blanks in all string members.set
recognizes theNCP
projection and converts it to the equivalentSIN
projection and it also recognizesGLS
as a synonym forSFL
. It does alias translation for the AIPS spectral types (FREQLSR
,FELOHEL
, etc.) but without changing the input header keywords.Raises: MemoryError
Memory allocation failed.
SingularMatrixError
Linear transformation matrix is singular.
InconsistentAxisTypesError
Inconsistent or unrecognized coordinate axis types.
ValueError
Invalid parameter value.
InvalidTransformError
Invalid coordinate transformation parameters.
InvalidTransformError
Illconditioned coordinate transformation parameters.

set_ps
(ps)¶ Sets
PSi_ma
keywords for each i and m.Parameters: ps : sequence of tuples
The input must be a sequence of tuples of the form (i, m, value):
 i: int. Axis number, as in
PSi_ma
, (i.e. 1relative)  m: int. Parameter number, as in
PSi_ma
, (i.e. 0relative)  value: string. Parameter value.
See also
 i: int. Axis number, as in

set_pv
(pv)¶ Sets
PVi_ma
keywords for each i and m.Parameters: pv : list of tuples
The input must be a sequence of tuples of the form (i, m, value):
 i: int. Axis number, as in
PVi_ma
, (i.e. 1relative)  m: int. Parameter number, as in
PVi_ma
, (i.e. 0relative)  value: float. Parameter value.
See also
 i: int. Axis number, as in

spcfix
() → int¶ Translates AIPSconvention spectral coordinate types. {
FREQ
,VELO
,FELO
}{OBS
,HEL
,LSR
} (e.g.FREQLSR
,VELOOBS
,FELOHEL
)Returns: success : int
Returns
0
for success;1
if no change required.

sptr
(ctype, i=1)¶ Translates the spectral axis in a WCS object.
For example, a
FREQ
axis may be translated intoZOPTF2W
and vice versa.Parameters: ctype : str
Required spectral
CTYPEia
, maximum of 8 characters. The first four characters are required to be given and are never modified. The remaining four, the algorithm code, are completely determined by, and must be consistent with, the first four characters. Wildcarding may be used, i.e. if the final three characters are specified as"???"
, or if just the eighth character is specified as"?"
, the correct algorithm code will be substituted and returned.i : int
Index of the spectral axis (0relative). If
i < 0
(or not provided), it will be set to the first spectral axis identified from theCTYPE
keyvalues in the FITS header.Raises: MemoryError
Memory allocation failed.
SingularMatrixError
Linear transformation matrix is singular.
InconsistentAxisTypesError
Inconsistent or unrecognized coordinate axis types.
ValueError
Invalid parameter value.
InvalidTransformError
Invalid coordinate transformation parameters.
InvalidTransformError
Illconditioned coordinate transformation parameters.
InvalidSubimageSpecificationError
Invalid subimage specification (no spectral axis).

sub
(axes)¶ Extracts the coordinate description for a subimage from a
WCS
object.The world coordinate system of the subimage must be separable in the sense that the world coordinates at any point in the subimage must depend only on the pixel coordinates of the axes extracted. In practice, this means that the
PCi_ja
matrix of the original image must not contain nonzero offdiagonal terms that associate any of the subimage axes with any of the nonsubimage axes.sub
can also add axes to a wcsprm object. The new axes will be created using the defaults set by the Wcsprm constructor which produce a simple, unnamed, linear axis with world coordinates equal to the pixel coordinate. These default values can be changed before invokingset
.Parameters: axes : int or a sequence.
 If an int, include the first N axes in their original order.
 If a sequence, may contain a combination of image axis numbers
(1relative) or special axis identifiers (see below). Order is
significant;
axes[0]
is the axis number of the input image that corresponds to the first axis in the subimage, etc. Use an axis number of 0 to create a new axis using the defaults.  If
0
,[]
orNone
, do a deep copy.
Coordinate axes types may be specified using either strings or special integer constants. The available types are:
'longitude'
/WCSSUB_LONGITUDE
: Celestial longitude'latitude'
/WCSSUB_LATITUDE
: Celestial latitude'cubeface'
/WCSSUB_CUBEFACE
: QuadcubeCUBEFACE
axis'spectral'
/WCSSUB_SPECTRAL
: Spectral axis'stokes'
/WCSSUB_STOKES
: Stokes axis'celestial'
/WCSSUB_CELESTIAL
: An alias for the combination of'longitude'
,'latitude'
and'cubeface'
.
Returns: new_wcs :
WCS
objectRaises: MemoryError
Memory allocation failed.
InvalidSubimageSpecificationError
Invalid subimage specification (no spectral axis).
NonseparableSubimageCoordinateSystem
Nonseparable subimage coordinate system.
Notes
Combinations of subimage axes of particular types may be extracted in the same order as they occur in the input image by combining the integer constants with the ‘binary or’ (

) operator. For example:wcs.sub([WCSSUB_LONGITUDE  WCSSUB_LATITUDE  WCSSUB_SPECTRAL])
would extract the longitude, latitude, and spectral axes in the same order as the input image. If one of each were present, the resulting object would have three dimensions.
For convenience,
WCSSUB_CELESTIAL
is defined as the combinationWCSSUB_LONGITUDE  WCSSUB_LATITUDE  WCSSUB_CUBEFACE
.The codes may also be negated to extract all but the types specified, for example:
wcs.sub([ WCSSUB_LONGITUDE, WCSSUB_LATITUDE, WCSSUB_CUBEFACE, (WCSSUB_SPECTRAL  WCSSUB_STOKES)])
The last of these specifies all axis types other than spectral or Stokes. Extraction is done in the order specified by
axes
, i.e. a longitude axis (if present) would be extracted first (viaaxes[0]
) and not subsequently (viaaxes[3]
). Likewise for the latitude and cubeface axes in this example.The number of dimensions in the returned object may be less than or greater than the length of
axes
. However, it will never exceed the number of axes in the input image.

to_header
(relax=False)¶ to_header
translates a WCS object into a FITS header.The details of the header depends on context:
The output header will almost certainly differ from the input in a number of respects:
 The output header only contains WCSrelated keywords. In
particular, it does not contain syntacticallyrequired keywords
such as
SIMPLE
,NAXIS
,BITPIX
, orEND
.  Deprecated (e.g.
CROTAn
) or nonstandard usage will be translated to standard (this is partially dependent on whetherfix
was applied).  Quantities will be converted to the units used internally, basically SI with the addition of degrees.
 Floatingpoint quantities may be given to a different decimal precision.
 Elements of the
PCi_j
matrix will be written if and only if they differ from the unit matrix. Thus, if the matrix is unity then no elements will be written.  Additional keywords such as
WCSAXES
,CUNITia
,LONPOLEa
andLATPOLEa
may appear.  The original keycomments will be lost, although
to_header
tries hard to write meaningful comments.  Keyword order may be changed.
Keywords can be translated between the image array, binary table, and pixel lists forms by manipulating the
colnum
orcolax
members of theWCS
object.Parameters: relax : bool or int
Degree of permissiveness:
False
: Recognize only FITS keywords defined by the published WCS standard.True
: Admit all recognized informal extensions of the WCS standard.int
: a bit field selecting specific extensions to write. See Headerwriting relaxation constants for details.
Returns: header : str
Raw FITS header as a string.
 The output header only contains WCSrelated keywords. In
particular, it does not contain syntacticallyrequired keywords
such as

unitfix
(translate_units='')¶ Translates nonstandard
CUNITia
keyvalues.For example,
DEG
>deg
, also stripping off unnecessary whitespace.Parameters: translate_units : str, optional
Do potentially unsafe translations of nonstandard unit strings.
Although
"S"
is commonly used to represent seconds, its recognizes"S"
formally as Siemens, however rarely that may be translation to"s"
is potentially unsafe since the standard used. The same applies to"H"
for hours (Henry), and"D"
for days (Debye).This string controls what to do in such cases, and is caseinsensitive.
 If the string contains
"s"
, translate"S"
to"s"
.  If the string contains
"h"
, translate"H"
to"h"
.  If the string contains
"d"
, translate"D"
to"d"
.
Thus
''
doesn’t do any unsafe translations, whereas'shd'
does all of them.Returns: success : int
Returns
0
for success;1
if no change required. If the string contains