Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Astro::FITS::Header(3)User Contributed Perl DocumentatioAstro::FITS::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 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>

perl v5.32.0			  2020-08-08		Astro::FITS::Header(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | TIED INTERFACE | SEE ALSO | COPYRIGHT | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Astro::FITS::Header&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help