Package nom.tam.fits
Class Fits
- java.lang.Object
-
- nom.tam.fits.Fits
-
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
public class Fits extends java.lang.Object implements java.io.Closeable
This class provides access to routines to allow users to read and write FITS files.
Description of the PackageThis 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.
- The Fits class provides capabilities to read and write data at the HDU
level, and to add and delete HDU's from the current Fits object. A large
number of constructors are provided which allow users to associate the Fits
object with some form of external data. This external data may be in a
compressed format.
Note that this association is limited, it only specifies where the various read methods should read data from. It does not automatically read the data content and store the results. To ensure that the external content has been read and parsed the user may wish to invoke the read() method after creating the Fits object associated with external data. E.g.,
File fl = ... ; Fits f = new Fits(fl); // Or we could have used one of the other constructors. // At this point the Fits object is empty. f.read(); // Read the external data into the Fits object // At this point the Fits object should have one or more HDUs depending // upon the external content.
Users can choose to read only some of the HDUs in a given input, and may add HDU's that were either read from other files or generated by the program. See the various read and addHDU methods. - The FitsFactory class is a factory class which is used to create HDUs.
HDU's can be of a number of types derived from the abstract class BasicHDU.
The hierarchy of HDUs is:
- BasicHDU
- ImageHDU
- RandomGroupsHDU
- TableHDU
- BinaryTableHDU
- AsciiTableHDU
- UndefinedHDU
- BasicHDU
- The Header class provides many functions to add, delete and read header keywords in a variety of formats.
- The HeaderCard class provides access to the structure of a FITS header card.
- The header package defines sets of enumerations that allow users to create and access header keywords in a controlled way.
- The Data class is an abstract class which provides the basic methods for reading and writing FITS data. It provides methods to get the the actual underlying arrays and detailed methods for manipulation specific to the different data types.
- The TableHDU class provides a large number of methods to access and modify information in tables.
- The utilities package includes simple tools to copy and list FITS files.
- Version:
- 1.12
-
-
Constructor Summary
Constructors Constructor Description 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 FileFits(java.io.InputStream str)
Create a Fits object associated with the given data stream.Fits(java.io.InputStream str, boolean compressed)
Deprecated.useFits(InputStream)
compression is auto detected.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 URLFits(java.net.URL myURL, boolean compressed)
Deprecated.useFits(InputStream)
compression is auto detected.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addHDU(BasicHDU<?> myHDU)
Add an HDU to the Fits object.static long
checksum(byte[] data)
Deprecated.void
close()
int
currentSize()
Deprecated.usegetNumberOfHDUs()
insteadvoid
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)
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 position)
Insert a FITS object into the list of HDUs.static <DataClass extends Data>
BasicHDU<DataClass>makeHDU(DataClass data)
static BasicHDU<?>
makeHDU(java.lang.Object o)
static BasicHDU<?>
makeHDU(Header h)
protected void
randomInit(java.io.File file)
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.static void
saveClose(java.io.InputStream in)
close the input stream, and ignore eventual errors.void
setChecksum()
Add or Modify the CHECKSUM keyword in all headers.static void
setChecksum(BasicHDU<?> hdu)
Deprecated.void
setStream(ArrayDataInput stream)
Set the data stream to be used for future input.int
size()
Deprecated.The meaning of size of ambiguous.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 inputStream)
Initialize the input stream.static java.lang.String
version()
void
write(java.io.DataOutput os)
Write a Fits Object to an external Stream.void
write(java.io.File file)
Write the FITS to the specified file.
-
-
-
Constructor Detail
-
Fits
public Fits()
Create an empty Fits object which is not associated with an input stream.
-
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. The content of this file will not be read into the Fits object until the user makes some explicit request. * @throws FitsException if the operation failed- Throws:
FitsException
- if the operation failed
-
Fits
public Fits(java.io.File myFile, boolean compressed) throws FitsException
Associate the Fits object with a File- Parameters:
myFile
- The File object. The content of this file will not be read into the Fits object until the user makes some explicit request.compressed
- Is the data compressed?- Throws:
FitsException
- if the operation failed
-
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. The content of this stream will not be read into the Fits object until the user makes some explicit request.- Throws:
FitsException
- if the operation failed
-
Fits
@Deprecated public Fits(java.io.InputStream str, boolean compressed) throws FitsException
Deprecated.useFits(InputStream)
compression is auto detected.Create a Fits object associated with a data stream.- Parameters:
str
- The data stream. The content of this stream will not be read into the Fits object until the user makes some explicit request.compressed
- Is the stream compressed? This is currently ignored. Compression is determined from the first two bytes in the stream.- Throws:
FitsException
- if the operation failed
-
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. The content of this file will not be read into the Fits object until the user makes some explicit request.- 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. The content of this file will not be read into the Fits object until the user makes some explicit request.compressed
- is the file compressed?- Throws:
FitsException
- Thrown if unable to find or open a file or URL from the string given.
-
Fits
public Fits(java.net.URL myURL) throws FitsException
Associate the FITS object with a given URL- Parameters:
myURL
- The URL to be read. The content of this URL will not be read into the Fits object until the user makes some explicit request.- Throws:
FitsException
- Thrown if unable to find or open a file or URL from the string given.
-
Fits
@Deprecated public Fits(java.net.URL myURL, boolean compressed) throws FitsException
Deprecated.useFits(InputStream)
compression is auto detected.Associate the FITS object with a given uncompressed URL- Parameters:
myURL
- The URL to be associated with the FITS file. The content of this URL will not be read into the Fits object until the user makes some explicit request.compressed
- Compression flag, ignored.- Throws:
FitsException
- Thrown if unable to use the specified URL.
-
-
Method Detail
-
makeHDU
public static <DataClass extends Data> BasicHDU<DataClass> makeHDU(DataClass data) throws FitsException
- Type Parameters:
DataClass
- the class of the HDU- Parameters:
data
- The data to be described in this HDU.- Returns:
- a newly created HDU from the given Data.
- Throws:
FitsException
- if the operation failed
-
makeHDU
public static BasicHDU<?> makeHDU(Header h) throws FitsException
- Parameters:
h
- The header which describes the FITS extension- Returns:
- a newly created HDU from the given header.
- Throws:
FitsException
- if the header could not be converted to a HDU.
-
makeHDU
public static BasicHDU<?> makeHDU(java.lang.Object o) throws FitsException
- Parameters:
o
- The data to be described in this HDU.- Returns:
- a newly created HDU from the given data kernel.
- Throws:
FitsException
- if the parameter could not be converted to a HDU.
-
version
public static java.lang.String version()
- Returns:
- the version of the library.
-
saveClose
public static void saveClose(java.io.InputStream in)
close the input stream, and ignore eventual errors.- Parameters:
in
- the input stream to close.
-
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
- if the HDU could not be inserted.
-
currentSize
@Deprecated public int currentSize()
Deprecated.usegetNumberOfHDUs()
insteadGet the current number of HDUs in the Fits object.- Returns:
- The number of HDU's in the object.
-
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
- if the HDU could not be deleted.
-
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
- if the opening of the file failed.
-
getHDU
public BasicHDU<?> getHDU(int n) throws FitsException, java.io.IOException
- Parameters:
n
- The index of the HDU to be read. The primary HDU is index 0.- Returns:
- 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.
- Throws:
FitsException
- if the header could not be readjava.io.IOException
- if the underlying buffer threw an error
-
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.
-
insertHDU
public void insertHDU(BasicHDU<?> myHDU, int position) throws FitsException
Insert a FITS object into the list of HDUs.- Parameters:
myHDU
- The HDU to be inserted into the list of HDUs.position
- The location at which the HDU is to be inserted.- Throws:
FitsException
- if the HDU could not be inserted.
-
randomInit
protected void randomInit(java.io.File file) throws FitsException
Initialize using buffered random access. This implies that the data is uncompressed.- Parameters:
file
- the file to open- Throws:
FitsException
- if the file could not be read
-
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
- if the reading failed.
-
read
public void read(java.io.InputStream is) throws FitsException
Read a FITS file from an InputStream object.- Parameters:
is
- The InputStream stream whence the FITS information is found.- Throws:
FitsException
- if the data read could not be interpreted
-
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
- if the header could not be readjava.io.IOException
- if the underlying buffer threw an error
-
setChecksum
public void setChecksum() throws FitsException, java.io.IOException
Add or Modify the CHECKSUM keyword in all headers. by R J Mathar- Throws:
FitsException
- if the operation failedjava.io.IOException
- if the underlying stream failed
-
setStream
public void setStream(ArrayDataInput stream)
Set the data stream to be used for future input.- Parameters:
stream
- The data stream to be used.
-
size
@Deprecated public int size() throws FitsException
Deprecated.The meaning of size of ambiguous. UsegetNumberOfHDUs()
instead. Note size() will read the input file/stream to the EOF before returning the number of HDUs whichgetNumberOfHDUs()
does not. If you wish to duplicate this behavior and ensure that the input has been exhausted before getting the number of HDUs then use the sequence:read(); getNumberofHDUs();
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
- if the file could not be read.
-
skipHDU
public void skipHDU() throws FitsException, java.io.IOException
Skip the next HDU on the default input stream.- Throws:
FitsException
- if the HDU could not be skippedjava.io.IOException
- if the underlying stream failed
-
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
- if the HDU could not be skippedjava.io.IOException
- if the underlying stream failed
-
streamInit
protected void streamInit(java.io.InputStream inputStream) 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:
inputStream
- stream to initialize- Throws:
FitsException
- if the initialization failed
-
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
- if the operation failed
-
write
public void write(java.io.File file) throws java.io.IOException, FitsException
Write the FITS to the specified file. This is a wrapper method provided for convenience, which calls thewrite(DataOutput)
method. It creates a suitableBufferedFile
, to which the FITS is then written. Upon completion the underlying stream is closed.- Parameters:
file
- a file to which the FITS is to be written.- Throws:
FitsException
- ifwrite(DataOutput)
failedjava.io.IOException
- if the underlying output stream could not be created or closed.
-
close
public void close() throws java.io.IOException
- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
java.io.IOException
-
setChecksum
@Deprecated public static void setChecksum(BasicHDU<?> hdu) throws FitsException
Deprecated.set the checksum of a HDU.- Parameters:
hdu
- the HDU to add a checksum- Throws:
FitsException
- the checksum could not be added to the header
-
checksum
@Deprecated public static long checksum(byte[] data)
Deprecated.calculate the checksum for the block of data- Parameters:
data
- the data to create the checksum for- Returns:
- the checksum
-
-