The relax keyword argument controls the handling of non-standard FITS WCS keywords.

Note that the default value of relax is True for reading (to accept all non standard keywords), and False for writing (to write out only standard keywords), in accordance with Postel’s prescription:

“Be liberal in what you accept, and conservative in what you send.”

Header-reading relaxation constants¶

WCS, Wcsprm and find_all_wcs have a relax argument, which may be either True, False or an int.

If True, (default), all non-standard WCS extensions recognized by the parser will be handled.
If False, none of the extensions (even those in the errata) will be handled. Non-conformant keywords will be handled in the same way as non-WCS keywords in the header, i.e. by simply ignoring them.
If an int, is is a bit field to provide fine-grained control over what non-standard WCS keywords to accept. The flag bits are subject to change in future and should be set by using the constants beginning with WCSHDR_ in the astropy.wcs module.

For example, to accept CD00i00j and PC00i00j use:
```
relax = astropy.wcs.WCSHDR_CD00i00j | astropy.wcs.WCSHDR_PC00i00j
```
The parser always treats EPOCH as subordinate to EQUINOXa if both are present, and VSOURCEa is always subordinate to ZSOURCEa.

Likewise, VELREF is subordinate to the formalism of WCS Paper III.

The flag bits are:

WCSHDR_none: Don’t accept any extensions (not even those in the errata). Treat non-conformant keywords in the same way as non-WCS keywords in the header, i.e. simply ignore them. (This is equivalent to passing False)
WCSHDR_all: Accept all extensions recognized by the parser. (This is equivalent to the default behavior or passing True).
WCSHDR_reject: Reject non-standard keyrecords (that are not otherwise explicitly accepted by one of the flags below). A warning will be displayed by default.

This flag may be used to signal the presence of non-standard keywords, otherwise they are simply passed over as though they did not exist in the header. It is mainly intended for testing conformance of a FITS header to the WCS standard.

Keyrecords may be non-standard in several ways:
- The keyword may be syntactically valid but with keyvalue of incorrect type or invalid syntax, or the keycomment may be malformed.
- The keyword may strongly resemble a WCS keyword but not, in fact, be one because it does not conform to the standard. For example, CRPIX01 looks like a CRPIXja keyword, but in fact the leading zero on the axis number violates the basic FITS standard. Likewise, LONPOLE2 is not a valid LONPOLEa keyword in the WCS standard, and indeed there is nothing the parser can sensibly do with it.
- Use of the keyword may be deprecated by the standard. Such will be rejected if not explicitly accepted via one of the flags below.
WCSHDR_CROTAia: Accept CROTAia, iCROTna, TCROTna
WCSHDR_EPOCHa: Accept EPOCHa.
WCSHDR_VELREFa: Accept VELREFa.

The constructor always recognizes the AIPS-convention keywords, CROTAn, EPOCH, and VELREF for the primary representation (a = ' ') but alternates are non-standard.

The constructor accepts EPOCHa and VELREFa only if WCSHDR_AUXIMG is also enabled.
WCSHDR_CD00i00j: Accept CD00i00j.
WCSHDR_PC00i00j: Accept PC00i00j.
WCSHDR_PROJPn: Accept PROJPn.

These appeared in early drafts of WCS Paper I+II (before they were split) and are equivalent to CDi_ja, PCi_ja, and PVi_ma for the primary representation (a = ' '). PROJPn is equivalent to PVi_ma with m = n <= 9, and is associated exclusively with the latitude axis.
WCSHDR_CD0i_0ja: Accept CD0i_0ja (wcspih()).
WCSHDR_PC0i_0ja: Accept PC0i_0ja (wcspih()).
WCSHDR_PV0i_0ma: Accept PV0i_0ja (wcspih()).
WCSHDR_PS0i_0ma: Accept PS0i_0ja (wcspih()).

Allow the numerical index to have a leading zero in doubly- parameterized keywords, for example, PC01_01. WCS Paper I (Sects 2.1.2 & 2.1.4) explicitly disallows leading zeroes. The FITS 3.0 standard document (Sect. 4.1.2.1) states that the index in singly-parameterized keywords (e.g. CTYPEia) “shall not have leading zeroes”, and later in Sect. 8.1 that “leading zeroes must not be used” on PVi_ma and PSi_ma. However, by an oversight, it is silent on PCi_ja and CDi_ja.

Only available if built with wcslib 5.0 or later.
WCSHDR_RADECSYS: Accept RADECSYS. This appeared in early drafts of WCS Paper I+II and was subsequently replaced by RADESYSa. The constructor accepts RADECSYS only if WCSHDR_AUXIMG is also enabled.
WCSHDR_VSOURCE: Accept VSOURCEa or VSOUna. This appeared in early drafts of WCS Paper III and was subsequently dropped in favor of ZSOURCEa and ZSOUna. The constructor accepts VSOURCEa only if WCSHDR_AUXIMG is also enabled.
WCSHDR_DOBSn: Allow DOBSn, the column-specific analogue of DATE-OBS. By an oversight this was never formally defined in the standard.
WCSHDR_LONGKEY: Accept long forms of the alternate binary table and pixel list WCS keywords, i.e. with “a” non- blank. Specifically:
```
jCRPXna  TCRPXna  :  jCRPXn  jCRPna  TCRPXn  TCRPna  CRPIXja
   -     TPCn_ka  :    -     ijPCna    -     TPn_ka  PCi_ja
   -     TCDn_ka  :    -     ijCDna    -     TCn_ka  CDi_ja
iCDLTna  TCDLTna  :  iCDLTn  iCDEna  TCDLTn  TCDEna  CDELTia
iCUNIna  TCUNIna  :  iCUNIn  iCUNna  TCUNIn  TCUNna  CUNITia
iCTYPna  TCTYPna  :  iCTYPn  iCTYna  TCTYPn  TCTYna  CTYPEia
iCRVLna  TCRVLna  :  iCRVLn  iCRVna  TCRVLn  TCRVna  CRVALia
iPVn_ma  TPVn_ma  :    -     iVn_ma    -     TVn_ma  PVi_ma
iPSn_ma  TPSn_ma  :    -     iSn_ma    -     TSn_ma  PSi_ma
```
where the primary and standard alternate forms together with the image-header equivalent are shown rightwards of the colon.

The long form of these keywords could be described as quasi- standard. TPCn_ka, iPVn_ma, and TPVn_ma appeared by mistake in the examples in WCS Paper II and subsequently these and also TCDn_ka, iPSn_ma and TPSn_ma were legitimized by the errata to the WCS papers.

Strictly speaking, the other long forms are non-standard and in fact have never appeared in any draft of the WCS papers nor in the errata. However, as natural extensions of the primary form they are unlikely to be written with any other intention. Thus it should be safe to accept them provided, of course, that the resulting keyword does not exceed the 8-character limit.

If WCSHDR_CNAMn is enabled then also accept:
```
iCNAMna  TCNAMna  :   ---   iCNAna    ---   TCNAna  CNAMEia
iCRDEna  TCRDEna  :   ---   iCRDna    ---   TCRDna  CRDERia
iCSYEna  TCSYEna  :   ---   iCSYna    ---   TCSYna  CSYERia
```
Note that CNAMEia, CRDERia, CSYERia, and their variants are not used by astropy.wcs but are stored as auxiliary information.
WCSHDR_CNAMn: Accept iCNAMn, iCRDEn, iCSYEn, TCNAMn, TCRDEn, and TCSYEn, i.e. with a blank. While non-standard, these are the analogues of iCTYPn, TCTYPn, etc.
WCSHDR_AUXIMG: Allow the image-header form of an auxiliary WCS keyword with representation-wide scope to provide a default value for all images. This default may be overridden by the column-specific form of the keyword.

For example, a keyword like EQUINOXa would apply to all image arrays in a binary table, or all pixel list columns with alternate representation a unless overridden by EQUIna.

Specifically the keywords are:
```
LATPOLEa  for LATPna
LONPOLEa  for LONPna
RESTFREQ  for RFRQna
RESTFRQa  for RFRQna
RESTWAVa  for RWAVna
```
whose keyvalues are actually used by WCSLIB, and also keywords that provide auxiliary information that is simply stored in the wcsprm struct:
```
EPOCH         -       ... (No column-specific form.)
EPOCHa        -       ... Only if WCSHDR_EPOCHa is set.
EQUINOXa  for EQUIna
RADESYSa  for RADEna
RADECSYS  for RADEna  ... Only if WCSHDR_RADECSYS is set.
SPECSYSa  for SPECna
SSYSOBSa  for SOBSna
SSYSSRCa  for SSRCna
VELOSYSa  for VSYSna
VELANGLa  for VANGna
VELREF        -       ... (No column-specific form.)
VELREFa       -       ... Only if WCSHDR_VELREFa is set.
VSOURCEa  for VSOUna  ... Only if WCSHDR_VSOURCE is set.
WCSNAMEa  for WCSNna  ... Or TWCSna (see below).
ZSOURCEa  for ZSOUna

DATE-AVG  for DAVGn
DATE-OBS  for DOBSn
MJD-AVG   for MJDAn
MJD-OBS   for MJDOBn
OBSGEO-X  for OBSGXn
OBSGEO-Y  for OBSGYn
OBSGEO-Z  for OBSGZn
```
where the image-header keywords on the left provide default values for the column specific keywords on the right.

Keywords in the last group, such as MJD-OBS, apply to all alternate representations, so MJD-OBS would provide a default value for all images in the header.

This auxiliary inheritance mechanism applies to binary table image arrays and pixel lists alike. Most of these keywords have no default value, the exceptions being LONPOLEa and LATPOLEa, and also RADESYSa and EQUINOXa which provide defaults for each other. Thus the only potential difficulty in using WCSHDR_AUXIMG is that of erroneously inheriting one of these four keywords.

Unlike WCSHDR_ALLIMG, the existence of one (or all) of these auxiliary WCS image header keywords will not by itself cause a Wcsprm object to be created for alternate representation a. This is because they do not provide sufficient information to create a non-trivial coordinate representation when used in conjunction with the default values of those keywords, such as CTYPEia, that are parameterized by axis number.
WCSHDR_ALLIMG: Allow the image-header form of all image header WCS keywords to provide a default value for all image arrays in a binary table (n.b. not pixel list). This default may be overridden by the column-specific form of the keyword.

For example, a keyword like CRPIXja would apply to all image arrays in a binary table with alternate representation a unless overridden by jCRPna.

Specifically the keywords are those listed above for WCSHDR_AUXIMG plus:
```
WCSAXESa  for WCAXna
```
which defines the coordinate dimensionality, and the following keywords which are parameterized by axis number:
```
CRPIXja   for jCRPna
PCi_ja    for ijPCna
CDi_ja    for ijCDna
CDELTia   for iCDEna
CROTAi    for iCROTn
CROTAia        -      ... Only if WCSHDR_CROTAia is set.
CUNITia   for iCUNna
CTYPEia   for iCTYna
CRVALia   for iCRVna
PVi_ma    for iVn_ma
PSi_ma    for iSn_ma

CNAMEia   for iCNAna
CRDERia   for iCRDna
CSYERia   for iCSYna
```
where the image-header keywords on the left provide default values for the column specific keywords on the right.

This full inheritance mechanism only applies to binary table image arrays, not pixel lists, because in the latter case there is no well-defined association between coordinate axis number and column number.

Note that CNAMEia, CRDERia, CSYERia, and their variants are not used by pywcs but are stored in the Wcsprm object as auxiliary information.

Note especially that at least one Wcsprm object will be returned for each a found in one of the image header keywords listed above:
- If the image header keywords for a are not inherited by a binary table, then the struct will not be associated with any particular table column number and it is up to the user to provide an association.
- If the image header keywords for a are inherited by a binary table image array, then those keywords are considered to be “exhausted” and do not result in a separate Wcsprm object.

Header-writing relaxation constants¶

to_header and to_header_string has a relax argument which may be either True, False or an int.

If True, write all recognized extensions.
If False (default), write all extensions that are considered to be safe and recommended, equivalent to WCSHDO_safe (described below).
If an int, is is a bit field to provide fine-grained control over what non-standard WCS keywords to accept. The flag bits are subject to change in future and should be set by using the constants beginning with WCSHDO_ in the astropy.wcs module.

The flag bits are:

WCSHDO_none: Don’t use any extensions.
WCSHDO_all: Write all recognized extensions, equivalent to setting each flag bit.
WCSHDO_safe: Write all extensions that are considered to be safe and recommended.
WCSHDO_DOBSn: Write DOBSn, the column-specific analogue of DATE-OBS for use in binary tables and pixel lists. WCS Paper III introduced DATE-AVG and DAVGn but by an oversight DOBSn was never formally defined by the standard. The alternative to using DOBSn is to write DATE-OBS which applies to the whole table. This usage is considered to be safe and is recommended.
WCSHDO_TPCn_ka: WCS Paper I defined
- TPn_ka and TCn_ka for pixel lists
  
  but WCS Paper II uses TPCn_ka in one example and subsequently the errata for the WCS papers legitimized the use of
- TPCn_ka and TCDn_ka for pixel lists
  
  provided that the keyword does not exceed eight characters. This usage is considered to be safe and is recommended because of the non-mnemonic terseness of the shorter forms.
WCSHDO_PVn_ma: WCS Paper I defined
- iVn_ma and iSn_ma for bintables and
- TVn_ma and TSn_ma for pixel lists
  
  but WCS Paper II uses iPVn_ma and TPVn_ma in the examples and subsequently the errata for the WCS papers legitimized the use of
- iPVn_ma and iPSn_ma for bintables and
- TPVn_ma and TPSn_ma for pixel lists
  
  provided that the keyword does not exceed eight characters. This usage is considered to be safe and is recommended because of the non-mnemonic terseness of the shorter forms.
WCSHDO_CRPXna: For historical reasons WCS Paper I defined
- jCRPXn, iCDLTn, iCUNIn, iCTYPn, and iCRVLn for bintables and
- TCRPXn, TCDLTn, TCUNIn, TCTYPn, and TCRVLn for pixel lists
  
  for use without an alternate version specifier. However, because of the eight-character keyword constraint, in order to accommodate column numbers greater than 99 WCS Paper I also defined
- jCRPna, iCDEna, iCUNna, iCTYna and iCRVna for bintables and
- TCRPna, TCDEna, TCUNna, TCTYna and TCRVna for pixel lists
  
  for use with an alternate version specifier (the a). Like the PC, CD, PV, and PS keywords there is a tendency to confuse these two forms for column numbers up to 99. It is very unlikely that any parser would reject keywords in the first set with a non-blank alternate version specifier so this usage is considered to be safe and is recommended.
WCSHDO_CNAMna: WCS Papers I and III defined
- iCNAna, iCRDna, and iCSYna for bintables and
- TCNAna, TCRDna, and TCSYna for pixel lists
  
  By analogy with the above, the long forms would be
- iCNAMna, iCRDEna, and iCSYEna for bintables and
- TCNAMna, TCRDEna, and TCSYEna for pixel lists
  
  Note that these keywords provide auxiliary information only, none of them are needed to compute world coordinates. This usage is potentially unsafe and is not recommended at this time.
WCSHDO_WCSNna: Write WCSNna instead of TWCSna for pixel lists. While the constructor treats WCSNna and TWCSna as equivalent, other parsers may not. Consequently, this usage is potentially unsafe and is not recommended at this time.
WCSHDO_SIP: Write out Simple Imaging Polynomial (SIP) keywords.
WCSHDO_P12, WCSHDO_P13, WCSHDO_P14, WCSHDO_P15, WCSHDO_P16, WCSHDO_P17, WCSHDO_EFMT

These constants control the precision of the WCS keywords returned by to_header.
- WCSHDO_P12 : Use “%20.12G” format for all floating-point keyvalues (12 significant digits)
- WCSHDO_P13 : Use “%21.13G” format for all floating-point keyvalues (13 significant digits)
- WCSHDO_P14 : Use “%22.14G” format for all floating-point keyvalues (14 significant digits)
- WCSHDO_P15 : Use “%23.15G” format for all floating-point keyvalues (15 significant digits)
- WCSHDO_P16 : Use “%24.16G” format for all floating-point keyvalues (16 significant digits)
- WCSHDO_P17 : Use “%25.17G” format for all floating-point keyvalues (17 significant digits)
- WCSHDO_EFMT : Use “%E” format instead of the default “%G” format above

Navigation

Header-reading relaxation constants¶

Header-writing relaxation constants¶