A more general facility is also provided to associate specified FITS extensions with NDF components by means of entries in a file (see the EXTABLE parameter).
Details of the supported special formats and rules for processing them are given in topic "Special Formats"; the general-case processing rules are described in the "Notes".
FITS2NDF can also process both external and internal compressed FITS files. The external compression applies to the whole file and FITS2NDF recognises gzip (.gz) and UNIX compress (.Z) formats. Internal compressions are where a large image is tiled and each tile is compressed. The supported formats are Rice, the IRAF PLIO, and GZIP.
Both NDF and FITS use the term extension, and they mean different things. Thus to avoid confusion in the descriptions below, the term `sub-file' is used to refer to a FITS IMAGE, TABLE or BINTABLE Header and Data Unit (HDU).
A comma-separated list of up to six values may be supplied, in which case the value actually used is the first in the list for which corresponding keywords can be found in the FITS header.
A FITS header may contain keywords from more than one of these encodings, in which case it is possible for the encodings to be inconsistent with each other. This may happen for instance if an application modifies the keyword associated with one encoding but fails to make equivalent modifications to the others.
If a null parameter value (!) is supplied for ENCODINGS, then an attempt is made to determine the most reliable encoding to use as follows. If both native and non-native encodings are available, then the first non-native encoding to be found which is inconsistent with the native encoding is used. If all encodings are consistent, then the native encoding is used (if present). [!]
An EXTABLE file contains records which may be:
Component specifier records have the form:
component; sub-file_specifiers; transformation_codewhere:
Each sub-file specifier may be:
NDFNAMES records have the format:
NDFNAMES name_listWhere name_list is a list of names for the NDFs to be created, one for each sub-file set specified by the component specifier lines. The names are separated by commas. If any of the names are omitted, the last name specified is assumed to be a root name to which an integer counter is to be added until a new name is found. If no names are specified, EXTN_SET is used as the root name. For example, NDFNAMES NDF,,SET_ would result in NDFs named NDF1, NDF2, SET_1, SET_2 etc. up to the given number of sub-file sets.
There may be multiple NDFNAMES records, the names will be concatenated. A name may not span records and a comma as the last non-blank character indicates an omitted name.
If there is only one sub-file set, name_list may be `*', in which case the NDF will be created at the top level of the output file.
Directive records have # in column 1 and will generally be treated as comments and ignored. An exception is a record starting with `#END', which may optionally be used to terminate the file.
Each HDU of the FITS file is processed in turn. If it matches one of the sub-file specifiers in the table, it is used to create the specified component of the appropriate NDF in the output file; otherwise the next HDU is processed. The table is searched in sub-file set order. If a table entry is matched it is removed from the table; this means that the same FITS sub-file specifier may be repeated for another NDF component but each FITS HDU can only be used once. If sub-file specifiers remain unmatched at the end, a warning message is displayed.
A simple example of an EXTABLE is:
# A simple exampleThe primary HDU and sub-files 1-6 of the FITS file will be written as the DATA components of NDFs EXTN_SET1-EXTN_SET7 within the HDS container file specified by the OUT parameter.
A contrived example, showing more of the facilities, is:
# A contrived exampleThe HDS container file specified by the OUT parameter will contain three NDFs, the NDFNAMES record specifies that they will be named OBS_1, OBS_2 and OBS_3.
DATA; 1, EXTNAME=IM4, IM7; none
VARIANCE; 2,im5, im8
NDF OBS_1 will have its DATA component created from the first extension (HDU 1) of the FITS file specified by the IN parameter, and its VARIANCE from the second. NDF OBS_1 will have an extension named CAL created from the third FITS extension.
NDF OBS_2 has DATA and VARIANCE components created from the FITS sub-files whose EXTNAME keywords have the value IM4 and IM5 respectively; no CAL extension is created in OBS_2.
OBS_3 DATA and VARIANCE are created from FITS sub-files named IM7 and IM8 and the CAL extension from the FITS sub-file whose EXTNAME and EXTVER keywords have values `CAL' and 2 respectively.
In all cases, if the PROFITS parameter is TRUE, the NDF's FITS extension will be created from the header of the sub-file associated with the DATA component of the NDF. It will have the form of a primary header and may include cards inherited from the primary header [!]
If FMTCNV="FALSE", the HDS type of the data array in the NDF will be the equivalent of the FITS data format on tape (e.g. BITPIX = 16 creates a _WORD array). If "TRUE", the data array in the NDF will be converted from the FITS data type to _REAL or _DOUBLE in the NDF.
The special value FMTCNV="Native" is a variant of "FALSE", that in addition creates a scaled form of NDF array, provided the array values are scaled through BSCALE and/or BZERO keywords (i.e. the keywords' values are not the null 1.0 and 0.0 respectively). This NDF scaled array contains the unscaled data values, and the scale and offset.
The actual NDF data type for FMTCNV="TRUE", and the data type after applying the scale and offset for FMTCNV="NATIVE" are both specified by Parameter TYPE. However, if TYPE is a blank string or null (!), then the choice of floating-point data type depends on the number of significant digits in the BSCALE and BZERO keywords.
FMTCNV may be a list of comma-separated values, enclosed in double quotes, to be applied to each conversion in turn. An error results if more values than the number of input FITS files are supplied. If too few are given, the last value in the list applied to all the conversions; thus a single value is applied to all the input files. If more than one line is required to enter the information at a prompt then place a "-" at the end of each line where a continuation line is desired. ["TRUE"]
Indirection may occur through text files (nested up to seven deep). The indirection character is "". If extra prompt lines are required, append the continuation character "-" to the end of the line. Comments in the indirection file begin with the character "#".
The simplest modification element is the asterisk "", which means call the output NDF files the same name (without any directory specification) as the corresponding input FITS file, but with file extension ".sdf".
Other types of modification can also occur so OUT = "x" would mean that the output files would have the same name as the input FITS files except for an "x" prefix. You can also replace a specified string in the output filename, for example OUT="x|cal|Starlink|" replaces the string "cal" with "Starlink" in any of the output names "x".
Some of the options create a series of NDFs in the original NDF, which becomes just an HDS container and no longer an NDF.
This parameter is ignored when the supplied FITS file is one of the special formats, including one defined by an EXTABLE but excluding NDF2FITS-created files, whose structure in terms of multiple FITS objects is defined. Specialist NDF extensions may be created in this case. See topic "Special Formats" for details.
It is also ignored if a sub-file is specified as the IN parameter, or Parameter CONTAINER is TRUE. [TRUE]
A null value (!) or blank requests that the type be propagated from the FITS (using the BITPIX keyword); or if FMTCNV is "TRUE", the type is either _REAL or _DOUBLE depending on the precision of the BSCALE and BZERO keywords.
TYPE may be a list of comma-separated values enclosed in double quotes, that are applied to each conversion in turn. An error results if more values than the number of input FITS files are supplied. If too few are given, the last value in the list is applied to all the conversions; thus a single value is applied to all the input files. If more than one line is required to enter the information at a prompt then place a "-" at the end of each line where a continuation line is desired. [!]
"WCS" is the recommended option as it offers most flexibility and many facilities such as transformations between co-ordinate systems. However, some legacy applications such as Figaro do not recognise WCS and for these "Axis" is more appropriate. If you are mixing data processing packages then you may need "Both", but care should be exercised to avoid inconsistent representations, especially if the data are exported to FITS with NDF2FITS (see its Parameter USEAXIS). ["WCS"]
The resultant NDFs take the filenames of the FITS files, so if
one of the FITS files was parker.fits, the resultant NDF
would be called parker.
Format conversion is performed on integer
data types. A FITS extension is created in each NDF and any
FITS sub-files present are propagated to NDF extensions.
Two other special cases are when a particular sub-file is specified by the IN parameter and when conversion is driven by an EXTABLE file.
The general rules for the conversion apply if the FITS file is not one of the "Special Formats" (including one defined by an EXTABLE) and Parameter CONTAINER is not TRUE.
The general rules are as follows:
Each group NDF contains the full header in the FITS extension, appended by the set of group parameters. The group parameters are evaluated using their scales and offsets, and made to look like FITS cards. The keywords of these FITS cards are derived from the values of PTYPEm in the main header, where m is the number of the group parameter.
|NPOINTS||Number of elements|
|WAVELENGTH||Start wavelength, axis label and units|
|FLUX||Data array, label, units, bad-pixel flag|
|remaining columns||Component in IUE_MX extension (NET and BACKGROUND are NDFs)|
|NPOINTS||Number of non-zero elements|
|WAVELENGTH||Start wavelength of the non-zero elements, label, and units|
|STARTPIX||Lower bound of the non-zero elements|
|ABS_CAL||Data array, label, and units|
|remaining columns (except 14-17)||Component in IUE_MH extension (NOISE, NET, BACKGROUND, and RIPPLE are NDFs each comprising a data array, label, units and wavelength axis)|
|WAVELENGTH||Start wavelength, axis label and units|
|FLUX||Data array, label, units, bad-pixel flag|
|ARRAY||Data, error, exposure arrays depending on the value of column TYPE|
|BLANK||Data blank (i.e. undefined value)|
|BSCALE||Data scale factor|
|CDELTn||Pixel increment along axis n|
|CRPIXn||Axis n reference pixel|
|CRVALn||Axis n co-ordinate of reference pixel|
|CTYPEn||Label for axis n|
|CUNITn||Units for axis n|
|NAXIS||Number of dimensions|
|NAXISn||Dimension of axis n|
|remaining columns||Keyword in FITS extension|
|LSANFLX||Data array, label, and units|
|LSANFLXU||Data errors, hence variance|
|LSANDET||Quality (bits 1 to 4)|
|LSANSDIR||Quality (bit 5)|
|LSANRPID||Axis centres, labels, and units x-y positions-- dimensions 1 and 2)|
|LSANSCNT||Axis centre, label, and unit (scan (count index--dimension 4)|
|LSANWAV||Axis centre, label, and unit (wavelength--dimension 3)|
|LSANWAVU||Axis errors (wavelength--dimension 3)|
|remaining columns||column name in LWSAN extension|
|SWAAWAVE||Axis centres, label, and units|
|SWAAFLUX||Data array, label, and units|
|SWAASTDV||Data errors, hence variance|
|remaining columns||column name in SWSAA extension|
CONVERT A Format-conversion Package