uk.ac.starlink.fits

## Class FitsUtil

- java.lang.Object
- - uk.ac.starlink.fits.FitsUtil

-     public class FitsUtil
      extends java.lang.Object

  Utilities for working with FITS files.
  Since:
    4 Mar 2022

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BLOCK_LENG` FITS block length in bytes (2880).
    `static int` | `CARD_LENG` FITS header card length in bytes (80).
    `static int` | `CARDS_PER_BLOCK` Number of header cards per FITS block (36).
    `static java.lang.String` | `FLOAT_REGEX` Regex pattern matching floating point value, no grouping.
    `static int` | `MAX_NCOLSTD` Maximum No.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.Object` | `asNumericArray(java.lang.String txt)` Attempts to interpret a string as a formatted numeric array.
    `static void` | `checkColumnCount(WideFits wide, int ncol)` Checks that a table with the given number of columns can be written.
    `static boolean` | `isFitsCharacter(int ch)` Indicates whether a given character is a legal FITS header character (0x20..0x7e inclusive).
    `static boolean` | `isMagic(byte[] buffer)` Indicates whether the supplied buffer is the start of a FITS file.
    `static boolean` | `matchesHeaderName(FitsHeader hdr, java.lang.String name)` Indicates whether the header has a given name.
    `static ParsedCard<?>` | `parseCard(byte[] buf80)` Turns an 80-byte array into a ParsedCard.
    `static FitsHeader` | `readHeader(java.io.InputStream in)` Reads a FITS header from an input stream.
    `static FitsHeader` | `readHeaderIfPresent(java.io.InputStream in)` Reads a FITS header from an input stream if the stream has content.
    `static long` | `roundUp(long value, int blockSize)` Utility method to round an integer value up to a multiple of a given block size.
    `static long` | `skipHDUs(java.io.InputStream in, int nskip)` Skips forward over a given number of HDUs in the supplied stream.
    `static void` | `writeEmptyPrimary(java.io.OutputStream out)` Writes a data-less Primary HDU.
    `static int` | `writeHeader(CardImage[] cards, java.io.OutputStream out)` Writes a FITS header whose content is supplied by an array of cards.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### BLOCK_LENG

          public static final int BLOCK_LENG

      FITS block length in bytes (2880).
      See Also:
        Constant Field Values

    - #### CARD_LENG

          public static final int CARD_LENG

      FITS header card length in bytes (80).
      See Also:
        Constant Field Values

    - #### CARDS_PER_BLOCK

          public static final int CARDS_PER_BLOCK

      Number of header cards per FITS block (36).
      See Also:
        Constant Field Values

    - #### MAX_NCOLSTD

          public static final int MAX_NCOLSTD

      Maximum No. of columns in standard FITS BINTABLE extension (999).
      See Also:
        Constant Field Values

    - #### FLOAT_REGEX

          public static final java.lang.String FLOAT_REGEX

      Regex pattern matching floating point value, no grouping.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### 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

    - #### isFitsCharacter

          public static boolean isFitsCharacter(int ch)

      Indicates whether a given character is a legal FITS header character (0x20..0x7e inclusive).
      Parameters:
        `ch` - character to check
      Returns:
        true iff ch is legal for inclusion in a FITS header

    - #### readHeader

          public static FitsHeader readHeader(java.io.InputStream in)
                                       throws java.io.IOException

      Reads a FITS header from an input stream. The stream is read until the end of the last header block. If the stream is positioned at its end on entry, or if there is any error in reading or parsing the header, an IOException is raised.
      Parameters:
        `in` - input stream positioned at start of HDU
      Returns:
        header, not null
      Throws:
        `java.io.IOException`

    - #### readHeaderIfPresent

          public static FitsHeader readHeaderIfPresent(java.io.InputStream in)
                                                throws java.io.IOException

      Reads a FITS header from an input stream if the stream has content. The stream is read until the end of the last header block. If the stream is positioned at its end on entry, null is returned.
      Parameters:
        `in` - input stream positioned where an HDU may start
      Returns:
        header, or null if the stream has no content
      Throws:
        `java.io.IOException`

    - #### parseCard

          public static ParsedCard<?> parseCard(byte[] buf80)

      Turns an 80-byte array into a ParsedCard. This will always succeed, but if the card doesn't look like a FITS header, the result will have CardType.UNKNOWN.
      Parameters:
        `buf80` - 80-byte array giving card image

    - #### skipHDUs

          public static long skipHDUs(java.io.InputStream in,
                                      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:
        `in` - the stream to skip through, positioned at start of HDU
        `nskip` - the number of HDUs to skip
      Returns:
        the number of bytes the stream was advanced
      Throws:
        `java.io.IOException`

    - #### roundUp

          public static long roundUp(long value,
                                     int blockSize)

      Utility method to round an integer value up to a multiple of a given block size.
      Parameters:
        `value` - non-negative count
        `blockSize` - non-negative size of block
      Returns:
        smallest integer that is >=`count` and a multiple of `blockSize`

    - #### writeHeader

          public static int writeHeader(CardImage[] cards,
                                        java.io.OutputStream out)
                                 throws java.io.IOException

      Writes a FITS header whose content is supplied by an array of cards. No checks are performed on the card content. An END card must be included in the supplied array if required. Padding is written to advance to a whole number of FITS blocks.
      Parameters:
        `cards` - cards forming content of header
        `out` - destination stream
      Returns:
        number of bytes written, including padding
      Throws:
        `java.io.IOException`

    - #### writeEmptyPrimary

          public static void writeEmptyPrimary(java.io.OutputStream out)
                                        throws java.io.IOException

      Writes a data-less Primary HDU. It declares EXTEND = T, indicating that extension HDUs will follow.
      Parameters:
        `out` - destination stream
      Throws:
        `java.io.IOException`

    - #### 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

    - #### matchesHeaderName

          public static boolean matchesHeaderName(FitsHeader hdr,
                                                  java.lang.String name)

      Indicates whether the header has a given name. EXTNAME or EXTNAME-EXTVER, matched case-insensitively, count. See FITS 4.0, section 4.4.2.6.
      Parameters:
        `hdr` - header
        `name` - required name
      Returns:
        true iff `hdr` appears to be named `name`
      See Also:
        FITS standard

    - #### asNumericArray

          public static java.lang.Object asNumericArray(java.lang.String txt)

      Attempts to interpret a string as a formatted numeric array. The string has to be of the form "(x, x, ...)", where x has the same form as a floating point header value. Whitespace is permitted. The output will be an int[] array if the tokens all look like 32-bit integers, or a double[] array if the tokens all look like floating point numbers, or null otherwise.

      This is a bit hacky, it doesn't correspond to prescriptions in the FITS stanard, but it's useful for some purposes.

      Parameters:
        `txt` - string
      Returns:
        int[] array or double[] array or null