Package nom.tam.fits
Class Fits
java.lang.Object
nom.tam.fits.Fits
- All Implemented Interfaces:
Closeable
,AutoCloseable
This class provides access to routines to allow users to read and write FITS
files.
Description of the Package
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.
- 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
ConstructorsConstructorDescriptionFits()
Create an empty Fits object which is not associated with an input stream.Associate FITS object with a File.Associate the Fits object with a FileFits
(InputStream str) Create a Fits object associated with the given data stream.Fits
(InputStream str, boolean compressed) Deprecated.Associate the FITS object with a file or URL.Associate the FITS object with a file or URL.Associate the FITS object with a given URLDeprecated.useFits(InputStream)
compression is auto detected. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Add an HDU to the Fits object.static long
checksum
(byte[] data) Deprecated.void
close()
int
Deprecated.usegetNumberOfHDUs()
insteadvoid
deleteHDU
(int n) Delete an HDU from the HDU list.protected void
Get a stream from the file and then use the stream initialization.BasicHDU
<?> getHDU
(int n) int
Get the current number of HDUs in the Fits object.Get the data stream used for the Fits Data.void
Insert a FITS object into the list of HDUs.makeHDU
(DataClass data) static BasicHDU
<?> static BasicHDU
<?> protected void
randomInit
(File file) Initialize using buffered random access.BasicHDU<?>[]
read()
Return all HDUs for the Fits object.void
read
(InputStream is) Read a FITS file from an InputStream object.BasicHDU
<?> readHDU()
Read the next HDU on the default input stream.static void
saveClose
(InputStream in) close the input stream, and ignore eventual errors.void
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
(InputStream inputStream) Initialize the input stream.static String
version()
void
write
(DataOutput os) Write a Fits Object to an external Stream.void
Write the FITS to the specified file.
-
Constructor Details
-
Fits
public Fits()Create an empty Fits object which is not associated with an input stream. -
Fits
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
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
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.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
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
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
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.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 Details
-
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
- 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
- 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
- Returns:
- the version of the library.
-
saveClose
close the input stream, and ignore eventual errors.- Parameters:
in
- the input stream to close.
-
addHDU
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.usegetNumberOfHDUs()
insteadGet the current number of HDUs in the Fits object.- Returns:
- The number of HDU's in the object.
-
deleteHDU
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
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
- 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 readIOException
- 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
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
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
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
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
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
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 readIOException
- if the underlying buffer threw an error
-
setChecksum
Add or Modify the CHECKSUM keyword in all headers. by R J Mathar- Throws:
FitsException
- if the operation failedIOException
- if the underlying stream failed
-
setStream
Set the data stream to be used for future input.- Parameters:
stream
- The data stream to be used.
-
size
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
Skip the next HDU on the default input stream.- Throws:
FitsException
- if the HDU could not be skippedIOException
- if the underlying stream failed
-
skipHDU
Skip HDUs on the associate input stream.- Parameters:
n
- The number of HDUs to be skipped.- Throws:
FitsException
- if the HDU could not be skippedIOException
- if the underlying stream failed
-
streamInit
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
Write a Fits Object to an external Stream.- Parameters:
os
- A DataOutput stream.- Throws:
FitsException
- if the operation failed
-
write
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)
failedIOException
- if the underlying output stream could not be created or closed.
-
close
- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
-
setChecksum
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.calculate the checksum for the block of data- Parameters:
data
- the data to create the checksum for- Returns:
- the checksum
-
Fits(InputStream)
compression is auto detected.