WCSLIB: wcsfix.h Source File

WCSLIB 5.17

wcsfix.h
Go to the documentation of this file.
1 /*============================================================================
2
3 WCSLIB 5.17 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2017, 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: wcsfix.h,v 5.17 2017/09/18 08:44:23 mcalabre Exp $
26 *=============================================================================
27 *
28 * WCSLIB 5.17 - C routines that implement the FITS World Coordinate System
29 * (WCS) standard. Refer to the README file provided with WCSLIB for an
30 * overview of the library.
31 *
32 *
33 * Summary of the wcsfix routines
34 * ------------------------------
35 * Routines in this suite identify and translate various forms of construct
36 * known to occur in FITS headers that violate the FITS World Coordinate System
37 * (WCS) standard described in
38 *
39 = "Representations of world coordinates in FITS",
40 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
41 =
42 = "Representations of celestial coordinates in FITS",
43 = Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077 (WCS Paper II)
44 =
45 = "Representations of spectral coordinates in FITS",
46 = Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
47 = 2006, A&A, 446, 747 (WCS Paper III)
48 *
49 * Repairs effected by these routines range from the translation of
50 * non-standard values for standard WCS keywords, to the repair of malformed
51 * coordinate representations.
52 *
53 * Non-standard keyvalues:
54 * -----------------------
55 * AIPS-convention celestial projection types, NCP and GLS, and spectral
56 * types, 'FREQ-LSR', 'FELO-HEL', etc., set in CTYPEia are translated
57 * on-the-fly by wcsset() but without modifying the relevant ctype[], pv[] or
58 * specsys members of the wcsprm struct. That is, only the information
59 * extracted from ctype[] is translated when wcsset() fills in wcsprm::cel
60 * (celprm struct) or wcsprm::spc (spcprm struct).
61 *
62 * On the other hand, these routines do change the values of wcsprm::ctype[],
63 * wcsprm::pv[], wcsprm::specsys and other wcsprm struct members as
64 * appropriate to produce the same result as if the FITS header itself had
65 * been translated.
66 *
67 * Auxiliary WCS header information not used directly by WCSLIB may also be
68 * translated. For example, the older DATE-OBS date format (wcsprm::dateobs)
69 * is recast to year-2000 standard form, and MJD-OBS (wcsprm::mjdobs) will be
70 * deduced from it if not already set.
71 *
72 * Certain combinations of keyvalues that result in malformed coordinate
73 * systems, as described in Sect. 7.3.4 of Paper I, may also be repaired.
74 * These are handled by cylfix().
75 *
76 * Non-standard keywords:
77 * ----------------------
78 * The AIPS-convention CROTAn keywords are recognized as quasi-standard and
79 * as such are accomodated by the wcsprm::crota[] and translated to
80 * wcsprm::pc[][] by wcsset(). These are not dealt with here, nor are any
81 * other non-standard keywords since these routines work only on the contents
82 * of a wcsprm struct and do not deal with FITS headers per se. In
83 * particular, they do not identify or translate CD00i00j, PC00i00j, PROJPn,
84 * EPOCH, VELREF or VSOURCEa keywords; this may be done by the FITS WCS
85 * header parser supplied with WCSLIB, refer to wcshdr.h.
86 *
87 * wcsfix() and wcsfixi() apply all of the corrections handled by the following
88 * specific functions which may also be invoked separately:
89 *
90 * - cdfix(): Sets the diagonal element of the CDi_ja matrix to 1.0 if all
91 * CDi_ja keywords associated with a particular axis are omitted.
92 *
93 * - datfix(): recast an older DATE-OBS date format in dateobs to year-2000
94 * standard form and derive mjdobs from it if not already set.
95 * Alternatively, if mjdobs is set and dateobs isn't, then derive dateobs
96 * from it.
97 *
98 * - unitfix(): translate some commonly used but non-standard unit strings in
99 * the CUNITia keyvalues, e.g. 'DEG' -> 'deg'.
100 *
101 * - spcfix(): translate AIPS-convention spectral types, 'FREQ-LSR',
102 * 'FELO-HEL', etc., in ctype[] as set from CTYPEia.
103 *
104 * - celfix(): translate AIPS-convention celestial projection types, NCP and
105 * GLS, in ctype[] as set from CTYPEia.
106 *
107 * - cylfix(): fixes WCS keyvalues for malformed cylindrical projections that
108 * suffer from the problem described in Sect. 7.3.4 of Paper I.
109 *
110 *
111 * wcsfix() - Translate a non-standard WCS struct
112 * ----------------------------------------------
113 * wcsfix() is identical to wcsfixi(), but lacks the info argument.
114 *
115 *
116 * wcsfixi() - Translate a non-standard WCS struct
117 * -----------------------------------------------
118 * wcsfix() applies all of the corrections handled separately by cdfix(),
119 * datfix(), unitfix(), spcfix(), celfix(), and cylfix().
120 *
121 * Given:
122 * ctrl int Do potentially unsafe translations of non-standard
123 * unit strings as described in the usage notes to
124 * wcsutrn().
125 *
126 * naxis const int []
127 * Image axis lengths. If this array pointer is set to
128 * zero then cylfix() will not be invoked.
129 *
130 * Given and returned:
131 * wcs struct wcsprm*
132 * Coordinate transformation parameters.
133 *
134 * Returned:
135 * stat int [NWCSFIX]
136 * Status returns from each of the functions. Use the
137 * preprocessor macros NWCSFIX to dimension this vector
138 * and CDFIX, DATFIX, UNITFIX, SPCFIX, CELFIX, and CYLFIX
139 * to access its elements. A status value of -2 is set
140 * for functions that were not invoked.
141 *
142 * info struct wcserr [NWCSFIX]
143 * Status messages from each of the functions. Use the
144 * preprocessor macros NWCSFIX to dimension this vector
145 * and CDFIX, DATFIX, UNITFIX, SPCFIX, CELFIX, and CYLFIX
146 * to access its elements.
147 *
148 * Function return value:
149 * int Status return value:
150 * 0: Success.
151 * 1: One or more of the translation functions
152 * returned an error.
153 *
154 *
155 * cdfix() - Fix erroneously omitted CDi_ja keywords
156 * -------------------------------------------------
157 * cdfix() sets the diagonal element of the CDi_ja matrix to unity if all
158 * CDi_ja keywords associated with a given axis were omitted. According to
159 * Paper I, if any CDi_ja keywords at all are given in a FITS header then those
160 * not given default to zero. This results in a singular matrix with an
161 * intersecting row and column of zeros.
162 *
163 * Given and returned:
164 * wcs struct wcsprm*
165 * Coordinate transformation parameters.
166 *
167 * Function return value:
168 * int Status return value:
169 * -1: No change required (not an error).
170 * 0: Success.
171 * 1: Null wcsprm pointer passed.
172 *
173 *
174 * datfix() - Translate DATE-OBS and derive MJD-OBS or vice versa
175 * --------------------------------------------------------------
176 * datfix() translates the old DATE-OBS date format set in wcsprm::dateobs to
177 * year-2000 standard form (yyyy-mm-ddThh:mm:ss) and derives MJD-OBS from it if
178 * not already set. Alternatively, if wcsprm::mjdobs is set and
179 * wcsprm::dateobs isn't, then datfix() derives wcsprm::dateobs from it. If
180 * both are set but disagree by more than half a day then status 5 is returned.
181 *
182 * Given and returned:
183 * wcs struct wcsprm*
184 * Coordinate transformation parameters. wcsprm::dateobs
185 * and/or wcsprm::mjdobs may be changed.
186 *
187 * Function return value:
188 * int Status return value:
189 * -1: No change required (not an error).
190 * 0: Success.
191 * 1: Null wcsprm pointer passed.
192 * 5: Invalid parameter value.
193 *
194 * For returns > 1, a detailed error message is set in
195 * wcsprm::err if enabled, see wcserr_enable().
196 *
197 * Notes:
198 * The MJD algorithms used by datfix() are from D.A. Hatcher, 1984, QJRAS,
199 * 25, 53-55, as modified by P.T. Wallace for use in SLALIB subroutines CLDJ
200 * and DJCL.
201 *
202 *
203 * unitfix() - Correct aberrant CUNITia keyvalues
204 * ----------------------------------------------
205 * unitfix() applies wcsutrn() to translate non-standard CUNITia keyvalues,
206 * e.g. 'DEG' -> 'deg', also stripping off unnecessary whitespace.
207 *
208 * Given:
209 * ctrl int Do potentially unsafe translations described in the
210 * usage notes to wcsutrn().
211 *
212 * Given and returned:
213 * wcs struct wcsprm*
214 * Coordinate transformation parameters.
215 *
216 * Function return value:
217 * int Status return value:
218 * -1: No change required (not an error).
219 * 0: Success (an alias was applied).
220 * 1: Null wcsprm pointer passed.
221 *
222 * When units are translated (i.e. status 0), status -2
223 * is set in the wcserr struct to allow an informative
224 * message to be returned.
225 *
226 *
227 * spcfix() - Translate AIPS-convention spectral types
228 * ---------------------------------------------------
229 * spcfix() translates AIPS-convention spectral coordinate types,
230 * '{FREQ,FELO,VELO}-{LSR,HEL,OBS}' (e.g. 'FREQ-OBS', 'FELO-HEL', 'VELO-LSR')
231 * set in wcsprm::ctype[], subject to VELREF set in wcsprm::velref.
232 *
233 * Note that if wcs::specsys is already set then it will not be overridden.
234 *
235 * Given and returned:
236 * wcs struct wcsprm*
237 * Coordinate transformation parameters. wcsprm::ctype[]
238 * and/or wcsprm::specsys may be changed.
239 *
240 * Function return value:
241 * int Status return value:
242 * -1: No change required (not an error).
243 * 0: Success.
244 * 1: Null wcsprm pointer passed.
245 * 2: Memory allocation failed.
246 * 3: Linear transformation matrix is singular.
247 * 4: Inconsistent or unrecognized coordinate axis
248 * types.
249 * 5: Invalid parameter value.
250 * 6: Invalid coordinate transformation parameters.
251 * 7: Ill-conditioned coordinate transformation
252 * parameters.
253 *
254 * For returns > 1, a detailed error message is set in
255 * wcsprm::err if enabled, see wcserr_enable().
256 *
257 *
258 * celfix() - Translate AIPS-convention celestial projection types
259 * ---------------------------------------------------------------
260 * celfix() translates AIPS-convention celestial projection types, NCP and
261 * GLS, set in the ctype[] member of the wcsprm struct.
262 *
263 * Two additional pv[] keyvalues are created when translating NCP, and three
264 * are created when translating GLS with non-zero reference point. If the pv[]
265 * array was initially allocated by wcsini() then the array will be expanded if
266 * necessary. Otherwise, error 2 will be returned if sufficient empty slots
267 * are not already available for use.
268 *
269 * Given and returned:
270 * wcs struct wcsprm*
271 * Coordinate transformation parameters. wcsprm::ctype[]
272 * and/or wcsprm::pv[] may be changed.
273 *
274 * Function return value:
275 * int Status return value:
276 * -1: No change required (not an error).
277 * 0: Success.
278 * 1: Null wcsprm pointer passed.
279 * 2: Memory allocation failed.
280 * 3: Linear transformation matrix is singular.
281 * 4: Inconsistent or unrecognized coordinate axis
282 * types.
283 * 5: Invalid parameter value.
284 * 6: Invalid coordinate transformation parameters.
285 * 7: Ill-conditioned coordinate transformation
286 * parameters.
287 *
288 * For returns > 1, a detailed error message is set in
289 * wcsprm::err if enabled, see wcserr_enable().
290 *
291 *
292 * cylfix() - Fix malformed cylindrical projections
293 * ------------------------------------------------
294 * cylfix() fixes WCS keyvalues for malformed cylindrical projections that
295 * suffer from the problem described in Sect. 7.3.4 of Paper I.
296 *
297 * Given:
298 * naxis const int []
299 * Image axis lengths.
300 *
301 * Given and returned:
302 * wcs struct wcsprm*
303 * Coordinate transformation parameters.
304 *
305 * Function return value:
306 * int Status return value:
307 * -1: No change required (not an error).
308 * 0: Success.
309 * 1: Null wcsprm pointer passed.
310 * 2: Memory allocation failed.
311 * 3: Linear transformation matrix is singular.
312 * 4: Inconsistent or unrecognized coordinate axis
313 * types.
314 * 5: Invalid parameter value.
315 * 6: Invalid coordinate transformation parameters.
316 * 7: Ill-conditioned coordinate transformation
317 * parameters.
318 * 8: All of the corner pixel coordinates are invalid.
319 * 9: Could not determine reference pixel coordinate.
320 * 10: Could not determine reference pixel value.
321 *
322 * For returns > 1, a detailed error message is set in
323 * wcsprm::err if enabled, see wcserr_enable().
324 *
325 *
326 * Global variable: const char *wcsfix_errmsg[] - Status return messages
327 * ---------------------------------------------------------------------
328 * Error messages to match the status value returned from each function.
329 *
330 *===========================================================================*/
331
332 #ifndef WCSLIB_WCSFIX
333 #define WCSLIB_WCSFIX
334
335 #include "wcs.h"
336 #include "wcserr.h"
337
338 #ifdef __cplusplus
339 extern "C" {
340 #endif
341
342 #define CDFIX 0
343 #define DATFIX 1
344 #define UNITFIX 2
345 #define SPCFIX 3
346 #define CELFIX 4
347 #define CYLFIX 5
348 #define NWCSFIX 6
349
350 extern const char *wcsfix_errmsg[];
351 #define cylfix_errmsg wcsfix_errmsg
352
353 enum wcsfix_errmsg_enum {
354 FIXERR_DATE_FIX = -4, /* The date formatting has been fixed up. */
355 FIXERR_SPC_UPDATE = -3, /* Spectral axis type modified. */
356 FIXERR_UNITS_ALIAS = -2, /* Units alias translation. */
357 FIXERR_NO_CHANGE = -1, /* No change. */
358 FIXERR_SUCCESS = 0, /* Success. */
359 FIXERR_NULL_POINTER = 1, /* Null wcsprm pointer passed. */
360 FIXERR_MEMORY = 2, /* Memory allocation failed. */
361 FIXERR_SINGULAR_MTX = 3, /* Linear transformation matrix is
362 singular. */
363 FIXERR_BAD_CTYPE = 4, /* Inconsistent or unrecognized coordinate
364 axis types. */
365 FIXERR_BAD_PARAM = 5, /* Invalid parameter value. */
366 FIXERR_BAD_COORD_TRANS = 6, /* Invalid coordinate transformation
367 parameters. */
368 FIXERR_ILL_COORD_TRANS = 7, /* Ill-conditioned coordinate transformation
369 parameters. */
370 FIXERR_BAD_CORNER_PIX = 8, /* All of the corner pixel coordinates are
371 invalid. */
372 FIXERR_NO_REF_PIX_COORD = 9, /* Could not determine reference pixel
373 coordinate. */
374 FIXERR_NO_REF_PIX_VAL = 10 /* Could not determine reference pixel
375 value. */
376 };
377
378 int wcsfix(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[]);
379
380 int wcsfixi(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[],
381 struct wcserr info[]);
382
383 int cdfix(struct wcsprm *wcs);
384
385 int datfix(struct wcsprm *wcs);
386
387 int unitfix(int ctrl, struct wcsprm *wcs);
388
389 int spcfix(struct wcsprm *wcs);
390
391 int celfix(struct wcsprm *wcs);
392
393 int cylfix(const int naxis[], struct wcsprm *wcs);
394
395
396 #ifdef __cplusplus
397 }
398 #endif
399
400 #endif /* WCSLIB_WCSFIX */
FIXERR_BAD_COORD_TRANS
Definition: wcsfix.h:366
unitfix
int unitfix(int ctrl, struct wcsprm *wcs)
Correct aberrant CUNITia keyvalues.
wcsfix
int wcsfix(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[])
Translate a non-standard WCS struct.
FIXERR_BAD_CORNER_PIX
Definition: wcsfix.h:370
wcserr
Error message handling.
Definition: wcserr.h:225
FIXERR_DATE_FIX
Definition: wcsfix.h:354
FIXERR_NO_REF_PIX_COORD
Definition: wcsfix.h:372
FIXERR_BAD_PARAM
Definition: wcsfix.h:365
wcsfixi
int wcsfixi(int ctrl, const int naxis[], struct wcsprm *wcs, int stat[], struct wcserr info[])
Translate a non-standard WCS struct.
FIXERR_NO_REF_PIX_VAL
Definition: wcsfix.h:374
wcsfix_errmsg_enum
wcsfix_errmsg_enum
Definition: wcsfix.h:353
FIXERR_UNITS_ALIAS
Definition: wcsfix.h:356
wcsfix_errmsg
const char * wcsfix_errmsg[]
Status return messages.
wcsprm
Coordinate transformation parameters.
Definition: wcs.h:1584
FIXERR_SPC_UPDATE
Definition: wcsfix.h:355
FIXERR_MEMORY
Definition: wcsfix.h:360
FIXERR_SUCCESS
Definition: wcsfix.h:358
cylfix
int cylfix(const int naxis[], struct wcsprm *wcs)
Fix malformed cylindrical projections.
FIXERR_ILL_COORD_TRANS
Definition: wcsfix.h:368
FIXERR_NO_CHANGE
Definition: wcsfix.h:357
FIXERR_NULL_POINTER
Definition: wcsfix.h:359
spcfix
int spcfix(struct wcsprm *wcs)
Translate AIPS-convention spectral types.
FIXERR_BAD_CTYPE
Definition: wcsfix.h:363
wcserr.h
wcs.h
cdfix
int cdfix(struct wcsprm *wcs)
Fix erroneously omitted CDi_ja keywords.
datfix
int datfix(struct wcsprm *wcs)
Translate DATE-OBS and derive MJD-OBS or vice versa.
FIXERR_SINGULAR_MTX
Definition: wcsfix.h:361
celfix
int celfix(struct wcsprm *wcs)
Translate AIPS-convention celestial projection types.