NAME
Astro::FITS::HdrTrans - Translate FITS headers into generic headers and back again
SYNOPSIS
use Astro::FITS::HdrTrans qw/ translate_from_FITS translate_to_FITS /;
%generic_headers = translate_from_FITS(\%FITS_headers);
%FITS_headers = translate_to_FITS(\%generic_headers);
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.
REVISION
$Id: HdrTrans.pm,v 1.18 2003/09/16 02:23:36 bradc Exp $
PUBLIC VARIABLES
The following variables are not exported by default, but can be exported.
- @generic_headers
-
Provides a list of generic headers that may or may not be available in the generic header hash, depending on if translations were set up for these headers in the instrument-specific subclasses.
Currently only the time-related headers (UTSTART, UTEND, and UTDATE) have type-checking done; these three generic headers must be returned as
Time::Piece
objects when translating from FITS headers into generic headers, and must be given asTime::Piece
objects when translating from generic headers back into FITS headers. A warning is raised if any of these headers are notTime::Piece
objects.
PRIVATE VARIABLES
The following variables are private to this module.
- @valid_classes
-
This parameter is a list of valid classes for which translations can be made. A class in this list does not include the
Astro::FITS::HdrTrans
prefix. For example, if theAstro::FITS::HdrTrans::IRCAM
class were to be used for translations, this list would include onlyIRCAM
.Values in this list are case-sensitive.
Values in this list can be added to using the
push_class
method.
PUBLIC METHODS
The following methods are not exported by default, but can be exported.
- 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_', );
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 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.
- 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.
- push_class
-
Allows another class to be pushed onto the list of valid classes.
push_class( \@classes ); push_class( $class );
If an array reference is passed, all classes contained in that array will be added to the list. If a scalar is passed, that single class will be added to the list.
GENERIC HEADERS
The following is a list of currently-supported generic headers. If no type is defined for the header, then it is assumed to be a scalar in any format.
- AIRMASS_START - Airmass at the start of the observation.
- AIRMASS_END - Airmass at the end of the observation.
- ALTITUDE - Telescope altitude. Must be in meters above mean sea level.
- AZIMUTH_START - Telescope azimuth at the start of the observation.
- AZIMUTH_END - Telescope azimuth at the end of the observation.
- BACKEND - Backend used.
- BOLOMETERS - Number of bolometers used in array.
- CAMERA - Camera used for observation.
- CHOP_ANGLE - Chop angle.
- CHOP_COORDINATE_SYSTEM - Coordinate system used for chopping.
- CHOP_THROW - Distance of chop throw.
- CONFIGURATION_INDEX - Unique identifier for hardware configuration.
- COORDINATE_UNITS - Units of coordinate system.
- COORDINATE_TYPE - Type of coordinate (typically B1950 or J2000).
- CYCLE_LENGTH - Length of observation cycle.
- DEC_BASE - Base declination position of observation. Must be a string in colon-delimited sexagesimal format (ie. +41:16:09.4), where the degrees, minutes, and seconds are zero-padded to two digits.
- DEC_SCALE - Pixel scale in declination.
- DEC_SCALE_UNITS - Units for declination pixel scale.
- DEC_TELESCOPE_OFFSET - Offset in declination from base position. Must be in arcseconds.
- DETECTOR_BIAS - Detector bias.
- DETECTOR_INDEX - Position number in detector scan.
- DETECTOR_READ_TYPE - Read type of detector.
- DR_GROUP - Data reduction group to which observation belongs.
- DR_RECIPE - Data reduction recipe to be used.
- ELEVATION - Elevation of telescope above sea level.
- ELEVATION_START - Telescope elevation at the start of the observation. Must be in degrees. 90 is zenith, 0 is horizon.
- ELEVATION_END - Telescope elevation at the end of the observation. Must be in degrees. 90 is zenith, 0 is horizon.
- EPOCH - Epoch in which observation was taken.
- EQUINOX - Equinox in which observation was taken.
- EXPOSURE_TIME - Exposure time of observation. Must be in decimal seconds.
- FILENAME - Name of data file.
- FILTER - Filter in which observation was taken.
- GAIN - Detector gain.
- GALACTIC_LATITUDE - Galactic latitude of observation. Must be a colon-separated sexagesimal string (ie. 121:10:12).
- GALACTIC_LONGITUDE - Galactic longitude of observation. Must be a colon-separated sexagesimal string (ie. -21:34:12).
- GRATING_DISPERSION - Wavelength dispersion.
- GRATING_NAME - Name of grating/grism used.
- GRATING_ORDER - Order of grating/grism used.
- GRATING_WAVELENGTH - Central wavelength of grating/grism used.
- INSTRUMENT - Instrument name.
- INST_DHS - Unique combination of instrument name and data handling system.
- LATITUDE - Latitude of telescope. Must be a colon-separated sexagesimal string (ie. 19:49:20.75).
- LONGITUDE - Longitude of telescope. Must be a colon-separated sexagesimal string (ie. -155:28:13.18).
- MSBID - Unique identifier for minimum schedulable block.
- NSCAN_POSITIONS - Number of scan positions.
- NUMBER_OF_COADDS - Number of coadds.
- NUMBER_OF_CYCLES - Number of cycles.
- NUMBER_OF_DETECTORS - Number of detectors.
- NUMBER_OF_EXPOSURES - Number of exposures.
- NUMBER_OF_OFFSETS - Number of offsets in dither pattern.
- NUMBER_OF_READS - Number of reads.
- NUMBER_OF_SUBFRAMES - Number of subframes.
- OBJECT - Object name.
- OBSERVATION_MODE - Mode of observation for multi-mode instruments.
- OBSERVATION_NUMBER - Number of observation.
- OBSERVATION_TYPE - Type of observation (ie. DARK, FLAT, etc.)
- POLARIMETRY - Polarimetry mode?
- PROJECT - Project name.
- RA_BASE - Base right ascension position of observation. Must be a colon-delimited sexagesimal string (ie. 00:42:44.31).
- RA_SCALE - Pixel scale in right ascension.
- RA_SCALE_UNITS - Units for right ascension pixel scale.
- RA_TELESCOPE_OFFSET - Offset in right ascension from base position. Must be in arcseconds.
- REST_FREQUENCY - Rest frequency of spectral line.
- ROTATION - Angle of the declination axis with respect to the frame's y axis, measured counter-clockwise.
- SAMPLING - Sampling type.
- SCAN_INCREMENT - Increment of scan.
- SEEING - Seeing when observation was taken.
- SLIT_ANGLE - Angle of slit on sky.
- SLIT_NAME - Name of slit used.
- SLIT_WIDTH - Width of slit.
- SPEED_GAIN - Readout speed.
- STANDARD - Is observation of a standard?
- SYSTEM_VELOCITY - System velocity.
- TAU - Atmospheric extinction at time of observation.
- TELESCOPE - Name of telescope.
- UTDATE - UT date on which observation was taken. Must be a Time::Piece object.
- UTEND - End time of observation. Must be a Time::Piece object.
- UTSTART - Start time of observation. Must be a Time::Piece object.
- VELOCITY -
- VELSYS -
- WAVEPLATE_ANGLE - Polarimetry waveplate angle.
- X_BASE - Base x-position of observation.
- Y_BASE - Base y-position of observation.
- X_OFFSET - Offset in x-direction from base position.
- Y_OFFSET - Offset in y-direction from base position.
- X_SCALE - Pixel scale in x-direction.
- Y_SCALE - Pixel scale in y-direction.
- X_DIM - Size of array in x-direction.
- Y_DIM - Size of array in y-direction.
- X_LOWER_BOUND - Lower bound of array in x-direction.
- X_UPPER_BOUND - Upper bound of array in x-direction.
- Y_LOWER_BOUND - Lower bound of array in y-direction.
- Y_UPPER_BOUND - Upper bound of array in y-direction.
- ZENITH_DISTANCE_START - Zenith distance at start of observation.
- ZENITH_DISTANCE_END - Zenith distance at end of observation.
NOTES
A number of the generic headers are more easily represented by objects. For example, all headers to do with the object coordinates (DEC_BASE, COORDINATE_UNITS, COORDINATE_TYPE, EPOCH, EQUINOX, and RA_BASE) are be better represented with a single
Astro::Coords
object. Such headers will at some point be merged into a single object header, but for backwards compatibility will be retained.
AUTHOR
Brad Cavanagh <b.cavanagh@jach.hawaii.edu>
COPYRIGHT
Copyright (C) 2003 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
8 POD Errors
The following errors were encountered while parsing the POD:
- Around line 239:
Expected text after =item, not a bullet
- Around line 245:
Expected text after =item, not a bullet
- Around line 380:
Expected text after =item, not a bullet
- Around line 386:
Expected text after =item, not a bullet
- Around line 396:
Expected text after =item, not a bullet
- Around line 546:
You forgot a '=back' before '=head1'
- Around line 766:
'=item' outside of any '=over'
- Around line 773:
You forgot a '=back' before '=head1'