Class FitsConstants


  • public class FitsConstants
    extends java.lang.Object
    Utility class providing some constants and static methods related to FITS file format and starlink classes.
    Author:
    Mark Taylor (Starlink)
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static nom.tam.fits.HeaderCard END_CARD
      Image of end-of-header card.
      static int FITS_BLOCK
      Standard size of a FITS block in bytes.
      static int MAX_NCOLSTD
      Maximum number of columns in standard FITS BINTABLE extension.
      static java.lang.String NDARRAY_ORIGIN
      FITS header card for indicating NDArray origin values.
      static java.lang.String NDARRAY_PREFIX
      Prefix for NDArray-related FITS header cards.
      static java.lang.String NDX_PREFIX
      Prefix for NDX-related FITS header cards.
      static java.lang.String NDX_XML
      FITS header card for location (relative URL) of XML representation.
      static boolean REQUIRE_HIERARCH
      Whether HIERARCH convention is used; true by default.
      static java.lang.String WCS_ENCODING
      Default encoding used for writing WCS into FITS headers.
    • Constructor Summary

      Constructors 
      Constructor Description
      FitsConstants()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void addStringValue​(nom.tam.fits.Header hdr, java.lang.String key, java.lang.String value, java.lang.String comment)
      Attempts to add a string-valued card to the header.
      static void addTrimmedValue​(nom.tam.fits.Header hdr, java.lang.String key, java.lang.String value, java.lang.String comment)
      Adds a string-valued card to the header.
      static void checkColumnCount​(WideFits wide, int ncol)
      Checks that a table with the given number of columns can be written.
      static void configureHierarch()
      Ensures that use of the HIERARCH convention when dealing with FITS headers is set to the state expected for STIL operation.
      static nom.tam.fits.HeaderCard createHeaderCard​(java.lang.String cardImage)
      Create a HeaderCard from a FITS card image.
      static nom.tam.fits.Header createUnsortedHeader()
      Creates a Header instance which does not perform any unsolicited reordering of the header cards.
      static java.util.List<java.lang.String> defaultFitsExtensions()
      Gets the default permitted list of extensions which identify a FITS resource in the path part of a URL.
      static long getDataSize​(nom.tam.fits.Header hdr)
      Utility function to find the number of bytes in the data segment of an HDU.
      static nom.tam.util.ArrayDataInput getInputStreamStart​(uk.ac.starlink.util.DataSource datsrc)
      Returns an input stream which can be used with the various FITS classes based on a given DataSource object, positioned at the start of the stream.
      static java.lang.Iterable<nom.tam.fits.HeaderCard> headerIterable​(nom.tam.fits.Header hdr)
      Returns an iterable over HeaderCards for a given Header.
      static boolean isMagic​(byte[] buffer)
      Indicates whether the supplied buffer is the start of a FITS file.
      static int readHeader​(nom.tam.fits.Header hdr, nom.tam.util.ArrayDataInput strm)
      Populates a header from an input stream, reporting its length in bytes.
      static long skipHDUs​(nom.tam.util.ArrayDataInput stream, int nskip)
      Skips forward over a given number of HDUs in the supplied stream.
      static void writeEmptyPrimary​(java.io.DataOutput strm)
      Writes a null header representing an empty primary HDU to a stream.
      static void writeHeader​(java.io.DataOutput strm, nom.tam.fits.Header hdr)
      Writes a header object to a DataOutput.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NDARRAY_PREFIX

        public static final java.lang.String NDARRAY_PREFIX
        Prefix for NDArray-related FITS header cards.
        See Also:
        Constant Field Values
      • END_CARD

        public static final nom.tam.fits.HeaderCard END_CARD
        Image of end-of-header card.
      • NDARRAY_ORIGIN

        public static final java.lang.String NDARRAY_ORIGIN
        FITS header card for indicating NDArray origin values. An integer (1, 2, ... ) is appended to this value for the different axes like for NAXIS.
        See Also:
        Constant Field Values
      • NDX_PREFIX

        public static final java.lang.String NDX_PREFIX
        Prefix for NDX-related FITS header cards.
        See Also:
        Constant Field Values
      • NDX_XML

        public static final java.lang.String NDX_XML
        FITS header card for location (relative URL) of XML representation.
        See Also:
        Constant Field Values
      • WCS_ENCODING

        public static final java.lang.String WCS_ENCODING
        Default encoding used for writing WCS into FITS headers.
        See Also:
        Constant Field Values
      • FITS_BLOCK

        public static final int FITS_BLOCK
        Standard size of a FITS block in bytes.
        See Also:
        Constant Field Values
      • MAX_NCOLSTD

        public static final int MAX_NCOLSTD
        Maximum number of columns in standard FITS BINTABLE extension.
        See Also:
        Constant Field Values
      • REQUIRE_HIERARCH

        public static boolean REQUIRE_HIERARCH
        Whether HIERARCH convention is used; true by default.
    • Constructor Detail

      • FitsConstants

        public FitsConstants()
    • Method Detail

      • defaultFitsExtensions

        public static java.util.List<java.lang.String> defaultFitsExtensions()
        Gets the default permitted list of extensions which identify a FITS resource in the path part of a URL.
        Returns:
        unmodifiable list of default FITS extensions - ".fits", ".fit" etc
      • configureHierarch

        public static void configureHierarch()
        Ensures that use of the HIERARCH convention when dealing with FITS headers is set to the state expected for STIL operation. If this involves changing the current setting, a warning is issued through the logging system.

        The general idea is that this is only issued once per JVM. If other components are resetting the hierarch handling that might not be enough, but there's no mechanism to ensure that it stays set anyway.

        The main reason this is necessary is that WideFits handling requires HIERARCH, but there is no per-call configuration of whether the convention is in use, so it has to be set on a global basis.

      • createUnsortedHeader

        public static nom.tam.fits.Header createUnsortedHeader()
        Creates a Header instance which does not perform any unsolicited reordering of the header cards. Some versions of nom.tam.fits force the EXTEND keyword to go directly after the NAXISn keywords. That screws up specification of the FITS-plus magic number, which is expected to have VOTMETA directly after NAXISn. Headers created using this method will leave header cards in the order they are added.
        Returns:
        new empty header
        See Also:
        nom.tam.fits github discussion
      • createHeaderCard

        public static nom.tam.fits.HeaderCard createHeaderCard​(java.lang.String cardImage)
        Create a HeaderCard from a FITS card image.
        Parameters:
        cardImage - the 80 character card image
        Returns:
        card object
      • headerIterable

        public static java.lang.Iterable<nom.tam.fits.HeaderCard> headerIterable​(nom.tam.fits.Header hdr)
        Returns an iterable over HeaderCards for a given Header.
        Parameters:
        hdr - header
        Returns:
        iterable over hdr's cards
      • skipHDUs

        public static long skipHDUs​(nom.tam.util.ArrayDataInput stream,
                                    int nskip)
                             throws java.io.IOException
        Skips forward over a given number of HDUs in the supplied stream. If it reaches the end of the stream, it throws an IOException with a Cause of a TruncatedFileException.
        Parameters:
        stream - the stream to skip through
        nskip - the number of HDUs to skip
        Returns:
        the number of bytes the stream was advanced
        Throws:
        java.io.IOException
      • isMagic

        public static boolean isMagic​(byte[] buffer)
        Indicates whether the supplied buffer is the start of a FITS file. Its contents is checked against the FITS 'magic number', which is the ASCII string "SIMPLE  =".
        Parameters:
        buffer - a byte buffer containing the start of a file to test
        Returns:
        true iff the bytes in buffer look like the start of a FITS file
      • getInputStreamStart

        public static nom.tam.util.ArrayDataInput getInputStreamStart​(uk.ac.starlink.util.DataSource datsrc)
                                                               throws java.io.IOException
        Returns an input stream which can be used with the various FITS classes based on a given DataSource object, positioned at the start of the stream.
        Parameters:
        datsrc - the DataSource pointing to the file/HDU required
        Returns:
        an ArrayDataInput acquired from datsrc,
        Throws:
        java.io.IOException
      • readHeader

        public static int readHeader​(nom.tam.fits.Header hdr,
                                     nom.tam.util.ArrayDataInput strm)
                              throws nom.tam.fits.TruncatedFileException,
                                     java.io.IOException
        Populates a header from an input stream, reporting its length in bytes. This does the same as Header.read(nom.tam.util.ArrayDataInput), but it returns the number of bytes read from the input stream in order to populate the header (including any padding bytes). There is no way to retrieve this information from the Header class in general; though Header.getSize() will sometimes give you the right answer, in the case of duplicated header keywords it can give an underestimate. This could be seen as a bug in nom.tam.fits classes, but there may be code somewhere which relies on that behaviour.

        You can make a Header from scratch by doing

             Header hdr = new Header();
             int headsize = read( hdr, strm );
         
        This method also differs from the Header implementation in that it does not print warnings to standard output about duplicate keywords.
        Parameters:
        hdr - the header to populate
        strm - the input stream supplying the data
        Returns:
        the number of bytes in the FITS blocks which comprise the header content
        Throws:
        nom.tam.fits.TruncatedFileException
        java.io.IOException
        See Also:
        Header.read(nom.tam.util.ArrayDataInput)
      • writeHeader

        public static void writeHeader​(java.io.DataOutput strm,
                                       nom.tam.fits.Header hdr)
                                throws java.io.IOException
        Writes a header object to a DataOutput.
        Parameters:
        strm - destination stream
        hdr - the header to write
        Throws:
        java.io.IOException
      • writeEmptyPrimary

        public static void writeEmptyPrimary​(java.io.DataOutput strm)
                                      throws java.io.IOException
        Writes a null header representing an empty primary HDU to a stream.
        Parameters:
        strm - stream to write to
        Throws:
        java.io.IOException
      • getDataSize

        public static long getDataSize​(nom.tam.fits.Header hdr)
        Utility function to find the number of bytes in the data segment of an HDU. As far as I can see, Header.getDataSize() ought to do this, but it doesn't seem to.
        Parameters:
        hdr - the Header
        Returns:
        the number of bytes in the data segment associated with hdr
      • addTrimmedValue

        public static void addTrimmedValue​(nom.tam.fits.Header hdr,
                                           java.lang.String key,
                                           java.lang.String value,
                                           java.lang.String comment)
                                    throws nom.tam.fits.HeaderCardException
        Adds a string-valued card to the header. If the value is too long, it is truncated appropriately, and a warning is emitted through the logging system.
        Parameters:
        hdr - header
        key - card key
        value - card value
        comment - card comment
        Throws:
        nom.tam.fits.HeaderCardException
      • addStringValue

        public static void addStringValue​(nom.tam.fits.Header hdr,
                                          java.lang.String key,
                                          java.lang.String value,
                                          java.lang.String comment)
        Attempts to add a string-valued card to the header. If the value is too long, no header is added, and a message is emitted through the logging system.
        Parameters:
        hdr - header
        key - card key
        value - card value
        comment - card comment
      • checkColumnCount

        public static void checkColumnCount​(WideFits wide,
                                            int ncol)
                                     throws java.io.IOException
        Checks that a table with the given number of columns can be written. If the column count is not exceeded, nothing happens, but if there are too many columns an informative IOException is thrown.
        Parameters:
        wide - extended column convention - may be null for FITS standard behaviour only
        ncol - number of columns to write
        Throws:
        java.io.IOException - if there are too many columns