Next Previous Up Contents
Next: FITS-plus
Up: Supplied Output Handlers
Previous: Supplied Output Handlers

3.6.1 FITS

The FITS handler, FitsTableWriter, will output a FITS file with N+1 HDUs for N tables; the first (primary) HDU has no interesting content, and subsequent ones (the extensions) are of type BINTABLE, one for each output table.

A variant handler, VariableFitsTableWriter is also provided. This behaves in much the same way, but in the case of columns which contain variable-shaped arrays (ones for which the last element of ColumnInfo.getShape() is negative) it will store the array data in the 'heap' following the table data in the BINTABLE HDU, using the 'P' or 'Q' data type specifiers in the relevant TFORMn header cards.

To write the FITS header for the table extension, certain things need to be known which may not be available from the StarTable object being written; in particular the number of rows and the size of any variable-sized arrays (including variable-length strings) in the table. This may necessitate two passes through the data to do the write.

To fix the value of the TNULLn magic value for a given column on output, set the value of the Tables.NULL_VALUE_INFO auxiliary metadata value, e.g.:


    colInfo.setAuxDatum(new DescribedValue(Tables.NULL_VALUE_INFO, new Integer(-99)));

Writing columns containing (scalar or array) unsigned byte values (TFORMnn = 'B') cannot be done simply by providing byte data to write, since the java byte type is signed. To do it, you must provide a column of java short (16-bit) integers, and set the value of the Tables.UBYTE_FLAG_INFO auxiliary metadata item to Boolean.TRUE, e.g.:


    colInfo.setAuxDatum(new DescribedValue(Tables.UBYTE_FLAG_INFO, Boolean.TRUE));

Writing columns containing (scalar or array) unsigned long values cannot be done straightforwardly, since, like FITS, the Java long type is signed. Instead, you can provide a column of java String values giving the integer representation of the numbers required, and set the value of the BintableStarTable.LONGOFF_INFO auxiliary metadata item to the string representation of the offset 2**63, e.g.:


   colInfo.setAuxDatum(new DescribedValue(BintableStarTable.LONGOFF_INFO, "9223372036854775808263"));

This will result in the values being written, where in range, with FITS headers TFORMnn = 'K', TZEROnn = '9223372036854775808263'. The same mechanism can be used for other long offsets if required (though not for other integer types).

See the "Binary Table Extension" section of the FITS standard for more details of the FITS BINTABLE format. This handler can write tables with more than the BINTABLE limit of 999 columns, as discussed in Section 3.8.1.

There is some support for the semi-standard HEALPix-FITS serialization convention. If some of the HPX_*_INFO metadata items defined by the class HealpixTableInfo are present in the output table's parameter list, the corresponding HEALPix-specific FITS headers will be written on a best-efforts basis into the output BINTABLE HDU. This may or may not be good enough to make that FITS file readable by external HEALPix-FITS-aware applications; one of the requirements of the convention is that the HEALPix pixel index, if present, appears in the first column of the table under the name "PIXEL". An alternative is to use the handler HealpixFitsTableWriter, which tries harder to write tables using the HEALPix convention. This will fail unless the required HPX_*_INFO metadata items mentioned above are present, and will reorder and rename columns as required for maximum compatibility.

StarTableOutput will write in FITS format (using the default handler) format string "fits" is used, or the format string is null and the destination string ends in ".fits".


Next Previous Up Contents
Next: FITS-plus
Up: Supplied Output Handlers
Previous: Supplied Output Handlers

STIL - Starlink Tables Infrastructure Library
Starlink User Note252
STIL web page: http://www.starlink.ac.uk/stil/
Author email: m.b.taylor@bristol.ac.uk