WCSLIB 4.23
tab.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.23 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2014, 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: tab.h,v 4.23 2014/05/13 05:50:51 mcalabre Exp $
26 *=============================================================================
27 *
28 * WCSLIB 4.23 - C routines that implement tabular coordinate systems as
29 * defined by the FITS World Coordinate System (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 spectral coordinates in FITS",
35 * Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
36 * 2006, A&A, 446, 747 (Paper III)
37 *
38 * Refer to the README file provided with WCSLIB for an overview of the
39 * library.
40 *
41 *
42 * Summary of the tab routines
43 * ---------------------------
44 * These routines implement the part of the FITS WCS standard that deals with
45 * tabular coordinates, i.e. coordinates that are defined via a lookup table.
46 * They define methods to be used for computing tabular world coordinates from
47 * intermediate world coordinates (a linear transformation of image pixel
48 * coordinates), and vice versa. They are based on the tabprm struct which
49 * contains all information needed for the computations. The struct contains
50 * some members that must be set by the user, and others that are maintained
51 * by these routines, somewhat like a C++ class but with no encapsulation.
52 *
53 * tabini(), tabmem(), tabcpy(), and tabfree() are provided to manage the
54 * tabprm struct, and another, tabprt(), to print its contents.
55 *
56 * A setup routine, tabset(), computes intermediate values in the tabprm struct
57 * from parameters in it that were supplied by the user. The struct always
58 * needs to be set up by tabset() but it need not be called explicitly - refer
59 * to the explanation of tabprm::flag.
60 *
61 * tabx2s() and tabs2x() implement the WCS tabular coordinate transformations.
62 *
63 * Accuracy:
64 * ---------
65 * No warranty is given for the accuracy of these routines (refer to the
66 * copyright notice); intending users must satisfy for themselves their
67 * adequacy for the intended purpose. However, closure effectively to within
68 * double precision rounding error was demonstrated by test routine ttab.c
69 * which accompanies this software.
70 *
71 *
72 * tabini() - Default constructor for the tabprm struct
73 * ----------------------------------------------------
74 * tabini() allocates memory for arrays in a tabprm struct and sets all members
75 * of the struct to default values.
76 *
77 * PLEASE NOTE: every tabprm struct should be initialized by tabini(), possibly
78 * repeatedly. On the first invokation, and only the first invokation, the
79 * flag member of the tabprm struct must be set to -1 to initialize memory
80 * management, regardless of whether tabini() will actually be used to allocate
81 * memory.
82 *
83 * Given:
84 * alloc int If true, allocate memory unconditionally for arrays in
85 * the tabprm struct.
86 *
87 * If false, it is assumed that pointers to these arrays
88 * have been set by the user except if they are null
89 * pointers in which case memory will be allocated for
90 * them regardless. (In other words, setting alloc true
91 * saves having to initalize these pointers to zero.)
92 *
93 * M int The number of tabular coordinate axes.
94 *
95 * K const int[]
96 * Vector of length M whose elements (K_1, K_2,... K_M)
97 * record the lengths of the axes of the coordinate array
98 * and of each indexing vector. M and K[] are used to
99 * determine the length of the various tabprm arrays and
100 * therefore the amount of memory to allocate for them.
101 * Their values are copied into the tabprm struct.
102 *
103 * It is permissible to set K (i.e. the address of the
104 * array) to zero which has the same effect as setting
105 * each element of K[] to zero. In this case no memory
106 * will be allocated for the index vectors or coordinate
107 * array in the tabprm struct. These together with the
108 * K vector must be set separately before calling
109 * tabset().
110 *
111 * Given and returned:
112 * tab struct tabprm*
113 * Tabular transformation parameters. Note that, in
114 * order to initialize memory management tabprm::flag
115 * should be set to -1 when tab is initialized for the
116 * first time (memory leaks may result if it had already
117 * been initialized).
118 *
119 * Function return value:
120 * int Status return value:
121 * 0: Success.
122 * 1: Null tabprm pointer passed.
123 * 2: Memory allocation failed.
124 * 3: Invalid tabular parameters.
125 *
126 * For returns > 1, a detailed error message is set in
127 * tabprm::err if enabled, see wcserr_enable().
128 *
129 *
130 * tabmem() - Acquire tabular memory
131 * ---------------------------------
132 * tabmem() takes control of memory allocated by the user for arrays in the
133 * tabprm struct.
134 *
135 * Given and returned:
136 * tab struct tabprm*
137 * Tabular transformation parameters.
138 *
139 * Function return value:
140 * int Status return value:
141 * 0: Success.
142 * 1: Null tabprm pointer passed.
143 * 2: Memory allocation failed.
144 *
145 * For returns > 1, a detailed error message is set in
146 * tabprm::err if enabled, see wcserr_enable().
147 *
148 *
149 * tabcpy() - Copy routine for the tabprm struct
150 * ---------------------------------------------
151 * tabcpy() does a deep copy of one tabprm struct to another, using tabini() to
152 * allocate memory for its arrays if required. Only the "information to be
153 * provided" part of the struct is copied; a call to tabset() is required to
154 * set up the remainder.
155 *
156 * Given:
157 * alloc int If true, allocate memory unconditionally for arrays in
158 * the tabprm struct.
159 *
160 * If false, it is assumed that pointers to these arrays
161 * have been set by the user except if they are null
162 * pointers in which case memory will be allocated for
163 * them regardless. (In other words, setting alloc true
164 * saves having to initalize these pointers to zero.)
165 *
166 * tabsrc const struct tabprm*
167 * Struct to copy from.
168 *
169 * Given and returned:
170 * tabdst struct tabprm*
171 * Struct to copy to. tabprm::flag should be set to -1
172 * if tabdst was not previously initialized (memory leaks
173 * may result if it was previously initialized).
174 *
175 * Function return value:
176 * int Status return value:
177 * 0: Success.
178 * 1: Null tabprm pointer passed.
179 * 2: Memory allocation failed.
180 *
181 * For returns > 1, a detailed error message is set in
182 * tabprm::err (associated with tabdst) if enabled, see
183 * wcserr_enable().
184 *
185 *
186 * tabcmp() - Compare two tabprm structs for equality
187 * --------------------------------------------------
188 * tabcmp() compares two tabprm structs for equality.
189 *
190 * Given:
191 * cmp int A bit field controlling the strictness of the
192 * comparison. At present, this value must always be 0,
193 * indicating a strict comparison. In the future, other
194 * options may be added.
195 *
196 * tab1 const struct tabprm*
197 * The first tabprm struct to compare.
198 *
199 * tab2 const struct tabprm*
200 * The second tabprm struct to compare.
201 *
202 * Returned:
203 * equal int* Non-zero when the given structs are equal.
204 *
205 * Function return value:
206 * int Status return value:
207 * 0: Success.
208 * 1: Null pointer passed.
209 *
210 *
211 * tabfree() - Destructor for the tabprm struct
212 * --------------------------------------------
213 * tabfree() frees memory allocated for the tabprm arrays by tabini().
214 * tabini() records the memory it allocates and tabfree() will only attempt to
215 * free this.
216 *
217 * PLEASE NOTE: tabfree() must not be invoked on a tabprm struct that was not
218 * initialized by tabini().
219 *
220 * Returned:
221 * tab struct tabprm*
222 * Coordinate transformation parameters.
223 *
224 * Function return value:
225 * int Status return value:
226 * 0: Success.
227 * 1: Null tabprm pointer passed.
228 *
229 *
230 * tabprt() - Print routine for the tabprm struct
231 * ----------------------------------------------
232 * tabprt() prints the contents of a tabprm struct using wcsprintf(). Mainly
233 * intended for diagnostic purposes.
234 *
235 * Given:
236 * tab const struct tabprm*
237 * Tabular transformation parameters.
238 *
239 * Function return value:
240 * int Status return value:
241 * 0: Success.
242 * 1: Null tabprm pointer passed.
243 *
244 *
245 * tabset() - Setup routine for the tabprm struct
246 * -----------------------------------------------
247 * tabset() allocates memory for work arrays in the tabprm struct and sets up
248 * the struct according to information supplied within it.
249 *
250 * Note that this routine need not be called directly; it will be invoked by
251 * tabx2s() and tabs2x() if tabprm::flag is anything other than a predefined
252 * magic value.
253 *
254 * Given and returned:
255 * tab struct tabprm*
256 * Tabular transformation parameters.
257 *
258 * Function return value:
259 * int Status return value:
260 * 0: Success.
261 * 1: Null tabprm pointer passed.
262 * 3: Invalid tabular parameters.
263 *
264 * For returns > 1, a detailed error message is set in
265 * tabprm::err if enabled, see wcserr_enable().
266 *
267 *
268 * tabx2s() - Pixel-to-world transformation
269 * ----------------------------------------
270 * tabx2s() transforms intermediate world coordinates to world coordinates
271 * using coordinate lookup.
272 *
273 * Given and returned:
274 * tab struct tabprm*
275 * Tabular transformation parameters.
276 *
277 * Given:
278 * ncoord,
279 * nelem int The number of coordinates, each of vector length
280 * nelem.
281 *
282 * x const double[ncoord][nelem]
283 * Array of intermediate world coordinates, SI units.
284 *
285 * Returned:
286 * world double[ncoord][nelem]
287 * Array of world coordinates, in SI units.
288 *
289 * stat int[ncoord]
290 * Status return value status for each coordinate:
291 * 0: Success.
292 * 1: Invalid intermediate world coordinate.
293 *
294 * Function return value:
295 * int Status return value:
296 * 0: Success.
297 * 1: Null tabprm pointer passed.
298 * 3: Invalid tabular parameters.
299 * 4: One or more of the x coordinates were invalid,
300 * as indicated by the stat vector.
301 *
302 * For returns > 1, a detailed error message is set in
303 * tabprm::err if enabled, see wcserr_enable().
304 *
305 *
306 * tabs2x() - World-to-pixel transformation
307 * ----------------------------------------
308 * tabs2x() transforms world coordinates to intermediate world coordinates.
309 *
310 * Given and returned:
311 * tab struct tabprm*
312 * Tabular transformation parameters.
313 *
314 * Given:
315 * ncoord,
316 * nelem int The number of coordinates, each of vector length
317 * nelem.
318 * world const double[ncoord][nelem]
319 * Array of world coordinates, in SI units.
320 *
321 * Returned:
322 * x double[ncoord][nelem]
323 * Array of intermediate world coordinates, SI units.
324 * stat int[ncoord]
325 * Status return value status for each vector element:
326 * 0: Success.
327 * 1: Invalid world coordinate.
328 *
329 * Function return value:
330 * int Status return value:
331 * 0: Success.
332 * 1: Null tabprm pointer passed.
333 * 3: Invalid tabular parameters.
334 * 5: One or more of the world coordinates were
335 * invalid, as indicated by the stat vector.
336 *
337 * For returns > 1, a detailed error message is set in
338 * tabprm::err if enabled, see wcserr_enable().
339 *
340 *
341 * tabprm struct - Tabular transformation parameters
342 * -------------------------------------------------
343 * The tabprm struct contains information required to transform tabular
344 * coordinates. It consists of certain members that must be set by the user
345 * ("given") and others that are set by the WCSLIB routines ("returned"). Some
346 * of the latter are supplied for informational purposes while others are for
347 * internal use only.
348 *
349 * int flag
350 * (Given and returned) This flag must be set to zero whenever any of the
351 * following tabprm structure members are set or changed:
352 *
353 * - tabprm::M (q.v., not normally set by the user),
354 * - tabprm::K (q.v., not normally set by the user),
355 * - tabprm::map,
356 * - tabprm::crval,
357 * - tabprm::index,
358 * - tabprm::coord.
359 *
360 * This signals the initialization routine, tabset(), to recompute the
361 * returned members of the tabprm struct. tabset() will reset flag to
362 * indicate that this has been done.
363 *
364 * PLEASE NOTE: flag should be set to -1 when tabini() is called for the
365 * first time for a particular tabprm struct in order to initialize memory
366 * management. It must ONLY be used on the first initialization otherwise
367 * memory leaks may result.
368 *
369 * int M
370 * (Given or returned) Number of tabular coordinate axes.
371 *
372 * If tabini() is used to initialize the tabprm struct (as would normally
373 * be the case) then it will set M from the value passed to it as a
374 * function argument. The user should not subsequently modify it.
375 *
376 * int *K
377 * (Given or returned) Pointer to the first element of a vector of length
378 * tabprm::M whose elements (K_1, K_2,... K_M) record the lengths of the
379 * axes of the coordinate array and of each indexing vector.
380 *
381 * If tabini() is used to initialize the tabprm struct (as would normally
382 * be the case) then it will set K from the array passed to it as a
383 * function argument. The user should not subsequently modify it.
384 *
385 * int *map
386 * (Given) Pointer to the first element of a vector of length tabprm::M
387 * that defines the association between axis m in the M-dimensional
388 * coordinate array (1 <= m <= M) and the indices of the intermediate world
389 * coordinate and world coordinate arrays, x[] and world[], in the argument
390 * lists for tabx2s() and tabs2x().
391 *
392 * When x[] and world[] contain the full complement of coordinate elements
393 * in image-order, as will usually be the case, then map[m-1] == i-1 for
394 * axis i in the N-dimensional image (1 <= i <= N). In terms of the FITS
395 * keywords
396 *
397 * map[PVi_3a - 1] == i - 1.
398 *
399 * However, a different association may result if x[], for example, only
400 * contains a (relevant) subset of intermediate world coordinate elements.
401 * For example, if M == 1 for an image with N > 1, it is possible to fill
402 * x[] with the relevant coordinate element with nelem set to 1. In this
403 * case map[0] = 0 regardless of the value of i.
404 *
405 * double *crval
406 * (Given) Pointer to the first element of a vector of length tabprm::M
407 * whose elements contain the index value for the reference pixel for each
408 * of the tabular coordinate axes.
409 *
410 * double **index
411 * (Given) Pointer to the first element of a vector of length tabprm::M of
412 * pointers to vectors of lengths (K_1, K_2,... K_M) of 0-relative indexes
413 * (see tabprm::K).
414 *
415 * The address of any or all of these index vectors may be set to zero,
416 * i.e.
417 *
418 = index[m] == 0;
419 *
420 * this is interpreted as default indexing, i.e.
421 *
422 = index[m][k] = k;
423 *
424 * double *coord
425 * (Given) Pointer to the first element of the tabular coordinate array,
426 * treated as though it were defined as
427 *
428 = double coord[K_M]...[K_2][K_1][M];
429 *
430 * (see tabprm::K) i.e. with the M dimension varying fastest so that the
431 * M elements of a coordinate vector are stored contiguously in memory.
432 *
433 * int nc
434 * (Returned) Total number of coordinate vectors in the coordinate array
435 * being the product K_1 * K_2 * ... * K_M (see tabprm::K).
436 *
437 * int padding
438 * (An unused variable inserted for alignment purposes only.)
439 *
440 * int *sense
441 * (Returned) Pointer to the first element of a vector of length tabprm::M
442 * whose elements indicate whether the corresponding indexing vector is
443 * monotonic increasing (+1), or decreasing (-1).
444 *
445 * int *p0
446 * (Returned) Pointer to the first element of a vector of length tabprm::M
447 * of interpolated indices into the coordinate array such that Upsilon_m,
448 * as defined in Paper III, is equal to (p0[m] + 1) + tabprm::delta[m].
449 *
450 * double *delta
451 * (Returned) Pointer to the first element of a vector of length tabprm::M
452 * of interpolated indices into the coordinate array such that Upsilon_m,
453 * as defined in Paper III, is equal to (tabprm::p0[m] + 1) + delta[m].
454 *
455 * double *extrema
456 * (Returned) Pointer to the first element of an array that records the
457 * minimum and maximum value of each element of the coordinate vector in
458 * each row of the coordinate array, treated as though it were defined as
459 *
460 = double extrema[K_M]...[K_2][2][M]
461 *
462 * (see tabprm::K). The minimum is recorded in the first element of the
463 * compressed K_1 dimension, then the maximum. This array is used by the
464 * inverse table lookup function, tabs2x(), to speed up table searches.
465 *
466 * struct wcserr *err
467 * (Returned) If enabled, when an error status is returned this struct
468 * contains detailed information about the error, see wcserr_enable().
469 *
470 * int m_flag
471 * (For internal use only.)
472 * int m_M
473 * (For internal use only.)
474 * int m_N
475 * (For internal use only.)
476 * int set_M
477 * (For internal use only.)
478 * int m_K
479 * (For internal use only.)
480 * int m_map
481 * (For internal use only.)
482 * int m_crval
483 * (For internal use only.)
484 * int m_index
485 * (For internal use only.)
486 * int m_indxs
487 * (For internal use only.)
488 * int m_coord
489 * (For internal use only.)
490 *
491 *
492 * Global variable: const char *tab_errmsg[] - Status return messages
493 * ------------------------------------------------------------------
494 * Error messages to match the status value returned from each function.
495 *
496 *===========================================================================*/
497 
498 #ifndef WCSLIB_TAB
499 #define WCSLIB_TAB
500 
501 #include "wcserr.h"
502 
503 #ifdef __cplusplus
504 extern "C" {
505 #endif
506 
507 
508 extern const char *tab_errmsg[];
509 
511  TABERR_SUCCESS = 0, /* Success. */
512  TABERR_NULL_POINTER = 1, /* Null tabprm pointer passed. */
513  TABERR_MEMORY = 2, /* Memory allocation failed. */
514  TABERR_BAD_PARAMS = 3, /* Invalid tabular parameters. */
515  TABERR_BAD_X = 4, /* One or more of the x coordinates were
516  invalid. */
517  TABERR_BAD_WORLD = 5 /* One or more of the world coordinates were
518  invalid. */
519 };
520 
521 struct tabprm {
522  /* Initialization flag (see the prologue above). */
523  /*------------------------------------------------------------------------*/
524  int flag; /* Set to zero to force initialization. */
525 
526  /* Parameters to be provided (see the prologue above). */
527  /*------------------------------------------------------------------------*/
528  int M; /* Number of tabular coordinate axes. */
529  int *K; /* Vector of length M whose elements */
530  /* (K_1, K_2,... K_M) record the lengths of */
531  /* the axes of the coordinate array and of */
532  /* each indexing vector. */
533  int *map; /* Vector of length M usually such that */
534  /* map[m-1] == i-1 for coordinate array */
535  /* axis m and image axis i (see above). */
536  double *crval; /* Vector of length M containing the index */
537  /* value for the reference pixel for each */
538  /* of the tabular coordinate axes. */
539  double **index; /* Vector of pointers to M indexing vectors */
540  /* of lengths (K_1, K_2,... K_M). */
541  double *coord; /* (1+M)-dimensional tabular coordinate */
542  /* array (see above). */
543 
544  /* Information derived from the parameters supplied. */
545  /*------------------------------------------------------------------------*/
546  int nc; /* Number of coordinate vectors (of length */
547  /* M) in the coordinate array. */
548  int padding; /* (Dummy inserted for alignment purposes.) */
549  int *sense; /* Vector of M flags that indicate whether */
550  /* the Mth indexing vector is monotonic */
551  /* increasing, or else decreasing. */
552  int *p0; /* Vector of M indices. */
553  double *delta; /* Vector of M increments. */
554  double *extrema; /* (1+M)-dimensional array of coordinate */
555  /* extrema. */
556 
557  /* Error handling */
558  /*------------------------------------------------------------------------*/
559  struct wcserr *err;
560 
561  /* Private - the remainder are for memory management. */
562  /*------------------------------------------------------------------------*/
563  int m_flag, m_M, m_N;
564  int set_M;
565  int *m_K, *m_map;
566  double *m_crval, **m_index, **m_indxs, *m_coord;
567 };
568 
569 /* Size of the tabprm struct in int units, used by the Fortran wrappers. */
570 #define TABLEN (sizeof(struct tabprm)/sizeof(int))
571 
572 
573 int tabini(int alloc, int M, const int K[], struct tabprm *tab);
574 
575 int tabmem(struct tabprm *tab);
576 
577 int tabcpy(int alloc, const struct tabprm *tabsrc, struct tabprm *tabdst);
578 
579 int tabcmp(int cmp, const struct tabprm *tab1, const struct tabprm *tab2,
580  int *equal);
581 
582 int tabfree(struct tabprm *tab);
583 
584 int tabprt(const struct tabprm *tab);
585 
586 int tabset(struct tabprm *tab);
587 
588 int tabx2s(struct tabprm *tab, int ncoord, int nelem, const double x[],
589  double world[], int stat[]);
590 
591 int tabs2x(struct tabprm *tab, int ncoord, int nelem, const double world[],
592  double x[], int stat[]);
593 
594 
595 /* Deprecated. */
596 #define tabini_errmsg tab_errmsg
597 #define tabcpy_errmsg tab_errmsg
598 #define tabfree_errmsg tab_errmsg
599 #define tabprt_errmsg tab_errmsg
600 #define tabset_errmsg tab_errmsg
601 #define tabx2s_errmsg tab_errmsg
602 #define tabs2x_errmsg tab_errmsg
603 
604 #ifdef __cplusplus
605 }
606 #endif
607 
608 #endif /* WCSLIB_TAB */