Package nom.tam.fits

Class BasicHDU<DataClass extends Data>

java.lang.Object
nom.tam.fits.BasicHDU<DataClass>
Type Parameters:
DataClass - the generic type of data contained in this HDU instance.
All Implemented Interfaces:
FitsElement
Direct Known Subclasses:
ImageHDU, RandomGroupsHDU, TableHDU, UndefinedHDU
public abstract class BasicHDU<DataClass extends Data> extends Object implements FitsElement
Abstract base class for all header-data unit (HDU) types. A HDU is a self-contained building block of the FITS files, which encapsulates information on a particular data object such as an image or table. As the name implies, HDUs constitute of a header and data entities, which can be accessed separately (via the getHeader() and getData() methods respectively). 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. It provides basic functionality for an HDU.

  • Field Details

  • Method Details

    • getDummyHDU

      @Deprecated public static NullDataHDU getDummyHDU()
      Deprecated.
      Use NullDataHDU instead. Gets a HDU with no data, only header.
      Returns:
      an HDU without content

    • isHeader

      public static boolean isHeader(Header header)
      Deprecated.
      (for internal use) Will be removed as it serves no purpose.
      Checks that this is a valid header for the HDU. This method is static but should be implemented by all subclasses.
      Parameters:
      header - to validate.
      Returns:
      true if this is a valid header.

    • isData

      public static boolean isData(Object o)
      Deprecated.
      (for internal use) Will be removed as it serves no purpose.
      Parameters:
      o - The Object being tested.
      Returns:
      if this object can be described as a FITS image. This method is static but should be implemented by all subclasses.

    • addValue

      public void addValue(IFitsHeader key, boolean val) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(IFitsHeader key, double val) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(IFitsHeader key, int val) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(IFitsHeader key, String val) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(String key, boolean val, String comment) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      comment - comment for the key/value pair
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(String key, double val, String comment) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      comment - comment for the key/value pair
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(String key, int val, String comment) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      comment - comment for the key/value pair
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • addValue

      public void addValue(String key, String val, String comment) throws HeaderCardException
      Add information to the header.
      Parameters:
      key - key to add to the header
      val - value for the key to add
      comment - comment for the key/value pair
      Throws:
      HeaderCardException - if the card does not follow the specification
      See Also:

    • getAuthor

      public String getAuthor()
      Return the name of the person who compiled the information in the data associated with this header.
      Returns:
      either null or a String object

    • getAxes

      public int[] getAxes() throws FitsException
      In FITS files the index represented by NAXIS1 is the index that changes most rapidly. This reflectsf the behavior of Fortran where there are true multidimensional arrays. In Java in a multidimensional array is an array of arrays and the first index is the index that changes slowest. So at some point a client of the library is going to have to invert the order. E.g., if I have a FITS file will 
       BITPIX=16
 NAXIS1=10
 NAXIS2=20
 NAXIS3=30
      this will be read into a Java array short[30][20][10] so it makes sense to me at least that the returned dimensions are 30,20,10
      Returns:
      the dimensions of the axis.
      Throws:
      FitsException - if the axis are configured wrong.

    • getBitpix

      public Bitpix getBitpix() throws FitsException
      Return the Bitpix enum type for this HDU.
      Returns:
      The Bitpix enum object for this HDU.
      Throws:
      FitsException - if the BITPIX value in the header is absent or invalid.
      Since:
      1.16
      See Also:

    • getBitPix

      public final int getBitPix() throws FitsException
      Deprecated.
      (for internal use) Will reduce visibility or remove entirely in the future.
      Return the BITPIX integer value as stored in the FIS header.
      Returns:
      The BITPIX integer values for this HDU as it appears in the header.
      Throws:
      FitsException - if the BITPIX value in the header is absent or invalid.
      See Also:

    • getBUnit

      public String getBUnit()
      Deprecated.
      This is only applicable to ImageHDU or RandomGroupsHDU and not for other HDU or data types.
      Returns the name of the physical unit in which images are represented.
      Returns:
      the standard name of the physical unit in which the image is expressed, e.g. "Jy beam^{-1}".

    • getBlankValue

      public long getBlankValue() throws FitsException
      Deprecated.
      This is only applicable to ImageHDU or RandomGroupsHDU with integer type data and not for other HDU or data types.
      Returns the integer value that signifies blank (missing or null) data in an integer image.
      Returns:
      the integer value used for identifying blank / missing data in integer images.
      Throws:
      FitsException - if the header does not specify a blanking value.

    • getBScale

      @Deprecated public double getBScale()
      Deprecated.
      This is only applicable to ImageHDU or RandomGroupsHDU with integer type data and not for other HDU or data types.
      Returns the floating-point increment between adjacent integer values in the image.
      Returns:
      the floating-point quantum that corresponds to the increment of 1 in the integer data representation.
      See Also:

    • getBZero

      @Deprecated public double getBZero()
      Deprecated.
      This is only applicable to ImageHDU or RandomGroupsHDU with integer type data and not for other HDU or data types.
      Returns the floating-point value that corresponds to an 0 integer value in the image.
      Returns:
      the floating point value that correspond to the integer 0 in the image data.
      See Also:

    • getCreationDate

      public Date getCreationDate()
      Get the FITS file creation date as a Date object.
      Returns:
      either null or a Date object

    • getData

      public DataClass getData()
      Returns the data component of this HDU.
      Returns:
      the associated Data object

    • getEpoch

      @Deprecated public double getEpoch()
      Deprecated.
      use getEquinox() instead
      Get the equinox in years for the celestial coordinate system in which positions given in either the header or data are expressed.
      Returns:
      either null or a String object

    • getEquinox

      public double getEquinox()
      Get the equinox in years for the celestial coordinate system in which positions given in either the header or data are expressed.
      Returns:
      either null or a String object

    • getFileOffset

      public long getFileOffset()
      Description copied from interface: FitsElement
      Returns the byte offset at which this element starts ina file. If the element was not obtained from an input, then 0 is returned.
      Specified by:
      getFileOffset in interface FitsElement
      Returns:
      the byte at which this element begins. This is only available if the data is originally read from a random access medium. Otherwise 0 is returned.

    • getGroupCount

      public int getGroupCount()
      Deprecated.
      Should not be exposed outside of RandomGroupsHDU -- will reduce visibility in the future/
      Returns the number of data objects (of identical shape and size) that are group together in this HDUs data segment. For most data types this would be simply 1, except for RandomGroupsData, where other values are possible.
      Returns:
      the number of data objects (of identical shape and size) that are grouped together in the data segment.
      See Also:

    • getStoredChecksum

      public long getStoredChecksum() throws FitsException
      Deprecated.
      Not very useful, since it has no meaning other than ensuring that the checksum of the HDU yields (int) -1 (that is 0xffffffff) after including this value for the CHECKSUM keyword in the header. It will be removed in the future. Use verifyIntegrity() instead when appropriate.
      Returns the decoded checksum that is stored in the header of this HDU under the CHECKSUM keyword. It does not have much use, and is not needed for integrity verification since the purpose of the CHECKSUM value is merely to ensure that the checksum of the HDU is always (int) -1.
      Returns:
      the decoded FITS checksum value recorded in the HDU
      Throws:
      FitsException - if the HDU's header does not contain a CHECKSUM keyword.
      Since:
      1.17
      See Also:

    • getStoredDatasum

      public long getStoredDatasum() throws FitsException
      Returns the FITS checksum for the HDU's data that is stored in the header of this HDU under the DATASUM keyword. This may be useful to compare against the checksum calculated from data in memory (e.g. via Data.calcChecksum()) to check changes / corruption of the in-memory data vs what was stored in the file. Note however, that this type of checkum test will fail if the file used non-standard padding at the end of the data segment, even if the data themselves are identical. Hence, for verifying data contained in a file verifyDataIntegrity() or verifyIntegrity() should be preferred.
      Returns:
      the FITS DATASUM value recorded in the HDU
      Throws:
      FitsException - if the HDU's header does not contain a DATASUM keyword.
      Since:
      1.17
      See Also:

    • setChecksum

      public void setChecksum() throws FitsException

      Computes the checksums for this HDU and stores the CHECKSUM and DATASUM values in the header. This should be the last modification to the HDU before writing it.

      Note, that this method will always calculate the checksum in memory. As a result it will load data in deferred read mode into RAM for performaing the calculation. If you prefer to keep deferred read mode data unloaded, you should use Fits.setChecksum(int) instead.

      Throws:
      FitsException - if there was an error serializing the HDU for the checksum computation.
      Since:
      1.17
      See Also:

    • verifyIntegrity

      public boolean verifyIntegrity() throws FitsException, IOException
      Checks the HDU's integrity, using the recorded CHECKSUM and/or DATASUM keywords if present. In addition of performing the same checks as verifyDataIntegrity(), it also checks the overall checksum of the HDU if possible. When the header has a CHECKSUM keyword stored, the overall checksum of the HDU must be 0xffffffff, that is -1 in 32-bit representation.
      Returns:
      true if the HDU has a CHECKSUM and/or DATASUM record to check against, otherwise false
      Throws:
      FitsException - if the HDU fails the integrity test.
      IOException - if there was an I/O error accessing the input.
      Since:
      1.18.1
      See Also:

    • verifyDataIntegrity

      public boolean verifyDataIntegrity() throws FitsException, IOException
      Checks that the HDUs data checksum is correct. The recorded DATASUM will be used, if available, to check the integrity of the data segment.
      Returns:
      true if the HDU has DATASUM record to check against, otherwise false
      Throws:
      FitsException - if the HDU fails the integrity test.
      IOException - if there was an I/O error accessing the input.
      Since:
      1.18.1
      See Also:

    • calcChecksum

      public long calcChecksum() throws FitsException
      Deprecated.
      Use 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.
      Computes and returns the FITS checksum for this HDU, e.g. to compare agains the stored CHECKSUM in the FITS header. This method always computes the checksum from data fully loaded in memory. As such it will load deferred read mode data into RAM to perform the calculation. If you prefer to leave the data in deferred read mode, you can use Fits.calcChecksum(int) instead.
      Returns:
      the computed HDU checksum (in memory).
      Throws:
      FitsException - if there was an error while calculating the checksum
      Since:
      1.17
      See Also:

    • getHeader

      public Header getHeader()
      Returns the FITS header component of this HDU
      Returns:
      the associated header
      See Also:

    • card

      public HeaderCardBuilder card(IFitsHeader key)
      Returns a header card builder for filling the header cards using the builder pattern.
      Parameters:
      key - the key for the first card.
      Returns:
      the builder for header cards.

    • getInstrument

      public String getInstrument()
      Get the name of the instrument which was used to acquire the data in this FITS file.
      Returns:
      either null or a String object

    • getKernel

      public final Object getKernel()
      Returns the underlying Java object (usually an array of some type) that stores the data internally.
      Returns:
      the non-FITS data object. Same as getData().getKernel().

    • getMaximumValue

      public double getMaximumValue()
      Return the minimum valid value in the array.
      Returns:
      minimum value.

    • getMinimumValue

      public double getMinimumValue()
      Return the minimum valid value in the array.
      Returns:
      minimum value.

    • getObject

      public String getObject()
      Get the name of the observed object in this FITS file.
      Returns:
      either null or a String object

    • getObservationDate

      public Date getObservationDate()
      Get the FITS file observation date as a Date object.
      Returns:
      either null or a Date object

    • getObserver

      public String getObserver()
      Get the name of the person who acquired the data in this FITS file.
      Returns:
      either null or a String object

    • getOrigin

      public String getOrigin()
      Get the name of the organization which created this FITS file.
      Returns:
      either null or a String object

    • getParameterCount

      public int getParameterCount()
      Deprecated.
      Should not be exposed outside of RandomGroupsHDU -- will reduce visibility in the future.
      Returns the number of parameter bytes (per data group) accompanying each data object in the group.
      Returns:
      the number of bytes used for arbitrary extra parameters accompanying each data object in the group.
      See Also:

    • getReference

      public String getReference()
      Return the citation of a reference where the data associated with this header are published.
      Returns:
      either null or a String object

    • getSize

      public long getSize()
      Description copied from interface: FitsElement
      Returns the size of this elements in the FITS representation. This may include padding if the element (such as a header or data segment) is expected to complete a FITS block of 2880 bytes.
      Specified by:
      getSize in interface FitsElement
      Returns:
      The size of this element in bytes, or 0 if the element is empty or invalid.

    • getTelescope

      public String getTelescope()
      Get the name of the telescope which was used to acquire the data in this FITS file.
      Returns:
      either null or a String object

    • getTrimmedString

      public String getTrimmedString(String keyword)
      Deprecated.
      (for internal use) Will reduced visibility in the future. Use Header.getStringValue(IFitsHeader) or similar instead followed by String.trim() if necessary.
      Get the String value associated with the header keyword. Trailing spaces are not significant in FITS headers and are automatically omitted during parsing. Leading spaces are however considered significant, and are retained otherwise.
      Parameters:
      keyword - the FITS keyword
      Returns:
      either null or a String with leading/trailing blanks stripped.

    • getTrimmedString

      public String getTrimmedString(IFitsHeader keyword)
      Deprecated.
      (for internal use) Will reduced visibility in the future. Use Header.getStringValue(String) or similar instead followed by String.trim() if necessary.
      Get the String value associated with the header keyword.with leading spaces removed. Trailing spaces are not significant in FITS headers and are automatically omitted during parsing. Leading spaces are however considered significant, and are retained otherwise.
      Parameters:
      keyword - the FITS keyword
      Returns:
      either null or a String with leading/trailing blanks stripped.

    • info

      public abstract void info(PrintStream stream) throws FitsException
      Print out some information about this HDU.
      Parameters:
      stream - the printstream to write the info on
      Throws:
      FitsException - if the HDU is malformed

    • read

      public void read(ArrayDataInput stream) throws FitsException, IOException
      Description copied from interface: FitsElement
      Read a FITS element from the input, starting at the current position. Ater the read, the implementations should leave the input position aligned to the start of the next FITS block.
      Specified by:
      read in interface FitsElement
      Parameters:
      stream - The input data stream
      Throws:
      FitsException - if the read was unsuccessful.
      IOException - if the read was unsuccessful.

    • reset

      public boolean reset()
      Description copied from interface: FitsElement
      Reset the input stream to point to the beginning of this element
      Specified by:
      reset in interface FitsElement
      Returns:
      True if the reset succeeded.

    • rewrite

      public void rewrite() throws FitsException, IOException
      Description copied from interface: FitsElement
      Rewrite the contents of the element in place. The data must have been originally read from a random access device, and the size of the element may not have changed.
      Specified by:
      rewrite in interface FitsElement
      Throws:
      FitsException - if the rewrite was unsuccessful.
      IOException - if the rewrite was unsuccessful.

    • rewriteable

      public boolean rewriteable()
      Description copied from interface: FitsElement
      Checks if we can write this element back to its source. An element can only be written back if it is associated to a random accessible input and the current size FITS within the old block size.
      Specified by:
      rewriteable in interface FitsElement
      Returns:
      true if this element can be rewritten?

    • write

      public void write(ArrayDataOutput stream) throws FitsException
      Description copied from interface: FitsElement
      Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.
      Specified by:
      write in interface FitsElement
      Parameters:
      stream - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.