WCSLIB: wcsfix.h Source File

WCSLIB 4.25.1

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

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