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

Handling of FITS files and streams. This class is a container of HDUs (header-data units), which together constitute a complete FITS file. Users of this library are strongly encouraged to study the FITS Standard documentation before using this library, as the library typically requires a level of familiarity with FITS and its capabilities. When constructing FITS files, users will typically want to populate their headers with as much of the standard information as possible to provide a full and accurate description of the data they wish to represent way beyond the bare essentials that are handled automatically by this library.

Fits objects can be built-up HDU-by-HDU, and then written to a file (or stream), e.g.: 

   // Create a new empty Fits containe
   Fits fits = new Fits(); 
   
   // Create an image HDU, e.g. from a 2D array we have prepared earlier
   float[][] image = ...
   BasicHDU<?> imageHDU = Fits.makeHDU(image);
   
   // ... we can of course add data to the HDU's header as we like...
   
   // Make this image the first HDU...
   fits.addHDU(imageHDU); 
   
   // Write the FITS to a file...
   fits.write("myimage.fits");

Or, we may read a Fits object from the input, e.g. as: 

   // Create and empty Fits assigned to an input file
   Fits f = new Fits(new File("myimage.fits");
   
   // Read the entire FITS (skipping over the data for now...)
   f.read();
   
   // Get the image data from the first HDU (will actually read the image now)
   float[][] image = (float[][]) f.getHDU(0).getKernel();

When reading FITS from random-accessible files (like in the example above), the read() call will parse the header for each HDU but will defer reading of actual data to a later time when it's actually accessed. This makes Fits objects fast, frugal, and lean, especially when one is interested in certain parts of the data contained in the FITS file. (When reading from streams, deferred reading is not an option, so read() will load all HDUs into memory each time).

Fits objects also allow reading HDUs sequentially one at a time using the readHDU(), or even when using getHDU(int) or getHDU(String) methods, even if read() was not called previously, e.g.: 

   // Create and empty Fits assigned to an input
   Fits f = new Fits(new File("myimage.fits");
   
   // Get HDU index 2 (0-based, i.e. 3rd HDU) FITS. It will read (stream) or skim (file) the FITS up to the 3rd
   // HDU, returning it. If the FITS file or stream contains further HDUs they will not be accessed until we
   // need them later (if at all).
   BasucHDU<?> hdu = f.getHDU(2);

When building Fits from local Java data objects, it's best to use makeHDU(Object) to create HDUs, which will chose the most appropriate type of HDU for the given data object (taking into some of the static preferences set in FitsFactory prior). makeHDU(Object) will return one of the following HDU objects:

all of which derive from BasicHDU.

Since HDU literally means 'header-data unit', they constitute of a header and data entities, which can be accessed separately. The Header class provides many functions to add, delete and read header keywords in HDUs in a variety of formats. The Data class, and its concrete subclassses provide access to the specific data object that the HDU encapsulates.

Version:
1.20
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Fits()
    Creates an empty Fits object which is not associated with an input stream.
    Fits(File myFile)
    Creates a new (empty) FITS container associated with a file input.
    Fits(File myFile, boolean compressed)
    Deprecated.
    Use Fits(File) instead (compression is auto detected).
    Fits(InputStream str)
    Creates a new (empty) FITS container associated with the given input stream.
    Fits(InputStream str, boolean compressed)
    Deprecated.
    Use Fits(InputStream) instead (compression is auto detected).
    Fits(String filename)
    Creates a new (empty) FITS container with a file or URL as its input.
    Fits(String filename, boolean compressed)
    Deprecated.
    Use Fits(String) instead (compression is auto detected).
    Fits(URL myURL)
    Creates a new (empty) FITS container with a given URL as its input.
    Fits(URL myURL, boolean compressed)
    Deprecated.
    Use Fits(URL) instead (compression is auto detected).
    Fits(FitsFile src)
    Creates a new (empty) FITS container associated with FitsFile input.
    Fits(RandomAccessFileIO src)
    Creates a new (empty) FITS container associated with an input that supports generalized random access.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addHDU(BasicHDU<?> myHDU)
    Add an HDU to the Fits object.
    long
    calcChecksum(int hduIndex)
    Deprecated.
    Use BasicHDU.verifyIntegrity() instead when appropriate.
    long
    calcDatasum(int hduIndex)
    Calculates the data checksum for a given HDU in the Fits.
    static long
    checksum(byte[] data)
    Deprecated.
    use FitsCheckSum.checksum(byte[])
    void
    close()
     
    int
    currentSize()
    Deprecated.
    use getNumberOfHDUs() instead
    void
    deleteHDU(int n)
    Delete an HDU from the HDU list.
    Header
    getCompleteHeader(int n)
    Returns the 'complete' header of the nth HDU in this FITS file/object.
    Header
    getCompleteHeader(String name)
    Returns the complete header of the first HDU by the specified name in this FITS file/object.
    Header
    getCompleteHeader(String name, int version)
    Returns the complete header of the first HDU by the specified name and version in this FITS file/object.
    BasicHDU<?>
    getHDU(int n)
    Returns the n'th HDU.
    BasicHDU<?>
    getHDU(String name)
    Returns the HDU by the given extension name (defined by EXTNAME header keyword).
    BasicHDU<?>
    getHDU(String name, int version)
    Returns the HDU by the given extension name and version (defined by EXTNAME and EXTVER keywords).
    int
    getNumberOfHDUs()
    Get the number of HDUs currently available in memory.
    Header
    getPrimaryHeader()
    Returns the primary header of this FITS file, that is the header of the primary HDU in this Fits object.
    ArrayDataInput
    getStream()
    Returns the input from which this Fits is associated to (if any)..
    void
    insertHDU(BasicHDU<?> myHDU, int position)
    Insert a FITS object into the list of HDUs.
    static <DataClass extends Data>
    BasicHDU<DataClass>
    makeHDU(DataClass data)
    Creates a new empty HDU for the given data type.
    static BasicHDU<?>
    makeHDU(Object o)
    Creates an HDU that wraps around the specified data object.
    static BasicHDU<?>
    makeHDU(Header h)
    Creates a new empty HDU based on the header description of the data
    BasicHDU<?>[]
    read()
    Return all HDUs for the Fits object.
    void
    read(InputStream is)
    Deprecated.
    Use Fits(InputStream) constructor instead.
    BasicHDU<?>
    readHDU()
    Read the next HDU on the default input stream.
    void
    rewrite()
    Re-writes all HDUs that have been loaded (and possibly modified) to the disk, if possible -- or else does nothing.
    static void
    saveClose(InputStream in)
    Deprecated.
    Use try-with-resources constructs in Java 8+ instead.
    void
    setChecksum()
    Add or modify the CHECKSUM keyword in all headers.
    void
    setChecksum(int hduIndex)
    Computes the CHECKSUM and DATASUM values for the specified HDU index and stores them in the HUS's header.
    static void
    setChecksum(BasicHDU<?> hdu)
    Deprecated.
    use FitsCheckSum.setChecksum(BasicHDU)
    void
    setStream(ArrayDataInput stream)
    Deprecated.
    This method is poorly conceived as we cannot really read FITS from just any ArrayDataInput but only those, which utilize FitsDecoder to convert Java types to FITS binary format, such as FitsInputStream or FitsFile (or else a wrapped DataInputStream).
    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.
    void
    verifyIntegrity()
    Checks the integrity of all HDUs.
    static String
    version()
    Returns the version sting of this FITS library
    void
    write(DataOutput os)
    Deprecated.
    This method is poorly conceived as we cannot really write FITS to just any DataOutput but only to specific ArrayDataOutput, which utilize FitsEncoder to convert Java types to FITS binary format, such as FitsOutputStream or FitsFile (or else a wrapped DataOutputStream).
    void
    write(File file)
    Writes the contents to a new file.
    void
    write(String fileName)
    Writes the contents to the specified file.
    void
    write(FitsFile file)
    Writes the contents to a designated FITS file.
    void
    write(FitsOutputStream out)
    Writes the contents to a designated FITS output stream.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Fits

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

    • Fits

      public Fits(File myFile) throws FitsException

      Creates a new (empty) FITS container associated with a file input. If the file is compressed a stream will be used, otherwise random access will be supported.

      While the FITS object is associated with the specified file, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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
      See Also:

    • Fits

      public Fits(File myFile, boolean compressed) throws FitsException
      Deprecated.
      Use Fits(File) instead (compression is auto detected). Will remove in the future.

      Creates a new (empty) FITS container associated with a file input.

      While the FITS object is associated with the specified file, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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
      See Also:

    • Fits

      public Fits(RandomAccessFileIO src) throws FitsException

      Creates a new (empty) FITS container associated with an input that supports generalized random access.

      While the FITS object is associated with the specified input, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      Parameters:
      src - the random access input. The content of this input will not be read into the Fits object until the user makes some explicit request.
      Throws:
      FitsException - if the operation failed
      See Also:

    • Fits

      public Fits(FitsFile src) throws FitsException

      Creates a new (empty) FITS container associated with FitsFile input.

      While the FITS object is associated with the specified file input, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      Parameters:
      src - the random access input. The content of this input will not be read into the Fits object until the user makes some explicit request.
      Throws:
      FitsException - if the input could not bew repositions to its beginning
      Since:
      1.18
      See Also:

    • Fits

      public Fits(InputStream str) throws FitsException

      Creates a new (empty) FITS container associated with the given input stream. Compression is determined from the first few bytes of the stream.

      While the FITS object is associated with the specified input stream, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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
      See Also:

    • Fits

      @Deprecated public Fits(InputStream str, boolean compressed) throws FitsException
      Deprecated.
      Use Fits(InputStream) instead (compression is auto detected). Will remove in the future.

      Creates a new (empty) FITS container associated with an input stream.

      While the FITS object is associated with the specified input stream, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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
      See Also:

    • Fits

      public Fits(String filename) throws FitsException

      Creates a new (empty) FITS container with a file or URL as its input. 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.

      While the FITS object is associated with the specified file, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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.
      See Also:

    • Fits

      public Fits(String filename, boolean compressed) throws FitsException
      Deprecated.
      Use Fits(String) instead (compression is auto detected). Will be a private method in the future.

      Creates a new (empty) FITS container associated with a file or URL as its input. 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.

      While the FITS object is associated with the specified file, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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.
      See Also:

    • Fits

      public Fits(URL myURL) throws FitsException

      Creates a new (empty) FITS container with a given URL as its input.

      While the FITS object is associated with the resource, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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.
      See Also:

    • Fits

      @Deprecated public Fits(URL myURL, boolean compressed) throws FitsException
      Deprecated.
      Use Fits(URL) instead (compression is auto detected). Will remove in the future.

      Creates a new (empty) FITS container associated with a given uncompressed URL as its input.

      While the FITS object is associated with the resource, it is initialized as an empty container with no data loaded from the input automatically. You may want to call read() to load all data from the input and/or readHDU()/getHDU(int) for select HDUs, which you can then add via addHDU(BasicHDU) to the container.

      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.
      See Also:

  • Method Details

    • makeHDU

      public static <DataClass extends Data> BasicHDU<DataClass> makeHDU(DataClass data) throws FitsException
      Creates a new empty HDU for the given data type.
      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
      Creates a new empty HDU based on the header description of the data
      Parameters:
      h - The header which describes the FITS extension
      Returns:
      a newly created HDU from the given header (and including the header).
      Throws:
      FitsException - if the header could not be converted to a HDU.

    • makeHDU

      public static BasicHDU<?> makeHDU(Object o) throws FitsException

      Creates an HDU that wraps around the specified data object. The HDUs header will be created and populated with the essential description of the data. The following HDU types may be returned depending on the nature of the argument:

      As of 1.18, this metohd will not create and return random group HDUs for Object[][2] style data. Instead, it will return an appropriate binary or ASCII table, since the FITS standard recommends against using random groups going forward, except for reading some old data from certain radio telescopes. If the need ever arises to create new random groups HDUs with this library, you may use RandomGroupsHDU.createFrom(Object[][]) instead.

      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.
      See Also:

    • version

      public static String version()
      Returns the version sting of this FITS library
      Returns:
      the version of the library.

    • saveClose

      public static void saveClose(InputStream in)
      Deprecated.
      Use try-with-resources constructs in Java 8+ instead.
      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.
      See Also:

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

    • getHDU

      public BasicHDU<?> getHDU(int n) throws FitsException, IOException, IndexOutOfBoundsException
      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.
      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 - if the header could not be read
      IOException - if the underlying buffer threw an error
      IndexOutOfBoundsException - if the Fits contains no HDU by the given index.
      See Also:

    • getPrimaryHeader

      public Header getPrimaryHeader() throws FitsException, IOException
      Returns the primary header of this FITS file, that is the header of the primary HDU in this Fits object. This method differs from getHDU(0).getHeader(), int that the primary header this way will be properly configured as the primary HDU with all mandatory keywords, even if the HDU's header did not contain these entries originally. (Subsequent calls to getHDU(0).getHeader() will also contain the populated mandatory keywords).
      Returns:
      The primary header of this FITS file/object.
      Throws:
      FitsException - If the Fits is empty (does not contain a primary HDU)
      IOException - if there was a problem accessing the FITS from the input
      Since:
      1.19
      See Also:

    • getCompleteHeader

      public Header getCompleteHeader(int n) throws FitsException, IOException, IndexOutOfBoundsException
      Returns the 'complete' header of the nth HDU in this FITS file/object. This differs from getHDU(int).getHeader() in two important ways:
      • The header will be populated with the mandatory FITS keywords based on whether it is that of a primary or extension HDU in this Fits, and the type of HDU it is. (Subsequent calls to getHDU(n).getHeader() will also include the populated mandatory keywords.)
      • If the header contains the Standard.INHERIT keyword, a new header object is returned, which merges the non-conflicting primary header keys on top of the keywords explicitly defined in the HDU already.
      Parameters:
      n - The zero-based index of the HDU.
      Returns:
      The completed header of the HDU. If the HDU contains the INHERIT key this header will be a new header object constructed by this call to include also all non-conflicting primary header keywords. Otherwise it will simply return the HDUs header (after adding the mandatory keywords).
      Throws:
      FitsException - If the FITS is empty
      IOException - If the HDU is not accessible from its source
      IndexOutOfBoundsException - If the FITS does not contain a HDU by the specified index
      Since:
      1.19
      See Also:

    • getCompleteHeader

      public Header getCompleteHeader(String name) throws FitsException, IOException, NoSuchElementException
      Returns the complete header of the first HDU by the specified name in this FITS file/object. This differs from getHDU(String).getHeader() in two important ways:
      • The header will be populated with the mandatory FITS keywords based on whether it is that of a primary or extension HDU in this Fits, and the type of HDU it is. (Subsequent calls to getHDU(n).getHeader() will also include the populated mandatory keywords.)
      • If the header contains the Standard.INHERIT keyword, a new header object is returned, which merges the non-conflicting primary header keys on top of the keywords explicitly defined in the HDU already.
      Parameters:
      name - The HDU name
      Returns:
      The completed header of the HDU. If the HDU contains the INHERIT key this header will be a new header object constructed by this call to include also all non-conflicting primary header keywords. Otherwise it will simply return the HDUs header (after adding the mandatory keywords).
      Throws:
      FitsException - If the FITS is empty
      IOException - If the HDU is not accessible from its source
      NoSuchElementException - If the FITS does not contain a HDU by the specified name
      Since:
      1.19
      See Also:

    • getCompleteHeader

      public Header getCompleteHeader(String name, int version) throws FitsException, IOException, NoSuchElementException
      Returns the complete header of the first HDU by the specified name and version in this FITS file/object. This differs from getHDU(String).getHeader() in two important ways:
      • The header will be populated with the mandatory FITS keywords based on whether it is that of a primary or extension HDU in this Fits, and the type of HDU it is. (Subsequent calls to getHDU(n).getHeader() will also include the populated mandatory keywords.)
      • If the header contains the Standard.INHERIT keyword, a new header object is returned, which merges the non-conflicting primary header keys on top of the keywords explicitly defined in the HDU already.
      Parameters:
      name - The HDU name
      version - The HDU version
      Returns:
      The completed header of the HDU. If the HDU contains the INHERIT key this header will be a new header object constructed by this call to include also all non-conflicting primary header keywords. Otherwise it will simply return the HDUs header (after adding the mandatory keywords).
      Throws:
      FitsException - If the FITS is empty
      IOException - If the HDU is not accessible from its source
      NoSuchElementException - If the FITS does not contain a HDU by the specified name and version
      Since:
      1.19
      See Also:

    • getHDU

      public BasicHDU<?> getHDU(String name) throws FitsException, IOException
      Returns the HDU by the given extension name (defined by EXTNAME header keyword). This method checks only for EXTNAME but will ignore the version (defined by EXTVER). If multiple HDUs have the same matching EXTNAME, this method will return the first match only.
      Parameters:
      name - The name of the HDU as defined by EXTNAME (case sensitive)
      Returns:
      The first HDU that matches the specified extension name and version, or null if the FITS does not contain a matching HDU.
      Throws:
      FitsException - if the header could not be read
      IOException - if the underlying buffer threw an error
      Since:
      1.17.0
      See Also:

    • getHDU

      public BasicHDU<?> getHDU(String name, int version) throws FitsException, IOException
      Returns the HDU by the given extension name and version (defined by EXTNAME and EXTVER keywords). If multiple HDUs have the same matching name and version, this method will return the first match only.
      Parameters:
      name - The name of the HDU as defined by EXTNAME (case sensitive)
      version - The extension version as defined by EXTVER in the matching HDU.
      Returns:
      The first HDU that matches the specified extension name and version, or null if the FITS does not contain a matching HDU.
      Throws:
      FitsException - if the header could not be read
      IOException - if the underlying buffer threw an error
      Since:
      1.17.0
      See Also:

    • getNumberOfHDUs

      public int getNumberOfHDUs()
      Get the number of HDUs currently available in memory. For FITS objects associated with an input this method returns only the number of HDUs that have already been read / scanned, e.g. via readHDU() or read() methods. Thus, if you want to know how many HDUs a FITS file might actually contain, you should call read() to register them all before calling this method.
      Returns:
      The number of HDU's in the object.
      See Also:

    • getStream

      public ArrayDataInput getStream()
      Returns the input from which this Fits is associated to (if any)..
      Returns:
      The associated data input, or null if this Fits container was not read from an input. Users may wish to call this function after opening a Fits object when they want low-level rea/wrte access to the FITS resource directly.

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

    • 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
      Deprecated.
      Use Fits(InputStream) constructor instead. We will remove this method in the future.
      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. This call may return any concrete subclass of BasicHDU, including compressed HDU types.
      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
      See Also:

    • setChecksum

      public void setChecksum(int hduIndex) throws FitsException, IOException

      Computes the CHECKSUM and DATASUM values for the specified HDU index and stores them in the HUS's header. For deferred data the data sum is calculated directly from the file (if possible), without loading the entire (potentially huge) data into RAM for the calculation.

      Parameters:
      hduIndex - The index of the HDU for which to compute and set the CHECKSUM and DATASUM header values.
      Throws:
      FitsException - if there was a problem computing the checksum for the HDU
      IOException - if there was an I/O error while accessing the data from the input
      Since:
      1.17
      See Also:

    • setChecksum

      public void setChecksum() throws FitsException, IOException

      Add or modify the CHECKSUM keyword in all headers. As of 1.17 the checksum for deferred data is calculated directly from the file (if possible), without loading the entire (potentially huge) data into RAM for the calculation.

      As of 1.17, the routine calculates checksums both for HDUs that are in RAM, as well as HDUs that were not yet loaded from the input (if any). Any HDUs not in RAM at the time of the call will stay in deferred mode (if the HDU itself supports it). After setting (new) checksums, you may want to call #rewrite()

      Throws:
      FitsException - if there was an error during the checksumming operation
      IOException - if there was an I/O error while accessing the data from the input
      See Also:

    • calcDatasum

      public long calcDatasum(int hduIndex) throws FitsException, IOException

      Calculates the data checksum for a given HDU in the Fits. If the HDU does not currently have data loaded from disk (in deferred read mode), the method will calculate the checksum directly from disk. Otherwise, it will calculate the datasum from the data in memory.

      Parameters:
      hduIndex - The index of the HDU for which to calculate the data checksum
      Returns:
      The data checksum. This may differ from the datasum or the original FITS input due to differences in padding used at the end of the data record by this library vs the library that was used to generate the FITS.
      Throws:
      FitsException - if there was an error processing the HDU.
      IOException - if there was an I/O error accessing the input.
      Since:
      1.17
      See Also:

    • calcChecksum

      public long calcChecksum(int hduIndex) throws FitsException, IOException
      Deprecated.
      Use BasicHDU.verifyIntegrity() instead when appropriate. It's not particularly useful since integrity checking does not use or require knowledge of this sum. May be removed from future releases.
      Calculates the FITS checksum for a given HDU in the Fits. If the HDU does not currently have data loaded from disk (i.e. in deferred read mode), the method will compute the checksum directly from disk. Otherwise, it will calculate the checksum from the data in memory and using the standard padding after it.
      Parameters:
      hduIndex - The index of the HDU for which to calculate the HDU checksum
      Returns:
      The checksum value that would appear in the header if this HDU was written to an output. This may differ from the checksum recorded in the input, due to different formating conventions used by this library vs the one that was used to generate the input.
      Throws:
      FitsException - if there was an error processing the HDU.
      IOException - if there was an I/O error accessing the input.
      Since:
      1.17
      See Also:

    • verifyIntegrity

      public void verifyIntegrity() throws FitsIntegrityException, FitsException, IOException
      Checks the integrity of all HDUs. HDUs that do not specify either CHECKSUM or DATASUM keyword will be ignored.
      Throws:
      FitsIntegrityException - if the FITS is corrupted, the message will inform about which HDU failed the integrity test first.
      FitsException - if the header or HDU is invalid or garbled.
      IOException - if the Fits object is not associated to a random-accessible input, or if there was an I/O error accessing the input.
      Since:
      1.18.1
      See Also:

    • setStream

      @Deprecated public void setStream(ArrayDataInput stream)
      Deprecated.
      This method is poorly conceived as we cannot really read FITS from just any ArrayDataInput but only those, which utilize FitsDecoder to convert Java types to FITS binary format, such as FitsInputStream or FitsFile (or else a wrapped DataInputStream). As such, this method is inherently unsafe as it can be used to parse FITS content iscorrectly. It will be removed from the public API in a future major release. 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
      See Also:

    • 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
      See Also:

    • write

      public void write(FitsFile file) throws IOException, FitsException
      Writes the contents to a designated FITS file. It is up to the caller to close the file as appropriate after writing to it.
      Parameters:
      file - a file that support FITS encoding
      Throws:
      FitsException - if there were any errors writing the contents themselves.
      IOException - if the underlying file could not be trimmed or closed.
      Since:
      1.16
      See Also:

    • write

      public void write(FitsOutputStream out) throws IOException, FitsException
      Writes the contents to a designated FITS output stream. It is up to the caller to close the stream as appropriate after writing to it.
      Parameters:
      out - an output stream that supports FITS encoding.
      Throws:
      FitsException - if there were any errors writing the contents themselves.
      IOException - if the underlying file could not be flushed or closed.
      Since:
      1.16
      See Also:

    • write

      public void write(File file) throws IOException, FitsException
      Writes the contents to a new file.
      Parameters:
      file - a file to which the FITS is to be written.
      Throws:
      FitsException - if there were any errors writing the contents themselves.
      IOException - if the underlying output stream could not be created or closed.
      See Also:

    • rewrite

      public void rewrite() throws FitsException, IOException
      Re-writes all HDUs that have been loaded (and possibly modified) to the disk, if possible -- or else does nothing. For HDUs that are in deferred mode (data unloaded and unchanged), only the header is re-written to disk. Otherwise, both header and data is re-written. Of course, rewriting is possible only if the sizes of all headers and data segments remain the same as before.
      Throws:
      FitsException - If one or more of the HDUs cannot be re-written, or if there was some other error serializing the HDUs to disk.
      IOException - If there was an I/O error accessing the output file.
      Since:
      1.17
      See Also:

    • write

      public void write(String fileName) throws IOException, FitsException
      Writes the contents to the specified file. It simply wraps write(File) for convenience.
      Parameters:
      fileName - the file name/path
      Throws:
      FitsException - if there were any errors writing the contents themselves.
      IOException - if the underlying stream could not be created or closed.
      Since:
      1.16
      See Also:

    • write

      @Deprecated public void write(DataOutput os) throws FitsException
      Deprecated.
      This method is poorly conceived as we cannot really write FITS to just any DataOutput but only to specific ArrayDataOutput, which utilize FitsEncoder to convert Java types to FITS binary format, such as FitsOutputStream or FitsFile (or else a wrapped DataOutputStream). As such, this method is inherently unsafe as it can be used to create unreadable FITS files. It will be removed from a future major release. Use one of the more appropriate other write() methods instead. Writes the contents to an external file or stream. The file or stream remains open and it is up to the caller to close it as appropriate.
      Parameters:
      os - A DataOutput stream.
      Throws:
      FitsException - if the operation failed
      See Also:

    • 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
      Deprecated.
      use FitsCheckSum.setChecksum(BasicHDU)
      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.
      use FitsCheckSum.checksum(byte[])
      calculate the checksum for the block of data
      Parameters:
      data - the data to create the checksum for
      Returns:
      the checksum