# wcsunits.h File Reference

`#include "wcserr.h"`

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.

## Enumerations

enum | wcsunits_errmsg_enum { UNITSERR_SUCCESS = 0, UNITSERR_BAD_NUM_MULTIPLIER = 1, UNITSERR_DANGLING_BINOP = 2, UNITSERR_BAD_INITIAL_SYMBOL = 3, UNITSERR_FUNCTION_CONTEXT = 4, UNITSERR_BAD_EXPON_SYMBOL = 5, UNITSERR_UNBAL_BRACKET = 6, UNITSERR_UNBAL_PAREN = 7, UNITSERR_CONSEC_BINOPS = 8, UNITSERR_PARSER_ERROR = 9, UNITSERR_BAD_UNIT_SPEC = 10, UNITSERR_BAD_FUNCS = 11, UNITSERR_UNSAFE_TRANS = 12 }

## Functions

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

## 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:

- wcsunitse(): given two unit specifications, derive the conversion from one to the other.

- wcsutrne(): translates certain commonly used but non-standard unit strings. It is intended to be called before wcsulexe() which only handles standard FITS units specifications.

- wcsulexe(): parses a standard FITS units specification of arbitrary complexity, deriving the conversion to canonical units.

## 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.

## Enumeration Type Documentation

enum wcsunits_errmsg_enum

Enumerator:

  UNITSERR_SUCCESS |
  UNITSERR_BAD_NUM_MULTIPLIER |
  UNITSERR_DANGLING_BINOP |
  UNITSERR_BAD_INITIAL_SYMBOL |
  UNITSERR_FUNCTION_CONTEXT |
  UNITSERR_BAD_EXPON_SYMBOL |
  UNITSERR_UNBAL_BRACKET |
  UNITSERR_UNBAL_PAREN |
  UNITSERR_CONSEC_BINOPS |
  UNITSERR_PARSER_ERROR |
  UNITSERR_BAD_UNIT_SPEC |
  UNITSERR_BAD_FUNCS |
  UNITSERR_UNSAFE_TRANS |

## Function Documentation

int wcsunitse | ( | const char | have[],
|  | const char | want[],
|  | double * | scale,
|  | double * | offset,
|  | double * | power,
|  | struct wcserr ** | err |
| ) |  |  |

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

A deprecated form of this function, wcsunits(), lacks the wcserr** parameter.

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;

  `[out]` | err | If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired.

Returns:
  Status return value:
  - 0: Success.
  - 1-9: Status return from wcsulexe().
  - 10: Non-conformant unit specifications.
  - 11: Non-conformant functions.
  scale is zeroed on return if an error occurs.

int wcsutrne | ( | int | ctrl,
|  | char | unitstr[],
|  | struct wcserr ** | err |
| ) |  |  |

wcsutrne() translates certain commonly used but non-standard unit strings, e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulexe(), 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.

A deprecated form of this function, wcsutrn(), lacks the wcserr** parameter.

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.

  `[in,out]` | err | If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired.

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 wcsulexe() itself as an unofficial extension of the standard, but they are converted to the standard form here.

int wcsulexe | ( | const char | unitstr[],
|  | int * | func,
|  | double * | scale,
|  | double | units[],
|  | struct wcserr ** | err |
| ) |  |  |

wcsulexe() 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.

A deprecated form of this function, wcsulex(), lacks the wcserr** parameter.

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.

  `[out]` | err | If enabled, for function return values > 1, this struct will contain a detailed error message, see wcserr_enable(). May be NULL if an error message is not desired.

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. wcsulexe() 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 will be returned.

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

int wcsutrn | ( | int | ctrl,
|  | char | unitstr[] |
| ) |  |  |

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

## 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 wcsulexe():

- 0: plane angle
- 1: solid angle
- 2: charge
- 3: mole
- 4: temperature
- 5: luminous intensity
- 6: mass
- 7: length
- 8: time
- 9: beam
- 10: bin
- 11: bit
- 12: count
- 13: stellar magnitude
- 14: pixel
- 15: solar ratio
- 16: voxel

const char * wcsunits_units[]

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

- 0: degree
- 1: steradian
- 2: Coulomb
- 3: mole
- 4: Kelvin
- 5: candela
- 6: kilogram
- 7: metre
- 8: second

The remainder are dimensionless.