Package nom.tam.fits

Class Fits

java.lang.Object
nom.tam.fits.Fits
All Implemented Interfaces:
Closeable, AutoCloseable

public class Fits extends Object implements Closeable
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.

  • 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
  • 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 Details

    • Fits

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

      public Fits(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(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(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(InputStream str, boolean compressed) throws FitsException
      Deprecated.
      use Fits(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(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(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(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(URL myURL, boolean compressed) throws FitsException
      Deprecated.
      use Fits(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

      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(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 String version()
      Returns:
      the version of the library.
    • saveClose

      public static void saveClose(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.
      use getNumberOfHDUs() instead
      Get 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(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, 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 read
      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(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(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, 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 read
      IOException - if the underlying buffer threw an error
    • setChecksum

      public void setChecksum() throws FitsException, IOException
      Add or Modify the CHECKSUM keyword in all headers. by R J Mathar
      Throws:
      FitsException - if the operation failed
      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. Use getNumberOfHDUs() instead. Note size() will read the input file/stream to the EOF before returning the number of HDUs which getNumberOfHDUs() 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, IOException
      Skip the next HDU on the default input stream.
      Throws:
      FitsException - if the HDU could not be skipped
      IOException - if the underlying stream failed
    • skipHDU

      public void skipHDU(int n) throws FitsException, 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 skipped
      IOException - if the underlying stream failed
    • streamInit

      protected void streamInit(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(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(File file) throws IOException, FitsException
      Write the FITS to the specified file. This is a wrapper method provided for convenience, which calls the write(DataOutput) method. It creates a suitable BufferedFile, 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 - if write(DataOutput) failed
      IOException - if the underlying output stream could not be created or closed.
    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException
    • setChecksum

      @Deprecated public static void setChecksum(BasicHDU<?> hdu) throws FitsException
      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)
      calculate the checksum for the block of data
      Parameters:
      data - the data to create the checksum for
      Returns:
      the checksum