Astro::FITS::Header - A FITS header
$header = new Astro::FITS::Header( Cards => \@array );
Stores information about a FITS header block in an object. Takes an hash with an array reference as an arguement. The array should contain a list of FITS header cards as input.
$Id: Header.pm,v 1.15 2002/11/15 02:37:38 timj Exp $
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.
Returns a FITS::Header:Item object referenced by index, undef if it does not exist.
undef
$item = $header->item($index);
Returns keyword referenced by index, undef if it does not exist.
$keyword = $header->keyword($index);
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.
@items = $header->itembyname($keyword); $item = $header->itembyname($keyword);
Returns an array of indices for the requested keyword if called in list context, or an empty array if it does not exist.
@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);
Returns an array of values for the requested keyword if called in list context, or an empty array if it does not exist.
@value = $header->value($keyword);
Returns an array of comments for the requested keyword if called in list context, or an empty array if it does not exist.
@comment = $header->comment($keyword);
$comment = $header->comment($keyword);
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.
Replace FITS header card at index $index with card $item
$card = $header->replace($index, $item);
returns the replaced card.
Removes a FITS header card object at position $index
$card = $header->remove($index);
returns the removed card.
Replace FITS header cards with keyword $keyword with card $item
$card = $header->replacebyname($keyword, $item);
Removes a FITS header card object by name
@card = $header->removebyname($keyword);
returns the removed cards.
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.
Return the object contents as an array of FITS cards.
@array = $header->cards;
Returns the header as an array of FITS::Header:Item objects.
@items = $header->allitems();
Configures the object, takes an array of FITS header cards or an array of Astro::FITS::Header::Item objects as input.
$header->configure( Cards => \@array ); $header->configure( Items => \@array );
Does nothing if the array is not supplied.
Method to return a blessed reference to the object so that we can store ths object on disk using Data::Dumper module.
These operators are overloaded:
When the object is used in a string context the FITS header block is returned as a single string.
These methods are for internal use only.
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.
The FITS::Header object can also be tied to a hash:
FITS::Header
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"; }
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).
There's no way to access the per-card comment fields using the tied interface.
Keywords are CaSE-inNSEnSiTIvE, unlike normal hash keywords. All keywords are translated to upper case internally, per the FITS standard.
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; all other keywords create normal valued cards. If you don't like that behavior, don't use the tied interface.
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())
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 hash array:
$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 n which they appear in the header.
Copyright (C) 2001-2002 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 same terms as Perl itself.
Alasdair Allan <aa@astro.ex.ac.uk>, Tim Jenness <t.jenness@jach.hawaii.edu>, Craig DeForest <deforest@boulder.swri.edu>
To install Astro::FITS::Header, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Astro::FITS::Header
CPAN shell
perl -MCPAN -e shell install Astro::FITS::Header
For more information on module installation, please visit the detailed CPAN module installation guide.