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));
See the "Binary Table Extension" section of the FITS standard for more details of the FITS BINTABLE format.
StarTableOutput
will write in FITS format
(without variable length array-valued columns) if a
format string "fits" is used, or the format string is null and
the destination string ends in ".fits".