casa::FITSKeywordUtil Class Reference

A class with static functions to help deal with FITS Keywords. More...

#include <FITSKeywordUtil.h>

List of all members.

Static Public Member Functions
static FitsKeywordList	makeKeywordList (Bool primHead=True, Bool binImage=True)
	Make an initial FitsKeywordList for either a FITS primary header or a FITS extension header (image or table).
static Bool	addKeywords (FitsKeywordList &out, const RecordInterface &in)
	Add the fields from in to the out FitsKeywordList as keywords.
static Bool	getKeywords (RecordInterface &out, ConstFitsKeywordList &in, const Vector< String > &ignore, Bool ignoreHistory=True)
	Extract keywords from in and define them in out.
static void	removeKeywords (RecordInterface &out, const Vector< String > &ignore)
	Remove some keywords from a record.
static Bool	fromTDIM (IPosition &shape, const String &tdim)
	Convert a TDIMnnn keyword value into an IPosition.
static Bool	toTDIM (String &tdim, const IPosition &shape)
	Convert an IPosition to a String appropriate for use as the value of a TDIMnnn keyword.
static void	addComment (RecordInterface &header, const String &comment)
	Add a comment/history to the supplied record.
static void	addHistory (RecordInterface &header, const String &history)

---

Detailed Description

A class with static functions to help deal with FITS Keywords.

Intended use:

Public interface

Review Status

Reviewed By:

Eric Sessoms

Date Reviewed:

2002/08/19

Test programs:

tFITSKeywordUtil

Prerequisite

• General knowledge of FITS, and particularly FITS keywords, is assumed.
• Presumably you are using this class in conjunction with the "native" FitsKeywordList
• You also need to understand the RecordInterface class.

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

• Get/set history as a vector of strings as well.
• This could be a namespace rather than a class.

Definition at line 128 of file FITSKeywordUtil.h.

---

Member Function Documentation

static void casa::FITSKeywordUtil::addComment	(	RecordInterface &	header,
		const String &	comment
	)		[static]

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 .

static void casa::FITSKeywordUtil::addHistory	(	RecordInterface &	header,
		const String &	history
	)		[static]

static Bool casa::FITSKeywordUtil::addKeywords	(	FitsKeywordList &	out,
		const RecordInterface &	in
	)		[static]

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 casa::FITSKeywordUtil::fromTDIM	(	IPosition &	shape,
		const String &	tdim
	)		[static]

Convert a TDIMnnn keyword value into an IPosition.

This returns False if the tdim string has an invalid format.

static Bool casa::FITSKeywordUtil::getKeywords	(	RecordInterface &	out,
		ConstFitsKeywordList &	in,
		const Vector< String > &	ignore,
		Bool	ignoreHistory = True
	)		[static]

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 FitsKeywordList casa::FITSKeywordUtil::makeKeywordList	(	Bool	primHead = True,
		Bool	binImage = True
	)		[static]

Make an initial FitsKeywordList for either a FITS primary header or a FITS extension header (image or table).

A primary header requires "SIMPLE = T", an extension header "XTENSION = IMAGE " or "XTENSION = BINTABLE " for image or table, respectively. This 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 void casa::FITSKeywordUtil::removeKeywords	(	RecordInterface &	out,
		const Vector< String > &	ignore
	)		[static]

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 casa::FITSKeywordUtil::toTDIM	(	String &	tdim,
		const IPosition &	shape
	)		[static]

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

Referenced by casa::VariableArrayFITSFieldCopier< recordType, fitsType >::copyToFITS().

---

The documentation for this class was generated from the following file:

• casacore/fits/FITS/FITSKeywordUtil.h