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

#include <FITSKeywordUtil.h>

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

static Bool	addKeywords (FitsKeywordList &out, const RecordInterface &in)
	Add the fields from in to the out FitsKeywordList as keywords. More...

static Bool	getKeywords (RecordInterface &out, ConstFitsKeywordList &in, const Vector< String > &ignore, Bool ignoreHistory=True)
	Extract keywords from in and define them in out. More...

static void	removeKeywords (RecordInterface &out, const Vector< String > &ignore)
	Remove some keywords from a record. More...

static Bool	fromTDIM (IPosition &shape, const String &tdim)
	Convert a TDIMnnn keyword value into an IPosition. More...

static Bool	toTDIM (String &tdim, const IPosition &shape)
	Convert an IPosition to a String appropriate for use as the value of a TDIMnnn keyword. More...

static void	addComment (RecordInterface &header, const String &comment)
	Add a comment/history to the supplied record. More...

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 Casacore types and a FitsKeywordList which is needed by the native FITS classes. It is more convenient to maintain the list within Casacore 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 Casacore 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 casacore::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 casacore::FITSKeywordUtil::addHistory	(	RecordInterface &	header,
		const String &	history
	)

static

static Bool casacore::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 casacore::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 casacore::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 casacore::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 casacore::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.