FITSKeywordUtil.h

Classes

FITSKeywordUtil -- A class with static functions to help deal with FITS Keywords. (full description)

class FITSKeywordUtil

Interface

Public Members
static FitsKeywordList makeKeywordList()
static Bool addKeywords(FitsKeywordList &out, const RecordInterface &in)
static Bool getKeywords(RecordInterface &out, ConstFitsKeywordList &in, const ConstFitsKeywordList<Vector> &ignore, Bool ignoreHistory=True)
static void removeKeywords(RecordInterface &out, const Vector<Vector> &ignore)
static Bool fromTDIM(IPosition& shape, const String& tdim)
static Bool toTDIM(String& tdim, const IPosition& shape)
static void addComment(RecordInterface &header, const String &comment)
static void addHistory(RecordInterface &header, const String &history)

Description

Review Status

Reviewed By:
Eric Sessoms
Date Reviewed:
2002/08/19
Programs:
Tests:

Prerequisite

Etymology

This is a collection of static utility functions for use with FITS keywords.

Synopsis

This class provides functions to conveniently interconvert between AIPS++ types and a FitsKeywordList which is needed by the native FITS classes. It is more convenient to maintain the list within AIPS++ as a Record, so we only need methods to turn a FitsKeywordList into a Record, and vice versa.

Note that it is not necessary to construct a FITSKeywordUtil object since you can use its static functions directly.

Example

This example shows how you put values from a Record into a FItsKeywordList. 
    Record rec;
    rec.define("hello", 6.5);
    rec.define("world", True);
    Vector<Int> naxis(5); 
    naxis(0) = 128; 
    naxis(1) = 64; 
    naxis(2) = 32;
    naxis(3) = 16;
    naxis(4) = 8;
    rec.define("naxis", naxis);
    // fields can have comments
    rec.setComment("hello","A comment for HELLO");
    // Add a comment to the rec
    FITSKeywordUtil::addComment(rec,"My comment goes here");
    // Create an empty FitsKeywordList, containing only "SIMPLE=T"
    FitsKeywordList kwl = FITSKeywordUtil::makeKeywordList();
    // and add the fields in rec to this list
    FITSKeywordUtil::addKeywords(kwl, rec);

Example

This example shows how you extract fits keywords into a Record. 
    Record rec;
    FitsKeywordList kwl;
    ConstFitsKeywordList kwlRO;
    Vector<String> ignore(1);
    ignore(1)= "simple"; // ignore the SIMPLE keyword
    FITSKeywordUtil::getKeywords(rec, kwlRO, ignore);

Motivation

The FitsKeywordList class can be somewhat tedious to use, as it deals with, e.g., char* pointers rather than Strings. This class makes it easy to interconvert between FITS keywords and AIPS++ types.

To Do

Member Description

static FitsKeywordList makeKeywordList()

Make an initial FitsKeywordList containing only "SIMPLE = T" which is required of any FITS keyword list. This is provided as a convenience so that you do not have to know anything about the class FitsKeywordList.

static Bool addKeywords(FitsKeywordList &out, const RecordInterface &in)

Add the fields from in to the out FitsKeywordList as keywords. Upcases field names, turns arrays into indexed keywords, tries to interleave e.g. crval, crpix, etc. COMMENT* are standalone comments, and HISTORY* are history cards. (COMMENT and HISTORY may be of any capitalization). Note however that you will generally add History keywords with the class FITSHistoryUtil. Returns False in the following instances:

  • The value of a string field is longer than 68 characters. The value is truncated.
  • An illegal type for a FITS keyword (e.g. Complex). The field is ignored.
  • An array field has more than 2 dimensions. The field is stored as a vector.
  • An array field name is too long to hold the name and the index characters. The name is truncated.
  • Too many rows or columns for a 2D array (first 999 in each are used).
  • Too many elements in a 1D array (first 999 are used).
  • A field is neither a scalar or an array (e.g. a record). The field is ignored.

    static Bool getKeywords(RecordInterface &out, ConstFitsKeywordList &in, const ConstFitsKeywordList<Vector> &ignore, Bool ignoreHistory=True)

    Extract keywords from in and define them in out. Output field names are downcased. Keywords matching the names in ignore (which are treated as regular expressions) are not created in out. This test happens after the field names have been downcased. All indexed keywords will be ignored if the root name is in the ignore vector (e.g. NAXIS implies NAXIS4 and other indexed NAXIS keywords are ignored). By default history keywords are ignored, since they should be handled in class FITSHistoryUtil. This always returns True.

    static void removeKeywords(RecordInterface &out, const Vector<Vector> &ignore)

    Remove some keywords from a record. This can be useful if, e.g., you first need to construct a coordinate system from the header, but you later want to remove CROTA etc. The strings in the ignore vector are treated as regular expressions.

    static Bool fromTDIM(IPosition& shape, const String& tdim)

    Convert a TDIMnnn keyword value into an IPosition. This returns False if the tdim string has an invalid format.

    static Bool toTDIM(String& tdim, const IPosition& shape)

    Convert an IPosition to a String appropriate for use as the value of a TDIMnnn keyword. This returns False if the converted string has more than 71 characters (making it impossible to be used as a string keyword value).

    static void addComment(RecordInterface &header, const String &comment)
    static void addHistory(RecordInterface &header, const String &history)

    Add a comment/history to the supplied record. It will automatically figure out a unique name and add it to the end. If the comment contains embedded newlines this function will break the string across multiple FITS comment entries. At present it will not however make sure that the strings are short enough (i.e. <= 72 characters per line).

    Note that while you can add history anywhere into header, in the actual keyword list they will always appear after the END keyword.

    Note however that you will generally manipulate History keywords with the class FITSHistoryUtil.