uk.ac.starlink.fits

Class FitsUtil

java.lang.Object

uk.ac.starlink.fits.FitsUtil

public class FitsUtil
extends Object

Utilities for working with FITS files.

Since:

4 Mar 2022

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static int	BLOCK_LENG FITS block length in bytes (@value).
static int	CARD_LENG FITS header card length in bytes (@value).
static int	CARDS_PER_BLOCK Number of header cards per FITS block (@value).
static String	FLOAT_REGEX Regex pattern matching floating point value, no grouping.
static int	MAX_NCOLSTD Maximum No.

Method Summary

Modifier and Type	Method and Description
static Object	asNumericArray(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 ParsedCard<?>	parseCard(byte[] buf80) Turns an 80-byte array into a ParsedCard.
static FitsHeader	readHeader(InputStream in) Reads a FITS header from an input stream.
static FitsHeader	readHeaderIfPresent(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(InputStream in, int nskip) Skips forward over a given number of HDUs in the supplied stream.
static void	writeEmptyPrimary(OutputStream out) Writes a data-less Primary HDU.
static int	writeHeader(CardImage[] cards, 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 (@value).

See Also:

Constant Field Values

CARD_LENG

public static final int CARD_LENG

FITS header card length in bytes (@value).

See Also:

Constant Field Values

CARDS_PER_BLOCK

public static final int CARDS_PER_BLOCK

Number of header cards per FITS block (@value).

See Also:

Constant Field Values

MAX_NCOLSTD

public static final int MAX_NCOLSTD

Maximum No. of columns in standard FITS BINTABLE extension (@value).

See Also:

Constant Field Values

FLOAT_REGEX

public static final 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(InputStream in)
                             throws 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:

IOException

readHeaderIfPresent

public static FitsHeader readHeaderIfPresent(InputStream in)
                                      throws 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:

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(InputStream in,
                            int nskip)
                     throws 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:

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,
                              OutputStream out)
                       throws 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:

IOException

writeEmptyPrimary

public static void writeEmptyPrimary(OutputStream out)
                              throws IOException

Writes a data-less Primary HDU. It declares EXTEND = T, indicating that extension HDUs will follow.

Parameters:

out - destination stream

Throws:

IOException

checkColumnCount

public static void checkColumnCount(WideFits wide,
                                    int ncol)
                             throws 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:

IOException - if there are too many columns

asNumericArray

public static Object asNumericArray(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