Package nom.tam.fits

Class Header

java.lang.Object
nom.tam.fits.Header
All Implemented Interfaces:
FitsElement
public class Header extends Object implements FitsElement

Access and manipulate the header of a HDU. FITS headers serve more than a single purpose:

  1. provide an essential description of the type, size, and layout of the HDUs data segment
  2. describe the data as completely as possible via standardized (or conventional) keywords
  3. provide storage for additional user-specific key / value pairs
  4. allow for comments to aid human readability

First and foremost headers provide a description of the data object that follows the header in the HDU. Some of that description is essential and critical to the integrity of the FITS file, such as the header keywords that describe the type, size, and layout of the data segment. This library will automatically populate the header with appropriate information using the mandatory keywords (such as SIMPLE or XTENSION, BITPIX, NAXIS, NAXISn, PCOUNT, GCOUNT keywords, as well as essential table column format descriptions). Users of the library should avoid overwriting these mandatory keywords manually, since they may corrupt the FITS file, rendering it unreadable.

Beyond the keywords that describe the type, shape, and size of data, the library will not add further information to the header. The users of the library are responsible to complete the header description as necessary. This includes non-enssential data descriptions (such as EXTNAME, BUNIT, OBSERVER, or optional table column descriptors TTYPEn, TUNITn, coordinate systems via the appropriate WCS keywords, or checksums). Users of the library are responsible for completing the data description using whatever standard or conventional keywords are available and appropriate. Please refer to the FITS Standard documentation to see what typical descriptions of data you might want to use.

Last but not least, the header is also a place where FITS creators can store (nearly) arbitrary key/value pairs. In earlier versions of the FITS standard, header keywords were restricted to max. 8 upper case letters and numbers (plus hyphen and underscore), and no more than 70 character value fields. However, as of FITS 4.0 (and even before as a registered convention), string values of arbitrary length may be stored using the OGIP 1.0 long string convention, while the ESO HIERARCH convention allows keywords with more than 8 characters and hierarchical keywords. Support, conformance, and compliance to these conventions can be toggled by static settings in FitsFactory to user preference.

As of version 1.16, we also support reserving space in headers for future additions using the ensureCardSpace(int) method, also part of the FITS 4.0 standard. It allows users to finish populating headers after data that follows the header is already written -- a useful feature for recording data from streaming sources.

  • Field Details

    • DEFAULT_COMMENT_ALIGN

      public static final int DEFAULT_COMMENT_ALIGN
      The default character position to which comments should be aligned if possible (zero-based). The fITS standard requires that 'fixed-format' values are right-justified to byte 30 (index 29 in Java), and recommends a space after that before the comment. As such, comments should normally start at byte 30 (counted from 0). (We will add a space at that position before the '/' indicating the comment start)
      See Also:

    • MIN_COMMENT_ALIGN

      public static final int MIN_COMMENT_ALIGN
      Deprecated.
      We will disable changing alignment in the future because it may violate the standard for 'fixed-format' header entries, and result in files that are unreadable by some other software. This constant will be obsoleted and removed.
      The earliest position (zero-based) at which a comment may start for a regular key/value entry.
      See Also:

    • MAX_COMMENT_ALIGN

      public static final int MAX_COMMENT_ALIGN
      Deprecated.
      We will disable changing alignment in the future because it may violate the standard for 'fixed-format' header entries, and result in files that are unreadable by some other software. This constant will be obsoleted and removed.
      The largest (zero-based) comment alignment allowed that can still contain some meaningful comment (word)
      See Also:

    • DEFAULT_KEYWORD_CHECK_POLICY

      public static final Header.KeywordCheck DEFAULT_KEYWORD_CHECK_POLICY
      The keyword checking mode used by the library until the user changes it it.
      Since:
      1.19

  • Constructor Details

    • Header

      public Header()
      Create a new header with the required default keywords for a standalone header.

    • Header

      public Header(ArrayDataInput is) throws TruncatedFileException, IOException
      Create a header and populate it from the input stream
      Parameters:
      is - The input stream where header information is expected.
      Throws:
      IOException - if the header could not be read.
      TruncatedFileException - if the stream ended prematurely

    • Header

      public Header(Data o) throws FitsException
      Create a header which points to the given data object.
      Parameters:
      o - The data object to be described.
      Throws:
      FitsException - if the data was not valid for this header.

    • Header

      public Header(String[] newCards)
      Create a header and initialize it with a vector of strings.
      Parameters:
      newCards - Card images to be placed in the header.

  • Method Details

    • readHeader

      public static Header readHeader(ArrayDataInput dis) throws TruncatedFileException, IOException
      Create a header by reading the information from the input stream.
      Parameters:
      dis - The input stream to read the data from.
      Returns:
      null if there was a problem with the header; otherwise return the header read from the input stream.
      Throws:
      TruncatedFileException - if the stream ended prematurely
      IOException - if the header could not be read.

    • setLongStringsEnabled

      @Deprecated public static void setLongStringsEnabled(boolean flag)
      Deprecated.
      please use FitsFactory.setLongStringsEnabled(boolean) instead.
      Parameters:
      flag - the new value for long-string enabling.

    • ensureCardSpace

      public void ensureCardSpace(int nCards)

      Reserves header card space for populating at a later time. When written to a stream, the header will be large enough to hold at least the specified number of cards. If the header has fewer physical cards then the remaining space will be padded with blanks, leaving space for future additions, as specified by the FITS 4.0 standard for preallocated header space.

      This method is also called by read(ArrayDataInput), with the number of cards (including reserved blank space) contained in the header input stream, in order to ensure that the header remains rewritable even if it is shortened by the removal of cards (explicitly, or because they were duplicates).

      A new setting always overrides prior ones. For example, calling this method with an argument that is %lt;=1 will eliminate (reset) any prior preallocated header space.

      Parameters:
      nCards - the mimimum number of 80-character header records that is header must be able to support when written to a stream, including preallocated blank header space.
      Since:
      1.16
      See Also:

    • mergeDistinct

      public void mergeDistinct(Header source)
      Merges copies of all cards from another header, provided they are not readily present in this header. That is, it merges only the non-conflicting or distinct header entries from the designated source (in contrast to updateLines(Header)). All comment cards are merged also (since these can always appear multiple times, so they do not conflict). The merged entries are added at the end of the header, in the same order as they appear in the source. The merged entries will be copies of the cards in the original, such that subsequent modifications to the source will not affect this header or vice versa.
      Parameters:
      source - The header from which to inherit non-conflicting entries
      Since:
      1.19
      See Also:

    • addLine

      public void addLine(HeaderCard fcard) throws IllegalArgumentException
      Insert a new header card at the current position, deleting any prior occurence of the same card while maintaining the current position to point to after the newly inserted card.
      Parameters:
      fcard - The card to be inserted.
      Throws:
      IllegalArgumentException - if the current keyword checking mode does not allow the headercard with its standard keyword in the header.
      See Also:

    • setKeywordChecking

      public void setKeywordChecking(Header.KeywordCheck mode)

      Sets the built-in standard keyword checking mode. When populating the header using IFitsHeader keywords the library will check if the given keyword is appropriate for the type of HDU that the header represents, and will throw an IllegalArgumentException if the specified keyword is not allowed for that type of HDU.

      This method changes the keyword checking mode for this header instance only. If you want to change the mode for all newly created headers globally, use setDefaultKeywordChecking(KeywordCheck) instead.

      Parameters:
      mode - The keyword checking mode to use.
      Since:
      1.19
      See Also:

    • setDefaultKeywordChecking

      public static void setDefaultKeywordChecking(Header.KeywordCheck mode)
      Sets the default mode of built-in standard keyword checking mode for new headers. When populating the header using IFitsHeader keywords the library will check if the given keyword is appropriate for the type of HDU that the header represents, and will throw an IllegalArgumentException if the specified keyword is not allowed for that type of HDU.
      Parameters:
      mode - The keyword checking policy to use.
      Since:
      1.19
      See Also:

    • getKeywordChecking

      public final Header.KeywordCheck getKeywordChecking()
      Returns the current keyword checking mode.
      Returns:
      the current keyword checking mode
      Since:
      1.19
      See Also:

    • addValue

      public HeaderCard addValue(IFitsHeader key, Boolean val) throws HeaderCardException, IllegalArgumentException
      Add or replace a key with the given boolean value and its standardized comment. If the value is not compatible with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The new card will be placed at the current mark position, as set e.g. by findCard(IFitsHeader).
      Parameters:
      key - The header key.
      val - The boolean value.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      IllegalArgumentException - If the keyword is invalid
      See Also:

    • addValue

      public HeaderCard addValue(IFitsHeader key, Number val) throws HeaderCardException, IllegalArgumentException
      Add or replace a key with the given double value and its standardized comment. If the value is not compatible with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The new card will be placed at the current mark position, as set e.g. by findCard(IFitsHeader).
      Parameters:
      key - The header key.
      val - The double value.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      IllegalArgumentException - If the keyword is invalid
      See Also:

    • addValue

      public HeaderCard addValue(IFitsHeader key, String val) throws HeaderCardException, IllegalArgumentException
      Add or replace a key with the given string value and its standardized comment. If the value is not compatible with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The new card will be placed at the current mark position, as set e.g. by findCard(IFitsHeader).
      Parameters:
      key - The header key.
      val - The string value.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      IllegalArgumentException - If the keyword is invalid
      See Also:

    • addValue

      public HeaderCard addValue(IFitsHeader key, ComplexValue val) throws HeaderCardException, IllegalArgumentException
      Add or replace a key with the given complex value and its standardized comment. If the value is not compatible with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The new card will be placed at the current mark position, as set e.g. by findCard(IFitsHeader).
      Parameters:
      key - The header key.
      val - The complex value.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      IllegalArgumentException - If the keyword is invalid
      Since:
      1.17
      See Also:

    • addValue

      public HeaderCard addValue(String key, Boolean val, String comment) throws HeaderCardException
      Add or replace a key with the given boolean value and comment. The new card will be placed at the current mark position, as set e.g. by findCard(String).
      Parameters:
      key - The header key.
      val - The boolean value.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      See Also:

    • addValue

      public HeaderCard addValue(String key, Number val, String comment) throws HeaderCardException
      Add or replace a key with the given number value and comment. The value will be represented in the header card with use the native precision of the value or at least FlexFormat.DOUBLE_DECIMALS, whichever fits in the available card space. Trailing zeroes will be ommitted. The new card will be placed at the current mark position, as set e.g. by findCard(String).
      Parameters:
      key - The header key.
      val - The number value.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      See Also:

    • addValue

      public HeaderCard addValue(String key, Number val, int decimals, String comment) throws HeaderCardException
      Add or replace a key with the given number value and comment, using up to the specified decimal places after the leading figure. Trailing zeroes will be ommitted. The new card will be placed at the current mark position, as set e.g. by findCard(String).
      Parameters:
      key - The header key.
      val - The number value.
      decimals - The number of decimal places to show after the leading figure, or FlexFormat.AUTO_PRECISION to use the native precision of the value or at least FlexFormat.DOUBLE_DECIMALS, whichever fits in the available card space.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      See Also:

    • addValue

      public HeaderCard addValue(String key, ComplexValue val, String comment) throws HeaderCardException
      Add or replace a key with the given complex number value and comment. Trailing zeroes will be ommitted. The new card will be placed at the current mark position, as set e.g. by findCard(String).
      Parameters:
      key - The header keyword.
      val - The complex number value.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      Since:
      1.16
      See Also:

    • addValue

      public HeaderCard addValue(String key, ComplexValue val, int decimals, String comment) throws HeaderCardException
      Add or replace a key with the given complex number value and comment, using up to the specified decimal places after the leading figure. Trailing zeroes will be ommitted. The new card will be placed at the current mark position, as set e.g. by findCard(String).
      Parameters:
      key - The header keyword.
      val - The complex number value.
      decimals - The number of decimal places to show after the leading figure, or FlexFormat.AUTO_PRECISION to use the native precision of the value, or at least FlexFormat.DOUBLE_DECIMALS, whichever fits in the available card space.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      Since:
      1.16
      See Also:

    • addHexValue

      @Deprecated public HeaderCard addHexValue(String key, long val, String comment) throws HeaderCardException
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself. We will remove this method in the future.
      Parameters:
      key - The header key.
      val - The integer value.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      Since:
      1.16
      See Also:

    • addValue

      public HeaderCard addValue(String key, String val, String comment) throws HeaderCardException
      Add or replace a key with the given string value and comment. The new card will be placed at the current mark position, as set e.g. by findCard(String).
      Parameters:
      key - The header key.
      val - The string value.
      comment - A comment to append to the card.
      Returns:
      the new card that was added.
      Throws:
      HeaderCardException - If the parameters cannot build a valid FITS card.
      See Also:

    • card

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

    • containsKey

      public final boolean containsKey(IFitsHeader key)
      Tests if the specified keyword is present in this table.
      Parameters:
      key - the keyword to be found.
      Returns:
      true if the specified keyword is present in this table; false otherwise.

    • containsKey

      public final boolean containsKey(String key)
      Tests if the specified keyword is present in this table.
      Parameters:
      key - the keyword to be found.
      Returns:
      true if the specified keyword is present in this table; false otherwise.

    • deleteKey

      public void deleteKey(IFitsHeader key)
      Delete the card associated with the given key. Nothing occurs if the key is not found.
      Parameters:
      key - The header key.

    • deleteKey

      public void deleteKey(String key)
      Delete the card associated with the given key. Nothing occurs if the key is not found.
      Parameters:
      key - The header key.

    • dumpHeader

      public void dumpHeader(PrintStream ps)
      Print the header to a given stream. Note that this method does not show reserved card space before the END keyword, and thus does not necessarily show the same layout as what would appear in a file.
      Parameters:
      ps - the stream to which the card images are dumped.
      See Also:

    • getCard

      public HeaderCard getCard(IFitsHeader key)
      Returns the card associated with a given key. Unlike findCard(IFitsHeader), it does not alter the mark position at which new cards are added.
      Parameters:
      key - the header key.
      Returns:
      null if the keyword could not be found; return the HeaderCard object otherwise.
      Since:
      1.18.1
      See Also:

    • findCard

      public HeaderCard findCard(IFitsHeader key)
      Find the card associated with a given key. If found this sets the mark (cursor) to the card, otherwise it unsets the mark. The mark is where new cards will be added to the header by default. If you do not want to change the mark position, use getCard(IFitsHeader) instead.
      Parameters:
      key - The header key.
      Returns:
      null if the keyword could not be found; return the HeaderCard object otherwise.
      See Also:

    • getCard

      public HeaderCard getCard(String key)
      Returns the card associated with a given key. Unlike findCard(String), it does not alter the mark position at which new cards are added.
      Parameters:
      key - the header key.
      Returns:
      null if the keyword could not be found; return the HeaderCard object otherwise.
      Since:
      1.18.1
      See Also:

    • findCard

      public HeaderCard findCard(String key)
      Finds the card associated with a given key, and returns it. If found this sets the mark (cursor) to just before the card, such that nextCard() will return that very same card on the first subsequent call. If the header contains no matching entry, the mark is reset to the tail of the header (the same as seekTail()). The mark determines where new cards will be added to the header by default. If you do not want to alter the mark position, use getCard(String) instead.
      Parameters:
      key - the header key.
      Returns:
      Returns the header entry for the given keyword, or null if the header has no such entry.
      See Also:

    • findCards

      public HeaderCard[] findCards(String regex)
      brief Collect the header cards that match a regular expression. This is useful if one needs to search for a keyword that is buried under some HIERARCH string conventions of unspecified depth. So to search for some key like "HIERARCH OBO SUBOBO MYOBO", which would appear with the key HIERARCH.OBO.SUBOBO.MYOBO in this FITS implementation, one could search with regex="HIER.*MYOBO" and find it, supposed FitsFactory.setUseHierarch(true) was called before creating the header.
      Parameters:
      regex - The generalized regular expression for the keyword search
      Returns:
      The list of header cards that match the regular expression.
      Since:
      1.19.1

    • findKey

      @Deprecated public String findKey(String key)
      Deprecated.
      Use findCard(String) or getCard(String) instead. Find the card associated with a given key.
      Parameters:
      key - The header key.
      Returns:
      null if the keyword could not be found; return the card image otherwise.

    • getBigDecimalValue

      public final BigDecimal getBigDecimalValue(IFitsHeader key)
      Deprecated.
      The FITS header does not support decimal types beyond those that can be represented by a 64-bit IEEE double-precision floating point value.
      Get the bid decimal value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0.0 if not found.

    • getBigDecimalValue

      public final BigDecimal getBigDecimalValue(IFitsHeader key, BigDecimal dft)
      Deprecated.
      The FITS header does not support decimal types beyond those that can be represented by a 64-bit IEEE double-precision floating point value.
      Get the big decimal value associated with the given key.
      Parameters:
      key - The header key.
      dft - The default value to return if the key cannot be found.
      Returns:
      the associated value.

    • getBigDecimalValue

      public final BigDecimal getBigDecimalValue(String key)
      Deprecated.
      The FITS header does not support decimal types beyond those that can be represented by a 64-bit IEEE double-precision floating point value.
      Get the big decimal value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0.0 if not found.

    • getBigDecimalValue

      public BigDecimal getBigDecimalValue(String key, BigDecimal dft)
      Deprecated.
      The FITS header does not support decimal types beyond those that can be represented by a 64-bit IEEE double-precision floating point value.
      Get the big decimal value associated with the given key.
      Parameters:
      key - The header key.
      dft - The default value to return if the key cannot be found.
      Returns:
      the associated value.

    • getBigIntegerValue

      public final BigInteger getBigIntegerValue(IFitsHeader key)
      Deprecated.
      The FITS header does not support integer types beyond those that can be represented by a 64-bit integer.
      Get the big integer value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      the associated value or 0 if not found.

    • getBigIntegerValue

      public final BigInteger getBigIntegerValue(IFitsHeader key, BigInteger dft)
      Deprecated.
      The FITS header does not support integer types beyond those that can be represented by a 64-bit integer.
      Get the big integer value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value to be returned if the key cannot be found.
      Returns:
      the associated value.

    • getBigIntegerValue

      public final BigInteger getBigIntegerValue(String key)
      Deprecated.
      The FITS header does not support integer types beyond those that can be represented by a 64-bit integer.
      Get the big integer value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0 if not found.

    • getBigIntegerValue

      public BigInteger getBigIntegerValue(String key, BigInteger dft)
      Deprecated.
      The FITS header does not support integer types beyond those that can be represented by a 64-bit integer.
      Get the big integer value associated with the given key.
      Parameters:
      key - The header key.
      dft - The default value to be returned if the key cannot be found.
      Returns:
      the associated value.

    • getComplexValue

      public final ComplexValue getComplexValue(String key)
      Get the complex number value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or ComplexValue.ZERO if not found.
      Since:
      1.16
      See Also:

    • getComplexValue

      public ComplexValue getComplexValue(String key, ComplexValue dft)
      Get the complex number value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value to return if the key cannot be found.
      Returns:
      the associated value.
      Since:
      1.16
      See Also:

    • getBooleanValue

      public final boolean getBooleanValue(IFitsHeader key)
      Get the boolean value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The value found, or false if not found or if the keyword is not a logical keyword.

    • getBooleanValue

      public final boolean getBooleanValue(IFitsHeader key, boolean dft)
      Get the boolean value associated with the given key.
      Parameters:
      key - The header key.
      dft - The value to be returned if the key cannot be found or if the parameter does not seem to be a boolean.
      Returns:
      the associated value.

    • getBooleanValue

      public final boolean getBooleanValue(String key)
      Get the boolean value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The value found, or false if not found or if the keyword is not a logical keyword.

    • getBooleanValue

      public boolean getBooleanValue(String key, boolean dft)
      Get the boolean value associated with the given key.
      Parameters:
      key - The header key.
      dft - The value to be returned if the key cannot be found or if the parameter does not seem to be a boolean.
      Returns:
      the associated value.

    • getCard

      @Deprecated public String getCard(int n)
      Deprecated.
      An iterator from iterator(int) or iterator() should be used for sequential access to the header.
      Get the n'th card image in the header
      Parameters:
      n - the card index to get
      Returns:
      the card image; return null if the n'th card does not exist.

    • getDataSize

      public long getDataSize()
      Return the size of the data including any needed padding.
      Returns:
      the data segment size including any needed padding.

    • getDoubleValue

      public final double getDoubleValue(IFitsHeader key)
      Get the double value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0.0 if not found.

    • getDoubleValue

      public final double getDoubleValue(IFitsHeader key, double dft)
      Get the double value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value to return if the key cannot be found.
      Returns:
      the associated value.

    • getDoubleValue

      public final double getDoubleValue(String key)
      Get the double value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0.0 if not found.

    • getDoubleValue

      public double getDoubleValue(String key, double dft)
      Get the double value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value to return if the key cannot be found.
      Returns:
      the associated value.

    • getDuplicates

      public List<HeaderCard> getDuplicates()

      Returns the list of duplicate cards in the order they appeared in the parsed header. You can access the first occurence of each of every duplicated FITS keyword using the usual Header.getValue(), and find further occurrences in the list returned here.

      The FITS standared strongly discourages using the keywords multiple times with assigned values, and specifies that the values of such keywords are undefined by definitions. Our library is thus far more tolerant than the FITS standard, allowing you to access each and every value that was specified for the same keyword.

      On the other hand FITS does not limit how many times you can add comment-style keywords to a header. If you must used the same keyword multiple times in your header, you should consider using comment-style entries instead.

      Returns:
      the list of duplicate cards. Note that when the header is read in, only the last entry for a given keyword is retained in the active header. This method returns earlier cards that have been discarded in the order in which they were encountered in the header. It is possible for there to be many cards with the same keyword in this list.
      See Also:

    • getDuplicateKeySet

      public Set<String> getDuplicateKeySet()
      Returns the set of keywords that had more than one value assignment in the parsed header.
      Returns:
      the set of header keywords that were assigned more than once in the same header, or null if there were no duplicate assignments.
      Since:
      1.17
      See Also:

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

    • getFloatValue

      public final float getFloatValue(IFitsHeader key)
      Get the float value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0.0 if not found.

    • getFloatValue

      public final float getFloatValue(IFitsHeader key, float dft)
      Get the float value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The value to be returned if the key is not found.
      Returns:
      the float value associated with the given key.

    • getFloatValue

      public final float getFloatValue(String key)
      Get the float value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0.0 if not found.

    • getFloatValue

      public float getFloatValue(String key, float dft)
      Get the float value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The value to be returned if the key is not found.
      Returns:
      the float value associated with the given key.

    • getIntValue

      public final int getIntValue(IFitsHeader key)
      Get the int value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0 if not found.

    • getIntValue

      public final int getIntValue(IFitsHeader key, int dft)
      Get the int value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The value to be returned if the key is not found.
      Returns:
      the value associated with the key as an int.

    • getIntValue

      public final int getIntValue(String key)
      Get the int value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0 if not found.

    • getIntValue

      public int getIntValue(String key, int dft)
      Get the int value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The value to be returned if the key is not found.
      Returns:
      the value associated with the key as an int.

    • getKey

      @Deprecated public String getKey(int n)
      Deprecated.
      An iterator from iterator(int) or iterator() should be used for sequential access to the header.
      Get the n'th key in the header.
      Parameters:
      n - the index of the key
      Returns:
      the card image; return null if the n'th key does not exist.

    • getLongValue

      public final long getLongValue(IFitsHeader key)
      Get the long value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0 if not found.

    • getLongValue

      public final long getLongValue(IFitsHeader key, long dft)
      Get the long value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value to be returned if the key cannot be found.
      Returns:
      the associated value.

    • getLongValue

      public final long getLongValue(String key)
      Get the long value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0 if not found.

    • getLongValue

      public long getLongValue(String key, long dft)
      Get the long value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value to be returned if the key cannot be found.
      Returns:
      the associated value.

    • getHexValue

      @Deprecated public final long getHexValue(String key)
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself.
      Parameters:
      key - The header key.
      Returns:
      The associated value or 0 if not found.
      Since:
      1.16
      See Also:

    • getHexValue

      public long getHexValue(String key, long dft)
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself.
      Parameters:
      key - The header key.
      dft - The default value to be returned if the key cannot be found.
      Returns:
      the associated value.
      Since:
      1.16
      See Also:

    • getNumberOfCards

      public int getNumberOfCards()
      Returns the nominal number of currently defined cards in this header. Each card can consist of one or more 80-character wide header records.
      Returns:
      the number of nominal cards in the header
      See Also:

    • getNumberOfPhysicalCards

      public int getNumberOfPhysicalCards()
      Returns the number of 80-character header records in this header, including an END marker (whether or not it is currently contained).
      Returns:
      the number of physical cards in the header, including the END marker.
      See Also:

    • getMinimumSize

      public long getMinimumSize()
      Returns the minimum number of bytes that will be written by this header, either as the original byte size of a header that was read, or else the minimum preallocated capacity after setting ensureCardSpace(int).
      Returns:
      the minimum byte size for this header. The actual header may take up more space than that (but never less!), depending on the number of cards contained.
      Since:
      1.16
      See Also:

    • getOriginalSize

      @Deprecated public final long getOriginalSize()
      Deprecated.
      for internal use) It should be a private method in the future. Returns the original size of the header in the stream from which it was read.
      Returns:
      the size of the original header in bytes, or 0 if the header was not read from a stream.
      See Also:

    • getSize

      public final 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.

    • getStringValue

      public final String getStringValue(IFitsHeader key)
      Get the String value associated with the given standard key.
      Parameters:
      key - The standard header key.
      Returns:
      The associated value or null if not found or if the value is not a string.
      See Also:

    • getStringValue

      public final String getStringValue(IFitsHeader key, String dft)
      Get the String value associated with the given standard key, or return a default value.
      Parameters:
      key - The standard header key.
      dft - The default value.
      Returns:
      The associated value or the default value if not found or if the value is not a string.
      See Also:

    • getStringValue

      public final String getStringValue(String key)
      Get the String value associated with the given key.
      Parameters:
      key - The header key.
      Returns:
      The associated value or null if not found or if the value is not a string.
      See Also:

    • getStringValue

      public String getStringValue(String key, String dft)
      Get the String value associated with the given key, or return a default value.
      Parameters:
      key - The header key.
      dft - The default value.
      Returns:
      The associated value or the default value if not found or if the value is not a string.
      See Also:

    • hadDuplicates

      public boolean hadDuplicates()
      Checks if the header had duplicate assignments in the FITS.
      Returns:
      Were duplicate header keys found when this record was read in?

    • insertCommentStyle

      public HeaderCard insertCommentStyle(String key, String comment)
      Adds a line to the header using the COMMENT style, i.e., no '=' in column 9. The comment text may be truncated to fit into a single record, which is returned. Alternatively, you can split longer comments among multiple consecutive cards of the same type by insertCommentStyleMultiline(String, String).
      Parameters:
      key - The comment style header keyword, or null for an empty comment line.
      comment - A string comment to follow. Illegal characters will be replaced by '?' and the comment may be truncated to fit into the card-space (71 characters).
      Returns:
      The new card that was inserted, or null if the keyword itself was invalid or the comment was null.
      See Also:

    • insertCommentStyleMultiline

      public int insertCommentStyleMultiline(String key, String comment)
      Adds a line to the header using the COMMENT style, i.e., no '=' in column 9. If the comment does not fit in a single record, then it will be split (wrapped) among multiple consecutive records with the same keyword. Wrapped lines will end with '&' (not itself a standard) to indicate comment cards that might belong together.
      Parameters:
      key - The comment style header keyword, or null for an empty comment line.
      comment - A string comment to follow. Illegal characters will be replaced by '?' and the comment may be split among multiple records as necessary to be fully preserved.
      Returns:
      The number of cards inserted.
      Since:
      1.16
      See Also:

    • insertComment

      public int insertComment(String value)
      Adds one or more consecutive COMMENT records, wrapping the comment text as necessary.
      Parameters:
      value - The comment.
      Returns:
      The number of consecutive COMMENT cards that were inserted
      See Also:

    • insertUnkeyedComment

      public int insertUnkeyedComment(String value)
      Adds one or more consecutive comment records with no keyword (bytes 1-9 left blank), wrapping the comment text as necessary.
      Parameters:
      value - The comment.
      Returns:
      The number of consecutive comment-style cards with no keyword (blank keyword) that were inserted.
      Since:
      1.16
      See Also:

    • insertBlankCard

      public void insertBlankCard()
      Adds a blank card into the header.
      Since:
      1.16
      See Also:

    • insertHistory

      public int insertHistory(String value)
      Adds one or more consecutive a HISTORY records, wrapping the comment text as necessary.
      Parameters:
      value - The history record.
      Returns:
      The number of consecutive HISTORY cards that were inserted
      See Also:

    • iterator

      public Cursor<String,HeaderCard> iterator()
      Returns a cursor-based iterator for this header's entries starting at the first entry.
      Returns:
      an iterator over the header cards

    • iterator

      @Deprecated public Cursor<String,HeaderCard> iterator(int index)
      Deprecated.
      We should never use indexed access to the header. This function will be removed in 2.0.
      Returns a cursor-based iterator for this header's entries.
      Parameters:
      index - the card index to start the iterator
      Returns:
      an iterator over the header cards starting at an index

    • seekHead

      public Cursor<String,HeaderCard> seekHead()
      Move the cursor to the end of the header. Subsequently, all addValue() calls will add new cards to the end of the header.
      Returns:
      the cursor after it has been repositioned to the end
      Since:
      1.18.1
      See Also:

    • seekTail

      public Cursor<String,HeaderCard> seekTail()
      Move the cursor to the end of the header. Subsequently, all addValue() calls will add new cards to the end of the header.
      Returns:
      the cursor after it has been repositioned to the end
      Since:
      1.18.1
      See Also:

    • makeData

      @Deprecated public Data makeData() throws FitsException
      Deprecated.
      (for internal use) Normally we either want to write a Java object to FITS (in which case we have the dataand want to make a header for it), or we read some data from a FITS input. In either case, there is no benefit of exposing such a function as this to the user.
      Returns:
      Create the data element corresponding to the current header
      Throws:
      FitsException - if the header did not contain enough information to detect the type of the data

    • nextCard

      public HeaderCard nextCard()
      Returns the header card at the currently set mark position and increments the mark position by one. The mark position determines the location at which new entries are added to the header. The mark is set either to just prior a particular card (e.g. via findCard(IFitsHeader).
      Returns:
      the next card in the Header using the built-in iterator
      See Also:

    • prevCard

      public HeaderCard prevCard()
      Returns the header card prior to the currently set mark position and decrements the mark position by one. The mark position determines the location at which new entries are added to the header. The mark is set either to just prior a particular card (e.g. via findCard(IFitsHeader).
      Returns:
      the next card in the Header using the built-in iterator
      Since:
      1.18.1
      See Also:

    • pointToData

      @Deprecated public void pointToData(Data o) throws FitsException
      Deprecated.
      Use the appropriate Header constructor instead. Will remove in a future releae.
      Create a header which points to the given data object.
      Parameters:
      o - The data object to be described.
      Throws:
      FitsException - if the data was not valid for this header.

    • isEmpty

      public boolean isEmpty()
      Checks if the header is empty, that is if it contains no cards at all.
      Returns:
      true if the header contains no cards, otherwise false.
      Since:
      1.16

    • read

      public void read(ArrayDataInput dis) throws TruncatedFileException, IOException

      Reads new header data from an input, discarding any prior content.

      As of 1.16, the header is ensured to (re)write at least the same number of cards as before, padding with blanks as necessary, unless the user resets the preallocated card space with a call to ensureCardSpace(int).

      Specified by:
      read in interface FitsElement
      Parameters:
      dis - The input stream to read the data from.
      Throws:
      TruncatedFileException - the the stream ended prematurely
      IOException - if the operation failed
      See Also:

    • removeCard

      @Deprecated public void removeCard(String key) throws HeaderCardException
      Deprecated.
      (duplicate method) Use deleteKey(String) instead.
      Delete a key.
      Parameters:
      key - The header key.
      Throws:
      HeaderCardException - if the operation failed

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

    • resetOriginalSize

      @Deprecated public final void resetOriginalSize()
      Deprecated.
      Use ensureCardSpace(int) with 1 as the argument instead.

      Resets any prior preallocated header space, such as was explicitly set by ensureCardSpace(int), or when the header was read from a stream to ensure it remains rewritable, if possible.

      For headers read from a stream, this will affect rewriteable(), so users should not call this method unless they do not intend to rewrite() this header into the original FITS.

      See Also:

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

    • setBitpix

      @Deprecated public void setBitpix(int val) throws IllegalArgumentException
      Deprecated.
      Use the safer setBitpix(Bitpix) instead.
      Set the BITPIX value for the header. The following values are permitted by FITS conventions:
      • 8 -- signed byte data. Also used for tables.
      • 16 -- signed short data.
      • 32 -- signed int data.
      • 64 -- signed long data.
      • -32 -- IEEE 32 bit floating point numbers.
      • -64 -- IEEE 64 bit floating point numbers.
      Parameters:
      val - The value set by the user.
      Throws:
      IllegalArgumentException - if the value is not a valid BITPIX value.
      See Also:

    • setBitpix

      @Deprecated public void setBitpix(Bitpix bitpix)
      Deprecated.
      (for internall use) Visibility will be reduced to the package level in the future.
      Sets a standard BITPIX value for the header.
      Parameters:
      bitpix - The predefined enum value, e.g. Bitpix.INTEGER.
      Since:
      1.16
      See Also:

    • setHeaderSorter

      public void setHeaderSorter(Comparator<String> headerSorter)
      Overwite the default header card sorter.
      Parameters:
      headerSorter - the sorter tu use or null to disable sorting

    • setNaxes

      @Deprecated public void setNaxes(int val)
      Deprecated.
      (for internal use) Visibility will be reduced to the package level in the future.
      Set the value of the NAXIS keyword
      Parameters:
      val - The dimensionality of the data.

    • setNaxis

      @Deprecated public void setNaxis(int axis, int dim)
      Deprecated.
      (for internal use) Visibility will be reduced to the package level in the future.
      Set the dimension for a given axis.
      Parameters:
      axis - The axis being set.
      dim - The dimension

    • setSimple

      @Deprecated public void setSimple(boolean val)
      Deprecated.
      (for internall use) Visibility will be reduced to the package level in the future.
      Set the SIMPLE keyword to the given value.
      Parameters:
      val - true for the primary header, otherwise false

    • setXtension

      @Deprecated public void setXtension(String val) throws IllegalArgumentException
      Deprecated.
      (for internall use) Visibility will be reduced to the package level in the future.
      Set the XTENSION keyword to the given value.
      Parameters:
      val - The name of the extension.
      Throws:
      IllegalArgumentException - if the string value contains characters that are not allowed in FITS headers, that is characters outside of the 0x20 thru 0x7E range.

    • size

      @Deprecated public int size()
      Deprecated.
      use getNumberOfCards(). The units of the size of the header may be unclear.
      Returns:
      the number of cards in the header

    • updateLine

      public void updateLine(IFitsHeader key, HeaderCard card) throws HeaderCardException
      Update a valued entry in the header, or adds a new header entry. If the header does not contain a prior entry for the specific keyword, or if the keyword is a comment-style key, a new entry is added at the current editing position. Otherwise, the matching existing entry is updated in situ.
      Parameters:
      key - The key of the card to be replaced (or added).
      card - A new card
      Throws:
      HeaderCardException - if the operation failed

    • updateLine

      public final void updateLine(String key, HeaderCard card) throws HeaderCardException
      Update an existing card in situ, without affecting the current position, or else add a new card at the current position.
      Parameters:
      key - The key of the card to be replaced.
      card - A new card
      Throws:
      HeaderCardException - if the operation failed

    • updateLines

      public void updateLines(Header newHdr) throws HeaderCardException
      Overwrite the lines in the header. Add the new PHDU header to the current one. If keywords appear twice, the new value and comment overwrite the current contents. By Richard J Mathar.
      Parameters:
      newHdr - the list of new header data lines to replace the current ones.
      Throws:
      HeaderCardException - if the operation failed
      See Also:

    • validate

      public void validate(boolean asPrimary) throws FitsException
      Validates this header by making it a proper primary or extension header. In both cases it means adding required keywords if missing, and removing conflicting cards. Then ordering is checked and corrected as necessary and ensures that the END card is at the tail.
      Parameters:
      asPrimary - true if this header is to be a primary FITS header
      Throws:
      FitsException - If there was an issue getting the header into proper form.
      Since:
      1.17

    • writeUnchecked

      public void writeUnchecked(ArrayDataOutput out) throws FitsException, IOException
      (for internal use) Similar to write(ArrayDataOutput), but writes the header as is, without ensuring that mandatory keys are present, and in the correct order, or that checksums are updated.
      Parameters:
      out - The output file or stream to which to write
      Throws:
      FitsException - if there was a violation of the FITS standard
      IOException - if the output was not accessible
      Since:
      1.20.1
      See Also:

    • write

      public void write(ArrayDataOutput out) 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:
      out - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.

    • setParserWarningsEnabled

      public static void setParserWarningsEnabled(boolean value)

      Sets whether warnings about FITS standard violations are logged when a header is being read (parsed). Enabling this feature can help identifying various standard violations in existing FITS headers, which nevertheless do not prevent the successful reading of the header by this library.

      If FitsFactory.setAllowHeaderRepairs(boolean) is set false, this will affect only minor violations (e.g. a misplaced '=', missing space after '=', non-standard characters in header etc.), which nevertheless do not interfere with the unamiguous parsing of the header information. More severe standard violations, where some guessing may be required about the intent of some malformed header record, will throw appropriate exceptions. If, however, FitsFactory.setAllowHeaderRepairs(boolean) is set true, the parsing will throw fewer exceptions, and the additional issues may get logged as additional warning instead.

      Parameters:
      value - true if parser warnings about FITS standard violations when reading in existing FITS headers are to be logged, otherwise false
      Since:
      1.16
      See Also:

    • isParserWarningsEnabled

      public static boolean isParserWarningsEnabled()
      Checks whether warnings about FITS standard violations are logged when a header is being read (parsed).
      Returns:
      true if parser warnings about FITS standard violations when reading in existing FITS headers are enabled and logged, otherwise false
      Since:
      1.16
      See Also:

    • getCommentAlignPosition

      public static int getCommentAlignPosition()
      Returns the current preferred alignment character position of inline header comments. This is the position at which the '/' is placed for the inline comment. #deprecated
      Returns:
      The current alignment position for inline comments.
      Since:
      1.17
      See Also:

    • setCommentAlignPosition

      public static void setCommentAlignPosition(int pos) throws IllegalArgumentException
      Deprecated.
      Not recommended as it may violate the FITS standart for 'fixed-format' header entries, and make our FITS files unreadable by software that expects strict adherence to the standard. We will remove this feature in the future.
      Sets a new alignment position for inline header comments.
      Parameters:
      pos - [20:70] The character position to which inline comments should be aligned if possible.
      Throws:
      IllegalArgumentException - if the position is outside of the allowed range.
      Since:
      1.17
      See Also: