wcsunits.h File Reference

Go to the source code of this file.

Defines

#define WCSUNITS_PLANE_ANGLE   0
 Array index for plane angle units type.
#define WCSUNITS_SOLID_ANGLE   1
 Array index for solid angle units type.
#define WCSUNITS_CHARGE   2
 Array index for charge units type.
#define WCSUNITS_MOLE   3
 Array index for mole units type.
#define WCSUNITS_TEMPERATURE   4
 Array index for temperature units type.
#define WCSUNITS_LUMINTEN   5
 Array index for luminous intensity units type.
#define WCSUNITS_MASS   6
 Array index for mass units type.
#define WCSUNITS_LENGTH   7
 Array index for length units type.
#define WCSUNITS_TIME   8
 Array index for time units type.
#define WCSUNITS_BEAM   9
 Array index for beam units type.
#define WCSUNITS_BIN   10
 Array index for bin units type.
#define WCSUNITS_BIT   11
 Array index for bit units type.
#define WCSUNITS_COUNT   12
 Array index for count units type.
#define WCSUNITS_MAGNITUDE   13
 Array index for stellar magnitude units type.
#define WCSUNITS_PIXEL   14
 Array index for pixel units type.
#define WCSUNITS_SOLRATIO   15
 Array index for solar mass ratio units type.
#define WCSUNITS_VOXEL   16
 Array index for voxel units type.
#define WCSUNITS_NTYPE   17
 Number of entries in the units array.

Functions

int wcsunits (const char have[], const char want[], double *scale, double *offset, double *power)
 FITS units specification conversion.
int wcsutrn (int ctrl, char unitstr[])
 Translation of non-standard unit specifications.
int wcsulex (const char unitstr[], int *func, double *scale, double units[])
 FITS units specification parser.

Variables

const char * wcsunits_errmsg []
 Status return messages.
const char * wcsunits_types []
 Names of physical quantities.
const char * wcsunits_units []
 Names of units.

Detailed Description

Routines in this suite deal with units specifications and conversions:

Define Documentation

#define WCSUNITS_PLANE_ANGLE   0

Array index for plane angle units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_SOLID_ANGLE   1

Array index for solid angle units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_CHARGE   2

Array index for charge units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_MOLE   3

Array index for mole ("gram molecular weight") units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_TEMPERATURE   4

Array index for temperature units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_LUMINTEN   5

Array index for luminous intensity units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_MASS   6

Array index for mass units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_LENGTH   7

Array index for length units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_TIME   8

Array index for time units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_BEAM   9

Array index for beam units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_BIN   10

Array index for bin units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_BIT   11

Array index for bit units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_COUNT   12

Array index for count units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_MAGNITUDE   13

Array index for stellar magnitude units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_PIXEL   14

Array index for pixel units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_SOLRATIO   15

Array index for solar mass ratio units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_VOXEL   16

Array index for voxel units in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

#define WCSUNITS_NTYPE   17

Number of entries in the units array returned by wcsulex(), and the wcsunits_types[] and wcsunits_units[] global variables.

Function Documentation

int wcsunits ( const char  have[],
const char  want[],
double *  scale,
double *  offset,
double *  power 
)

wcsunits() derives the conversion from one system of units to another.

Parameters:
[in] have FITS units specification to convert from (null- terminated), with or without surrounding square brackets (for inline specifications); text following the closing bracket is ignored.
[in] want FITS units specification to convert to (null- terminated), with or without surrounding square brackets (for inline specifications); text following the closing bracket is ignored.
[out] scale,offset,power Convert units using 
                          pow(scale*value + offset, power);
Normally offset is zero except for log() or ln() conversions, e.g. "log(MHz)" to "ln(Hz)". Likewise, power is normally unity except for exp() conversions, e.g. "exp(ms)" to "exp(/Hz)". Thus conversions ordinarily consist of 
                          value *= scale;
Returns:
Status return value:
  • 0: Success.
  • 1-9: Status return from wcsulex().
  • 10: Non-conformant unit specifications.
  • 11: Non-conformant functions.
scale is zeroed on return if an error occurs.

int wcsutrn ( int  ctrl,
char  unitstr[] 
)

wcsutrn() translates certain commonly used but non-standard unit strings, e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulex(), refer to the notes below for a full list. Compounds are also recognized, e.g. "JY/BEAM" and "KM/SEC/SEC". Extraneous embedded blanks are removed.

Parameters:
[in] ctrl Although "S" is commonly used to represent seconds, its translation to "s" is potentially unsafe since the standard recognizes "S" formally as Siemens, however rarely that may be used. The same applies to "H" for hours (Henry), and "D" for days (Debye). This bit-flag controls what to do in such cases:
  • 1: Translate "S" to "s".
  • 2: Translate "H" to "h".
  • 4: Translate "D" to "d".
Thus ctrl == 0 doesn't do any unsafe translations, whereas ctrl == 7 does all of them.
[in,out] unitstr Null-terminated character array containing the units specification to be translated.
Inline units specifications in the a FITS header keycomment are also handled. If the first non-blank character in unitstr is '[' then the unit string is delimited by its matching ']'. Blanks preceding '[' will be stripped off, but text following the closing bracket will be preserved without modification.
Returns:
Status return value:
  • -1: No change was made, other than stripping blanks (not an error).
  • 0: Success.
  • 9: Internal parser error.
  • 12: Potentially unsafe translation, whether applied or not (see notes).
Notes:
Translation of non-standard unit specifications: apart from leading and trailing blanks, a case-sensitive match is required for the aliases listed below, in particular the only recognized aliases with metric prefixes are "KM", "KHZ", "MHZ", and "GHZ". Potentially unsafe translations of "D", "H", and "S", shown in parentheses, are optional. 
      Unit       Recognized aliases
      ----       -------------------------------------------------------------
      Angstrom   angstrom
      arcmin     arcmins, ARCMIN, ARCMINS
      arcsec     arcsecs, ARCSEC, ARCSECS
      beam       BEAM
      byte       Byte
      d          day, days, (D), DAY, DAYS
      deg        degree, degrees, DEG, DEGREE, DEGREES
      GHz        GHZ
      h          hr, (H), HR
      Hz         hz, HZ
      kHz        KHZ
      Jy         JY
      K          kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
      km         KM
      m          metre, meter, metres, meters, M, METRE, METER, METRES, METERS
      min        MIN
      MHz        MHZ
      Ohm        ohm
      Pa         pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
      pixel      pixels, PIXEL, PIXELS
      rad        radian, radians, RAD, RADIAN, RADIANS
      s          sec, second, seconds, (S), SEC, SECOND, SECONDS
      V          volt, volts, Volt, Volts, VOLT, VOLTS
      yr         year, years, YR, YEAR, YEARS

The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte) are recognized by wcsulex() itself as an unofficial extension of the standard, but they are converted to the standard form here.

int wcsulex ( const char  unitstr[],
int *  func,
double *  scale,
double  units[] 
)

wcsulex() parses a standard FITS units specification of arbitrary complexity, deriving the scale factor required to convert to canonical units - basically SI with degrees and "dimensionless" additions such as byte, pixel and count.

Parameters:
[in] unitstr Null-terminated character array containing the units specification, with or without surrounding square brackets (for inline specifications); text following the closing bracket is ignored.
[out] func Special function type, see note 4:
  • 0: None
  • 1: log() ...base 10
  • 2: ln() ...base e
  • 3: exp()
[out] scale Scale factor for the unit specification; multiply a value expressed in the given units by this factor to convert it to canonical units.
[out] units A units specification is decomposed into powers of 16 fundamental unit types: angle, mass, length, time, count, pixel, etc. Preprocessor macro WCSUNITS_NTYPE is defined to dimension this vector, and others such WCSUNITS_PLANE_ANGLE, WCSUNITS_LENGTH, etc. to access its elements.
Corresponding character strings, wcsunits_types[] and wcsunits_units[], are predefined to describe each quantity and its canonical units.
Returns:
Status return value:
  • 0: Success.
  • 1: Invalid numeric multiplier.
  • 2: Dangling binary operator.
  • 3: Invalid symbol in INITIAL context.
  • 4: Function in invalid context.
  • 5: Invalid symbol in EXPON context.
  • 6: Unbalanced bracket.
  • 7: Unbalanced parenthesis.
  • 8: Consecutive binary operators.
  • 9: Internal parser error.
scale and units[] are zeroed on return if an error occurs.
Notes:
  1. wcsulex() is permissive in accepting whitespace in all contexts in a units specification where it does not create ambiguity (e.g. not between a metric prefix and a basic unit string), including in strings like "log (m ** 2)" which is formally disallowed.

  2. Supported extensions:
    • "angstrom" (OGIP usage) is allowed in addition to "Angstrom".
    • "ohm" (OGIP usage) is allowed in addition to "Ohm".
    • "Byte" (common usage) is allowed in addition to "byte".

  3. Table 6 of WCS Paper I lists eleven units for which metric prefixes are allowed. However, in this implementation only prefixes greater than unity are allowed for "a" (annum), "yr" (year), "pc" (parsec), "bit", and "byte", and only prefixes less than unity are allowed for "mag" (stellar magnitude).

    Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to avoid confusion with "Pa" (Pascal, not peta-annum). Note that metric prefixes are specifically disallowed for "h" (hour) and "d" (day) so that "ph" (photons) cannot be interpreted as pico-hours, nor "cd" (candela) as centi-days.

  4. Function types log(), ln() and exp() may only occur at the start of the units specification. The scale and units[] returned for these refers to the string inside the function "argument", e.g. to "MHz" in log(MHz) for which a scale of $10^6$ will be returned.

Variable Documentation

const char * wcsunits_errmsg[]

Error messages to match the status value returned from each function.

const char * wcsunits_types[]

Names for physical quantities to match the units vector returned by wcsulex():

const char * wcsunits_units[]

Names for the units (SI) to match the units vector returned by wcsulex():

The remainder are dimensionless.

Generated on Mon Sep 14 17:03:56 2009 for WCSLIB 4.4 by  doxygen 1.5.1