FITSDIN - Reads a FITS disc file composed of simple, group or table objects

Description:

This application reads selected disc-FITS files. The files may be Basic (simple) FITS, and/or have TABLE extensions (Harten et al. 1988).

The programme reads a simple or a random-groups-format FITS file (Wells et al. 1981; Greisen & Harten 1981), and writes the data into an NDF , and the headers into the NDF's FITS extension. Table-format files (Grosbøl et al. 1988) are read, and the application creates two files: a text formatted table/catalogue and a FACTS description file (as used by SCAR) based upon the FITS header cards. Composite FITS files can be processed. You may specify a list of files, including wildcards. A record of the FITS headers, and group parameters (for a group-format file) can be stored in a text file.

There is an option to run in automatic mode, where the names of output NDF data structures are generated automatically, and you can decide whether or not format conversion is to be applied to all files (rather than being prompted for each). This is very useful if there is a large number of files to be processed. Even if you want unique file names, format-conversion prompting may be switched off globally.

Usage:

fitsdin files out [auto] fmtcnv [logfile] dscftable=? table=?

Parameters:

AUTO = _LOGICAL (Read)

It is TRUE if automatic mode is required, where the name of each output NDF structure or table file is to be generated by the application, and therefore not prompted; and a global format-conversion switch may be set. In manual mode the FITS header is reported, but not in automatic.

In automatic mode the application generates a filename beginning with the input filename, less any extension. For example, if the input file was saturn.fits the filename of the output NDF would be saturn.sdf, and an output table would be saturn.dat with a description file dscfsaturn.dat. If there are sub-files (more than one FITS object in the file) a suffix _<subfile> is appended. So if saturn.fits comprised a simple file followed by a table, the table would be called SATURN_2.DAT and the description file DSCFSATURN_2.DAT. For group format a suffix G<groupnumber> is appended. Thus if saturn.fits is a group format file, the first NDF created would be called saturn.sdf, the second would be saturnG2.sdf. [FALSE]

DSCFTABLE = FILENAME (Read)

Name of the text file to contain the FACTS descriptors, which defines the table's format for SCAR. Since SCAR is now deprecated, this parameter has little use, except perhaps to give a summary of the format of the file specified by Parameter TABLE. A null value (!) means that no description file will be created, so this is now the recommended usage. If your FITS file comprises just tables, you should consider other tools such as the CURSA package, which has facilities for examining and processing ASCII and binary tables in FITS files.

A suggested filename for the description file is reported immediately prior to prompting in manual mode. It is the name of the catalogue, as written in the FITS header, with a "dscf" prefix.

ENCODINGS = LITERAL (Read)

Determines which FITS keywords should be used to define the world co-ordinate systems to be stored in the NDF's WCS component. The allowed values (case-insensitive) are as follows.

• "FITS-IRAF" -- This uses keywords CRVALi CRPIXi, CDi_j, and is the system commonly used by IRAF. It is described in the document ``World Coordinate Systems Representations Within the FITS Format'' by R.J. Hanisch and D.G. Wells, 1988, available by ftp from fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z.

• "FITS-WCS" -- This is the FITS standard WCS encoding scheme described in the paper ``Representation of celestial coordinates in FITS''
  (http://www.cv.nrao.edu/fits/documents/wcs/wcs.html).
  

  It is very similar to FITS-IRAF but supports a wider range of projections and co-ordinate systems. Once the standard has been agreed, this encoding should be understood by any FITS-WCS compliant software and it is likely to be adopted widely for FITS data in future.

• "FITS-PC" -- This uses keywords CRVALi, CDELTi, CRPIXi, PCiiijjj, etc, as in a previous (now superseded) draft of the above FITS world co-ordinate system paper by E.W. Greisen and M. Calabretta.

• "FITS-AIPS" -- This uses conventions described in the document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th September, 1994), available by ftp from fits.cv.nrao.edu /fits/documents/wcs/aips27.ps.Z. It is currently employed by the AIPS data analysis facility, so its use will facilitate data exchange with AIPS. This encoding uses CROTAi and CDELTi keywords to describe axis rotation and scaling.

• "DSS" -- This is the system used by the Digital Sky Survey, and uses keywords AMDXn, AMDYn, PLTRAH, etc.

• "Native" -- This is the native system used by the AST library (see SUN/210), and provides a loss-free method for transferring WCS information between AST-based application. It allows more complicated WCS information to be stored and retrieved than any of the other encodings.

A comma-separated list of up to six values may be supplied, in which case the value actually used is in 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). [!]

FILES() = LITERAL (Read)

A list of (optionally wild-carded) file specifications which identify the disc-FITS files to be processed. Up to ten values may be given, but only a single specification such as "*.fits" is normally required. Be careful not to include non-FITS files in this list.

FMTCNV = _LOGICAL (Read)

This specifies whether or not format conversion will occur. If FALSE, the HDS type of the data array in the NDF will be the equivalent of the FITS data format in the file (e.g. BITPIX=16 creates a _WORD array). If TRUE, the data array in the current file, or all files in automatic mode, will be converted from the FITS data type in the FITS file to _REAL in the NDF. The conversion applies the values of the FITS keywords BSCALE and BZERO to the FITS-file data to generate the `true' data values. If BSCALE and BZERO are not given in the FITS header, they are taken to be 1.0 and 0.0 respectively. The suggested default is TRUE.

GLOCON = _LOGICAL (Read)

If FALSE a format-conversion query occurs for each FITS file. If TRUE, the value of Parameter FMTCNV is obtained before any file numbers and will apply to all data arrays. It is ignored in automatic mode--in effect it becomes TRUE. [FALSE]

LOGFILE = FILENAME (Read)

The file name of the text log of the FITS header cards. For group-format data the group parameters are evaluated and appended to the full header. The log includes the names of the output files used to store the data array or table. A null value (!) means that no log file is produced. [!]

OUT = NDF (Write)

Output NDF structure holding the full contents of the FITS file. If the null value (!) is given no NDF will be created. This offers an opportunity to review the descriptors before deciding whether or not the data are to be extracted.

TABLE = FILENAME (Read)

Name of the text file to contain the table itself, read from the file. In manual mode, the suggested default filename is the name of description file less the "dscf" prefix, or if there is no description file or if the description file does not have the "dscf" prefix, the suggested name reverts to the catalogue name in the FITS header.

Examples:

fitsdin files=*.fit auto nofmtcnv

This reads all the files with extension "fit" in the default directory. If the files were sao.fit and moimp.fit and each contained just an image array, the output NDFs will be sao and moimp respectively. The data will not have format conversion.

fitsdin files=ccd.ifits fmtcnv logfile=jkt.log

This reads the file ccd.ifits and processes all the FITS objects within it. Integer data arrays are converted to real using the scale and zero found in the FITS header. A record of the headers and the names of the output files are written to the text file jkt.log.

fitsdin files=[*.*fits,*.mt] glocon fmtcnv

This reads the files *.*fits and *.mt and processes all the FITS objects within them. Integer data arrays are converted to real using the scale and zero found in the FITS header. Any IEEE-format data will not be converted although the global conversion switch is on.

References

• Wells, D.C., Greisen, E.W. & Harten, R.H. 1981, Astron. Astrophys. Suppl. Ser. 44, 363.

• Greisen, E.W. & Harten, R.H. 1981, Astron. Astrophys. Suppl. Ser. 44, 371.

• Grosbøl, P., Harten, R.H., Greisen, E.W & Wells, D.C. 1988 Astron. Astrophys. Suppl. Ser. 73, 359.

• Harten, R.H., Grosbøl, P., Greisen, E.W & Wells, D.C. 1988 Astron. Astrophys. Suppl. Ser. 73, 365.

Related Applications

KAPPA: FITSHEAD, FITSIMP, FITSIN, FITSLIST; CONVERT: FITS2NDF; CURSA; FIGARO: RDFITS.

Implementation Status:

• The application processes FITS files blocked at other than an integer multiple of 2880 bytes up to a maximum of 28800, provided it is a multiple of the number of bytes per data value.

• For simple or group format FITS:
  • IEEE floating point is supported.

  • If BUNIT is present its value will appear as the NDF's UNITS component.

  • If OBJECT is present its value will appear as the NDF's TITLE component.

  • If the BLANK item is present in the header, undefined pixels are converted from the BLANK value to Starlink-standard bad value during data conversion.

  • An AXIS  component will be stored in the NDF if the CRVALn keyword is present. (n is the number of the dimension.) If the CRPIXn keyword is absent it defaults to 1, and likewise for the CDELTn keyword. The value of CTYPEn is made the label of the axis structure.

• For groups format, a new NDF is created for each data array. The name of the NDF of the second and subsequent data arrays is generated by the application as the <filename>G<number>, where <filename> is the name of the first NDF, you supply or generated automatically, and <number> is the number of the group.

  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, whose keywords are derived from the values of PTYPEm in the main header. (m is the number of the group parameter.) The same format is used in the log file.

• If there is no data array in the FITS file, i.e. the FITS file comprises header cards only, then a dummy vector data array of dimension two is created to make the output a valid NDF. This data array is undefined.