uk.ac.starlink.oldfits

Class FitsConstants

java.lang.Object

uk.ac.starlink.oldfits.FitsConstants

public class FitsConstants
extends 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 and Description
static 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 String	NDARRAY_ORIGIN FITS header card for indicating NDArray origin values.
static String	NDARRAY_PREFIX Prefix for NDArray-related FITS header cards.
static String	NDX_PREFIX Prefix for NDX-related FITS header cards.
static 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 String	WCS_ENCODING Default encoding used for writing WCS into FITS headers.

Constructor Summary

Constructors

Constructor and Description
FitsConstants()

Method Summary

Modifier and Type	Method and Description
static void	addStringValue(Header hdr, String key, String value, String comment) Attempts to add a string-valued card to the header.
static void	addTrimmedValue(Header hdr, String key, String value, String comment) Adds a string-valued card to the header.
static HeaderCard	createHeaderCard(String cardImage) Create a HeaderCard from a FITS card image.
static HeaderCard	createRawHeaderCard(String keyname, String rawvalue, String comment) Create a header card given the final representation of the card value.
static Header	createUnsortedHeader() Creates a Header instance which does not perform any unsolicited reordering of the header cards.
static List<String>	defaultFitsExtensions() Gets the default permitted list of extensions which identify a FITS resource in the path part of a URL.
static long	getDataSize(Header hdr) Utility function to find the number of bytes in the data segment of an HDU.
static ArrayDataInput	getInputStreamStart(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 Iterable<HeaderCard>	headerIterable(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(Header hdr, ArrayDataInput strm) Populates a header from an input stream, reporting its length in bytes.
static long	skipHDUs(ArrayDataInput stream, int nskip) Skips forward over a given number of HDUs in the supplied stream.
static void	writeEmptyPrimary(DataOutput strm) Writes a null header representing an empty primary HDU to a stream.
static void	writeHeader(DataOutput strm, 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 String NDARRAY_PREFIX

Prefix for NDArray-related FITS header cards.

See Also:

Constant Field Values

END_CARD

public static final HeaderCard END_CARD

Image of end-of-header card.

NDARRAY_ORIGIN

public static final 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 String NDX_PREFIX

Prefix for NDX-related FITS header cards.

See Also:

Constant Field Values

NDX_XML

public static final String NDX_XML

FITS header card for location (relative URL) of XML representation.

See Also:

Constant Field Values

WCS_ENCODING

public static final 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 List<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

createUnsortedHeader

public static 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 HeaderCard createHeaderCard(String cardImage)

Create a HeaderCard from a FITS card image.

Parameters:

cardImage - the 80 character card image

Returns:

card object

createRawHeaderCard

public static HeaderCard createRawHeaderCard(String keyname,
                                             String rawvalue,
                                             String comment)
                                      throws HeaderCardException

Create a header card given the final representation of the card value. No additional manipulation will be done on the value; for instance it will not be wrapped in quotes. Use this method with caution, since the arguments may not be checked as rigorously as during normal header creation, though steps will be taken to ensure that the header does not overflow the 80 character limit.

Parameters:

keyname - header card name

rawvalue - raw header card value

comment - comment text (ignored if too long)

Returns:

new header card

Throws:

HeaderCardException - if card would be too long

headerIterable

public static Iterable<HeaderCard> headerIterable(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(ArrayDataInput stream,
                            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:

stream - the stream to skip through

nskip - the number of HDUs to skip

Returns:

the number of bytes the stream was advanced

Throws:

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 ArrayDataInput getInputStreamStart(DataSource datsrc)
                                          throws 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:

IOException

readHeader

public static int readHeader(Header hdr,
                             ArrayDataInput strm)
                      throws TruncatedFileException,
                             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:

TruncatedFileException

IOException

See Also:

Header.read(nom.tam.util.ArrayDataInput)

writeHeader

public static void writeHeader(DataOutput strm,
                               Header hdr)
                        throws IOException

Writes a header object to a DataOutput.

Parameters:

strm - destination stream

hdr - the header to write

Throws:

IOException

writeEmptyPrimary

public static void writeEmptyPrimary(DataOutput strm)
                              throws IOException

Writes a null header representing an empty primary HDU to a stream.

Parameters:

strm - stream to write to

Throws:

IOException

getDataSize

public static long getDataSize(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(Header hdr,
                                   String key,
                                   String value,
                                   String comment)
                            throws 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:

HeaderCardException

addStringValue

public static void addStringValue(Header hdr,
                                  String key,
                                  String value,
                                  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