NAME

Astro::FITS::HdrTrans - Translate FITS headers to standardised form

SYNOPSIS

  use Astro::FITS::HdrTrans qw/ translate_from_FITS
                                translate_to_FITS /;

  %generic_headers = translate_from_FITS(\%FITS_headers,
                                     frameset => $frameset);

  %FITS_headers = translate_to_FITS(\%generic_headers);

  @headers = Astro::FITS::HdrTrans->generic_headers();
  @classes = Astro::FITS::HdrTrans->translation_classes();

DESCRIPTION

Converts information contained in instrument-specific FITS headers to and from generic headers. A list of generic headers are given at the end of the module documentation.

CLASS METHODS

Some class methods are available

generic_headers

Returns a list of all the generic headers that can in principal be used for header translation. Note that not all the instruments support all the headers.

 @hdrs = Astro::FITS::HdrTrans->generic_headers();

translation_classes

Return the names of all the translation classes that will be tried when translating a FITS header.

 @classes = Astro::FITS::HdrTrans->translation_classes();

If arguments are supplied, the list of translation classes is set to the supplied values.

 Astro::FITS::HdrTrans->translation_classes( @new );

reset_translation_classes

Revert back to the reference list of translation classes.

  Astro::FITS::HdrTrans->reset_translation_classes;

Useful if the list has been modified for a specific translation.

push_class

Allows additional classes to be pushed on the list of valid translation classes.

  Astro::FITS::HdrTrans->push_class( $class );

The class[es] can be specified either as a list or a reference to an array.

FUNCTIONS

The following functions are available. They can be exported but are not exported by default.

translate_from_FITS

Converts a hash containing instrument-specific FITS headers into a hash containing generic headers.

  %generic_headers = translate_from_FITS(\%FITS_headers,
                                         class => \@classes,
                                         prefix => 'ORAC_',
                                         frameset => $frameset,
                                        );

This method takes a reference to a hash containing untranslated headers, and a hash reference containing the following optional keys:

• class - A reference to a list of subclasses to try to use for header translations. This list overrides the default list. If left blank, the default list will be used, as returned by the translation_classes method. This is sometimes required to break degeneracy when you know you have a limited set of valid instruments.

• frameset - An AST FrameSet describing the WCS. The WCS in this FrameSet will override any WCS information contained in the FITS headers.

• prefix - A string prefix to add to the front of every translated header name. For example, if this prefix is set to 'ORAC_', then the translated header for the instrument value, whose key is normally 'INSTRUMENT', will have a key named 'ORAC_INSTRUMENT'. The original keys will not be in the returned hash. If left blank, no prefix will be added.

This method returns a hash of generic headers. This function dies if the header translation fails in any way.

translate_to_FITS

Converts a hash containing generic headers into one containing instrument-specific FITS headers.

  %FITS_headers = translate_to_FITS(\%generic_headers,
                                    class => \@classes,
                                   );

This method takes a reference to a hash containing untranslated headers, and a hash reference containing the following optional keys:

• class - A reference to a list of subclasses to try to use for header translations. This list overrides the default list. If left blank, the default list will be used.

• prefix - A string prefix to remove from the generic header key before doing header translation. Why you would want to do this is if you've used a prefix in the translate_from_FITS call, and want to translate back from the generic headers returned from that method. If left blank, no prefix will be removed.

This method returns a hash of instrument-specific headers. This function dies if the header translation fails in any way.

determine_class

Determine which class should be used for the translation (either way). It is given a reference to the header hash and a reference to an array of classes which can be queried.

  $class = determine_class( \%hdr, \@classes, $fromfits );

The classes are loaded for each test. Failure to load indicates failure to translate. If the classes are undefined, the default internal list will be used.

The third argument is a boolean indicating whether the class is being used to translate from FITS (true) or to FITS (false). This is used for error message clarity.

This function can be useful to allow a single header translation to be calculated without requiring that all translation are performed. For example,

  $class = Astro::FITS::HdrTrans::determine_class( \%hdr, undef, 1 );
  $value = $class->to_OBSERVATION_ID( \%hdr, $frameset );

If the key _TRANSLATION_CLASS exists and this class allows translation and no override classes have been specified, that class is returned without checking all classes. This key is automatically filled in when a translation from fits is executed.

clean_prefix

If a prefix has been used and a targetted conversion is required (which will not understand the prefix) the prefix must first be removed. This function will remove the preifx, only returning headers that contained the prefix.

  %cleaned = clean_prefix( \%header, $prefix );

If prefix is an empty string or undefined, returns all headers.

NOTES

Individual translations can be invoked explicitly if a class name is known. The syntax for conversion from a FITS header to generic value is

  $result = $class->to_GENERIC_KEYWORD( \%header, $frameset );

Frameset information (Starlink::AST object) is optional.

The syntax for conversion from generic to FITS headers is:

  %fits = $class->from_GENERIC_KEYWORD( \%translated_hdr );

Note that the conversion to FITS can result in multiple header items and can require more than a single generic translated header item.

If you are using a prefix, the general paradigm for converting a translated header back to FITS is:

  my %cleaned = Astro::FITS::HdrTrans::clean_prefix( \%translated_hdr, $prefix );
  my $class = Astro::FITS::HdrTrans::determine_class( \%cleaned, undef, 0 );
  my %fits = $class->from_DR_RECIPE( \%cleaned );

AUTHOR

Brad Cavanagh <b.cavanagh@jach.hawaii.edu>, Tim Jenness <t.jenness@jach.hawaii.edu>, Malcolm J. Currie <mjc@jach.hawaii.edu>

COPYRIGHT

Copyright (C) 2007-2009, 2013 Science and Technology Facilities Council. Copyright (C) 2003-2007 Particle Physics and Astronomy Research Council. 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 2 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.