Skip to content

FITSHeader

Jump to bottom
user29A edited this page Dec 14, 2021 · 5 revisions

Usage

FITSImageHeader class for managing FITS file Image headers. Typically this class is accessed via an instance of FITSImage, at FITSImage->Header. That is, when a FITSImage is constructed, it will contain its header already as part of its construction process. But if you require an instance of FITSImageHeader to do something with you may use this.

Constructors

FITSImageHeader(bool mayContainExtensions, array<double, 2>^ image); Creates an instance of a FITSImageHeader, with options to indicate whether extensions are present, and sets essential keywords for a given image it will be the header for. If the image is to be an extension, then use GetFormattedHeaderBlock to pull the header out with SIMPLE = T changed to XTENSION = IMAGE for writing.

  • mayContainExtensions If true, keyword EXTEND = T is added, otherwise it is left out.
  • image If image is nullptr, then NAXIS = 0 and there are no NAXISn keywords or BSCALE or BZERO. Otherwise NAXIS, NAXISn, BSCALE and BZERO are set as per the image dimensions. If the image will be saved at a different precision than double, use SetBITPIXNAXISBSCZ(precision, image) at write time.

FITSImageHeader(ArrayList^ headerlines, bool populate_nonessential); Creates an instance of a FITSImageHeader out of a String^ list of header lines. Typically the headerlines would be returned from FITSFILEOPS::SCANPRIMARYUNIT.

  • headerlines A String^ list of header lines to be extracted and formatted into keys, values, and comments, or as comment lines.
  • populate_nonessential If false, non-essential key lines will be ignored. Saves a little bit of construction time if you don't need those, but they'll be lost if you re-write the file without them.

Members

String^ GetKeyName(int index); GetKeyName returns the key name of the primary header line at index. Returns empty String if the index exceeds the number of header lines.

  • index The zero-based line number to get the key name from.

String^ GetKeyValue(int index); Returns the value of the primary header line at index. Returns empty String if the index exceeds the number of header lines.

String^ GetKeyComment(int index); Returns the comment of the primary header line at index. Returns empty String if the index exceeds the number of header lines. If the key is formatted as the comment, then it gets the entire line. To check is the line is a comment, use HeaderLineIsComment[index].

String^ GetKeyValue(String^ Key); Returns the value of the primary header key named Key. Returns empty String if the key is not found.

  • Key The header key to find the value of.

String^ GetKeyComment(String^ Key); GetKeyComment returns the comment of the primary header key named Key. Returns empty String if the key is not found.

int GetKeyIndex(String^ Key, bool KeyIsFullLineFormatted); Returns the zero-based index in the primary header of the key named Key. Returns -1 if the key is not found.

  • Key The header key to find the index of.
  • KeyIsFullLineFormatted If true then the entire formatted 80-element long line is compared; helpful if multiple keys have the same name or are formatted as comment lines.

int GetKeyIndex(String^ Key, String^ Value);

  • Key The header key to find the index of.
  • Value The matching header key value to find the index of. Helpful if multiple keys have the same name, but different values.

int GetKeyIndex(String^ Key, String^ Value, String^ Comment);

  • Key The header key to find the index of.
  • Value The matching header key value to find the index of.
  • Comment The matching header key comment to find the index of. Helpful if multiple keys have the same name and/or values and/or different comments.

void SetKey(String^ Key, String^ Value, bool AddIfNotFound, int AddAtIndex); Sets the value of the key. If the key already exists then the value will be replaced but the comment will remain the same.

  • Key The header key to access. Value The header key value to set.
  • AddIfNotFound Optionally add the key to the header if it isn't found.
  • AddAtIndex If the key wasn't found, add at this zero-based index. Use -1 to append to the end of the header (before END key). If keyIndex exceeds the header, the line is appended to the end of the header.

void SetKey(String^ Key, String^ Value, String^ Comment, bool AddIfNotFound, int AddAtIndex); SetKey sets the value and comment of the key. If the key already exists then the value and comment will be replaced.

  • Key The header key to access. Value The header key value to set.
  • AddIfNotFound Optionally add the key to the header if it isn't found. Comment The header key comment to set.
  • AddAtIndex If the key wasn't found, add at this zero-based index. Use -1 to append to the end of the header (before END key). If keyIndex exceeds the header, the line is appended to the end of the header.

void SetKey(int index, String^ Key, String^ Value, String^ Comment); Sets the key, value and comment of the key at the given header index. This will overwrite whatever key exists at that index.

void AddKey(String^ NewKey, String^ NewValue, String^ NewComment, int KeyIndex); Adds a new key with value and comment to the primary header.

  • KeyIndex Add at this zero-based index. Use -1 to append to the end of the header (before END key). If keyIndex exceeds the header, the line is appended to the end of the header.

public void AddKey(JPFITS.FITSHeaderKey keyLine, int keyIndex) AddKey adds a new key to the primary header.

  • keyIndex Add at this zero-based index. Use -1 to append to the end of the header (before END key).

void AddCommentKeyLine(String^ commentKeyLine, int keyIndex); Adds a new key line formatted as a comment. If the length of the commentKeyLine is more than 80 elements, the comment will be continued on subsequent lines until depleted. If the user wishes the line to begin with COMMENT, then write the input commentKeyLine beginning as such. If the user wishes the line to be blank, then pass commentKeyLine as an empty string or as only containing blanks (whitespace).

  • commentKeyLine The comment line.
  • keyIndex Insert at this zero-based index. Use -1 to append to the end of the header (before END key). If keyIndex exceeds the header, the line is appended to the end of the header.

public void MoveKey(int currentIndex, int newIndex) Move a key line to another position in the header.

void RemoveKey(int KeyIndex); Removes the key at the given index from the primary header.

  • KeyIndex The zero-based index of the key to remove. If the index is outside of the range of the header then nothing happens.

void RemoveKey(String^ Key); Removes the given key from the primary header. If there is more than one key with the given name, only the first occurrence will be removed.

  • Key The name of the header key to remove. If Key doesn't exist, nothing happens.

void RemoveKey(String^ Key, String^ Value); Removes the given key with matching value from the primary header. If there is more than one key with the given name and value, only the first occurence will be removed.

  • Key The name of the header key to remove. If Key doesn't exist, nothing happens.
  • Value The corresponding header key value.

void RemoveAllKeys(array<double, 2>^ image); Clears all keys from the primary header. Essential keywords will remain. image is supplied to re-create essential keywords, or pass nullptr to set NAXIS = 0.

void CopyHeaderFrom(JPFITS::FITSImageHeader^ sourceHeader); Copies a header from another FITSImageHeader into this one. Restricted keywords are neither copied nor overwritten.

void SetBITPIXNAXISBSCZ(TypeCode precision, array<double, 2>^ image); This sets the BITPIX, NAXIS, NAXISn, BSCALE and BZERO keywords of the header given the TypeCode and the image. If the image is null then NAXIS = 0 and any NAXISn keywords are removed as well as BSCALE and BZERO.

array<String^>^ GetFormattedHeaderBlock(bool asExtension, bool keysOnly); Returns a formatted header block with the existing keys, and sets the first key to either SIMPLE = T or XTENSION = IMAGE. If a full 2880-multiple block is needed, set keysOnly to false.

  • asExtension If true then the first keyword is set to XTENSION = IMAGE, otherwise it is SIMPLE = T.
  • keysOnly If true then only the existing keywords are returned formatted, otherwise if you need the entire 2880-multiple block (with padded white space) pass false. True typically needed for display, false typically needed for writing.

public static bool ValidKeyEdit(string key, bool showMessageBox) Returns whether the given key is an essential key and shouldn't be user-modified.

public string[] GetAllKeyNames() Returns all of the key names from the header.

Properties

public FITSHeaderKey this[int i] >Returns the FITSHeaderKey object at a given zero-based index in the header.

public int Length Returns the number of header key lines in the header, excluding any padding after END key.

array<String^>^ HeaderKeys Accesses an array of Strings of all keys of the primary header. Individual String^ keys may be accessed by indexing HeaderKeys[i].

array<String^>^ HeaderKeyValues HeaderKeyValues accesses a string array of all key values of the primary header. Individual String^ values may be accessed by indexing HeaderKeyValues[i].

array<String^>^ HeaderKeyComments HeaderKeyComments accesses a string array of all key comments of the primary header. Individual String^ comments may be accessed by indexing HeaderKeyComments[i].

String^ HeaderLine[int lineIndex] Returns a formatted header line from the existing key at the lineIndex.

bool HeaderLineIsComment[int lineIndex] Returns whether a header line at an index is formatted as a comment line.

Clone this wiki locally