[fitsbits] Proposed Changes to the FITS Standard

On Wed 2007/08/01 09:26:13 -0400, Phil Hodge wrote
in a message to: Mark Calabretta

Phil,

Is keyword "RADECSYS" an allowed alias for "RADESYS" for the primary
WCS? I didn't see that option in your Paper II.

RADECSYS appeared in earlier drafts of Paper II but was subsequently
replaced with RADESYSa. RESTFREQ in early drafts of Paper III was
replaced by RESTFRQa, but RESTFREQ is still mentioned explicitly because
no doubt everyone still uses it. It would be appropriate for RADECSYS
and maybe RESTFREQ to be marked in Table 8.2 as deprecated.

The broader question is what a FITS writer should be allowed to write,
and what a FITS reader should be prepared to read. Obviously the
latter must be prepared to exorcise greater evils than the former is
allowed to produce! RADECSYS falls into this category and much more
besides, as indicated by the usage notes appended for the WCSLIB header
parsers wcspih() and wcsbth() (the latter being a work in progress).

Other weird things appeared for a time in early drafts of the WCS papers
but I'm sure it safe to forget about them.

Cheers, Mark



* 5) wcspih() and wcsbth() interpret the "relax" argument as a vector of
* flag bits 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 preprocessor macros defined below for the
* purpose.
*
* 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.
*
* WCSHDR_reject: Reject non-standard keywords (that are not otherwise
* accepted). A message will optionally be printed on stderr, as
* determined by the ctrl argument, and nreject is incremented.
* This flag may be used to signal the presence of such keywords,
* otherwise they are simply passed over as though they did not
* exist in the header. Useful for testing conformance.
*
* WCSHDR_all: Accept all extensions recognized by the parser.
*
* WCSHDR_CROTAia: Accept CROTAia (wcspih),
* iCROTna (wcsbth),
* TCROTna (wcsbth).
* WCSHDR_EPOCHa: Accept EPOCHa.
* WCSHDR_VELREFa: Accept VELREFa.
* wcspih() always recognizes the AIPS-convention keywords,
* CROTAn, EPOCH, and VELREF for the primary representation
* (a = ' ') but alternates are non-standard.
*
* wcsbth() accepts EPOCHa and VELREFa only if WCSHDR_ASCOPE is
* also enabled.
*
* WCSHDR_CD00i00j: Accept CD00i00j (wcspih).
* WCSHDR_PC00i00j: Accept PC00i00j (wcspih).
* WCSHDR_PROJPn: Accept PROJPn (wcspih).
* 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_RADECSYS: Accept RADECSYS (wcspih). This appeared in early
* drafts of WCS Paper I+II and was subsequently replaced by
* RADESYSa.
*
* WCSHDR_VSOURCE: Accept VSOURCEa (wcspih) or VSOUna (wcsbth).
* This appeared in early drafts of WCS Paper III and was
* subsequently dropped in favour of ZSOURCEa and ZSOUna.
*
* WCSHDR_DOBS (wcsbth only): Allow DOBSn, the column-specific analogue
* of DATE-OBS. By an oversight this was never formally defined
* in the standard.
*
* WCSHDR_LONGKEY (wcsbth only): Accept long forms of the alternate
* binary table and pixel list WCS keywords. Specifically
*
* jCRPXna TCRPXna (jCRPXn, jCRPna, TCRPXn, TCRPna, CRPIXja)
* TPCn_ka ( TPn_ka, PCi_ja)
* TCDn_ka ( TCn_ka, CDi_ja)
* iCDLTna TCDLTna (iCDLTn, iCDEna, TCDLTn, TCDLna, CDELTia)
* iCRVLna TCRVLna (iCRVLn, iCRVna, TCRVLn, TCRVna, CRVALia)
* iCUNIna TCUNIna (iCUNIn, iCUNna, TCUNIn, TCUNna, CUNITia)
* iCTYPna TCTYPna (iCTYPn, iCTYna, TCTYPn, TCTYna, CTYPEia)
* iPVn_ma TPVn_ma ( iVn_ma, TVn_ma, PVi_ma)
* iPSn_ma TPSn_ma ( iSn_ma, TSn_ma, PSi_ma)
* iCRDEna TCRDEna ( iCRDna, TCRDna, CRDERia)
* iCSYEna TCSYEna ( iCSYna, TCSYna, CSYERia)
*
* where the primary and standard alternate forms together with
* the image-header equivalent are shown in parentheses.
*
* TPCn_ka, iPVn_ma, 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. They could be described as quasi-standard.
*
* The other long forms are non-standard and in fact have never
* appeared in any draft of the WCS papers. 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.
*
* WCSHDR_WCSN (wcsbth only): Allow the use of WCSNna in pixel lists in
* place of TWCSna.
*
* WCSHDR_ASCOPE (wcsbth only): 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
*
* DATE-AVG DAVGn
* DATE-OBS DOBSn ... Only if WCSHDR_DOBS is set.
* EPOCH - ... No column-specific form.
* EPOCHa - ... Only if WCSHDR_EPOCHa is set.
* EQUINOXa EQUIna
* LATPOLEa LATPna
* LONPOLEa LONPna
* MJD-AVG MJDAn
* MJD-OBS MJDOBn
* OBSGEO-X OBSGXn
* OBSGEO-Y OBSGYn
* OBSGEO-Z OBSGZn
* RADECSYS RADEna ... Only if WCSHDR_RADECSYS is set.
* RADESYSa RADEna
* RESTFREQ RFRQna
* RESTFRQa RFRQna
* RESTWAVa RWAVna
* SPECSYSa SPECna
* SSYSOBSa SOBSna
* SSYSSRCa SSRCna
* VELOSYSa VSYSna
* VELANGLa VANGna
* VELREF - ... No column-specific form.
* VELREFa - ... Only if WCSHDR_VELREFa is set.
* VSOURCEa VSOUna ... Only if WCSHDR_VSOURCE is set.
* WCSAXESa WCAXna
* WCSNAMEa WCSNna/TWCSna
* ZSOURCEa ZSOUna
*
* A number of these keywords, such as MJDOBn, apply to all
* alternate representations, so MJD-OBS would provide a default
* value for all images in the header.
*
* Unlike WCSHDR_BSCOPE, the existence of one of these auxiliary
* WCS image header keywords will not by itself cause a wcsprm
* struct to be created for alternate representation "a".
*
* WCSHDR_BSCOPE (wcsbth only): Allow the image-header form of *any*
* WCS keyword with representation-wide scope to provide a
* default value for all image arrays in a binary table. 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_ASCOPE plus the following keywords which are
* parameterized by axis number:
*
* CRPIXja jCRPna
* CDELTia iCDEna
* CRVALia iCRVna
* CUNITia iCUNna
* CTYPEia iCTYna
* PVi_ma iVn_ma
* PSi_ma iSn_ma
* CNAMEia iCNAna
* CRDERia iCRDna
* CSYERia iCSYna
*
* This only applies to binary tables, not pixel lists.
*
* Note especially that one wcsprm struct will be returned for
* every "a" found in one of the ten keywords listed above. If
* there are no column-specific keywords for that "a" then it
* will not be associated with any particular table column number
* so it is up to the user to provide that association.
*
* For example, to accept CD00i00j and PC00i00j and reject all other
* extensions, use
*
* relax = WCSHDR_reject | WCSHDR_CD00i00j | 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. In
* the AIPS convention VELREF has the following integer values:
* 1: LSR kinematic, originally described as "LSR" without distinction
* 2: Barycentric, originally described as "HEL" meaning heliocentric
* 3: Topocentric, originally described as "OBS" meaning geocentric
* but widely interpreted as topocentric
* AIPS++ extensions to VELREF are also recognized:
* 4: LSR dynamic
* 5: Geocentric
* 6: Source rest frame
* 7: Galactocentric
* A radio convention velocity is denoted by adding 256 to these,
* otherwise an optical velocity is indicated.
*
* Neither wcspih() nor wcsbth() currently recognize the AIPS-convention
* keywords ALTRPIX or ALTRVAL which effectively define an alternative
* representation for a spectral axis.