/usr/include/wcslib-5.15/wcsunits.h is in wcslib-dev 5.15-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 | /*============================================================================
WCSLIB 5.15 - an implementation of the FITS WCS standard.
Copyright (C) 1995-2016, Mark Calabretta
This file is part of WCSLIB.
WCSLIB is free software: you can redistribute it and/or modify it under the
terms of the GNU Lesser General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.
WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
more details.
You should have received a copy of the GNU Lesser General Public License
along with WCSLIB. If not, see http://www.gnu.org/licenses.
Direct correspondence concerning WCSLIB to mark@calabretta.id.au
Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
http://www.atnf.csiro.au/people/Mark.Calabretta
$Id: wcsunits.h,v 5.15 2016/04/05 12:55:10 mcalabre Exp $
*=============================================================================
*
* WCSLIB 5.15 - C routines that implement the FITS World Coordinate System
* (WCS) standard. Refer to the README file provided with WCSLIB for an
* overview of the library.
*
*
* Summary of the wcsunits routines
* --------------------------------
* 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://fits.gsfc.nasa.gov
*
* 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.
*
*
* wcsunitse() - 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.
*
* Given:
* have const char []
* FITS units specification to convert from (null-
* terminated), with or without surrounding square
* brackets (for inline specifications); text following
* the closing bracket is ignored.
*
* want const char []
* FITS units specification to convert to (null-
* terminated), with or without surrounding square
* brackets (for inline specifications); text following
* the closing bracket is ignored.
*
* Returned:
* scale,
* offset,
* power double* 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;
*
* err struct wcserr **
* 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.
*
* Function return value:
* int 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() - 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.
*
* Given:
* ctrl int 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.
*
* Given and returned:
* unitstr char [] 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.
*
* err struct wcserr **
* 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.
*
* Function return value:
* int 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.
*
*
* wcsulexe() - 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.
*
* Given:
* unitstr const char []
* Null-terminated character array containing the units
* specification, with or without surrounding square
* brackets (for inline specifications); text following
* the closing bracket is ignored.
*
* Returned:
* func int* Special function type, see note 4:
* 0: None
* 1: log() ...base 10
* 2: ln() ...base e
* 3: exp()
*
* scale double* Scale factor for the unit specification; multiply a
* value expressed in the given units by this factor to
* convert it to canonical units.
*
* units double[WCSUNITS_NTYPE]
* 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.
*
* err struct wcserr **
* 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.
*
* Function return value:
* int 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 1e6 will be returned.
*
*
* Global variable: const char *wcsunits_errmsg[] - Status return messages
* -----------------------------------------------------------------------
* Error messages to match the status value returned from each function.
*
*
* Global variable: const char *wcsunits_types[] - 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
*
*
* Global variable: const char *wcsunits_units[] - 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.
*===========================================================================*/
#ifndef WCSLIB_WCSUNITS
#define WCSLIB_WCSUNITS
#include "wcserr.h"
#ifdef __cplusplus
extern "C" {
#endif
extern const char *wcsunits_errmsg[];
enum wcsunits_errmsg_enum {
UNITSERR_SUCCESS = 0, /* Success. */
UNITSERR_BAD_NUM_MULTIPLIER = 1, /* Invalid numeric multiplier. */
UNITSERR_DANGLING_BINOP = 2, /* Dangling binary operator. */
UNITSERR_BAD_INITIAL_SYMBOL = 3, /* Invalid symbol in INITIAL
context. */
UNITSERR_FUNCTION_CONTEXT = 4, /* Function in invalid context. */
UNITSERR_BAD_EXPON_SYMBOL = 5, /* Invalid symbol in EXPON context. */
UNITSERR_UNBAL_BRACKET = 6, /* Unbalanced bracket. */
UNITSERR_UNBAL_PAREN = 7, /* Unbalanced parenthesis. */
UNITSERR_CONSEC_BINOPS = 8, /* Consecutive binary operators. */
UNITSERR_PARSER_ERROR = 9, /* Internal parser error. */
UNITSERR_BAD_UNIT_SPEC = 10, /* Non-conformant unit
specifications. */
UNITSERR_BAD_FUNCS = 11, /* Non-conformant functions. */
UNITSERR_UNSAFE_TRANS = 12 /* Potentially unsafe translation. */
};
extern const char *wcsunits_types[];
extern const char *wcsunits_units[];
#define WCSUNITS_PLANE_ANGLE 0
#define WCSUNITS_SOLID_ANGLE 1
#define WCSUNITS_CHARGE 2
#define WCSUNITS_MOLE 3
#define WCSUNITS_TEMPERATURE 4
#define WCSUNITS_LUMINTEN 5
#define WCSUNITS_MASS 6
#define WCSUNITS_LENGTH 7
#define WCSUNITS_TIME 8
#define WCSUNITS_BEAM 9
#define WCSUNITS_BIN 10
#define WCSUNITS_BIT 11
#define WCSUNITS_COUNT 12
#define WCSUNITS_MAGNITUDE 13
#define WCSUNITS_PIXEL 14
#define WCSUNITS_SOLRATIO 15
#define WCSUNITS_VOXEL 16
#define WCSUNITS_NTYPE 17
int wcsunitse(const char have[], const char want[], double *scale,
double *offset, double *power, struct wcserr **err);
int wcsutrne(int ctrl, char unitstr[], struct wcserr **err);
int wcsulexe(const char unitstr[], int *func, double *scale,
double units[WCSUNITS_NTYPE], struct wcserr **err);
/* Deprecated. */
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]);
#ifdef __cplusplus
}
#endif
#endif /* WCSLIB_WCSUNITS */
|