Package nom.tam.fits

Class BinaryTable

java.lang.Object
nom.tam.fits.Data
nom.tam.fits.AbstractTableData
nom.tam.fits.BinaryTable
All Implemented Interfaces:
Cloneable, FitsElement, TableData
Direct Known Subclasses:
CompressedImageData, CompressedTableData
public class BinaryTable extends AbstractTableData implements Cloneable
Table data for binary table HDUs. It has been thoroughly re-written for 1.18 to improve consistency, increase performance, make it easier to use, and to enhance.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    BinaryTable.ColumnDesc
    Describes the data type and shape stored in a binary table column.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BinaryTable()
    Creates an empty binary table, which can be populated with columns / rows as desired.
    BinaryTable(Object[] columns)
    Deprecated.
    The constructor is ambiguous, use fromColumnMajor(Object[]) instead.
    BinaryTable(Object[][] rowColTable)
    Deprecated.
    The constructor is ambiguous, use fromRowMajor(Object[][]) instead.
    BinaryTable(Header header)
    Deprecated.
    (for internal use) This constructor should only be called from a Fits object reading an input; visibility may be reduced to the package level in the future.
    BinaryTable(ColumnTable<?> tab)
    Deprecated.
    DO NOT USE -- it will be removed in the future.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    addBitsColumn(Object o)
    Adds a column of bits.
    int
    addColumn(Object o)
    Adds a new column with the specified data array, with some default mappings.
    int
    addColumn(BinaryTable.ColumnDesc descriptor)
    Adds a new empty column to the table to the specification.
    int
    addComplexColumn(Object o, Class<?> decimalType)
    Adds a column of complex values stored as the specified decimal type of components in the FITS.
    int
    addFlattenedColumn(Object o, int... dims)
    Deprecated.
    (for internal use) No longer used, will be removed in the future
    int
    addRow(Object[] o)
    Adds a row to the table.
    int
    addStringColumn(String[] o)
    Adds a column of string values (one per row), optimized for storage size.
    int
    addVariableSizeColumn(Object o)
    Adds a new variable-length data column, populating it with the specified data object.
    void
    compact()
    Discard the information about the original heap size (if this table was read from an input), and instead use the real size of the actual heap (plus reserved space around it) when writing to an output.
    final boolean
    containsHeap()
    Checks if this table contains a heap for storing variable length arrays (VLAs).
    boolean
    convertToBits(int col)
    Converts a column from FITS logical values to bits.
    BinaryTable
    copy()
    Returns an independent copy of the binary table.
    static void
    createColumnDataFor(BinaryTable table)
    Deprecated.
    (for internal use) It may become a private method in the future.
    long
    defragment()
    Defragments the heap area of this table, compacting the heap area, and returning the number of bytes by which the heap size has been reduced.
    void
    deleteColumns(int start, int len)
    Removes a set of consecutive columns from this table, without updating assocu=iated the header information for the columns that were removed.
    void
    deleteRows(int row, int len)
    Removes a set of consecutive rows from this table without updating any associated header information for an encompassing HDU.
    void
    fillHeader(Header h)
    Deprecated.
    (for internal use) Visibility should be reduced to protected.
    static BinaryTable
    fromColumnMajor(Object[] columns)
    Creates a binary table from existing data in column-major format order.
    static BinaryTable
    fromRowMajor(Object[][] table)
    Creates a binary table from existing table data in row-major format.
    Object
    get(int row, int col)
    Returns a table element using the usual Java boxing for primitive scalar (singleton) entries, or packaging complex values as ComplexValue, or as appropriate primitive or object arrays.
    Object
    getArrayElement(int row, int col)
    Returns a table element as an array of the FITS storage type.
    Object
    getArrayElementAs(int row, int col, Class<?> asType)
    Returns a numerical table element as an array of a specific underlying other numerical type.
    Class<?>[]
    getBases()
    Deprecated.
    (for internal use) Ambiguous, use BinaryTable.ColumnDesc.getElementClass() instead.
    Object
    getColumn(int col)
    Returns the data for a particular column in as an array of elements.
    ColumnTable<?>
    getData()
    Returns the underlying Java representation of the data contained in this HDU's data segment.
    BinaryTable.ColumnDesc
    getDescriptor(int column)
    Returns the column descriptor of a given column in this table
    BinaryTable.ColumnDesc
    getDescriptor(String name)
    Returns the (first) column descriptor whose name matches the specified value.
    static BinaryTable.ColumnDesc
    getDescriptor(Header header, int col)
    Extracts a column descriptor from the FITS header for a given column index
    int[][]
    getDimens()
    Deprecated.
    (for internal use) Use BinaryTable.ColumnDesc.getEntryShape() to access the shape of Java elements individually for columns instead.
    final double
    getDouble(int row, int col)
    Returns the decimal value, if possible, of a scalar table entry.
    Object
    getElement(int row, int col)
    Returns a table element as a Java array.
    Object[]
    getFlatColumns()
    Deprecated.
    (for internal use) It may be private in the future.
    Object
    getFlattenedColumn(int col)
    Deprecated.
    (for internal use) It may be reduced to private visibility in the future.
    final Boolean
    getLogical(int row, int col)
    Returns the boolean value, if possible, for scalar elements.
    final long
    getLong(int row, int col)
    Returns a 64-bit integer value, if possible, of a scalar table entry.
    Object[]
    getModelRow()
    Deprecated.
    (for internal use) Use getElement(int, int) instead for low-level reading of tables in deferred mode.
    int
    getNCols()
    Returns the number of columns contained in this table.
    int
    getNRows()
    Returns the number of columns contained in this table.
    final Number
    getNumber(int row, int col)
    Returns the numerical value, if possible, for scalar elements.
    Object
    getRawElement(int row, int col)
    Deprecated.
    (for internal use) Will reduce visibility in the future.
    Object[]
    getRow(int row)
    Returns an array of elements in a particualr table row.
    int[]
    getSizes()
    Deprecated.
    (for internal use) Use BinaryTable.ColumnDesc.getElementCount() instead.
    final String
    getString(int row, int col)
    Returns the string value, if possible, for scalar elements.
    char[]
    getTypes()
    Deprecated.
    (for internal use) Use BinaryTable.ColumnDesc.getElementClass() instead.
    int
    indexOf(String name)
    Returns the Java index of the first column by the specified name.
    static int[]
    parseTDims(String tdims)
    Deprecated.
    (for internal use) It may be reduced to private visibility in the future.
    void
    read(ArrayDataInput in)
    Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.
    void
    reserveHeapSpace(int bytes)
    Reserves space in the file at the end of the heap for future heap growth (e.g. different/longer or new VLA entries).
    void
    reserveRowSpace(int rows)
    Reserves space for future addition of rows at the end of the regular table.
    void
    set(int row, int col, Object o)
    The Swiss-army knife of setting table entries, including Java boxing, and with some support for automatic type conversions.
    void
    setColumn(int col, Object o)
    Sets new data for a table column.
    boolean
    setComplexColumn(int index)
    Convert a column from float/double to float complex/double complex.
    void
    setElement(int row, int col, Object o)
    Consider using the more Java-friendly set(int, int, Object) with implicit scalar type conversions.
    void
    setFlattenedColumn(int col, Object data)
    Deprecated.
    (for internal use) It may be reduced to private visibility in the future.
    void
    setRow(int row, Object[] data)
    Sets new data for a table row.
    BinaryTableHDU
    toHDU()
    Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
    void
    updateAfterDelete(int oldNcol, Header hdr)
    Deprecated.
    It is not entirely foolproof for keeping the header in sync -- it is better to (re)wrap tables in a new HDU after column deletions, and then edit the new header as necessary to incorporate custom entries.
    void
    write(ArrayDataOutput os)
    Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.

    Methods inherited from class nom.tam.fits.Data

    calcChecksum, detach, getFileOffset, getKernel, getSize, isDeferred, isEmpty, reset, rewrite, rewriteable

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface nom.tam.fits.TableData

    addRowEntries, setRowEntries

  • Constructor Details

    • BinaryTable

      public BinaryTable()
      Creates an empty binary table, which can be populated with columns / rows as desired.

    • BinaryTable

      public BinaryTable(ColumnTable<?> tab) throws FitsException
      Deprecated.
      DO NOT USE -- it will be removed in the future.
      Creates a binary table from an existing column table. WARNING!, as of 1.18 we no longer use the column data extra state to carry information about an enclosing class, because it is horribly bad practice. You should not use this constructor to create imperfect copies of binary tables. Rather, use copy() if you want to create a new binary table, which properly inherits ALL of the properties of an original one. As for this constructor, you should assume that it will not use anything beyond what's available in any generic vanilla column table.
      Parameters:
      tab - the column table to create the binary table from. It must be a regular column table that contains regular data of scalar or fixed 1D arrays only (not heap pointers). No information beyond what a generic vanilla column table provides will be used. Column tables don't store imensions for their elements, and don't have variable-sized entries. Thus, if the table was the used in another binary table to store flattened multidimensional data, we'll detect that data as 1D arrays. Andm if the table was used to store heap pointers for variable length arrays, we'll detect these as regular int[2] or long[2] values.
      Throws:
      FitsException - if the table could not be copied and threw a TableException, which is preserved as the cause.
      See Also:

    • BinaryTable

      public BinaryTable(Header header) throws FitsException
      Deprecated.
      (for internal use) This constructor should only be called from a Fits object reading an input; visibility may be reduced to the package level in the future.
      Creates a binary table from a given FITS header description. The table columns are initialized but no data will be available, at least initially. Data may be loaded later (e.g. deferred read mode), provided the table is associated to an input (usually only if this constructor is called from a Fits object reading an input). When the table has an input configured via a Fits object, the table entries may be accessed in-situ in the file while in deferred read mode, but operations affecting significant portions of the table (e.g. retrieving all data via getData() or accessing entire columns) may load the data in memory. You can also call Data.detach() any time to force loading the data into memory, so that alterations after that will not be reflected in the original file, at least not unitl Data.rewrite() is called explicitly.
      Parameters:
      header - A FITS header describing what the binary table should look like.
      Throws:
      FitsException - if the specified header is not usable for a binary table
      See Also:

    • BinaryTable

      public BinaryTable(Object[][] rowColTable) throws FitsException
      Deprecated.
      The constructor is ambiguous, use fromRowMajor(Object[][]) instead. You can have a column-major array that has no scalar primitives which would also be an Object[][] and could be passed erroneously.
      Creates a binary table from existing table data int row-major format. That is the first array index is the row index while the second array index is the column index.
      Parameters:
      rowColTable - Row / column array. Scalars elements are wrapped in arrays of 1, s.t. a single int elements is stored as int[1] at its [row][col] index.
      Throws:
      FitsException - if the argument is not a suitable representation of data in rows.

    • BinaryTable

      public BinaryTable(Object[] columns) throws FitsException
      Deprecated.
      The constructor is ambiguous, use fromColumnMajor(Object[]) instead. One could call this method with any row-major Object[][] table by mistake.
      Create a binary table from existing data in column-major format order.
      Parameters:
      columns - array of columns. The data for scalar entries is a primive array. For all else, the entry is an Object[] array of sorts.
      Throws:
      FitsException - if the data for the columns could not be used as coulumns
      See Also:

  • Method Details

    • fromRowMajor

      public static BinaryTable fromRowMajor(Object[][] table) throws FitsException
      Creates a binary table from existing table data in row-major format. That is the first array index is the row index while the second array index is the column index;
      Parameters:
      table - Row / column array. Scalars elements are wrapped in arrays of 1, s.t. a single int elements is stored as int[1] at its [row][col] index.
      Returns:
      a new binary table with the data. The tables data may be partially independent from the argument. Modifications to the table data, or that to the argument have undefined effect on the other object. If it is important to decouple them, you can use a ArrayFuncs.deepClone(Object) of your original data as an argument.
      Throws:
      FitsException - if the argument is not a suitable representation of FITS data in rows.
      Since:
      1.18
      See Also:

    • fromColumnMajor

      public static BinaryTable fromColumnMajor(Object[] columns) throws FitsException
      Creates a binary table from existing data in column-major format order.
      Parameters:
      columns - array of columns. The data for scalar entries is a primive array. For all else, the entry is an Object[] array of sorts.
      Returns:
      a new binary table with the data. The tables data may be partially independent from the argument. Modifications to the table data, or that to the argument have undefined effect on the other object. If it is important to decouple them, you can use a ArrayFuncs.deepClone(Object) of your original data as an argument.
      Throws:
      FitsException - if the argument is not a suitable representation of FITS data in rows.
      Since:
      1.18
      See Also:

    • copy

      public BinaryTable copy() throws FitsException
      Returns an independent copy of the binary table.
      Returns:
      a new binary that tnat contains an exact copy of us, but is completely independent.
      Throws:
      FitsException - if the table could not be copied
      Since:
      1.18

    • createColumnDataFor

      public static void createColumnDataFor(BinaryTable table) throws FitsException
      Deprecated.
      (for internal use) It may become a private method in the future.
      Parameters:
      table - the table to create the column data.
      Throws:
      FitsException - if the data could not be created.

    • parseTDims

      public static int[] parseTDims(String tdims)
      Deprecated.
      (for internal use) It may be reduced to private visibility in the future. Parse the TDIMS value. If the TDIMS value cannot be deciphered a one-d array with the size given in arrsiz is returned.
      Parameters:
      tdims - The value of the TDIMSn card.
      Returns:
      An int array of the desired dimensions. Note that the order of the tdims is the inverse of the order in the TDIMS key.

    • addComplexColumn

      public int addComplexColumn(Object o, Class<?> decimalType) throws FitsException

      Adds a column of complex values stored as the specified decimal type of components in the FITS. While you can also use addColumn(Object) to add complex values, that method will always add them as 64-bit double-precision values. So, this method is provided to allow users more control over how they want their complex data be stored.

      The new column will be named as "Column n" (where n is the 1-based index of the column) by default, which can be changed by BinaryTable.ColumnDesc.name(String) after.

      Parameters:
      o - A ComplexValue or an array (possibly multi-dimensional) thereof.
      decimalType - float.class or double.class (all other values default to double.class).
      Returns:
      the number of column in the table including the new column.
      Throws:
      FitsException - if the object contains values other than ComplexValue types or if the array is not suitable for storing in the FITS, e.g. because it is multi-dimensional but varying in shape / size.
      Since:
      1.18
      See Also:

    • addStringColumn

      public int addStringColumn(String[] o) throws FitsException

      Adds a column of string values (one per row), optimized for storage size. Unlike addColumn(Object), which always store strings in fixed format, this method will automatically use variable-length columns for storing the strings if their lengths vary sufficiently to make that form of storage more efficient, or if the array contains nulls (which may be defined later).

      The new column will be named as "Column n" (where n is the 1-based index of the column) by default, which can be changed by BinaryTable.ColumnDesc.name(String) after.

      Parameters:
      o - A 1D string array, with 1 string element per table row. The array may contain null entries, in which case variable-length columns will be used, since these may be defined later...
      Returns:
      the number of column in the table including the new column.
      Throws:
      FitsException - if the object contains values other than ComplexValue types or if the array is not suitable for storing in the FITS, e.g. because it is multi-dimensional but varying in shape / size.
      Since:
      1.18
      See Also:

    • addBitsColumn

      public int addBitsColumn(Object o) throws FitsException

      Adds a column of bits. This uses much less space than if adding boolean values as logicals (the default behaviot of addColumn(Object), since logicals take up 1 byte per element, whereas bits are really single bits.

      The new column will be named as "Column n" (where n is the 1-based index of the column) by default, which can be changed by BinaryTable.ColumnDesc.name(String) after.

      Parameters:
      o - An any-dimensional array of boolean values.
      Returns:
      the number of column in the table including the new column.
      Throws:
      IllegalArgumentException - if the argument is not an array of boolean values.
      FitsException - if the object is not an array of boolean values.
      Since:
      1.18
      See Also:

    • addColumn

      public int addColumn(BinaryTable.ColumnDesc descriptor) throws IllegalStateException

      Adds a new empty column to the table to the specification. This is useful when the user may want ot have more control on how columns are configured before calling addRow(Object[]) to start populating. The new column will be named as "Column n" (where n is the 1-based index of the column) by default, unless already named otherwise.

      The new column will be named as "Column n" (where n is the 1-based index of the column) by default, which can be changed by BinaryTable.ColumnDesc.name(String) after.

      Parameters:
      descriptor - the column descriptor
      Returns:
      the number of table columns after the addition
      Throws:
      IllegalStateException - if the table already contains data rows that prevent the addition of empty comlumns.
      See Also:

    • addColumn

      public int addColumn(Object o) throws FitsException

      Adds a new column with the specified data array, with some default mappings. This method will always use double-precision representation for ComplexValue-based data, and will represent boolean based array data as one-byte-per element FITS logical values (for back compatibility). It will also store strings as fixed sized (sized for the longest string element contained).

      The new column will be named as "Column n" (where n is the 1-based index of the column) by default, which can be changed by BinaryTable.ColumnDesc.name(String) after.

      If you want other complex-valued representations use addComplexColumn(Object, Class) instead, and if you want to pack boolean-based data more efficiently (using up to 8 times less space), use addBitsColumn(Object) instead, or else convert the column to bits afterwards using convertToBits(int). And, if you want to allow storing strings more effiently in variable-length columns, you should use addStringColumn(String[]) instead.

      As of 1.18, the argument can be a boxed primitive for a coulmn containing a single scalar-valued entry (row).

      Specified by:
      addColumn in interface TableData
      Parameters:
      o - the new column information. it should be either a primitive array, in which each element stores a scalar value for every row, or else an Object[] where type of all of the constituents is identical. Multidimensional data should have the same layout in each row, but varied length one-dimensional arrays are OK. The arrat's length must match the number of rows already contained in the table, unless the table is still empty.
      Returns:
      the number of columns in the adapted table
      Throws:
      FitsException - if the operation failed
      See Also:

    • addVariableSizeColumn

      public int addVariableSizeColumn(Object o) throws FitsException

      Adds a new variable-length data column, populating it with the specified data object. Unlike addColumn(Object) which will use fixed-size data storage provided the data allows it, this method forces the use of variable-sized storage regardless of the data layout -- for example to accommodate addiing rows / elements of different sized at a later time.

      The new column will be named as "Column n" (where n is the 1-based index of the column) by default, which can be changed by BinaryTable.ColumnDesc.name(String) after.

      Parameters:
      o - An array containing one entry per row. Multi-dimensional entries will be flattened to 1D for storage on the heap.
      Returns:
      the number of table columns after the addition.
      Throws:
      FitsException - if the column could not be created as requested.
      Since:
      1.18
      See Also:

    • addFlattenedColumn

      public int addFlattenedColumn(Object o, int... dims) throws FitsException
      Deprecated.
      (for internal use) No longer used, will be removed in the future
      Add a column where the data is already flattened.
      Parameters:
      o - The new column data. This should be a one-dimensional primitive array.
      dims - The dimensions of an element in the column, or null for singleton (scalar) columns
      Returns:
      the new column size
      Throws:
      FitsException - if the array could not be flattened

    • addRow

      public int addRow(Object[] o) throws FitsException

      Adds a row to the table. If this is the first row in a new table, fixed-length columns will be created from the data type automatically. If you want more control over the column formats, you may want to specify columns beforehand such as: 

         BinaryTable table = new BinaryTable();
   
   // A column containing 64-bit floating point scalar values, 1 per row...
   table.addColumn(ColumnDesc.createForScalars(double.class));
   
   // A column containing 5x4 arrays of single-precision complex values...
   table.addColumn(ColumnDesc.createForArrays(ComplexValue.Float.class, 5, 4)
  
   // A column containing Strings of variable length using 32-bit heap pointers...
   table.addColumn(ColumnDesc.creatForVariableStrings(false);

      For scalar columns of primitive types, the argument may be the corresponding java boxed type (new style), or a primitive array of 1 (old style). Thus, you can write either: 

       table.addRow(1, 3.14159265);

      or, 

         table.addRow(new Object[] { new int[] {1}, new double[] {3.14159265} };
      Specified by:
      addRow in interface TableData
      Parameters:
      o - An array of elements to be added. Each element of o should be an array of primitives or a String.
      Returns:
      the number of rows in the adapted table
      Throws:
      FitsException - if the operation failed
      See Also:

    • deleteColumns

      public void deleteColumns(int start, int len) throws FitsException
      Description copied from interface: TableData
      Removes a set of consecutive columns from this table, without updating assocu=iated the header information for the columns that were removed. You should not use this method on tables already in an HDU, since it will not update the HDUs headers. Instead you should always create a new HDU for the table after editing, adding or migrating any custom header entries as necessary after.
      Specified by:
      deleteColumns in interface TableData
      Parameters:
      start - the 0-based index of the first column to remove
      len - the number of subsequent columns to remove
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • deleteRows

      public void deleteRows(int row, int len) throws FitsException
      Description copied from interface: TableData
      Removes a set of consecutive rows from this table without updating any associated header information for an encompassing HDU. You should not use this method on tables already in an HDU, since it will not update the HDUs headers. Instead you should always create a new HDU for the table after editing, adding or migrating any custom header entries as necessary after.
      Specified by:
      deleteRows in interface TableData
      Parameters:
      row - the 0-based index of the first row to remove
      len - the number of subsequent rows to remove
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • getBases

      public Class<?>[] getBases()
      Deprecated.
      (for internal use) Ambiguous, use BinaryTable.ColumnDesc.getElementClass() instead. Will remove in the future.
      Returns the Java type of elements returned or expected by the older srray-based access methods. It can be confusing, because:
      • Columns with variable sized entries report int.class or long.class regardless of data type.
      • Regular logical and bit columns bith report boolean.class.
      • Regular complex valued columns report float.class or double.class.
      Returns:
      the types in the table, not the underlying types (e.g., for varying length arrays or booleans).

    • getColumn

      public Object getColumn(int col) throws FitsException

      Returns the data for a particular column in as an array of elements. See addColumn(Object) for more information about the format of data elements in general.

      Specified by:
      getColumn in interface TableData
      Parameters:
      col - The zero-based column index.
      Returns:
      an array of primitives (for scalar columns), or else an Object[] array, or possibly null
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • indexOf

      public int indexOf(String name)
      Returns the Java index of the first column by the specified name.
      Parameters:
      name - the name of the column (case sensitive).
      Returns:
      The column index, or else -1 if this table does not contain a column by the specified name.
      Since:
      1.20
      See Also:

    • getData

      public ColumnTable<?> getData() throws FitsException
      Description copied from class: Data
      Returns the underlying Java representation of the data contained in this HDU's data segment. Typically it will return a Java array of some kind.
      Overrides:
      getData in class Data
      Returns:
      the underlying Java representation of the data core object, such as a multi-dimensional Java array.
      Throws:
      FitsException - if the data could not be gathered.
      See Also:

    • getDimens

      public int[][] getDimens()
      Deprecated.
      (for internal use) Use BinaryTable.ColumnDesc.getEntryShape() to access the shape of Java elements individually for columns instead. Not useful to users since it returns the dimensions of the primitive storage types, which is not always the dimension of elements on the Java side (notably for string entries).
      Returns the dimensions of elements in each column.
      Returns:
      an array of arrays with the dimensions of each column's data.
      See Also:

    • getFlatColumns

      public Object[] getFlatColumns() throws FitsException
      Deprecated.
      (for internal use) It may be private in the future.
      Returns:
      An array with flattened data, in which each column's data is represented by a 1D array
      Throws:
      FitsException - if the reading of the data failed.

    • getFlattenedColumn

      public Object getFlattenedColumn(int col) throws FitsException
      Deprecated.
      (for internal use) It may be reduced to private visibility in the future.
      Parameters:
      col - the column to flatten
      Returns:
      column in flattened format. This is sometimes useful for fixed-sized columns. Variable-sized columns will still return an Object[] array in which each entry is the variable-length data for a row.
      Throws:
      FitsException - if the column could not be flattened

    • reserveRowSpace

      public void reserveRowSpace(int rows)

      Reserves space for future addition of rows at the end of the regular table. In effect, this pushes the heap to start at an offset value, leaving a gap between the main table and the heap in the FITS file. If your table contains variable-length data columns, you may also want to reserve extra heap space for these via reserveHeapSpace(int).

      Note, that (C)FITSIO, as of version 4.4.0, has no proper support for offset heaps, and so you may want to be careful using this function as the resulting FITS files, while standard, may not be readable by other tools due to their own lack of support. Note, however, that you may also use this function to undo an offset heap with an argument <=0;

      Parameters:
      rows - The number of future rows fow which space should be reserved (relative to the current table size) for future additions, or <=0 to ensure that the heap always follows immediately after the main table, e.g. for better (C)FITSIO interoperability.
      Since:
      1.19.1
      See Also:

    • reserveHeapSpace

      public void reserveHeapSpace(int bytes)
      Reserves space in the file at the end of the heap for future heap growth (e.g. different/longer or new VLA entries). You may generally want to call this along with reserveRowSpace(int) if yuor table contains variable-length columns, to ensure storage for future data in these. You may call with <=0 to discards any previously reserved space.
      Parameters:
      bytes - The number of bytes of unused space to reserve at the end of the heap, e.g. for future modifications or additions, when writing the data to file.
      Since:
      1.19.1
      See Also:

    • getModelRow

      public Object[] getModelRow()
      Deprecated.
      (for internal use) Use getElement(int, int) instead for low-level reading of tables in deferred mode. Not recommended for uses because it requires a deep understanding of how data (especially varialbe length columns) are represented in the FITS. Will reduce visibility to private in the future.
      Returns an empty row for the table. Such model rows are useful when low-level reading binary tables from an input row-by-row. You can simply all ArrayDataInput.readArrayFully(Object) to populate it with data from a stream. You may also use model rows to add additional rows to an existing table.
      Returns:
      a row that may be used for direct i/o to the table.

    • getNCols

      public int getNCols()
      Description copied from interface: TableData
      Returns the number of columns contained in this table.
      Specified by:
      getNCols in interface TableData
      Returns:
      the current number of columns in the table.
      See Also:

    • getNRows

      public int getNRows()
      Description copied from interface: TableData
      Returns the number of columns contained in this table.
      Specified by:
      getNRows in interface TableData
      Returns:
      the current number of columns in the table.
      See Also:

    • getRawElement

      public Object getRawElement(int row, int col) throws FitsException
      Deprecated.
      (for internal use) Will reduce visibility in the future.
      Returns an unprocessed element from the table as a 1D array of the elements that are stored in the regular table data, whithout reslving heap references. That is this call will return flattened versions of multidimensional arrays, and will return only the heap locator (offset and size) for variable-sized columns.
      Parameters:
      row - The row of the element.
      col - The column of the element.
      Returns:
      a particular element from the table but do no processing of this element (e.g., dimension conversion or extraction of variable length array elements/)
      Throws:
      FitsException - if the operation failed

    • getElement

      public Object getElement(int row, int col) throws FitsException
      Returns a table element as a Java array. Consider using the more Java-friendly get(int, int) or one of the scalar access methods with implicit type conversion support.
      Specified by:
      getElement in interface TableData
      Parameters:
      row - the 0-based row index of the element
      col - the 0-based column index of the element
      Returns:
      A primitive array containing the data for the the specified (row, col) entry in the table.
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • getArrayElement

      public Object getArrayElement(int row, int col)
      Returns a table element as an array of the FITS storage type. Similar to the original getElement(int, int), except that FITS logicals are returned as arrays of Boolean (rather than boolean), bits are returned as arrays of boolean, and complex values are returned as arrays of ComplexValue rather than arrays of double[2] or float[2]. Singleton (scalar) table elements are not boxed to an enclosing Java type (unlike get(int, int)), an instead returned as arrays of just one element. For example, a single logical as a Boolean[1], a single float as a float[1] or a single double-precision complex value as ComplexValue[1].
      Parameters:
      row - zero-based row index
      col - zero-based column index
      Returns:
      The table entry as an array of the stored Java type, without applying any type or quantization conversions.
      Since:
      1.20
      See Also:

    • getArrayElementAs

      public Object getArrayElementAs(int row, int col, Class<?> asType) throws IllegalArgumentException

      Returns a numerical table element as an array of a specific underlying other numerical type. Similar getArrayElement(int, int) except that table entries are converted to the specified array type before returning. If an integer-decimal conversion is involved, it will be performed through the column's quantizer (if any) or else via a simple rounding as necessary.

      For example, if you have an short-type column, and you want is an array of double values that are represented by the 16-bit integers, then the conversion will use the column's quantizer scaling and offset before returning the result either as an array of doubles, and the designated short blanking values will be converted to NaNs.

      Parameters:
      row - zero-based row index
      col - zero-based column index
      asType - The desired underlying type, a primitive class or a ComplexValue type for appropriate numerical arrays (with a trailing Java dimension of 2 for the real/imaginary pairs).
      Returns:
      An array of the desired type (e.g. double[][] if asType is double.class and the column contains 2D arrays of some numerical type).
      Throws:
      IllegalArgumentException - if the numerical conversion is not possible for the given column type or if the type argument is not a supported numerical primitive or ComplexValue type.
      Since:
      1.20
      See Also:

    • get

      public Object get(int row, int col) throws FitsException

      Returns a table element using the usual Java boxing for primitive scalar (singleton) entries, or packaging complex values as ComplexValue, or as appropriate primitive or object arrays. FITS string columns return String values. Logical (boolean columns will return a Boolean, which may be null if undefined (as per the FITS standard). Multibit FITS bits colums return arrays of boolean.

      As opposed to getElement(int, int) scalar (singleton) values are not wrapped into primitive arrays, but return either a singular object, such as a (String, or a ComplexValue, or a boxed Java primitive. Thus, columns containing single short entries will return the selected element as a Short, or columns containing single double values will return the element as a Double and so on.

      Array columns will return the expected arrays of primitive values, or arrays of one of the mentioned types. Note however, that logical arrays are returned as arrays of Boolean, e.g. Boolean[][], not boolean[][]. This is because FITS allows null values for logicals beyond true and false, which is reproduced by the boxed type, but not by the primitive type. FITS columns of bits (generally preferrably to logicals if support for null values is not required) will return arrays of boolean.

      Columns containing multidimensional arrays, will return the expected multidimensional array of the above mentioned types for the FITS storage type. You can then convert numerical arrays to other types as required for your application via ArrayFuncs.convertArray(Object, Class, Quantizer), including any appropriate quantization for the colummn (see BinaryTable.ColumnDesc.getQuantizer()).

      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      Returns:
      the element, either as a Java boxed type (for scalar entries), a singular Java Object, or as a (possibly multi-dimensional) array of String, Boolean, ComplexValue, or primitives.
      Throws:
      FitsException - if the element could not be obtained
      Since:
      1.18
      See Also:

    • getNumber

      public final Number getNumber(int row, int col) throws FitsException, ClassCastException, NumberFormatException
      Returns the numerical value, if possible, for scalar elements. Scalar numerical columns return the boxed type of their primitive type. Thus, a column of long values will return Long, whereas a column of float values will return a Float. Logical columns will return 1 if true or 0 if false, or null if undefined. Array columns and other column types will throw an exception.
      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      Returns:
      the number value of the specified scalar entry
      Throws:
      FitsException - if the element could not be obtained
      ClassCastException - if the specified column in not a numerical scalar type.
      NumberFormatException - if the it's a string column but the entry does not seem to be a number
      Since:
      1.18
      See Also:

    • getDouble

      public final double getDouble(int row, int col) throws FitsException, ClassCastException

      Returns the decimal value, if possible, of a scalar table entry. See getNumber(int, int) for more information on the conversion process.

      Since version 1.20, if the column has a quantizer and stores integer elements, the conversion to double-precision will account for the quantization of the column, if any, and will return NaN if the stored integer is the designated blanking value (if any). To bypass quantization, you can use getNumber(int, int) instead followed by Number.doubleValue() to to get the stored integer values as a double.

      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      Returns:
      the number value of the specified scalar entry
      Throws:
      FitsException - if the element could not be obtained
      ClassCastException - if the specified column in not a numerical scalar type.
      Since:
      1.18
      See Also:

    • getLong

      public final long getLong(int row, int col) throws FitsException, ClassCastException, IllegalStateException

      Returns a 64-bit integer value, if possible, of a scalar table entry. Boolean columns will return 1 if true or 0 if false, or throw a NullPointerException if undefined. See getNumber(int, int) for more information on the conversion process of the stored data element.

      Additionally, since version 1.20, if the column has a quantizer and stores floating-point elements, the conversion to integer will include the quantization, and NaN values will be converted to the designated integer blanking values. To bypass quantization, you can use getNumber(int, int) instead followed by Number.longValue() to to get the stored floating point values rounded directly to a long.

      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      Returns:
      the 64-bit integer number value of the specified scalar table entry.
      Throws:
      FitsException - if the element could not be obtained
      ClassCastException - if the specified column in not a numerical scalar type.
      IllegalStateException - if the column contains a undefined (blanking value), such as a Double.NaN when no quantizer is set for the column, or a Boolean null value.
      Since:
      1.18
      See Also:

    • getLogical

      public final Boolean getLogical(int row, int col) throws FitsException, ClassCastException
      Returns the boolean value, if possible, for scalar elements. It will will returntrue, or false, or null if undefined. Numerical columns will return null if the corresponding decimal value is NaN, or false if the value is 0, or else true for all non-zero values (just like in C).
      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      Returns:
      the boolean value of the specified scalar entry, or null if undefined.
      Throws:
      ClassCastException - if the specified column in not a scalar boolean type.
      FitsException - if the element could not be obtained
      Since:
      1.18
      See Also:

    • getString

      public final String getString(int row, int col) throws FitsException, ClassCastException
      Returns the string value, if possible, for scalar elements. All scalar columns will return the string representation of their values, while byte[] and char[] are converted to appropriate strings.
      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      Returns:
      the string representatiof the specified table entry
      Throws:
      ClassCastException - if the specified column contains array elements other than byte[] or char[]
      FitsException - if the element could not be obtained
      Since:
      1.18
      See Also:

    • getRow

      public Object[] getRow(int row) throws FitsException
      Description copied from interface: TableData
      Returns an array of elements in a particualr table row. See TableData.getElement(int, int) for more information about the format of each element in the row.
      Specified by:
      getRow in interface TableData
      Parameters:
      row - the 0-based row index
      Returns:
      an object containing the row data (for all column) of the specified row, or possubly null. See TableData.getElement(int, int) for more information about the format of each element in the row.
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • getSizes

      public int[] getSizes()
      Deprecated.
      (for internal use) Use BinaryTable.ColumnDesc.getElementCount() instead. This one returns the number of elements in the FITS representation, not in the java representation. For example, for String entries, this returns the number of bytes stored, not the number of strings. Similarly, for complex values it returns the number of components not the number of values.
      Returns the flattened (1D) size of elements in each column of this table. As of 1.18, this method returns a copy ot the array used internally, which is safe to modify.
      Returns:
      an array with the byte sizes of each column

    • getTypes

      public char[] getTypes()
      Deprecated.
      (for internal use) Use BinaryTable.ColumnDesc.getElementClass() instead. Not very useful to users since this returns the FITS primitive storage type for the data column.
      Get the characters describing the base classes of the columns. As of 1.18, this method returns a copy ot the array used internally, which is safe to modify.
      Returns:
      An array of type characters (Java array types), one for each column.

    • setColumn

      public void setColumn(int col, Object o) throws FitsException
      Description copied from interface: TableData
      Sets new data for a table column. See TableData.addColumn(Object) for more information on the column data format.
      Specified by:
      setColumn in interface TableData
      Parameters:
      col - the 0-based column index
      o - an object containing the new column data (for all rows) of the specified column. See TableData.getColumn(int) for more information on the column data format.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • setElement

      public void setElement(int row, int col, Object o) throws FitsException
      Consider using the more Java-friendly set(int, int, Object) with implicit scalar type conversions.
      Specified by:
      setElement in interface TableData
      Parameters:
      row - the 0-based row index of the element
      col - the 0-based column index of the element
      o - the new element at the specified table location as a primitive array.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • set

      public void set(int row, int col, Object o) throws FitsException, IllegalArgumentException

      The Swiss-army knife of setting table entries, including Java boxing, and with some support for automatic type conversions. The argument may be one of the following type:

      For array-type columns the argument needs to match the column type exactly. However, you may call ArrayFuncs.convertArray(Object, Class, Quantizer) prior to setting values to convert arrays to the desired numerical types, including the quantization that is appropriate for the column (see BinaryTable.ColumnDesc.getQuantizer()).

      For scalar (single element) columns, automatic type conversions may apply, to make setting scalar columns more flexible:

      • Any numerical column can take any Number value. The conversion is as if an explicit Java cast were applied. For example, if setting a double value for a column of single short values it as if a (short) cast were applied to the value.
      • Numerical colums can also take Boolean values which set the entry to 1, or 0, or to Double.isNaN() (or the equivalent integer minimum value) if the argument is null. Numerical columns can also set String values, by parsing the string according to the numerical type of the column.
      • Logical columns can set Boolean values, including nullvalues, but also any Number type. In case of numbers, zero values map to false while definite non-zero values map to true. Double.isNaN() maps to a null (or undefined) entry. Loginal columns can be also set to the String values of 'true' or 'false', or to a Character of 'T'/'F' (or equivalently '1'/'0') and 0 (undefined)
      • Singular string columns can be set to any scalar type owing to Java's Object.toString() method performing the conversion, as long as the string representation fits into the size constraints (if any) for the string column.

      Additionally, scalar columns can take single-element array arguments, just like setElement(int, int, Object).

      Parameters:
      row - the zero-based row index
      col - the zero-based column index
      o - the new value to set. For array columns this must match the Java array type exactly, but for scalar columns additional flexibility is provided for fuzzy type matching (see description above).
      Throws:
      FitsException - if the column could not be set
      IllegalArgumentException - if the argument cannot be converted to a value for the specified column type.
      Since:
      1.18
      See Also:

    • setFlattenedColumn

      public void setFlattenedColumn(int col, Object data) throws FitsException
      Deprecated.
      (for internal use) It may be reduced to private visibility in the future. Sets a column with the data already flattened.
      Parameters:
      col - The index of the column to be replaced.
      data - The new data array. This should be a one-d primitive array.
      Throws:
      FitsException - Thrown if the type of length of the replacement data differs from the original.

    • setRow

      public void setRow(int row, Object[] data) throws FitsException
      Description copied from interface: TableData
      Sets new data for a table row. See TableData.getElement(int, int) for more information about the format of elements.
      Specified by:
      setRow in interface TableData
      Parameters:
      row - the 0-based row index
      data - an object containing the row data (for all column) of the specified row. See TableData.getElement(int, int) for more information about the format of each element in the row.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • updateAfterDelete

      public void updateAfterDelete(int oldNcol, Header hdr) throws FitsException
      Deprecated.
      It is not entirely foolproof for keeping the header in sync -- it is better to (re)wrap tables in a new HDU after column deletions, and then edit the new header as necessary to incorporate custom entries. May be removed from the API in the future.
      Description copied from interface: TableData
      Updates the table dimensions in the header following deletion. Whoever calls TableData.deleteColumns(int, int) on this table should call this method after the deletion(s), at least once after all desired column deletions have been processed).
      Specified by:
      updateAfterDelete in interface TableData
      Parameters:
      oldNcol - The number of columns in the table before the first call to TableData.deleteColumns(int, int).
      hdr - The table header
      Throws:
      FitsException - if the header could not be updated

    • write

      public void write(ArrayDataOutput os) throws FitsException
      Description copied from interface: FitsElement
      Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.
      Specified by:
      write in interface FitsElement
      Specified by:
      write in class Data
      Parameters:
      os - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.

    • read

      public void read(ArrayDataInput in) throws FitsException
      Description copied from class: Data

      Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.

      In case the argument is a an instance of RandomAccess input (such as a FitsFile, the call will simply note where in the file the data segment can be found for reading at a later point, only when the data content is accessed. This 'deferred' reading behavior make it possible to process large HDUs even with small amount of RAM, and can result in a significant performance boost when inspectring large FITS files, or using only select content from large FITS files.

      Specified by:
      read in interface FitsElement
      Overrides:
      read in class Data
      Parameters:
      in - The input data stream
      Throws:
      PaddingException - if there is missing padding between the end of the data segment and the enf-of-file.
      FitsException - if the data appears to be corrupted.
      See Also:

    • getDescriptor

      public static BinaryTable.ColumnDesc getDescriptor(Header header, int col) throws FitsException
      Extracts a column descriptor from the FITS header for a given column index
      Parameters:
      header - the FITS header containing the column description(s)
      col - zero-based column index
      Returns:
      the Descriptor for that column.
      Throws:
      FitsException - if the header deswcription is invalid or incomplete

    • fillHeader

      public void fillHeader(Header h) throws FitsException
      Deprecated.
      (for internal use) Visibility should be reduced to protected.
      Throws:
      FitsException

    • getDescriptor

      public BinaryTable.ColumnDesc getDescriptor(int column) throws ArrayIndexOutOfBoundsException
      Returns the column descriptor of a given column in this table
      Parameters:
      column - the zero-based column index
      Returns:
      the column's descriptor
      Throws:
      ArrayIndexOutOfBoundsException - if this table does not contain a column with that index.
      See Also:

    • getDescriptor

      public BinaryTable.ColumnDesc getDescriptor(String name)
      Returns the (first) column descriptor whose name matches the specified value.
      Parameters:
      name - The column name (case sensitive).
      Returns:
      The descriptor of the first column by that name, or null if the table contains no column by that name.
      Since:
      1.20
      See Also:

    • convertToBits

      public boolean convertToBits(int col)
      Converts a column from FITS logical values to bits. Null values (allowed in logical columns) will map to false.
      Parameters:
      col - The zero-based index of the column to be reset.
      Returns:
      Whether the conversion was possible. *
      Since:
      1.18

    • setComplexColumn

      public boolean setComplexColumn(int index) throws FitsException
      Convert a column from float/double to float complex/double complex. This is only possible for certain columns. The return status indicates if the conversion is possible.
      Parameters:
      index - The zero-based index of the column to be reset.
      Returns:
      Whether the conversion is possible. *
      Throws:
      FitsException - if the operation failed
      Since:
      1.18
      See Also:

    • containsHeap

      public final boolean containsHeap()
      Checks if this table contains a heap for storing variable length arrays (VLAs).
      Returns:
      true if the table contains a heap, or else false.
      Since:
      1.19.1

    • defragment

      public long defragment() throws FitsException

      Defragments the heap area of this table, compacting the heap area, and returning the number of bytes by which the heap size has been reduced. When tables with variable-sized columns are modified, the heap may retain old data as columns are removed or elements get replaced with new data of different size. The data order in the heap may also get jumbled, causing what would appear to be sequential reads to jump all over the heap space with the caching. And, depending on how the heap was constructed in the first place, it may not be optimal for the row-after-row table access that is the most typical use case.

      This method rebuilds the heap by taking elements in table read order (by rows, and columns) and puts them on a new heap.

      For best squential read performance, you should defragment all tables that have been built column-by-column before writing them to a FITS file. The only time defragmentation is really not needed is if the table was built row-by-row, with no modifications to variable-length content after the fact.

      Returns:
      the number of bytes by which the heap has shrunk as a result of defragmentation.
      Throws:
      FitsException - if there was an error accessing the heap or the main data table comntaining the heap locators. In case of an error the table content may be left in a damaged state.
      Since:
      1.18
      See Also:

    • compact

      public void compact()
      Discard the information about the original heap size (if this table was read from an input), and instead use the real size of the actual heap (plus reserved space around it) when writing to an output. Compacted tables may not be re-writeable to the same file from which they were read, since they may be shorter than the original, but they can always be written to a different file, which may at times be smaller than the original. It may be used along with defragment() to create FITS files with optimized storage from FITS files that may contain wasted space.
      Since:
      1.19.1
      See Also:

    • toHDU

      public BinaryTableHDU toHDU() throws FitsException
      Description copied from class: Data
      Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
      Specified by:
      toHDU in class Data
      Returns:
      a HDU object ocntaining the data and its minimal required header description
      Throws:
      FitsException - If the data cannot be converted to an HDU for some reason.