#include "wcserr.h"

Macros
#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[WCSUNITS_NTYPE], 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[WCSUNITS_NTYPE])

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, as described in

"Representations of world coordinates in FITS",

Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)

The Flexible Image Transport System (FITS), a data format widely used in astronomy for data interchange and archive, is described in

"Definition of the Flexible Image Transport System (FITS), version 3.0",
Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362

See also http:
These routines perform basic units-related operations:

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.

Macro Definition Documentation

◆ WCSUNITS_PLANE_ANGLE

#define WCSUNITS_PLANE_ANGLE 0

Array index for plane angle units type.

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

◆ WCSUNITS_SOLID_ANGLE

#define WCSUNITS_SOLID_ANGLE 1

Array index for solid angle units type.

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

◆ WCSUNITS_CHARGE

#define WCSUNITS_CHARGE 2

Array index for charge units type.

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

◆ WCSUNITS_MOLE

#define WCSUNITS_MOLE 3

Array index for mole units type.

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

◆ WCSUNITS_TEMPERATURE

#define WCSUNITS_TEMPERATURE 4

Array index for temperature units type.

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

◆ WCSUNITS_LUMINTEN

#define WCSUNITS_LUMINTEN 5

Array index for luminous intensity units type.

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

◆ WCSUNITS_MASS

#define WCSUNITS_MASS 6

Array index for mass units type.

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

◆ WCSUNITS_LENGTH

#define WCSUNITS_LENGTH 7

Array index for length units type.

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

◆ WCSUNITS_TIME

#define WCSUNITS_TIME 8

Array index for time units type.

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

◆ WCSUNITS_BEAM

#define WCSUNITS_BEAM 9

Array index for beam units type.

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

◆ WCSUNITS_BIN

#define WCSUNITS_BIN 10

Array index for bin units type.

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

◆ WCSUNITS_BIT

#define WCSUNITS_BIT 11

Array index for bit units type.

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

◆ WCSUNITS_COUNT

#define WCSUNITS_COUNT 12

Array index for count units type.

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

◆ WCSUNITS_MAGNITUDE

#define WCSUNITS_MAGNITUDE 13

Array index for stellar magnitude units type.

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

◆ WCSUNITS_PIXEL

#define WCSUNITS_PIXEL 14

Array index for pixel units type.

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

◆ WCSUNITS_SOLRATIO

#define WCSUNITS_SOLRATIO 15

Array index for solar mass ratio units type.

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

◆ WCSUNITS_VOXEL

#define WCSUNITS_VOXEL 16

Array index for voxel units type.

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

◆ WCSUNITS_NTYPE

#define WCSUNITS_NTYPE 17

Number of entries in the units array.

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

Enumeration Type Documentation

◆ wcsunits_errmsg_enum

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

◆ wcsunitse()

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

FITS units specification conversion.

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(scalevalue + 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. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

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.

◆ wcsutrne()

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

Translation of non-standard unit specifications.

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 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. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

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 Angstroms angstrom angstroms

arcmin arcmins, ARCMIN, ARCMINS

arcsec arcsecs, ARCSEC, ARCSECS

beam BEAM

byte Byte

d day, days, (D), DAY, DAYS

deg degree, degrees, 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.

◆ wcsulexe()

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

FITS units specification parser.

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. Otherwise, the user is responsible for deleting the memory allocated for the wcserr struct.

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:

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

◆ wcsunits()

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

◆ wcsutrn()

int wcsutrn	(	int	ctrl,
		char	unitstr[]
	)

◆ wcsulex()

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

Variable Documentation

◆ wcsunits_errmsg

const char * wcsunits_errmsg[]

extern

Status return messages.

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

◆ wcsunits_types

const char * wcsunits_types[]

extern

Names of physical quantities.

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

◆ wcsunits_units

const char * wcsunits_units[]

extern

Names of 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.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ WCSUNITS_PLANE_ANGLE

◆ WCSUNITS_SOLID_ANGLE

◆ WCSUNITS_CHARGE

◆ WCSUNITS_MOLE

◆ WCSUNITS_TEMPERATURE

◆ WCSUNITS_LUMINTEN

◆ WCSUNITS_MASS

◆ WCSUNITS_LENGTH

◆ WCSUNITS_TIME

◆ WCSUNITS_BEAM

◆ WCSUNITS_BIN

◆ WCSUNITS_BIT

◆ WCSUNITS_COUNT

◆ WCSUNITS_MAGNITUDE

◆ WCSUNITS_PIXEL

◆ WCSUNITS_SOLRATIO

◆ WCSUNITS_VOXEL

◆ WCSUNITS_NTYPE

Enumeration Type Documentation

◆ wcsunits_errmsg_enum

Function Documentation

◆ wcsunitse()

◆ wcsutrne()

◆ wcsulexe()

◆ wcsunits()

◆ wcsutrn()

◆ wcsulex()

Variable Documentation

◆ wcsunits_errmsg

◆ wcsunits_types

◆ wcsunits_units