Provided by: libastro-fits-header-perl_3.07-1_all 
NAME
Astro::FITS::Header - Object Orientated interface to FITS HDUs
SYNOPSIS
$header = new Astro::FITS::Header( Cards => \@array );
DESCRIPTION
Stores information about a FITS header block in an object. Takes an hash with an array
reference as an argument. The array should contain a list of FITS header cards as input.
METHODS
Constructor
new Create a new instance from an array of FITS header cards.
$item = new Astro::FITS::Header( Cards => \@header );
returns a reference to a Header object. If you pass in no cards, you get the
(required) first SIMPLE card for free.
Accessor Methods
tiereturnsref
Indicates whether the tied object should return multiple values as a single string
joined by newline characters (false) or it should return a reference to an array
containing all the values.
Only affects the tied interface.
tie %keywords, "Astro::FITS::Header", $header, tiereturnsref => 1;
$ref = $keywords{COMMENT};
Defaults to returning a single string in all cases (for backwards compatibility)
subhdrs
Set or return the subheaders for a Header object. Arguments must be given as
"Astro::FITS::Header" objects.
$header->subhdrs(@hdrs);
@hdrs = $header->subhdrs;
This method should be used when you have additional header components that should be
associated with the primary header but they are not associated with a particular name,
just an ordering.
FITS headers that are associated with a name can be stored directly in the header
using an "Astro::FITS::Header::Item" of type 'HEADER'.
item
Returns a FITS::Header:Item object referenced by index, "undef" if it does not exist.
$item = $header->item($index);
get_wcs
Returns a Starlink::AST FrameSet object representing the WCS of the FITS Header.
$ast = $header->get_wcs();
keyword
Returns keyword referenced by index, "undef" if it does not exist.
$keyword = $header->keyword($index);
itembyname
Returns an array of Header::Items for the requested keyword if called in list context,
or the first matching Header::Item if called in scalar context. Returns "undef" if the
keyword does not exist. The keyword may be a regular expression created with the "qr"
operator.
@items = $header->itembyname($keyword);
$item = $header->itembyname($keyword);
itembytype
Returns an array of Header::Items for the requested type if called in list context, or
the first matching Header::Item if called in scalar context. See
"Astro::FITS::Header::Item" for a list of allowed types.
@items = $header->itembytype( "COMMENT" );
@items = $header->itembytype( "HEADER" );
$item = $header->itembytype( "INT" );
index
Returns an array of indices for the requested keyword if called in list context, or an
empty array if it does not exist. The keyword may be a regular expression created
with the "qr" operator.
@index = $header->index($keyword);
If called in scalar context it returns the first item in the array, or "undef" if the
keyword does not exist.
$index = $header->index($keyword);
value
Returns an array of values for the requested keyword if called in list context, or an
empty array if it does not exist. The keyword may be a regular expression created
with the "qr" operator.
@value = $header->value($keyword);
If called in scalar context it returns the first item in the array, or "undef" if the
keyword does not exist.
comment
Returns an array of comments for the requested keyword if called in list context, or
an empty array if it does not exist. The keyword may be a regular expression created
with the "qr" operator.
@comment = $header->comment($keyword);
If called in scalar context it returns the first item in the array, or "undef" if the
keyword does not exist.
$comment = $header->comment($keyword);
insert
Inserts a FITS header card object at position $index
$header->insert($index, $item);
the object $item is not copied, multiple inserts of the same object mean that future
modifications to the one instance of the inserted object will modify all inserted
copies.
The insert position can be negative.
replace
Replace FITS header card at index $index with card $item
$card = $header->replace($index, $item);
returns the replaced card.
remove
Removes a FITS header card object at position $index
$card = $header->remove($index);
returns the removed card.
replacebyname
Replace FITS header cards with keyword $keyword with card $item
$card = $header->replacebyname($keyword, $item);
returns the replaced card. The keyword may be a regular expression created with the
"qr" operator.
removebyname
Removes a FITS header card object by name
@card = $header->removebyname($keyword);
returns the removed cards. The keyword may be a regular expression created with the
"qr" operator.
splice
Implements a standard splice operation for FITS headers
@cards = $header->splice($offset [,$length [, @list]]);
$last_card = $header->splice($offset [,$length [, @list]]);
Removes the FITS header cards from the header designated by $offset and $length, and
replaces them with @list (if specified) which must be an array of FITS::Header::Item
objects. Returns the cards removed. If offset is negative, counts from the end of the
FITS header.
cards
Return the object contents as an array of FITS cards.
@array = $header->cards;
sizeof
Returns the highest index in use in the FITS header. To get the total number of
header items, add 1.
$number = $header->sizeof;
allitems
Returns the header as an array of FITS::Header:Item objects.
@items = $header->allitems();
General Methods
configure
Configures the object, takes an array of FITS header cards, an array of
Astro::FITS::Header::Item objects or a simple hash as input. If you feed in nothing
at all, it uses a default array containing just the SIMPLE card required at the top of
all FITS files.
$header->configure( Cards => \@array );
$header->configure( Items => \@array );
$header->configure( Hash => \%hash );
Does nothing if the array is not supplied. If the hash scheme is used and the hash
contains the special key of SUBHEADERS pointing to an array of hashes, these will be
read as proper sub headers. All other references in the hash will be ignored. Note
that the default key order will be retained in the object created via the hash.
merge_primary
Given the current header and a set of "Astro::FITS::Header" objects, return a merged
FITS header (with the cards that have the same value and comment across all headers)
along with, for each input, header objects containing all the header items that differ
(including, by default, keys that are not present in all headers). Only the primary
headers are merged, subheaders are ignored.
($clone) = $headerr->merge_primary();
($same, @different) = $header->merge_primary( $fits1, $fits2, ...);
($same, @different) = $header->merge_primary( \%options, $fits1, $fits2 );
@different can be empty if all headers match (but see the "force_return_diffs" option)
but if any headers are different there will always be the same number of headers in
@different as supplied to the function (including the reference header). A clone of
the input header (stripped of any subheaders) is returned if no comparison headers are
supplied.
In scalar context, just returns the merged header.
$merged = $header->merge_primary( @hdrs );
The options hash is itself optional. It contains the following keys:
merge_unique - if an item is identical across multiple headers and only
exists in those headers, propogate to the merged header rather
than storing it in the difference headers.
force_return_diffs - return an empty difference object per input header
even if there are no diffs
freeze
Method to return a blessed reference to the object so that we can store ths object on
disk using Data::Dumper module.
append
Append or update a card.
$header->append( $card );
This method can take either an Astro::FITS::Header::Item object, an
Astro::FITS::Header object, or a reference to an array of Astro::FITS::Header::Item
objects.
In all cases, if the given Astro::FITS::Header::Item keyword exists in the header,
then the value will be overwritten with the one passed to the method. Otherwise, the
card will be appended to the end of the header.
Nothing is returned.
Operator Overloading
These operators are overloaded:
"" When the object is used in a string context the FITS header block is returned as a
single string.
Private methods
These methods are for internal use only.
_rebuild_lookup
Private function used to rebuild the lookup table after modifying the header block,
its easier to do it this way than go through and add one to the indices of all header
cards following the modifed card.
TIED INTERFACE
The "FITS::Header" object can also be tied to a hash:
use Astro::FITS::Header;
$header = new Astro::FITS::Header( Cards => \@array );
tie %hash, "Astro::FITS::Header", $header
$value = $hash{$keyword};
$hash{$keyword} = $value;
print "keyword $keyword is present" if exists $hash{$keyword};
foreach my $key (keys %hash) {
print "$key = $hash{$key}\n";
}
Basic hash translation
Header value type is determined on-the-fly by parsing of the input values. Anything that
parses as a number or a logical is converted to that before being put in a card (but see
below).
Per-card comment fields can be accessed using the tied interface by specifying a key name
of "key_COMMENT". This works because in general "_COMMENT" is too long to be confused with
a normal key name.
$comment = $hdr{CRPIX1_COMMENT};
will return the comment associated with CRPIX1 header item. The comment can be modified in
the same way:
$hdr{CRPIX1_COMMENT} = "An axis";
You can also modify the comment by slash-delimiting it when setting the associated
keyword:
$hdr{CRPIX1} = "34 / Set this field manually";
If you want an actual slash character in your string field you must escape it with a
backslash. (If you're in double quotes you have to use a double backslash):
$hdr{SLASHSTR} = 'foo\/bar / field contains "foo/bar"';
Keywords are CaSE-inNSEnSiTIvE, unlike normal hash keywords. All keywords are translated
to upper case internally, per the FITS standard.
Aside from the SIMPLE and END keywords, which are automagically placed at the beginning
and end of the header respectively, keywords are included in the header in the order
received. This gives you a modicum of control over card order, but if you actually care
what order they're in, you probably don't want the tied interface.
Comment cards
Comment cards are a special case because they have no normal value and their comment field
is treated as the hash value. The keywords "COMMENT" and "HISTORY" are magic and refer to
comment cards; nearly all other keywords create normal valued cards. (see "SIMPLE and END
cards", below).
Multi-card values
Multiline string values are broken up, one card per line in the string. Extra-long string
values are handled gracefully: they get split among multiple cards, with a backslash at
the end of each card image. They're transparently reassembled when you access the data,
so that there is a strong analogy between multiline string values and multiple cards.
In general, appending to hash entries that look like strings does what you think it
should. In particular, comment cards have a newline appended automatically on FETCH, so
that
$hash{HISTORY} .= "Added multi-line string support";
adds a new HISTORY comment card, while
$hash{TELESCOP} .= " dome B";
only modifies an existing TELESCOP card.
You can make multi-line values by feeding in newline-delimited strings, or by assigning
from an array ref. If you ask for a tag that has a multiline value it's always expanded
to a multiline string, even if you fed in an array ref to start with. That's by design:
multiline string expansion often acts as though you are getting just the first value back
out, because perl string-to-number conversion stops at the first newline. So:
$hash{CDELT1} = [3,4,5];
print $hash{CDELT1} + 99,"\n$hash{CDELT1}";
prints "102\n3\n4\n5", and then
$hash{CDELT1}++;
print $hash{CDELT1};
prints "4".
In short, most of the time you get what you want. But you can always fall back on the
non-tied interface by calling methods like so:
((tied $hash)->method())
If you prefer to have multi-valued items automagically become array refs, then you can get
that behavior using the "tiereturnsref" method:
tie %keywords, "Astro::FITS::Header", $header, tiereturnsref => 1;
When tiereturnsref is true, multi-valued items will be returned via a reference to an
array (ties do not respect calling context). Note that if this is configured you will have
to test each return value to see whether it is returning a real value or a reference to an
array if you are not sure whether there will be more than one card with a duplicate name.
Type forcing
Because perl uses behind-the-scenes typing, there is an ambiguity between strings and
numeric and/or logical values: sometimes you want to create a STRING card whose value
could parse as a number or as a logical value, and perl kindly parses it into a number for
you. To force string evaluation, feed in a trivial array ref:
$hash{NUMSTR} = 123; # generates an INT card containing 123.
$hash{NUMSTR} = "123"; # generates an INT card containing 123.
$hash{NUMSTR} = ["123"]; # generates a STRING card containing "123".
$hash{NUMSTR} = [123]; # generates a STRING card containing "123".
$hash{ALPHA} = "T"; # generates a LOGICAL card containing T.
$hash{ALPHA} = ["T"]; # generates a STRING card containing "T".
Calls to keys() or each() will, by default, return the keywords in the order in which they
appear in the header.
Sub-headers
When the key refers to a subheader entry (ie an item of type "HEADER"), a hash reference
is returned. If a hash reference is stored in a value it is converted to a
"Astro::FITS::Header" object.
If the special key "SUBHEADERS" is used, it will return the array of subheaders, (as
stored using the "subhdrs" method) each of which will be tied to a hash. Subheaders can be
stored using normal array operations.
SIMPLE and END cards
No FITS interface would becomplete without special cases.
When you assign to SIMPLE or END, the tied interface ensures that they are first or last,
respectively, in the deck -- as the FITS standard requires. Other cards are inserted in
between the first and last elements, in the order that you define them.
The SIMPLE card is forced to FITS LOGICAL (boolean) type. The FITS standard forbids you
from setting it to F, but you can if you want -- we're not the FITS police.
The END card is forced to a null type, so any value you assign to it will fall on the
floor. If present in the deck, the END keyword always contains the value " ", which is
both more-or-less invisible when printed and also true -- so you can test the return value
to see if an END card is present.
SIMPLE and END come pre-defined from the constructor. If for some nefarious reason you
want to remove them you must explicitly do so with "delete" or the appropriate method call
from the object interface.
SEE ALSO
"Astro::FITS::Header::Item", "Starlink::AST", "Astro::FITS::Header::CFITSIO",
"Astro::FITS::Header::Item::NDF".
COPYRIGHT
Copyright (C) 2007-2011 Science and Technology Facilties Council. Copyright (C) 2001-2007
Particle Physics and Astronomy Research Council and portions Copyright (C) 2002 Southwest
Research Institute. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation; either
version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program;
if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA
02111-1307, USA
AUTHORS
Alasdair Allan <aa@astro.ex.ac.uk>, Tim Jenness <t.jenness@jach.hawaii.edu>, Craig
DeForest <deforest@boulder.swri.edu>, Jim Lewis <jrl@ast.cam.ac.uk>, Brad Cavanagh
<b.cavanagh@jach.hawaii.edu>