/ 
Astro-FITS-HdrTrans-1.54
River stage zero No dependents
/ Astro::FITS::HdrTrans::Base

NAME

Astro::FITS::HdrTrans::Base - Base class for header translation

SYNOPSIS

use base qw/ Astro::FITS::HdrTrans::Base /;

%generic = Astro::FITS::HdrTrans::Base->translate_from_FITS( \%fits );
%fits = Astro::FITS::HdrTrans::Base->translate_to_FITS( \%gen );

DESCRIPTION

This is the header translation base class. Not to be confused with Astro::FITS::HdrTrans itself, which is a high level abstraction class. In general users should use Astro::FITS::HdrTrans for initiating header translations unless they know what they are doing. Also Astro::FITS::HdrTrans is the only public interface to the header translation.

PUBLIC METHODS

All methods in this class are CLASS METHODS. No state is retained outside of the hash argument.

translate_from_FITS

Do the header translation from FITS for the specified class.

%generic = $class->translate_to_FITS( \%fitshdr,
                                      prefix => $prefix,
                                      frameset => $wcs,
                                   );

Prefix is attached to the keys in the returned hash if it is defined. The frameset is an optional Starlink::AST object.

If a translation results in an undefined value (for example, if the headers can represent both imaging and spectroscopy there may be no requirement for a DISPERSION header), the result is not stored in the translated hash.

A list of failed translations is available in the _UNDEFINED_TRANSLATIONS key in the generic hash. This points to a reference to an array of all the failed generic translations.

The class used for the translation is stored in the key _TRANSLATION_CLASS. This can then be used to reverse the translation without having to re-scan the headers.

translate_to_FITS

Do the header translation from generic headers to FITS for the specified class.

%fits = $class->translate_to_FITS( \%generic );

PROTECTED METHODS

These methods are available to translation subclasses and should not be used by external classes.

can_translate

Returns true if the supplied headers can be handled by this class.

$cando = $class->can_translate( \%hdrs );

The base class version of this method returns true if either the INSTRUME or INSTRUMENT key exist and match the value returned by the this_instrument method. Comparisons are case-insensitive and can use regular expressions on instrument name if provided by the base class.

this_instrument

Name of the instrument that can be translated by this class. Defaults to an empty string. The method must be subclassed.

$inst = $class->this_instrument();

Can return a regular expresion object (qr).

valid_class

Historically this method was used to determine whether this class can handle the supplied FITS headers. The headers can be either in generic form or in FITS form.

$isvalid = $class->valid_class( \%fits );

The base class always returns false. This is a backwards compatibility method to prevent mixing of translation modules from earlier release of Astro::FITS::HdrTrans with the current object-oriented version. See the can_translate method for the new interface.

_generate_lookup_methods

We generate the unit and constant mapping methods automatically from a lookup table.

Astro::FITS::HdrTrans::UKIRT->_generate_lookup_methods( \%const, \%unit);

This method generates all the simple internal methods. Expects two arguments, both references to hashes. The first is a reference to a hash with constant mapping from FITS to generic (and no reverse mapping), the second is a reference to a hash with unit mappings (both from and to methods are created). The methods are placed into the package given by the class supplied to the method.

Astro::FITS::HdrTrans::UKIRT->_generate_lookup_methods( \%const, \%unit, \%null);

Additionally, an optional third argument can be used to indicate methods that should be null translations. This is a reference to an array of generic keywords and should be used in the rare cases when a base class implementation should be nullified. This will result in undefined values in the generic hash but no value in the generic to FITS mapping.

A fourth optional argument can specify those unit mappings that should use the final entry in a subheader (if a subheader is present). Mainly associated with END events such as AIRMASS_END or ELEVATION_END.

Astro::FITS::HdrTrans::UKIRT->_generate_lookup_methods( \%const, \%unit,
                                                        \%null, \%endobs);

These methods will have the standard interface of

$generic = $class->_to_GENERIC_NAME( \%fits );
%fits = $class->_from_GENERIC_NAME( \%generic );

Generic unit map translations use the via_subheader() method in scalar context and so will retrieve the first sub header value if the keyword is not present in the primary header.

nint

Return the nearest integer to a supplied floating point value. 0.5 is rounded up.

$int = Astro::FITS::HdrTrans->nint( $value );
_parse_iso_date

Converts a UT date in form YYYY-MM-DDTHH:MM:SS.sss into a date object (Time::Piece).

$object = $trans->_parse_iso_date( $date );
_parse_yyyymmdd_date

Converts a UT date in format YYYYMMDD into a date object.

$ojbect = $trans->_parse_yyyymmdd_date( $date, $sep );

Where $sep is the separator string and can be an empty string. This allows 20090215, 2009-02-15 and 2009:02:15 to be parsed by the same routine by using '', '-' and ':' respectively.

_add_seconds

Add the supplied number of seconds to the supplied time object and return a new object.

$new = $trans->_add_seconds( $base, $delta );
_utdate_to_object

Converts a UT date in YYYYMMDD format to a date object at midnight.

$obj = $trans->_utdate_to_object( $YYYYMMDD );
cosdeg

Return the cosine of the angle. The angle must be in degrees.

sindeg

Return the sine of the angle. The angle must be in degrees.

via_subheader

For the supplied FITS header item, first check the primary header for existence, then check SUBHEADERS, then check "In" named subheaders.

In scalar context returns the first value that matches.

$value = $trans->via_subheader( $FITS_headers, $keyword );

In list context returns all the available values in order.

@values = $trans->via_subheader( $FITS_headers, $keyword );
via_subheader_undef_check

Version of via_subheader that removes undefined values from the list before returning the answer. Useful for SCUBA-2 where the first dark may not include the TCS information.

Same interface as via_subheader.

PROTECTED IMPORTS

Not all translation methods warrant a full blown inheritance. For cases where one or two translation routines should be imported (e.g. reading DATE-OBS FITS standard headers without importing the additional FITS methods) a special import routine can be used when using the class.

use Astro::FITS::HdrTrans::FITS qw/ ROTATION /;

This will load the from_ROTATION and to_ROTATION methods into the namespace.

WRITING A TRANSLATION CLASS

In order to create a translation class for a new instrument it is first necessary to work out the different types of translations that are required; whether they are unit mappings (a simple change of keyword but no change in value), constant mappings (a constant is returned independently of the FITS header), mappings that already exist in another class or complex mappings that have to be explicitly coded.

All translation classes must ultimately inherit from Astro::FITS::HdrTrans::Base.

The first step in creation of a class is to handle the "can this class translate the supplied headers" query that will be requested from the Astro::FITS::HdrTrans package. If the instrument name is present in the standard "INSTRUME" FITS header then this can be achieved simply by writing a this_instrument method in the subclass that will return the name of the instrument that can be translated. If a more complex decision is required it will be necessary to subclass the can_translate method. This takes the headers that are to be translated (either in FITS or generic form since the method is queried for either direction) and returns a boolean indicating whether the class can be used.

Once the class can declare it's translation instrument the next step is to write the actual translation methods themselves. If any unit- or constant-mappings are required they can be setup by defining the %UNIT_MAP and %CONST_MAP (the names are unimportant) hashes and calling the base class automated method constructor:

__PACKAGE__->_generate_lookup_methods( \%CONST_MAP, \%UNIT_MAP );

If your translations are very similar to an existing set of translations you can inherit from that class instead of Astro::FITS::HdrTrans::Base. Multiple inheritance is supported if, for example, you need to inherit from both the standard FITS translations (eg for DATE-OBS processing) and from a more telescope-specific set of translations.

If inheritance causes some erroneous mappings to leak through it is possible to disable a specific mapping by specifying a @NULL_MAP array to the method generation. This is an array of generic keywords.

__PACKAGE__->_generate_lookup_methods( \%CONST_MAP, \%UNIT_MAP,
                                       \@NULL_MAP );

If a subset of translation methods are required from another class but there is no desire to inherit the full set of methods then it is possible to import specific translation methods from other classes.

use Astro::FITS::HdrTrans::FITS qw/ UTSTART UTEND /;

would import just the DATE-OBS and DATE-END handling functions from the FITS class. Note that both the from- and to- translations will be imported.

At some point you may want to write your own more complex translations. To do this you must write to- and from- methods. The API for all the from_FITS translations is identical:

$translation = $class->to_GENERIC_KEYWORD( \%fits_headers );

ie given a reference to a hash of FITS headers (which can be a tied Astro::FITS::Header object), return a scalar value which is the translated value.

To convert from generic to FITS the interface is:

%fits_subset = $class->from_GENERIC_KEYWORD( \%generic_header );

ie multiple FITS keywords and values can be returned since in some cases a single generic keyword is obtained by combining information from multiple FITS headers.

Finally, if this translation module is to be part of the Astro::FITS::HdrTrans distribution the default list of translation classes must be updated in Astro::FITS::HdrTrans. If this is to be a runtime plugin, then the list of classes can be expanded at runtime. For example, it should be possible for Astro::FITS::HdrTrans::MyNewInst to automatically append itself to the list of known classes if the module is explicitly loaded by the user (rather than dynamically loaded to test the headers).

Some generic keywords actually return scalar objects. Any new instruments must consistently return compatible objects. For example, UTDATE, UTSTART and UTEND return (currently) Time::Piece objects.

REVISION

$Id$

SEE ALSO

Astro::FITS::HdrTrans

AUTHOR

Tim Jenness <t.jenness@jach.hawaii.edu>

COPYRIGHT

Copyright (C) 2003-2005 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