nom.tam.fits
Class Header

java.lang.Object
  extended by nom.tam.fits.Header
All Implemented Interfaces:
FitsElement

public class Header
extends java.lang.Object
implements FitsElement

This class describes methods to access and manipulate the header for a FITS HDU. This class does not include code specific to particular types of HDU. As of version 1.1 this class supports the long keyword convention which allows long string keyword values to be split among multiple keywords

    KEY        = 'ABC&'   /A comment
    CONTINUE      'DEF&'  / Another comment
    CONTINUE      'GHIJKL '
 
The methods getStringValue(key), addValue(key,value,comment) and deleteCard(key) will get, create/update and delete long string values if the longStringsEnabled flag is set. This flag is set automatically when a FITS header with a LONGSTRN card is found. The value is not checked. It may also be set/unset using the static method setLongStringsEnabled(boolean). [So if a user wishes to ensure that it is not set, it should be unset after any header is read] When long strings are found in the FITS header users should be careful not to interpose new header cards within a long value sequence. When writing long strings, the comment is included in the last card. If a user is writing long strings, a the keyword LONGSTRN = 'OGIP 1.0' should be added to the FITS header, but this is not done automatically for the user.


Constructor Summary
Header()
          Create an empty header
Header(ArrayDataInput is)
          Create a header and populate it from the input stream
Header(Data o)
          Create a header which points to the given data object.
Header(java.lang.String[] newCards)
          Create a header and initialize it with a vector of strings.
 
Method Summary
 void addLine(HeaderCard fcard)
          Add a card image to the header.
 void addLine(java.lang.String card)
          Add a card image to the header.
protected  void addLongString(java.lang.String key, java.lang.String val, java.lang.String comment)
           
 void addValue(java.lang.String key, boolean val, java.lang.String comment)
          Add or replace a key with the given boolean value and comment.
 void addValue(java.lang.String key, double val, java.lang.String comment)
          Add or replace a key with the given double value and comment.
 void addValue(java.lang.String key, long val, java.lang.String comment)
          Add or replace a key with the given long value and comment.
 void addValue(java.lang.String key, java.lang.String val, java.lang.String comment)
          Add or replace a key with the given string value and comment.
 boolean containsKey(java.lang.String key)
          Tests if the specified keyword is present in this table.
 void deleteKey(java.lang.String key)
          Delete the card associated with the given key.
 void dumpHeader(java.io.PrintStream ps)
          Print the header to a given stream.
 HeaderCard findCard(java.lang.String key)
          Find the card associated with a given key.
 java.lang.String findKey(java.lang.String key)
          Find the card associated with a given key.
 boolean getBooleanValue(java.lang.String key)
          Get the boolean value associated with the given key.
 boolean getBooleanValue(java.lang.String key, boolean dft)
          Get the boolean value associated with the given key.
 java.lang.String getCard(int n)
          Deprecated. An iterator should be used for sequential access to the header.
 long getDataSize()
          Return the size of the data including any needed padding.
 double getDoubleValue(java.lang.String key)
          Get the double value associated with the given key.
 double getDoubleValue(java.lang.String key, double dft)
          Get the double value associated with the given key.
 java.util.List<HeaderCard> getDuplicates()
          Return the list of duplicate cards.
 long getFileOffset()
          Get the offset of this header
 float getFloatValue(java.lang.String key)
          Get the float value associated with the given key.
 float getFloatValue(java.lang.String key, float dft)
          Get the float value associated with the given key.
 int getIntValue(java.lang.String key)
          Get the int value associated with the given key.
 int getIntValue(java.lang.String key, int dft)
          Get the value associated with the key as an int.
 java.lang.String getKey(int n)
          Deprecated. An iterator should be used for sequential access to the header.
static boolean getLongStringsEnabled()
           
 long getLongValue(java.lang.String key)
          Get the long value associated with the given key.
 long getLongValue(java.lang.String key, long dft)
          Get the long value associated with the given key.
 int getNumberOfCards()
          Find the number of cards in the header
 long getOriginalSize()
          Get the size of the original header in bytes.
 long getSize()
          Get the size of the header in bytes
 java.lang.String getStringValue(java.lang.String key)
          Get the String value associated with the given key.
 boolean hadDuplicates()
          Were duplicate header keys found when this record was read in?
 void insertComment(java.lang.String value)
          Add a COMMENT line.
 void insertCommentStyle(java.lang.String header, java.lang.String value)
          Add a line to the header using the COMMENT style, i.e., no '=' in column 9.
 void insertHistory(java.lang.String value)
          Add a HISTORY line.
 Cursor iterator()
          Get an iterator over the header cards
 Data makeData()
          Create the data element corresponding to the current header
 HeaderCard nextCard()
          Get the next card in the Header using the current iterator
 void pointToData(Data o)
          Deprecated. Use the appropriate Header constructor.
 void read(ArrayDataInput dis)
          Read a stream for header data.
static Header readHeader(ArrayDataInput dis)
          Create a header by reading the information from the input stream.
 void removeCard(java.lang.String key)
          Delete a key.
 boolean reset()
          Reset the file pointer to the beginning of the header
 void resetOriginalSize()
          Indicate that we can use the current internal size of the Header as the 'original' size (e.g., perhaps we've rewritten the header to disk).
 void rewrite()
          Rewrite the header.
 boolean rewriteable()
          Can the header be rewritten without rewriting the entire file?
 void setBitpix(int val)
          Set the BITPIX value for the header.
static void setLongStringsEnabled(boolean flag)
           
 void setNaxes(int val)
          Set the value of the NAXIS keyword
 void setNaxis(int axis, int dim)
          Set the dimension for a given axis.
 void setSimple(boolean val)
          Set the SIMPLE keyword to the given value.
 void setXtension(java.lang.String val)
          Set the XTENSION keyword to the given value.
 int size()
          Deprecated. see numberOfCards(). The units of the size of the header may be unclear.
 void updateLine(java.lang.String key, HeaderCard card)
          Update a line in the header
 void updateLines(Header newHdr)
          Overwrite the lines in the header.
 void write(ArrayDataOutput dos)
          Write the current header (including any needed padding) to the output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Header

public Header()
Create an empty header


Header

public Header(ArrayDataInput is)
       throws TruncatedFileException,
              java.io.IOException
Create a header and populate it from the input stream

Parameters:
is - The input stream where header information is expected.
Throws:
TruncatedFileException
java.io.IOException

Header

public Header(java.lang.String[] newCards)
Create a header and initialize it with a vector of strings.

Parameters:
newCards - Card images to be placed in the header.

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.
Method Detail

setLongStringsEnabled

public static void setLongStringsEnabled(boolean flag)

getLongStringsEnabled

public static boolean getLongStringsEnabled()

makeData

public Data makeData()
              throws FitsException
Create the data element corresponding to the current header

Throws:
FitsException

getOriginalSize

public long getOriginalSize()
Get the size of the original header in bytes.


resetOriginalSize

public void resetOriginalSize()
Indicate that we can use the current internal size of the Header as the 'original' size (e.g., perhaps we've rewritten the header to disk). Note that affects the results of rewriteable(), so users should not call this method unless the underlying data has actually been updated.


updateLine

public void updateLine(java.lang.String key,
                       HeaderCard card)
                throws HeaderCardException
Update a line in the header

Parameters:
key - The key of the card to be replaced.
card - A new card
Throws:
HeaderCardException

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.

Parameters:
newHdr - the list of new header data lines to replace the current ones.
Throws:
HeaderCardException
Since:
2005-10-24

getNumberOfCards

public int getNumberOfCards()
Find the number of cards in the header


iterator

public Cursor iterator()
Get an iterator over the header cards


getFileOffset

public long getFileOffset()
Get the offset of this header

Specified by:
getFileOffset in interface FitsElement

getDataSize

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

Returns:
the data segment size including any needed padding.

getSize

public long getSize()
Get the size of the header in bytes

Specified by:
getSize in interface FitsElement

findCard

public HeaderCard findCard(java.lang.String key)
Find the card associated with a given key. If found this sets the mark to the card, otherwise it unsets the mark.

Parameters:
key - The header key.
Returns:
null if the keyword could not be found; return the HeaderCard object otherwise.

getIntValue

public int getIntValue(java.lang.String key,
                       int dft)
Get the value associated with the key as an int.

Parameters:
key - The header key.
dft - The value to be returned if the key is not found.

getIntValue

public int getIntValue(java.lang.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.

getLongValue

public long getLongValue(java.lang.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(java.lang.String key,
                         long dft)
Get the long 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.

getFloatValue

public float getFloatValue(java.lang.String key,
                           float dft)
Get the float value associated with the given key.

Parameters:
key - The header key.
dft - The value to be returned if the key is not found.

getFloatValue

public float getFloatValue(java.lang.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.

getDoubleValue

public double getDoubleValue(java.lang.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(java.lang.String key,
                             double dft)
Get the double 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.

getBooleanValue

public boolean getBooleanValue(java.lang.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(java.lang.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.

getStringValue

public java.lang.String getStringValue(java.lang.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.

addLine

public void addLine(HeaderCard fcard)
Add a card image to the header.

Parameters:
fcard - The card to be added.

addLine

public void addLine(java.lang.String card)
             throws HeaderCardException
Add a card image to the header.

Parameters:
card - The card to be added.
Throws:
HeaderCardException - If the card is not valid.

readHeader

public static Header readHeader(ArrayDataInput dis)
                         throws TruncatedFileException,
                                java.io.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
java.io.IOException

read

public void read(ArrayDataInput dis)
          throws TruncatedFileException,
                 java.io.IOException
Read a stream for header data.

Specified by:
read in interface FitsElement
Parameters:
dis - The input stream to read the data from.
Throws:
TruncatedFileException
java.io.IOException

hadDuplicates

public boolean hadDuplicates()
Were duplicate header keys found when this record was read in?


getDuplicates

public java.util.List<HeaderCard> getDuplicates()
Return 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.


findKey

public java.lang.String findKey(java.lang.String key)
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.

write

public void write(ArrayDataOutput dos)
           throws FitsException
Write the current header (including any needed padding) to the output stream.

Specified by:
write in interface FitsElement
Parameters:
dos - The output stream to which the data is to be written.
Throws:
FitsException - if the header could not be written.

rewrite

public void rewrite()
             throws FitsException,
                    java.io.IOException
Rewrite the header.

Specified by:
rewrite in interface FitsElement
Throws:
FitsException
java.io.IOException

reset

public boolean reset()
Reset the file pointer to the beginning of the header

Specified by:
reset in interface FitsElement
Returns:
True if the reset succeeded.

rewriteable

public boolean rewriteable()
Can the header be rewritten without rewriting the entire file?

Specified by:
rewriteable in interface FitsElement

addValue

public void addValue(java.lang.String key,
                     boolean val,
                     java.lang.String comment)
              throws HeaderCardException
Add or replace a key with the given boolean value and comment.

Parameters:
key - The header key.
val - The boolean value.
comment - A comment to append to the card.
Throws:
HeaderCardException - If the parameters cannot build a valid FITS card.

addValue

public void addValue(java.lang.String key,
                     double val,
                     java.lang.String comment)
              throws HeaderCardException
Add or replace a key with the given double value and comment. Note that float values will be promoted to doubles.

Parameters:
key - The header key.
val - The double value.
comment - A comment to append to the card.
Throws:
HeaderCardException - If the parameters cannot build a valid FITS card.

addValue

public void addValue(java.lang.String key,
                     java.lang.String val,
                     java.lang.String comment)
              throws HeaderCardException
Add or replace a key with the given string value and comment.

Parameters:
key - The header key.
val - The string value.
comment - A comment to append to the card.
Throws:
HeaderCardException - If the parameters cannot build a valid FITS card.

addValue

public void addValue(java.lang.String key,
                     long val,
                     java.lang.String comment)
              throws HeaderCardException
Add or replace a key with the given long value and comment. Note that int's will be promoted to long's.

Parameters:
key - The header key.
val - The long value.
comment - A comment to append to the card.
Throws:
HeaderCardException - If the parameters cannot build a valid FITS card.

addLongString

protected void addLongString(java.lang.String key,
                             java.lang.String val,
                             java.lang.String comment)
                      throws HeaderCardException
Throws:
HeaderCardException

removeCard

public void removeCard(java.lang.String key)
                throws HeaderCardException
Delete a key.

Parameters:
key - The header key.
Throws:
HeaderCardException

insertCommentStyle

public void insertCommentStyle(java.lang.String header,
                               java.lang.String value)
Add a line to the header using the COMMENT style, i.e., no '=' in column 9.

Parameters:
header - The comment style header.
value - A string to follow the header.
Throws:
HeaderCardException - If the parameters cannot build a valid FITS card.

insertComment

public void insertComment(java.lang.String value)
                   throws HeaderCardException
Add a COMMENT line.

Parameters:
value - The comment.
Throws:
HeaderCardException - If the parameter is not a valid FITS comment.

insertHistory

public void insertHistory(java.lang.String value)
                   throws HeaderCardException
Add a HISTORY line.

Parameters:
value - The history record.
Throws:
HeaderCardException - If the parameter is not a valid FITS comment.

deleteKey

public void deleteKey(java.lang.String key)
Delete the card associated with the given key. Nothing occurs if the key is not found.

Parameters:
key - The header key.

containsKey

public final boolean containsKey(java.lang.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.

setSimple

public void setSimple(boolean val)
Set the SIMPLE keyword to the given value.

Parameters:
val - The boolean value -- Should be true for FITS data.

setXtension

public void setXtension(java.lang.String val)
Set the XTENSION keyword to the given value.

Parameters:
val - The name of the extension. "IMAGE" and "BINTABLE" are supported.

setBitpix

public void setBitpix(int val)
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.

setNaxes

public void setNaxes(int val)
Set the value of the NAXIS keyword

Parameters:
val - The dimensionality of the data.

setNaxis

public void setNaxis(int axis,
                     int dim)
Set the dimension for a given axis.

Parameters:
axis - The axis being set.
dim - The dimension

dumpHeader

public void dumpHeader(java.io.PrintStream ps)
Print the header to a given stream.

Parameters:
ps - the stream to which the card images are dumped.

size

public int size()
Deprecated. see numberOfCards(). The units of the size of the header may be unclear.

Find the number of cards in the header


getCard

public java.lang.String getCard(int n)
Deprecated. An iterator should be used for sequential access to the header.

Get the n'th card image in the header

Returns:
the card image; return null if the n'th card does not exist.

getKey

public java.lang.String getKey(int n)
Deprecated. An iterator should be used for sequential access to the header.

Get the n'th key in the header.

Returns:
the card image; return null if the n'th key does not exist.

pointToData

public void pointToData(Data o)
                 throws FitsException
Deprecated. Use the appropriate Header constructor.

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.

nextCard

public HeaderCard nextCard()
Get the next card in the Header using the current iterator