Astro::FITS::Header man page on Peanut

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
Peanut logo
[printable version]

Header(3)	      User Contributed Perl Documentation	     Header(3)

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 arguement. The array should contain
       a list of FITS header cards as input.

REVISION
       $Id: Header.pm,v 1.26 2003/10/23 03:28:28 bradc Exp $

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

       tieRetRef
	   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

	       $header->subhdrs(@hdrs);
	       @hdrs = $header->subhdrs;

       item
	   Returns a FITS::Header:Item object referenced by index, "undef" if
	   it does not exist.

	      $item = $header->item($index);

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

       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.

       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;

       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 or an
	   array of Astro::FITS::Header::Item objects 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 );

	   Does nothing if the array is not supplied.

       freeze
	   Method to return a blessed reference to the object so that we can
	   store ths object on disk using Data::Dumper module.

       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 n which they appear in the header.

       When the key refers to a subheader entry, a hash reference is returned.
       If a hash reference is stored in a value it is converted to a
       "Astro::FITS::Header" object.

       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.

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

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>

perl v5.10.0			  2003-10-23			     Header(3)
[top]

List of man pages available for Peanut

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net