WCSLIB 4.20
wcsunits.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.20 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2013, Mark Calabretta
5 
6  This file is part of WCSLIB.
7 
8  WCSLIB is free software: you can redistribute it and/or modify it under the
9  terms of the GNU Lesser General Public License as published by the Free
10  Software Foundation, either version 3 of the License, or (at your option)
11  any later version.
12 
13  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16  more details.
17 
18  You should have received a copy of the GNU Lesser General Public License
19  along with WCSLIB. If not, see http://www.gnu.org/licenses.
20 
21  Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22 
23  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24  http://www.atnf.csiro.au/people/Mark.Calabretta
25  $Id: wcsunits_8h_source.html,v 1.1 2014/02/12 21:11:37 irby Exp $
26 *=============================================================================
27 *
28 * WCSLIB 4.20 - C routines that implement the FITS World Coordinate System
29 * (WCS) standard. Refer to
30 *
31 * "Representations of world coordinates in FITS",
32 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
33 *
34 * The Flexible Image Transport System (FITS), a data format widely used in
35 * astronomy for data interchange and archive, is described in
36 *
37 * "Definition of the Flexible Image Transport System (FITS), version 3.0",
38 * Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
39 * A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362
40 *
41 * See also http://fits.gsfc.nasa.gov
42 *
43 * Refer to the README file provided with WCSLIB for an overview of the
44 * library.
45 *
46 *
47 * Summary of the wcsunits routines
48 * --------------------------------
49 * Routines in this suite deal with units specifications and conversions:
50 *
51 * - wcsunitse(): given two unit specifications, derive the conversion from
52 * one to the other.
53 *
54 * - wcsutrne(): translates certain commonly used but non-standard unit
55 * strings. It is intended to be called before wcsulexe() which only
56 * handles standard FITS units specifications.
57 *
58 * - wcsulexe(): parses a standard FITS units specification of arbitrary
59 * complexity, deriving the conversion to canonical units.
60 *
61 *
62 * wcsunitse() - FITS units specification conversion
63 * -------------------------------------------------
64 * wcsunitse() derives the conversion from one system of units to another.
65 *
66 * A deprecated form of this function, wcsunits(), lacks the wcserr**
67 * parameter.
68 *
69 * Given:
70 * have const char []
71 * FITS units specification to convert from (null-
72 * terminated), with or without surrounding square
73 * brackets (for inline specifications); text following
74 * the closing bracket is ignored.
75 *
76 * want const char []
77 * FITS units specification to convert to (null-
78 * terminated), with or without surrounding square
79 * brackets (for inline specifications); text following
80 * the closing bracket is ignored.
81 *
82 * Returned:
83 * scale,
84 * offset,
85 * power double* Convert units using
86 *
87 = pow(scale*value + offset, power);
88 *
89 * Normally offset is zero except for log() or ln()
90 * conversions, e.g. "log(MHz)" to "ln(Hz)". Likewise,
91 * power is normally unity except for exp() conversions,
92 * e.g. "exp(ms)" to "exp(/Hz)". Thus conversions
93 * ordinarily consist of
94 *
95 = value *= scale;
96 *
97 * err struct wcserr **
98 * If enabled, for function return values > 1, this
99 * struct will contain a detailed error message, see
100 * wcserr_enable(). May be NULL if an error message is
101 * not desired. Otherwise, the user is responsible for
102 * deleting the memory allocated for the wcserr struct.
103 *
104 * Function return value:
105 * int Status return value:
106 * 0: Success.
107 * 1-9: Status return from wcsulexe().
108 * 10: Non-conformant unit specifications.
109 * 11: Non-conformant functions.
110 *
111 * scale is zeroed on return if an error occurs.
112 *
113 *
114 * wcsutrne() - Translation of non-standard unit specifications
115 * ------------------------------------------------------------
116 * wcsutrne() translates certain commonly used but non-standard unit strings,
117 * e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulexe(), refer to
118 * the notes below for a full list. Compounds are also recognized, e.g.
119 * "JY/BEAM" and "KM/SEC/SEC". Extraneous embedded blanks are removed.
120 *
121 * A deprecated form of this function, wcsutrn(), lacks the wcserr** parameter.
122 *
123 * Given:
124 * ctrl int Although "S" is commonly used to represent seconds,
125 * its translation to "s" is potentially unsafe since the
126 * standard recognizes "S" formally as Siemens, however
127 * rarely that may be used. The same applies to "H" for
128 * hours (Henry), and "D" for days (Debye). This
129 * bit-flag controls what to do in such cases:
130 * 1: Translate "S" to "s".
131 * 2: Translate "H" to "h".
132 * 4: Translate "D" to "d".
133 * Thus ctrl == 0 doesn't do any unsafe translations,
134 * whereas ctrl == 7 does all of them.
135 *
136 * Given and returned:
137 * unitstr char [] Null-terminated character array containing the units
138 * specification to be translated.
139 *
140 * Inline units specifications in the a FITS header
141 * keycomment are also handled. If the first non-blank
142 * character in unitstr is '[' then the unit string is
143 * delimited by its matching ']'. Blanks preceding '['
144 * will be stripped off, but text following the closing
145 * bracket will be preserved without modification.
146 *
147 * err struct wcserr **
148 * If enabled, for function return values > 1, this
149 * struct will contain a detailed error message, see
150 * wcserr_enable(). May be NULL if an error message is
151 * not desired. Otherwise, the user is responsible for
152 * deleting the memory allocated for the wcserr struct.
153 *
154 * Function return value:
155 * int Status return value:
156 * -1: No change was made, other than stripping blanks
157 * (not an error).
158 * 0: Success.
159 * 9: Internal parser error.
160 * 12: Potentially unsafe translation, whether applied
161 * or not (see notes).
162 *
163 * Notes:
164 * Translation of non-standard unit specifications: apart from leading and
165 * trailing blanks, a case-sensitive match is required for the aliases listed
166 * below, in particular the only recognized aliases with metric prefixes are
167 * "KM", "KHZ", "MHZ", and "GHZ". Potentially unsafe translations of "D",
168 * "H", and "S", shown in parentheses, are optional.
169 *
170 = Unit Recognized aliases
171 = ---- -------------------------------------------------------------
172 = Angstrom angstrom
173 = arcmin arcmins, ARCMIN, ARCMINS
174 = arcsec arcsecs, ARCSEC, ARCSECS
175 = beam BEAM
176 = byte Byte
177 = d day, days, (D), DAY, DAYS
178 = deg degree, degrees, DEG, DEGREE, DEGREES
179 = GHz GHZ
180 = h hr, (H), HR
181 = Hz hz, HZ
182 = kHz KHZ
183 = Jy JY
184 = K kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
185 = km KM
186 = m metre, meter, metres, meters, M, METRE, METER, METRES, METERS
187 = min MIN
188 = MHz MHZ
189 = Ohm ohm
190 = Pa pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
191 = pixel pixels, PIXEL, PIXELS
192 = rad radian, radians, RAD, RADIAN, RADIANS
193 = s sec, second, seconds, (S), SEC, SECOND, SECONDS
194 = V volt, volts, Volt, Volts, VOLT, VOLTS
195 = yr year, years, YR, YEAR, YEARS
196 *
197 * The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte)
198 * are recognized by wcsulexe() itself as an unofficial extension of the
199 * standard, but they are converted to the standard form here.
200 *
201 *
202 * wcsulexe() - FITS units specification parser
203 * --------------------------------------------
204 * wcsulexe() parses a standard FITS units specification of arbitrary
205 * complexity, deriving the scale factor required to convert to canonical
206 * units - basically SI with degrees and "dimensionless" additions such as
207 * byte, pixel and count.
208 *
209 * A deprecated form of this function, wcsulex(), lacks the wcserr** parameter.
210 *
211 * Given:
212 * unitstr const char []
213 * Null-terminated character array containing the units
214 * specification, with or without surrounding square
215 * brackets (for inline specifications); text following
216 * the closing bracket is ignored.
217 *
218 * Returned:
219 * func int* Special function type, see note 4:
220 * 0: None
221 * 1: log() ...base 10
222 * 2: ln() ...base e
223 * 3: exp()
224 *
225 * scale double* Scale factor for the unit specification; multiply a
226 * value expressed in the given units by this factor to
227 * convert it to canonical units.
228 *
229 * units double[WCSUNITS_NTYPE]
230 * A units specification is decomposed into powers of 16
231 * fundamental unit types: angle, mass, length, time,
232 * count, pixel, etc. Preprocessor macro WCSUNITS_NTYPE
233 * is defined to dimension this vector, and others such
234 * WCSUNITS_PLANE_ANGLE, WCSUNITS_LENGTH, etc. to access
235 * its elements.
236 *
237 * Corresponding character strings, wcsunits_types[] and
238 * wcsunits_units[], are predefined to describe each
239 * quantity and its canonical units.
240 *
241 * err struct wcserr **
242 * If enabled, for function return values > 1, this
243 * struct will contain a detailed error message, see
244 * wcserr_enable(). May be NULL if an error message is
245 * not desired. Otherwise, the user is responsible for
246 * deleting the memory allocated for the wcserr struct.
247 *
248 * Function return value:
249 * int Status return value:
250 * 0: Success.
251 * 1: Invalid numeric multiplier.
252 * 2: Dangling binary operator.
253 * 3: Invalid symbol in INITIAL context.
254 * 4: Function in invalid context.
255 * 5: Invalid symbol in EXPON context.
256 * 6: Unbalanced bracket.
257 * 7: Unbalanced parenthesis.
258 * 8: Consecutive binary operators.
259 * 9: Internal parser error.
260 *
261 * scale and units[] are zeroed on return if an error
262 * occurs.
263 *
264 * Notes:
265 * 1: wcsulexe() is permissive in accepting whitespace in all contexts in a
266 * units specification where it does not create ambiguity (e.g. not
267 * between a metric prefix and a basic unit string), including in strings
268 * like "log (m ** 2)" which is formally disallowed.
269 *
270 * 2: Supported extensions:
271 * - "angstrom" (OGIP usage) is allowed in addition to "Angstrom".
272 * - "ohm" (OGIP usage) is allowed in addition to "Ohm".
273 * - "Byte" (common usage) is allowed in addition to "byte".
274 *
275 * 3: Table 6 of WCS Paper I lists eleven units for which metric prefixes are
276 * allowed. However, in this implementation only prefixes greater than
277 * unity are allowed for "a" (annum), "yr" (year), "pc" (parsec), "bit",
278 * and "byte", and only prefixes less than unity are allowed for "mag"
279 * (stellar magnitude).
280 *
281 * Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to
282 * avoid confusion with "Pa" (Pascal, not peta-annum). Note that metric
283 * prefixes are specifically disallowed for "h" (hour) and "d" (day) so
284 * that "ph" (photons) cannot be interpreted as pico-hours, nor "cd"
285 * (candela) as centi-days.
286 *
287 * 4: Function types log(), ln() and exp() may only occur at the start of the
288 * units specification. The scale and units[] returned for these refers
289 * to the string inside the function "argument", e.g. to "MHz" in log(MHz)
290 * for which a scale of 1e6 will be returned.
291 *
292 *
293 * Global variable: const char *wcsunits_errmsg[] - Status return messages
294 * -----------------------------------------------------------------------
295 * Error messages to match the status value returned from each function.
296 *
297 *
298 * Global variable: const char *wcsunits_types[] - Names of physical quantities
299 * ----------------------------------------------------------------------------
300 * Names for physical quantities to match the units vector returned by
301 * wcsulexe():
302 * - 0: plane angle
303 * - 1: solid angle
304 * - 2: charge
305 * - 3: mole
306 * - 4: temperature
307 * - 5: luminous intensity
308 * - 6: mass
309 * - 7: length
310 * - 8: time
311 * - 9: beam
312 * - 10: bin
313 * - 11: bit
314 * - 12: count
315 * - 13: stellar magnitude
316 * - 14: pixel
317 * - 15: solar ratio
318 * - 16: voxel
319 *
320 *
321 * Global variable: const char *wcsunits_units[] - Names of units
322 * --------------------------------------------------------------
323 * Names for the units (SI) to match the units vector returned by wcsulexe():
324 * - 0: degree
325 * - 1: steradian
326 * - 2: Coulomb
327 * - 3: mole
328 * - 4: Kelvin
329 * - 5: candela
330 * - 6: kilogram
331 * - 7: metre
332 * - 8: second
333 *
334 * The remainder are dimensionless.
335 *===========================================================================*/
336 
337 #ifndef WCSLIB_WCSUNITS
338 #define WCSLIB_WCSUNITS
339 
340 #include "wcserr.h"
341 
342 #ifdef __cplusplus
343 extern "C" {
344 #endif
345 
346 
347 extern const char *wcsunits_errmsg[];
348 
349 enum wcsunits_errmsg_enum {
350  UNITSERR_SUCCESS = 0, /* Success. */
351  UNITSERR_BAD_NUM_MULTIPLIER = 1, /* Invalid numeric multiplier. */
352  UNITSERR_DANGLING_BINOP = 2, /* Dangling binary operator. */
353  UNITSERR_BAD_INITIAL_SYMBOL = 3, /* Invalid symbol in INITIAL
354  context. */
355  UNITSERR_FUNCTION_CONTEXT = 4, /* Function in invalid context. */
356  UNITSERR_BAD_EXPON_SYMBOL = 5, /* Invalid symbol in EXPON context. */
357  UNITSERR_UNBAL_BRACKET = 6, /* Unbalanced bracket. */
358  UNITSERR_UNBAL_PAREN = 7, /* Unbalanced parenthesis. */
359  UNITSERR_CONSEC_BINOPS = 8, /* Consecutive binary operators. */
360  UNITSERR_PARSER_ERROR = 9, /* Internal parser error. */
361  UNITSERR_BAD_UNIT_SPEC = 10, /* Non-conformant unit
362  specifications. */
363  UNITSERR_BAD_FUNCS = 11, /* Non-conformant functions. */
364  UNITSERR_UNSAFE_TRANS = 12 /* Potentially unsafe translation. */
365 };
366 
367 extern const char *wcsunits_types[];
368 extern const char *wcsunits_units[];
369 
370 #define WCSUNITS_PLANE_ANGLE 0
371 #define WCSUNITS_SOLID_ANGLE 1
372 #define WCSUNITS_CHARGE 2
373 #define WCSUNITS_MOLE 3
374 #define WCSUNITS_TEMPERATURE 4
375 #define WCSUNITS_LUMINTEN 5
376 #define WCSUNITS_MASS 6
377 #define WCSUNITS_LENGTH 7
378 #define WCSUNITS_TIME 8
379 #define WCSUNITS_BEAM 9
380 #define WCSUNITS_BIN 10
381 #define WCSUNITS_BIT 11
382 #define WCSUNITS_COUNT 12
383 #define WCSUNITS_MAGNITUDE 13
384 #define WCSUNITS_PIXEL 14
385 #define WCSUNITS_SOLRATIO 15
386 #define WCSUNITS_VOXEL 16
387 
388 #define WCSUNITS_NTYPE 17
389 
390 
391 int wcsunitse(const char have[], const char want[], double *scale,
392  double *offset, double *power, struct wcserr **err);
393 
394 int wcsutrne(int ctrl, char unitstr[], struct wcserr **err);
395 
396 int wcsulexe(const char unitstr[], int *func, double *scale,
397  double units[WCSUNITS_NTYPE], struct wcserr **err);
398 
399 /* Deprecated. */
400 int wcsunits(const char have[], const char want[], double *scale,
401  double *offset, double *power);
402 int wcsutrn(int ctrl, char unitstr[]);
403 int wcsulex(const char unitstr[], int *func, double *scale,
404  double units[WCSUNITS_NTYPE]);
405 
406 #ifdef __cplusplus
407 }
408 #endif
409 
410 #endif /* WCSLIB_WCSUNITS */
Generated on Wed Dec 18 2013 16:43:15 for WCSLIB 4.20 by   doxygen 1.8.4