WCSLIB 4.17: wcsunits.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# wcsunits.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.17 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2013, Mark Calabretta
    00005
    00006   This file is part of WCSLIB.
    00007
    00008   WCSLIB is free software: you can redistribute it and/or modify it under the
    00009   terms of the GNU Lesser General Public License as published by the Free
    00010   Software Foundation, either version 3 of the License, or (at your option)
    00011   any later version.
    00012
    00013   WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    00014   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    00015   FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    00016   more details.
    00017
    00018   You should have received a copy of the GNU Lesser General Public License
    00019   along with WCSLIB.  If not, see http://www.gnu.org/licenses.
    00020
    00021   Direct correspondence concerning WCSLIB to mark@calabretta.id.au
    00022
    00023   Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
    00024   http://www.atnf.csiro.au/people/Mark.Calabretta
    00025   $Id: wcsunits.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $
    00026 *=============================================================================
    00027 *
    00028 * WCSLIB 4.17 - C routines that implement the FITS World Coordinate System
    00029 * (WCS) standard.  Refer to
    00030 *
    00031 *   "Representations of world coordinates in FITS",
    00032 *   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
    00033 *
    00034 * The Flexible Image Transport System (FITS), a data format widely used in
    00035 * astronomy for data interchange and archive, is described in
    00036 *
    00037 *   "Definition of The Flexible Image Transport System (FITS)",
    00038 *   Hanisch, R.J., Farris, A., Greisen, E.W., et al. 2001, A&A, 376, 359
    00039 *
    00040 * which formalizes NOST 100-2.0, a document produced by the NASA/Science
    00041 * Office of Standards and Technology, see http://fits.gsfc.nasa.gov.
    00042 *
    00043 * Refer to the README file provided with WCSLIB for an overview of the
    00044 * library.
    00045 *
    00046 *
    00047 * Summary of the wcsunits routines
    00048 * --------------------------------
    00049 * Routines in this suite deal with units specifications and conversions:
    00050 *
    00051 *   - wcsunitse(): given two unit specifications, derive the conversion from
    00052 *     one to the other.
    00053 *
    00054 *   - wcsutrne(): translates certain commonly used but non-standard unit
    00055 *     strings.  It is intended to be called before wcsulexe() which only
    00056 *     handles standard FITS units specifications.
    00057 *
    00058 *   - wcsulexe(): parses a standard FITS units specification of arbitrary
    00059 *     complexity, deriving the conversion to canonical units.
    00060 *
    00061 *
    00062 * wcsunitse() - FITS units specification conversion
    00063 * -------------------------------------------------
    00064 * wcsunitse() derives the conversion from one system of units to another.
    00065 *
    00066 * A deprecated form of this function, wcsunits(), lacks the wcserr**
    00067 * parameter.
    00068 *
    00069 * Given:
    00070 *   have      const char []
    00071 *                       FITS units specification to convert from (null-
    00072 *                       terminated), with or without surrounding square
    00073 *                       brackets (for inline specifications); text following
    00074 *                       the closing bracket is ignored.
    00075 *
    00076 *   want      const char []
    00077 *                       FITS units specification to convert to (null-
    00078 *                       terminated), with or without surrounding square
    00079 *                       brackets (for inline specifications); text following
    00080 *                       the closing bracket is ignored.
    00081 *
    00082 * Returned:
    00083 *   scale,
    00084 *   offset,
    00085 *   power     double*   Convert units using
    00086 *
    00087 =                         pow(scale*value + offset, power);
    00088 *
    00089 *                       Normally offset is zero except for log() or ln()
    00090 *                       conversions, e.g. "log(MHz)" to "ln(Hz)".  Likewise,
    00091 *                       power is normally unity except for exp() conversions,
    00092 *                       e.g. "exp(ms)" to "exp(/Hz)".  Thus conversions
    00093 *                       ordinarily consist of
    00094 *
    00095 =                         value *= scale;
    00096 *
    00097 *   err       struct wcserr **
    00098 *                       If enabled, for function return values > 1, this
    00099 *                       struct will contain a detailed error message, see
    00100 *                       wcserr_enable().  May be NULL if an error message is
    00101 *                       not desired.  Otherwise, the user is responsible for
    00102 *                       deleting the memory allocated for the wcserr struct.
    00103 *
    00104 * Function return value:
    00105 *             int       Status return value:
    00106 *                          0: Success.
    00107 *                        1-9: Status return from wcsulexe().
    00108 *                         10: Non-conformant unit specifications.
    00109 *                         11: Non-conformant functions.
    00110 *
    00111 *                       scale is zeroed on return if an error occurs.
    00112 *
    00113 *
    00114 * wcsutrne() - Translation of non-standard unit specifications
    00115 * ------------------------------------------------------------
    00116 * wcsutrne() translates certain commonly used but non-standard unit strings,
    00117 * e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulexe(), refer to
    00118 * the notes below for a full list.  Compounds are also recognized, e.g.
    00119 * "JY/BEAM" and "KM/SEC/SEC".  Extraneous embedded blanks are removed.
    00120 *
    00121 * A deprecated form of this function, wcsutrn(), lacks the wcserr** parameter.
    00122 *
    00123 * Given:
    00124 *   ctrl      int       Although "S" is commonly used to represent seconds,
    00125 *                       its translation to "s" is potentially unsafe since the
    00126 *                       standard recognizes "S" formally as Siemens, however
    00127 *                       rarely that may be used.  The same applies to "H" for
    00128 *                       hours (Henry), and "D" for days (Debye).  This
    00129 *                       bit-flag controls what to do in such cases:
    00130 *                         1: Translate "S" to "s".
    00131 *                         2: Translate "H" to "h".
    00132 *                         4: Translate "D" to "d".
    00133 *                       Thus ctrl == 0 doesn't do any unsafe translations,
    00134 *                       whereas ctrl == 7 does all of them.
    00135 *
    00136 * Given and returned:
    00137 *   unitstr   char []   Null-terminated character array containing the units
    00138 *                       specification to be translated.
    00139 *
    00140 *                       Inline units specifications in the a FITS header
    00141 *                       keycomment are also handled.  If the first non-blank
    00142 *                       character in unitstr is '[' then the unit string is
    00143 *                       delimited by its matching ']'.  Blanks preceding '['
    00144 *                       will be stripped off, but text following the closing
    00145 *                       bracket will be preserved without modification.
    00146 *
    00147 *   err       struct wcserr **
    00148 *                       If enabled, for function return values > 1, this
    00149 *                       struct will contain a detailed error message, see
    00150 *                       wcserr_enable().  May be NULL if an error message is
    00151 *                       not desired.  Otherwise, the user is responsible for
    00152 *                       deleting the memory allocated for the wcserr struct.
    00153 *
    00154 * Function return value:
    00155 *             int       Status return value:
    00156 *                        -1: No change was made, other than stripping blanks
    00157 *                            (not an error).
    00158 *                         0: Success.
    00159 *                         9: Internal parser error.
    00160 *                        12: Potentially unsafe translation, whether applied
    00161 *                             or not (see notes).
    00162 *
    00163 * Notes:
    00164 *   Translation of non-standard unit specifications: apart from leading and
    00165 *   trailing blanks, a case-sensitive match is required for the aliases listed
    00166 *   below, in particular the only recognized aliases with metric prefixes are
    00167 *   "KM", "KHZ", "MHZ", and "GHZ".  Potentially unsafe translations of "D",
    00168 *   "H", and "S", shown in parentheses, are optional.
    00169 *
    00170 =     Unit       Recognized aliases
    00171 =     ----       -------------------------------------------------------------
    00172 =     Angstrom   angstrom
    00173 =     arcmin     arcmins, ARCMIN, ARCMINS
    00174 =     arcsec     arcsecs, ARCSEC, ARCSECS
    00175 =     beam       BEAM
    00176 =     byte       Byte
    00177 =     d          day, days, (D), DAY, DAYS
    00178 =     deg        degree, degrees, DEG, DEGREE, DEGREES
    00179 =     GHz        GHZ
    00180 =     h          hr, (H), HR
    00181 =     Hz         hz, HZ
    00182 =     kHz        KHZ
    00183 =     Jy         JY
    00184 =     K          kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
    00185 =     km         KM
    00186 =     m          metre, meter, metres, meters, M, METRE, METER, METRES, METERS
    00187 =     min        MIN
    00188 =     MHz        MHZ
    00189 =     Ohm        ohm
    00190 =     Pa         pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
    00191 =     pixel      pixels, PIXEL, PIXELS
    00192 =     rad        radian, radians, RAD, RADIAN, RADIANS
    00193 =     s          sec, second, seconds, (S), SEC, SECOND, SECONDS
    00194 =     V          volt, volts, Volt, Volts, VOLT, VOLTS
    00195 =     yr         year, years, YR, YEAR, YEARS
    00196 *
    00197 *   The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte)
    00198 *   are recognized by wcsulexe() itself as an unofficial extension of the
    00199 *   standard, but they are converted to the standard form here.
    00200 *
    00201 *
    00202 * wcsulexe() - FITS units specification parser
    00203 * --------------------------------------------
    00204 * wcsulexe() parses a standard FITS units specification of arbitrary
    00205 * complexity, deriving the scale factor required to convert to canonical
    00206 * units - basically SI with degrees and "dimensionless" additions such as
    00207 * byte, pixel and count.
    00208 *
    00209 * A deprecated form of this function, wcsulex(), lacks the wcserr** parameter.
    00210 *
    00211 * Given:
    00212 *   unitstr   const char []
    00213 *                       Null-terminated character array containing the units
    00214 *                       specification, with or without surrounding square
    00215 *                       brackets (for inline specifications); text following
    00216 *                       the closing bracket is ignored.
    00217 *
    00218 * Returned:
    00219 *   func      int*      Special function type, see note 4:
    00220 *                         0: None
    00221 *                         1: log()  ...base 10
    00222 *                         2: ln()   ...base e
    00223 *                         3: exp()
    00224 *
    00225 *   scale     double*   Scale factor for the unit specification; multiply a
    00226 *                       value expressed in the given units by this factor to
    00227 *                       convert it to canonical units.
    00228 *
    00229 *   units     double[WCSUNITS_NTYPE]
    00230 *                       A units specification is decomposed into powers of 16
    00231 *                       fundamental unit types: angle, mass, length, time,
    00232 *                       count, pixel, etc.  Preprocessor macro WCSUNITS_NTYPE
    00233 *                       is defined to dimension this vector, and others such
    00234 *                       WCSUNITS_PLANE_ANGLE, WCSUNITS_LENGTH, etc. to access
    00235 *                       its elements.
    00236 *
    00237 *                       Corresponding character strings, wcsunits_types[] and
    00238 *                       wcsunits_units[], are predefined to describe each
    00239 *                       quantity and its canonical units.
    00240 *
    00241 *   err       struct wcserr **
    00242 *                       If enabled, for function return values > 1, this
    00243 *                       struct will contain a detailed error message, see
    00244 *                       wcserr_enable().  May be NULL if an error message is
    00245 *                       not desired.  Otherwise, the user is responsible for
    00246 *                       deleting the memory allocated for the wcserr struct.
    00247 *
    00248 * Function return value:
    00249 *             int       Status return value:
    00250 *                         0: Success.
    00251 *                         1: Invalid numeric multiplier.
    00252 *                         2: Dangling binary operator.
    00253 *                         3: Invalid symbol in INITIAL context.
    00254 *                         4: Function in invalid context.
    00255 *                         5: Invalid symbol in EXPON context.
    00256 *                         6: Unbalanced bracket.
    00257 *                         7: Unbalanced parenthesis.
    00258 *                         8: Consecutive binary operators.
    00259 *                         9: Internal parser error.
    00260 *
    00261 *                       scale and units[] are zeroed on return if an error
    00262 *                       occurs.
    00263 *
    00264 * Notes:
    00265 *   1: wcsulexe() is permissive in accepting whitespace in all contexts in a
    00266 *      units specification where it does not create ambiguity (e.g. not
    00267 *      between a metric prefix and a basic unit string), including in strings
    00268 *      like "log (m ** 2)" which is formally disallowed.
    00269 *
    00270 *   2: Supported extensions:
    00271 *      - "angstrom" (OGIP usage) is allowed in addition to "Angstrom".
    00272 *      - "ohm"      (OGIP usage) is allowed in addition to "Ohm".
    00273 *      - "Byte"   (common usage) is allowed in addition to "byte".
    00274 *
    00275 *   3: Table 6 of WCS Paper I lists eleven units for which metric prefixes are
    00276 *      allowed.  However, in this implementation only prefixes greater than
    00277 *      unity are allowed for "a" (annum), "yr" (year), "pc" (parsec), "bit",
    00278 *      and "byte", and only prefixes less than unity are allowed for "mag"
    00279 *      (stellar magnitude).
    00280 *
    00281 *      Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to
    00282 *      avoid confusion with "Pa" (Pascal, not peta-annum).  Note that metric
    00283 *      prefixes are specifically disallowed for "h" (hour) and "d" (day) so
    00284 *      that "ph" (photons) cannot be interpreted as pico-hours, nor "cd"
    00285 *      (candela) as centi-days.
    00286 *
    00287 *   4: Function types log(), ln() and exp() may only occur at the start of the
    00288 *      units specification.  The scale and units[] returned for these refers
    00289 *      to the string inside the function "argument", e.g. to "MHz" in log(MHz)
    00290 *      for which a scale of 1e6 will be returned.
    00291 *
    00292 *
    00293 * Global variable: const char *wcsunits_errmsg[] - Status return messages
    00294 * -----------------------------------------------------------------------
    00295 * Error messages to match the status value returned from each function.
    00296 *
    00297 *
    00298 * Global variable: const char *wcsunits_types[] - Names of physical quantities
    00299 * ----------------------------------------------------------------------------
    00300 * Names for physical quantities to match the units vector returned by
    00301 * wcsulexe():
    00302 *   -  0: plane angle
    00303 *   -  1: solid angle
    00304 *   -  2: charge
    00305 *   -  3: mole
    00306 *   -  4: temperature
    00307 *   -  5: luminous intensity
    00308 *   -  6: mass
    00309 *   -  7: length
    00310 *   -  8: time
    00311 *   -  9: beam
    00312 *   - 10: bin
    00313 *   - 11: bit
    00314 *   - 12: count
    00315 *   - 13: stellar magnitude
    00316 *   - 14: pixel
    00317 *   - 15: solar ratio
    00318 *   - 16: voxel
    00319 *
    00320 *
    00321 * Global variable: const char *wcsunits_units[] - Names of units
    00322 * --------------------------------------------------------------
    00323 * Names for the units (SI) to match the units vector returned by wcsulexe():
    00324 *   -  0: degree
    00325 *   -  1: steradian
    00326 *   -  2: Coulomb
    00327 *   -  3: mole
    00328 *   -  4: Kelvin
    00329 *   -  5: candela
    00330 *   -  6: kilogram
    00331 *   -  7: metre
    00332 *   -  8: second
    00333 *
    00334 * The remainder are dimensionless.
    00335 *===========================================================================*/
    00336
    00337 #ifndef WCSLIB_WCSUNITS
    00338 #define WCSLIB_WCSUNITS
    00339
    00340 #include "wcserr.h"
    00341
    00342 #ifdef __cplusplus
    00343 extern "C" {
    00344 #endif
    00345
    00346
    00347 extern const char *wcsunits_errmsg[];
    00348
    00349 enum wcsunits_errmsg_enum {
    00350   UNITSERR_SUCCESS            =  0,     /* Success. */
    00351   UNITSERR_BAD_NUM_MULTIPLIER =  1,     /* Invalid numeric multiplier. */
    00352   UNITSERR_DANGLING_BINOP     =  2,     /* Dangling binary operator. */
    00353   UNITSERR_BAD_INITIAL_SYMBOL =  3,     /* Invalid symbol in INITIAL
    00354                                            context. */
    00355   UNITSERR_FUNCTION_CONTEXT   =  4,     /* Function in invalid context. */
    00356   UNITSERR_BAD_EXPON_SYMBOL   =  5,     /* Invalid symbol in EXPON context. */
    00357   UNITSERR_UNBAL_BRACKET      =  6,     /* Unbalanced bracket. */
    00358   UNITSERR_UNBAL_PAREN        =  7,     /* Unbalanced parenthesis. */
    00359   UNITSERR_CONSEC_BINOPS      =  8,     /* Consecutive binary operators. */
    00360   UNITSERR_PARSER_ERROR       =  9,     /* Internal parser error. */
    00361   UNITSERR_BAD_UNIT_SPEC      = 10,     /* Non-conformant unit
    00362                                            specifications. */
    00363   UNITSERR_BAD_FUNCS          = 11,     /* Non-conformant functions. */
    00364   UNITSERR_UNSAFE_TRANS       = 12      /* Potentially unsafe translation. */
    00365 };
    00366
    00367 extern const char *wcsunits_types[];
    00368 extern const char *wcsunits_units[];
    00369
    00370 #define WCSUNITS_PLANE_ANGLE 0
    00371 #define WCSUNITS_SOLID_ANGLE 1
    00372 #define WCSUNITS_CHARGE      2
    00373 #define WCSUNITS_MOLE        3
    00374 #define WCSUNITS_TEMPERATURE 4
    00375 #define WCSUNITS_LUMINTEN    5
    00376 #define WCSUNITS_MASS        6
    00377 #define WCSUNITS_LENGTH      7
    00378 #define WCSUNITS_TIME        8
    00379 #define WCSUNITS_BEAM        9
    00380 #define WCSUNITS_BIN        10
    00381 #define WCSUNITS_BIT        11
    00382 #define WCSUNITS_COUNT      12
    00383 #define WCSUNITS_MAGNITUDE  13
    00384 #define WCSUNITS_PIXEL      14
    00385 #define WCSUNITS_SOLRATIO   15
    00386 #define WCSUNITS_VOXEL      16
    00387
    00388 #define WCSUNITS_NTYPE      17
    00389
    00390
    00391 int wcsunitse(const char have[], const char want[], double *scale,
    00392               double *offset, double *power, struct wcserr **err);
    00393
    00394 int wcsutrne(int ctrl, char unitstr[], struct wcserr **err);
    00395
    00396 int wcsulexe(const char unitstr[], int *func, double *scale,
    00397              double units[WCSUNITS_NTYPE], struct wcserr **err);
    00398
    00399 /* Deprecated. */
    00400 int wcsunits(const char have[], const char want[], double *scale,
    00401              double *offset, double *power);
    00402 int wcsutrn(int ctrl, char unitstr[]);
    00403 int wcsulex(const char unitstr[], int *func, double *scale,
    00404             double units[WCSUNITS_NTYPE]);
    00405
    00406 #ifdef __cplusplus
    00407 }
    00408 #endif
    00409
    00410 #endif /* WCSLIB_WCSUNITS */