Interface WideFits

  • All Known Implementing Classes:
    AbstractWideFits

    public interface WideFits
    Defines a convention for storing extended column data in a FITS BINTABLE extension. The general idea assumes storing the BINTABLE data as if there were no 999 column limit, with a container column containing the byte data for all the extended columns and some non-standard way to record column metadata for the columns beyond the container. For practical purposes it only makes sense to use a container column index of 999, the maximum allowed standard column index allowed by FITS BINTABLE. But the interface provides the option to use a smaller value, perhaps for testing purposes.

    There are various options for filling in the details, in particular how the metadata for the extended columns is stored in the FITS headers. These are defined by the implementation(s) in the AbstractWideFits class.

    This convention is based on an idea suggested by William Pence on the FITSBITS list in June 2012, and by Francois-Xavier Pineau (CDS) in 2016. It was discussed at some length on the FITSBITS mailing list in July 2017 in the thread BINTABLE convention for >999 columns

    Since:
    27 Jul 2017
    Author:
    Mark Taylor
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static WideFits DEFAULT
      Default WideFits instance; currently TFORMaaa using column 999.
      static int MAX_NCOLSTD
      Maximum number of standard columns, imposed by FITS standard (999).
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addContainerColumnHeader​(nom.tam.fits.Header hdr, long nbyteExt, long nslice)
      Adds the per-HDU header cards that describe the single container column (with index icolContainer) used to implement this convention in a BINTABLE HDU.
      void addExtensionHeader​(nom.tam.fits.Header hdr, int ncolExt)
      Adds the per-HDU header cards that announce the operation of this convention in a BINTABLE HDU.
      BintableColumnHeader createExtendedHeader​(int icolContainer, int jcol)
      Creates a BintableColumnHeader instance suitable for use with the extended column convention defined by this class.
      int getContainerColumnIndex()
      Returns the index of the column used (if any) by this specification for extended column data.
      int getExtColumnMax()
      Maximum extended number of columns that can be represented by this convention.
      int getExtendedColumnCount​(HeaderCards cards, int ncolStd)
      Returns the total number of columns, including extended ones, described by a FITS header according to this convention.
    • Field Detail

      • MAX_NCOLSTD

        static final int MAX_NCOLSTD
        Maximum number of standard columns, imposed by FITS standard (999).
        See Also:
        Constant Field Values
      • DEFAULT

        static final WideFits DEFAULT
        Default WideFits instance; currently TFORMaaa using column 999.
    • Method Detail

      • getContainerColumnIndex

        int getContainerColumnIndex()
        Returns the index of the column used (if any) by this specification for extended column data. The result is the FITS column index, so the first column in the table is 1. This value is equal to the number of standard columns if extended columns are included.

        Under normal circumstances, this returns 999 (MAX_NCOLSTD).

        Returns:
        1-based index of container column
      • getExtColumnMax

        int getExtColumnMax()
        Maximum extended number of columns that can be represented by this convention. This value includes the standard columns.
        Returns:
        maximum extended column count
      • addExtensionHeader

        void addExtensionHeader​(nom.tam.fits.Header hdr,
                                int ncolExt)
        Adds the per-HDU header cards that announce the operation of this convention in a BINTABLE HDU.
        Parameters:
        hdr - header to append to
        ncolExt - total column count including extended
      • addContainerColumnHeader

        void addContainerColumnHeader​(nom.tam.fits.Header hdr,
                                      long nbyteExt,
                                      long nslice)
        Adds the per-HDU header cards that describe the single container column (with index icolContainer) used to implement this convention in a BINTABLE HDU.
        Parameters:
        hdr - header to append to
        nbyteExt - number of bytes per row in container column
        nslice - if >0 this will result in a TDIMnnn header that gives a 2-element shape, with the supplied value being the second element; if you don't want TDIMnnn, use 0
      • getExtendedColumnCount

        int getExtendedColumnCount​(HeaderCards cards,
                                   int ncolStd)
        Returns the total number of columns, including extended ones, described by a FITS header according to this convention.
        Parameters:
        cards - FITS header
        ncolStd - number of 'standard' BINTABLE columns, got from TFIELDS header
        Returns:
        extended number of columns, includes standard ones
      • createExtendedHeader

        BintableColumnHeader createExtendedHeader​(int icolContainer,
                                                  int jcol)
        Creates a BintableColumnHeader instance suitable for use with the extended column convention defined by this class.
        Parameters:
        icolContainer - 1-based index of container column used for storing extended column data
        jcol - 1-based column index for an extended column
        Returns:
        new column header instance