nom.tam.fits
Class Fits

java.lang.Object
  extended by nom.tam.fits.Fits

public class Fits
extends java.lang.Object

This class provides access to routines to allow users to read and write FITS files.

Description of the Package

This FITS package attempts to make using FITS files easy, but does not do exhaustive error checking. Users should not assume that just because a FITS file can be read and written that it is necessarily legal FITS. These classes try to make it easy to transform between arrays of Java primitives and their FITS encodings.

Version:
1.10 September 27, 2012

Constructor Summary
Fits()
          Create an empty Fits object which is not associated with an input stream.
Fits(java.io.File myFile)
          Associate FITS object with a File.
Fits(java.io.File myFile, boolean compressed)
          Associate the Fits object with a File
Fits(java.io.InputStream str)
          Create a Fits object associated with the given data stream.
Fits(java.io.InputStream str, boolean compressed)
          Create a Fits object associated with a data stream.
Fits(java.lang.String filename)
          Associate the FITS object with a file or URL.
Fits(java.lang.String filename, boolean compressed)
          Associate the FITS object with a file or URL.
Fits(java.net.URL myURL)
          Associate the FITS object with a given URL
Fits(java.net.URL myURL, boolean compressed)
          Associate the FITS object with a given uncompressed URL
 
Method Summary
 void addHDU(BasicHDU myHDU)
          Add an HDU to the Fits object.
static long checksum(byte[] data)
          Calculate the Seaman-Pence 32-bit 1's complement checksum over the byte stream.
 int currentSize()
          Deprecated. See getNumberOfHDUs()
 void deleteHDU(int n)
          Delete an HDU from the HDU list.
protected  void fileInit(java.io.File myFile, boolean compressed)
          Get a stream from the file and then use the stream initialization.
 BasicHDU getHDU(int n)
          Return the n'th HDU.
 int getNumberOfHDUs()
          Get the current number of HDUs in the Fits object.
 ArrayDataInput getStream()
          Get the data stream used for the Fits Data.
 void insertHDU(BasicHDU myHDU, int n)
          Insert a FITS object into the list of HDUs.
static BasicHDU makeHDU(Data datum)
          Create an HDU from the given Data.
static BasicHDU makeHDU(Header h)
          Create an HDU from the given header.
static BasicHDU makeHDU(java.lang.Object o)
          Create an HDU from the given data kernel.
protected  void randomInit(java.io.File f)
          Initialize using buffered random access.
 BasicHDU[] read()
          Return all HDUs for the Fits object.
 void read(java.io.InputStream is)
          Read a FITS file from an InputStream object.
 BasicHDU readHDU()
          Read the next HDU on the default input stream.
 void setChecksum()
          Add or Modify the CHECKSUM keyword in all headers.
static void setChecksum(BasicHDU hdu)
          Add or update the CHECKSUM keyword.
 void setStream(ArrayDataInput stream)
          Set the data stream to be used for future input.
 int size()
          Deprecated. The meaning of size of ambiguous. Use
 void skipHDU()
          Skip the next HDU on the default input stream.
 void skipHDU(int n)
          Skip HDUs on the associate input stream.
protected  void streamInit(java.io.InputStream str)
          Initialize the input stream.
protected  void streamInit(java.io.InputStream str, boolean seekable)
          Initialize the stream.
protected  void streamInit(java.io.InputStream str, boolean compressed, boolean seekable)
          Do the stream initialization.
static java.lang.String version()
          Indicate the version of these classes
 void write(java.io.DataOutput os)
          Write a Fits Object to an external Stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Fits

public Fits()
Create an empty Fits object which is not associated with an input stream.


Fits

public Fits(java.io.InputStream str)
     throws FitsException
Create a Fits object associated with the given data stream. Compression is determined from the first few bytes of the stream.

Parameters:
str - The data stream.
Throws:
FitsException

Fits

public Fits(java.io.InputStream str,
            boolean compressed)
     throws FitsException
Create a Fits object associated with a data stream.

Parameters:
str - The data stream.
compressed - Is the stream compressed? This is currently ignored. Compression is determined from the first two bytes in the stream.
Throws:
FitsException

Fits

public Fits(java.io.File myFile)
     throws FitsException
Associate FITS object with a File. If the file is compressed a stream will be used, otherwise random access will be supported.

Parameters:
myFile - The File object.
Throws:
FitsException

Fits

public Fits(java.io.File myFile,
            boolean compressed)
     throws FitsException
Associate the Fits object with a File

Parameters:
myFile - The File object.
compressed - Is the data compressed?
Throws:
FitsException

Fits

public Fits(java.lang.String filename)
     throws FitsException
Associate the FITS object with a file or URL. The string is assumed to be a URL if it begins one of the protocol strings. If the string ends in .gz it is assumed that the data is in a compressed format. All string comparisons are case insensitive.

Parameters:
filename - The name of the file or URL to be processed.
Throws:
FitsException - Thrown if unable to find or open a file or URL from the string given.

Fits

public Fits(java.lang.String filename,
            boolean compressed)
     throws FitsException
Associate the FITS object with a file or URL. The string is assumed to be a URL if it begins one of the protocol strings. If the string ends in .gz it is assumed that the data is in a compressed format. All string comparisons are case insensitive.

Parameters:
filename - The name of the file or URL to be processed.
Throws:
FitsException - Thrown if unable to find or open a file or URL from the string given.

Fits

public Fits(java.net.URL myURL,
            boolean compressed)
     throws FitsException
Associate the FITS object with a given uncompressed URL

Parameters:
myURL - The URL to be associated with the FITS file.
compressed - Compression flag, ignored.
Throws:
FitsException - Thrown if unable to use the specified URL.

Fits

public Fits(java.net.URL myURL)
     throws FitsException
Associate the FITS object with a given URL

Parameters:
myURL -
Throws:
FitsException - Thrown if unable to find or open a file or URL from the string given.
Method Detail

version

public static java.lang.String version()
Indicate the version of these classes


streamInit

protected void streamInit(java.io.InputStream str,
                          boolean seekable)
                   throws FitsException
Initialize the stream.

Parameters:
str - The user specified input stream
seekable - ignored
Throws:
FitsException

streamInit

protected void streamInit(java.io.InputStream str,
                          boolean compressed,
                          boolean seekable)
                   throws FitsException
Do the stream initialization.

Parameters:
str - The input stream.
compressed - Is this data compressed? This flag is ignored. The compression is determined from the stream content.
seekable - Can one seek on the stream. This parameter is ignored.
Throws:
FitsException

streamInit

protected void streamInit(java.io.InputStream str)
                   throws FitsException
Initialize the input stream. Mostly this checks to see if the stream is compressed and wraps the stream if necessary. Even if the stream is not compressed, it will likely be wrapped in a PushbackInputStream. So users should probably not supply a BufferedDataInputStream themselves, but should allow the Fits class to do the wrapping.

Parameters:
str -
Throws:
FitsException

randomInit

protected void randomInit(java.io.File f)
                   throws FitsException
Initialize using buffered random access. This implies that the data is uncompressed.

Parameters:
f -
Throws:
FitsException

fileInit

protected void fileInit(java.io.File myFile,
                        boolean compressed)
                 throws FitsException
Get a stream from the file and then use the stream initialization.

Parameters:
myFile - The File to be associated.
compressed - Is the data compressed?
Throws:
FitsException

read

public BasicHDU[] read()
                throws FitsException
Return all HDUs for the Fits object. If the FITS file is associated with an external stream make sure that we have exhausted the stream.

Returns:
an array of all HDUs in the Fits object. Returns null if there are no HDUs associated with this object.
Throws:
FitsException

readHDU

public BasicHDU readHDU()
                 throws FitsException,
                        java.io.IOException
Read the next HDU on the default input stream.

Returns:
The HDU read, or null if an EOF was detected. Note that null is only returned when the EOF is detected immediately at the beginning of reading the HDU.
Throws:
FitsException
java.io.IOException

skipHDU

public void skipHDU(int n)
             throws FitsException,
                    java.io.IOException
Skip HDUs on the associate input stream.

Parameters:
n - The number of HDUs to be skipped.
Throws:
FitsException
java.io.IOException

skipHDU

public void skipHDU()
             throws FitsException,
                    java.io.IOException
Skip the next HDU on the default input stream.

Throws:
FitsException
java.io.IOException

getHDU

public BasicHDU getHDU(int n)
                throws FitsException,
                       java.io.IOException
Return the n'th HDU. If the HDU is already read simply return a pointer to the cached data. Otherwise read the associated stream until the n'th HDU is read.

Parameters:
n - The index of the HDU to be read. The primary HDU is index 0.
Returns:
The n'th HDU or null if it could not be found.
Throws:
FitsException
java.io.IOException

size

public int size()
         throws FitsException
Deprecated. The meaning of size of ambiguous. Use

Return the number of HDUs in the Fits object. If the FITS file is associated with an external stream make sure that we have exhausted the stream.

Returns:
number of HDUs.
Throws:
FitsException

addHDU

public void addHDU(BasicHDU myHDU)
            throws FitsException
Add an HDU to the Fits object. Users may intermix calls to functions which read HDUs from an associated input stream with the addHDU and insertHDU calls, but should be careful to understand the consequences.

Parameters:
myHDU - The HDU to be added to the end of the FITS object.
Throws:
FitsException

insertHDU

public void insertHDU(BasicHDU myHDU,
                      int n)
               throws FitsException
Insert a FITS object into the list of HDUs.

Parameters:
myHDU - The HDU to be inserted into the list of HDUs.
n - The location at which the HDU is to be inserted.
Throws:
FitsException

deleteHDU

public void deleteHDU(int n)
               throws FitsException
Delete an HDU from the HDU list.

Parameters:
n - The index of the HDU to be deleted. If n is 0 and there is more than one HDU present, then the next HDU will be converted from an image to primary HDU if possible. If not a dummy header HDU will then be inserted.
Throws:
FitsException

write

public void write(java.io.DataOutput os)
           throws FitsException
Write a Fits Object to an external Stream.

Parameters:
os - A DataOutput stream.
Throws:
FitsException

read

public void read(java.io.InputStream is)
          throws FitsException,
                 java.io.IOException
Read a FITS file from an InputStream object.

Parameters:
is - The InputStream stream whence the FITS information is found.
Throws:
FitsException
java.io.IOException

currentSize

public int currentSize()
Deprecated. See getNumberOfHDUs()

Get the current number of HDUs in the Fits object.

Returns:
The number of HDU's in the object.

getNumberOfHDUs

public int getNumberOfHDUs()
Get the current number of HDUs in the Fits object.

Returns:
The number of HDU's in the object.

getStream

public ArrayDataInput getStream()
Get the data stream used for the Fits Data.

Returns:
The associated data stream. Users may wish to call this function after opening a Fits object when they wish detailed control for writing some part of the FITS file.

setStream

public void setStream(ArrayDataInput stream)
Set the data stream to be used for future input.

Parameters:
stream - The data stream to be used.

makeHDU

public static BasicHDU makeHDU(Header h)
                        throws FitsException
Create an HDU from the given header.

Parameters:
h - The header which describes the FITS extension
Throws:
FitsException

makeHDU

public static BasicHDU makeHDU(java.lang.Object o)
                        throws FitsException
Create an HDU from the given data kernel.

Parameters:
o - The data to be described in this HDU.
Throws:
FitsException

makeHDU

public static BasicHDU makeHDU(Data datum)
                        throws FitsException
Create an HDU from the given Data.

Parameters:
datum - The data to be described in this HDU.
Throws:
FitsException

setChecksum

public static void setChecksum(BasicHDU hdu)
                        throws HeaderCardException,
                               FitsException,
                               java.io.IOException
Add or update the CHECKSUM keyword.

Parameters:
hdu - the HDU to be updated.
Throws:
HeaderCardException
FitsException
java.io.IOException
Since:
2005-10-05

setChecksum

public void setChecksum()
                 throws HeaderCardException,
                        FitsException,
                        java.io.IOException
Add or Modify the CHECKSUM keyword in all headers.

Throws:
HeaderCardException
FitsException
java.io.IOException
Since:
2005-10-05

checksum

public static long checksum(byte[] data)
Calculate the Seaman-Pence 32-bit 1's complement checksum over the byte stream. The option to start from an intermediate checksum accumulated over another previous byte stream is not implemented. The implementation accumulates in two 64-bit integer values the two low-order and the two high-order bytes of adjacent 4-byte groups. A carry-over of bits is never done within the main loop (only once at the end at reduction to a 32-bit positive integer) since an overflow of a 64-bit value (signed, with maximum at 2^63-1) by summation of 16-bit values could only occur after adding approximately 140G short values (=2^47) (280GBytes) or more. We assume for now that this routine here is never called to swallow FITS files of that size or larger.

Parameters:
data - the byte sequence
Returns:
the 32bit checksum in the range from 0 to 2^32-1
Since:
2005-10-05
See Also:
"http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html"