WCSLIB  5.3.1
dis.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 5.3 - 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: dis.h,v 5.3.1.1 2015/04/21 02:54:02 mcalabre Exp mcalabre $
26 *=============================================================================
27 *
28 * WCSLIB 5.3 - experimental C routines that implement proposed extensions to
29 * the FITS World Coordinate System (WCS) standard. Refer to
30 *
31 * "Representations of distortions in FITS world coordinate systems",
32 * Calabretta, M.R. et al. (Paper IV), draft dated 2004/04/22 available from
33 * http://www.atnf.csiro.au/people/Mark.Calabretta
34 *
35 * The distortion function component of the TPV "projection" is also supported.
36 * The TPV projection, originally proposed in a draft of WCS Paper II, consists
37 * of a TAN projection with sequent polynomial distortion, the coefficients of
38 * which are encoded in PVi_ma keyrecords. Full details may be found at the
39 * registry of FITS conventions:
40 *
41 * http://fits.gsfc.nasa.gov/registry/tpvwcs/tpv.html
42 *
43 * Refer to the README file provided with WCSLIB for an overview of the
44 * library.
45 *
46 *
47 * Summary of the dis routines
48 * ---------------------------
49 * These routines apply the distortion functions defined by the extension to
50 * the FITS WCS standard proposed in Paper IV. They are based on the disprm
51 * struct which contains all information needed for the computations. The
52 * struct contains some members that must be set by the user, and others that
53 * are maintained by these routines, somewhat like a C++ class but with no
54 * encapsulation.
55 *
56 * disndp(), dpfill(), disini(), discpy(), and disfree() are provided to manage
57 * the disprm struct, and another, disprt(), prints its contents.
58 *
59 * A setup routine, disset(), computes intermediate values in the disprm struct
60 * from parameters in it that were supplied by the user. The struct always
61 * needs to be set up by disset(), though disset() need not be called
62 * explicitly - refer to the explanation of disprm::flag.
63 *
64 * disp2x() and disx2p() implement the WCS distortion functions, disp2x() using
65 * separate functions, such as dispoly() and tpv7(), to do the computation.
66 *
67 * An auxiliary routine, diswarp(), computes various measures of the distortion
68 * over a specified range of coordinates.
69 *
70 * PLEASE NOTE: Distortions are not currently handled by wcspih(), wcsbth(),
71 * wcssub(), wcscompare(), or wcshdo().
72 *
73 *
74 * disndp() - Memory allocation for DPja and DQia
75 * ----------------------------------------------
76 * disndp() changes the value of NDPMAX (default 256). This global variable
77 * controls the number of dpkey structs, for holding DPja or DQia keyvalues,
78 * that disini() should allocate space for.
79 *
80 * PLEASE NOTE: This function is not thread-safe.
81 *
82 * Given:
83 * n int Value of NDPMAX; ignored if < 0.
84 *
85 * Function return value:
86 * int Current value of NDPMAX.
87 *
88 *
89 * dpfill() - Fill the contents of a dpkey struct
90 * ----------------------------------------------
91 * dpfill() is a utility routine to aid in filling the contents of the dpkey
92 * struct. No checks are done on the validity of the inputs.
93 *
94 * WCS Paper IV specifies the syntax of a record-valued keyword as
95 *
96 = keyword = '<field-specifier>: <float>'
97 *
98 * However, some DPja and DQia record values, such as those of DPja.NAXES and
99 * DPja.AXIS.j, are intrinsically integer-valued. While FITS header parsers
100 * are not expected to know in advance which of DPja and DQia are integral and
101 * which are floating point, if the record's value parses as an integer (i.e.
102 * without decimal point or exponent), then preferably enter it into the dpkey
103 * struct as an integer. Either way, it doesn't matter as disset() accepts
104 * either data type for all record values.
105 *
106 * Given and returned:
107 * dp struct dpkey*
108 * Store for DPja and DQia keyvalues.
109 *
110 * Given:
111 * keyword const char *
112 * field const char *
113 * These arguments are concatenated with an intervening
114 * "." to construct the full record field name, i.e.
115 * including the keyword name, DPja or DQia (but
116 * excluding the colon delimiter which is NOT part of the
117 * name). Either may be given as a NULL pointer. Set
118 * both NULL to omit setting this component of the
119 * struct.
120 *
121 * j int Axis number (1-relative), i.e. the j in DPja or
122 * i in DQia. Can be given as 0, in which case the axis
123 * number will be obtained from the keyword component of
124 * the field name which must either have been given or
125 * preset.
126 *
127 * type int Data type of the record's value
128 * 0: Integer,
129 * 1: Floating point.
130 *
131 * ival int For type == 0, the integer value of the record.
132 *
133 * fval double For type == 1, the floating point value of the record.
134 *
135 * Function return value:
136 * int Status return value:
137 * 0: Success.
138 *
139 *
140 * disini() - Default constructor for the disprm struct
141 * ----------------------------------------------------
142 * disini() allocates memory for arrays in a disprm struct and sets all members
143 * of the struct to default values. Memory is allocated for up to NDPMAX DPja
144 * or DQia keywords per WCS representation. This may be changed via disndp()
145 * before disini() is called.
146 *
147 * PLEASE NOTE: every disprm struct must be initialized by disini(), possibly
148 * repeatedly. On the first invokation, and only the first invokation,
149 * disprm::flag must be set to -1 to initialize memory management, regardless
150 * of whether disini() will actually be used to allocate memory.
151 *
152 * Given:
153 * alloc int If true, allocate memory unconditionally for arrays in
154 * the disprm struct.
155 *
156 * If false, it is assumed that pointers to these arrays
157 * have been set by the user except if they are null
158 * pointers in which case memory will be allocated for
159 * them regardless. (In other words, setting alloc true
160 * saves having to initalize these pointers to zero.)
161 *
162 * naxis int The number of world coordinate axes, used to determine
163 * array sizes.
164 *
165 * Given and returned:
166 * dis struct disprm*
167 * Distortion function parameters. Note that, in order
168 * to initialize memory management disprm::flag must be
169 * set to -1 when dis is initialized for the first time
170 * (memory leaks may result if it had already been
171 * initialized).
172 *
173 * Function return value:
174 * int Status return value:
175 * 0: Success.
176 * 1: Null disprm pointer passed.
177 * 2: Memory allocation failed.
178 *
179 * For returns > 1, a detailed error message is set in
180 * disprm::err if enabled, see wcserr_enable().
181 *
182 *
183 * discpy() - Copy routine for the disprm struct
184 * ---------------------------------------------
185 * discpy() does a deep copy of one disprm struct to another, using disini() to
186 * allocate memory unconditionally for its arrays if required. Only the
187 * "information to be provided" part of the struct is copied; a call to
188 * disset() is required to initialize the remainder.
189 *
190 * Given:
191 * alloc int If true, allocate memory unconditionally for arrays in
192 * the destination. Otherwise, it is assumed that
193 * pointers to these arrays have been set by the user
194 * except if they are null pointers in which case memory
195 * will be allocated for them regardless.
196 *
197 * dissrc const struct disprm*
198 * Struct to copy from.
199 *
200 * Given and returned:
201 * disdst struct disprm*
202 * Struct to copy to. disprm::flag should be set to -1
203 * if disdst was not previously initialized (memory leaks
204 * may result if it was previously initialized).
205 *
206 * Function return value:
207 * int Status return value:
208 * 0: Success.
209 * 1: Null disprm pointer passed.
210 * 2: Memory allocation failed.
211 *
212 * For returns > 1, a detailed error message is set in
213 * disprm::err if enabled, see wcserr_enable().
214 *
215 *
216 * disfree() - Destructor for the disprm struct
217 * --------------------------------------------
218 * disfree() frees memory allocated for the disprm arrays by disini().
219 * disini() keeps a record of the memory it allocates and disfree() will only
220 * attempt to free this.
221 *
222 * PLEASE NOTE: disfree() must not be invoked on a disprm struct that was not
223 * initialized by disini().
224 *
225 * Given:
226 * dis struct disprm*
227 * Distortion function parameters.
228 *
229 * Function return value:
230 * int Status return value:
231 * 0: Success.
232 * 1: Null disprm pointer passed.
233 *
234 *
235 * disprt() - Print routine for the disprm struct
236 * ----------------------------------------------
237 * disprt() prints the contents of a disprm struct using wcsprintf(). Mainly
238 * intended for diagnostic purposes.
239 *
240 * Given:
241 * dis const struct disprm*
242 * Distortion function parameters.
243 *
244 * Function return value:
245 * int Status return value:
246 * 0: Success.
247 * 1: Null disprm pointer passed.
248 *
249 *
250 * disset() - Setup routine for the disprm struct
251 * ----------------------------------------------
252 * disset(), sets up the disprm struct according to information supplied within
253 * it - refer to the explanation of disprm::flag.
254 *
255 * Note that this routine need not be called directly; it will be invoked by
256 * disp2x() and disx2p() if the disprm::flag is anything other than a
257 * predefined magic value.
258 *
259 * Given and returned:
260 * dis struct disprm*
261 * Distortion function parameters.
262 *
263 * Function return value:
264 * int Status return value:
265 * 0: Success.
266 * 1: Null disprm pointer passed.
267 * 2: Memory allocation failed.
268 * 3: Invalid parameter.
269 *
270 * For returns > 1, a detailed error message is set in
271 * disprm::err if enabled, see wcserr_enable().
272 *
273 *
274 * disp2x() - Apply distortion function
275 * ------------------------------------
276 * disp2x() applies the distortion functions. By definition, the distortion
277 * is in the pixel-to-world direction.
278 *
279 * Depending on the point in the algorithm chain at which it is invoked,
280 * disp2x() may transform pixel coordinates to corrected pixel coordinates, or
281 * intermediate pixel coordinates to corrected intermediate pixel coordinates,
282 * or image coordinates to corrected image coordinates.
283 *
284 *
285 * Given and returned:
286 * dis struct disprm*
287 * Distortion function parameters.
288 *
289 * Given:
290 * rawcrd const double[naxis]
291 * Array of coordinates.
292 *
293 * Returned:
294 * discrd double[naxis]
295 * Array of coordinates to which the distortion functions
296 * have been applied.
297 *
298 * Function return value:
299 * int Status return value:
300 * 0: Success.
301 * 1: Null disprm pointer passed.
302 * 2: Memory allocation failed.
303 * 3: Invalid parameter.
304 * 4: Distort error.
305 *
306 * For returns > 1, a detailed error message is set in
307 * disprm::err if enabled, see wcserr_enable().
308 *
309 *
310 * disx2p() - Apply de-distortion function
311 * ---------------------------------------
312 * disx2p() applies the inverse of the distortion functions. By definition,
313 * the de-distortion is in the world-to-pixel direction.
314 *
315 * Depending on the point in the algorithm chain at which it is invoked,
316 * disx2p() may transform corrected pixel coordinates to pixel coordinates, or
317 * corrected intermediate pixel coordinates to intermediate pixel coordinates,
318 * or corrected image coordinates to image coordinates.
319 *
320 * disx2p() iteratively solves for the inverse using disp2x(). It assumes
321 * that the distortion is small and the functions are well-behaved, being
322 * continuous and with continuous derivatives. Also that, to first order
323 * in the neighbourhood of the solution, discrd[j] ~= a + b*rawcrd[j], i.e.
324 * independent of rawcrd[i], where i != j. This is effectively equivalent to
325 * assuming that the distortion functions are separable to first order.
326 * Furthermore, a is assumed to be small, and b close to unity.
327 *
328 * Given and returned:
329 * dis struct disprm*
330 * Distortion function parameters.
331 *
332 * Given:
333 * discrd const double[naxis]
334 * Array of coordinates.
335 *
336 * Returned:
337 * rawcrd double[naxis]
338 * Array of coordinates to which the inverse distortion
339 * functions have been applied.
340 *
341 * Function return value:
342 * int Status return value:
343 * 0: Success.
344 * 1: Null disprm pointer passed.
345 * 2: Memory allocation failed.
346 * 3: Invalid parameter.
347 * 5: De-distort error.
348 *
349 * For returns > 1, a detailed error message is set in
350 * disprm::err if enabled, see wcserr_enable().
351 *
352 *
353 * diswarp() - Compute measures of distortion
354 * ------------------------------------------
355 * diswarp() computes various measures of the distortion over a specified range
356 * of coordinates.
357 *
358 * For prior distortions, the measures may be interpreted simply as an offset
359 * in pixel coordinates. For sequent distortions, the interpretation depends
360 * on the nature of the linear transformation matrix (PCi_ja or CDi_ja). If
361 * the latter introduces a scaling, then the measures will also be scaled.
362 * Note also that the image domain, which is rectangular in pixel coordinates,
363 * may be rotated, skewed, and/or stretched in intermediate pixel coordinates,
364 * and in general cannot be defined using pixblc[] and pixtrc[].
365 *
366 * PLEASE NOTE: the measures of total distortion may be essentially meaningless
367 * if there are multiple sequent distortions with different scaling.
368 *
369 * See also linwarp().
370 *
371 * Given and returned:
372 * dis struct disprm*
373 * Distortion function parameters.
374 *
375 * Given:
376 * pixblc const double[naxis]
377 * Start of the range of pixel coordinates (for prior
378 * distortions), or intermediate pixel coordinates (for
379 * sequent distortions). May be specified as a NULL
380 * pointer which is interpreted as (1,1,...).
381 *
382 * pixtrc const double[naxis]
383 * End of the range of pixel coordinates (prior) or
384 * intermediate pixel coordinates (sequent).
385 *
386 * pixsamp const double[naxis]
387 * If positive or zero, the increment on the particular
388 * axis, starting at pixblc[]. Zero is interpreted as a
389 * unit increment. pixsamp may also be specified as a
390 * NULL pointer which is interpreted as all zeroes, i.e.
391 * unit increments on all axes.
392 *
393 * If negative, the grid size on the particular axis (the
394 * absolute value being rounded to the nearest integer).
395 * For example, if pixsamp is (-128.0,-128.0,...) then
396 * each axis will be sampled at 128 points between
397 * pixblc[] and pixtrc[] inclusive. Use caution when
398 * using this option on non-square images.
399 *
400 * Returned:
401 * nsamp int* The number of pixel coordinates sampled.
402 *
403 * Can be specified as a NULL pointer if not required.
404 *
405 * maxdis double[naxis]
406 * For each individual distortion function, the
407 * maximum absolute value of the distortion.
408 *
409 * Can be specified as a NULL pointer if not required.
410 *
411 * maxtot double* For the combination of all distortion functions, the
412 * maximum absolute value of the distortion.
413 *
414 * Can be specified as a NULL pointer if not required.
415 *
416 * avgdis double[naxis]
417 * For each individual distortion function, the
418 * mean value of the distortion.
419 *
420 * Can be specified as a NULL pointer if not required.
421 *
422 * avgtot double* For the combination of all distortion functions, the
423 * mean value of the distortion.
424 *
425 * Can be specified as a NULL pointer if not required.
426 *
427 * rmsdis double[naxis]
428 * For each individual distortion function, the
429 * root mean square deviation of the distortion.
430 *
431 * Can be specified as a NULL pointer if not required.
432 *
433 * rmstot double* For the combination of all distortion functions, the
434 * root mean square deviation of the distortion.
435 *
436 * Can be specified as a NULL pointer if not required.
437 *
438 * Function return value:
439 * int Status return value:
440 * 0: Success.
441 * 1: Null disprm pointer passed.
442 * 2: Memory allocation failed.
443 * 3: Invalid parameter.
444 * 4: Distort error.
445 *
446 *
447 * disprm struct - Distortion parameters
448 * -------------------------------------
449 * The disprm struct contains all of the information required to apply a set of
450 * distortion functions. It consists of certain members that must be set by
451 * the user ("given") and others that are set by the WCSLIB routines
452 * ("returned"). While the addresses of the arrays themselves may be set by
453 * disini() if it (optionally) allocates memory, their contents must be set by
454 * the user.
455 *
456 * int flag
457 * (Given and returned) This flag must be set to zero whenever any of the
458 * following members of the disprm struct are set or modified:
459 *
460 * - disprm::naxis,
461 * - disprm::dtype,
462 * - disprm::ndp,
463 * - disprm::dp.
464 *
465 * This signals the initialization routine, disset(), to recompute the
466 * returned members of the disprm struct. disset() will reset flag to
467 * indicate that this has been done.
468 *
469 * PLEASE NOTE: flag must be set to -1 when disini() is called for the
470 * first time for a particular disprm struct in order to initialize memory
471 * management. It must ONLY be used on the first initialization otherwise
472 * memory leaks may result.
473 *
474 * int naxis
475 * (Given or returned) Number of pixel and world coordinate elements.
476 *
477 * If disini() is used to initialize the disprm struct (as would normally
478 * be the case) then it will set naxis from the value passed to it as a
479 * function argument. The user should not subsequently modify it.
480 *
481 * char (*dtype)[72]
482 * (Given) Pointer to the first element of an array of char[72] containing
483 * the name of the distortion function for each axis.
484 *
485 * int ndp
486 * (Given) The number of entries in the disprm::dp[] array.
487 *
488 * int ndpmax
489 * (Given) The length of the disprm::dp[] array.
490 *
491 * ndpmax will be set by disini() if it allocates memory for disprm::dp[],
492 * otherwise it must be set by the user. See also disndp().
493 *
494 * struct dpkey dp
495 * (Given) Address of the first element of an array of length ndpmax of
496 * dpkey structs.
497 *
498 * As a FITS header parser encounters each DPja or DQia keyword it should
499 * load it into a dpkey struct in the array and increment ndp. However,
500 * note that a single disprm struct must hold only DPja or DQia keyvalues,
501 * not both. disset() interprets them as required by the particular
502 * distortion function.
503 *
504 * double *maxdis
505 * (Given) Pointer to the first element of an array of double specifying
506 * the maximum absolute value of the distortion for each axis computed over
507 * the whole image.
508 *
509 * It is not necessary to reset the disprm struct (via disset()) when
510 * disprm::maxdis is changed.
511 *
512 * double totdis
513 * (Given) The maximum absolute value of the combination of all distortion
514 * functions specified as an offset in pixel coordinates computed over the
515 * whole image.
516 *
517 * It is not necessary to reset the disprm struct (via disset()) when
518 * disprm::totdis is changed.
519 *
520 * int **axmap
521 * (Returned) Pointer to the first element of an array of int* containing
522 * pointers to the first elements of the axis mapping arrays for each axis.
523 *
524 * An axis mapping associates the independent variables of a distortion
525 * function with the 1-relative image axis number. For example, consider
526 * an image with a spectrum on the first axis, followed by RA, Dec, and
527 * time axes. For a distortion in (RA,Dec) and no distortion on the
528 * spectral or time axes, the axis mapping arrays, axmap[j][], would be
529 *
530 = j=0: [0, 0, 0, 0] ...no distortion on spectral axis,
531 = 1: [2, 3, 0, 0] ...RA distortion depends on RA and Dec,
532 = 2: [3, 2, 0, 0] ...Dec distortion depends on Dec and RA,
533 = 3: [0, 0, 0, 0] ...no distortion on time axis,
534 *
535 * where zero indicates that there is no corresponding independent
536 * variable.
537 *
538 * int *Nhat
539 * (Returned) Pointer to the first element of an array of int* containing
540 * the number of coordinate axes that form the independent variables of the
541 * distortion function.
542 *
543 * double **offset
544 * (Returned) Pointer to the first element of an array of double*
545 * containing an offset used to renormalize the independent variables of
546 * the distortion function for each axis.
547 *
548 * The offsets are subtracted from the independent variables before
549 * scaling.
550 *
551 * double **scale
552 * (Returned) Pointer to the first element of an array of double*
553 * containing a scale used to renormalize the independent variables of the
554 * distortion function for each axis.
555 *
556 * The scale is applied to the independent variables after the offsets are
557 * subtracted.
558 *
559 * int **iparm
560 * (Returned) Pointer to the first element of an array of int*
561 * containing pointers to the first elements of the arrays of integer
562 * distortion parameters for each axis.
563 *
564 * double **dparm
565 * (Returned) Pointer to the first element of an array of double*
566 * containing pointers to the first elements of the arrays of floating
567 * point distortion parameters for each axis.
568 *
569 * int i_naxis
570 * (Returned) Dimension of the internal arrays (normally equal to naxis).
571 *
572 * int ndis
573 * (Returned) The number of distortion functions.
574 *
575 * struct wcserr *err
576 * (Returned) If enabled, when an error status is returned, this struct
577 * contains detailed information about the error, see wcserr_enable().
578 *
579 * int (**disp2x)(DISP2X_ARGS)
580 * (For internal use only.)
581 * int (**disx2p)(DISX2P_ARGS)
582 * (For internal use only.)
583 * double *tmpmem
584 * (For internal use only.)
585 * int m_flag
586 * (For internal use only.)
587 * int m_naxis
588 * (For internal use only.)
589 * char (*m_dtype)[72]
590 * (For internal use only.)
591 * double **m_dp
592 * (For internal use only.)
593 * double *m_maxdis
594 * (For internal use only.)
595 *
596 *
597 * dpkey struct - Store for DPja and DQia keyvalues
598 * ------------------------------------------------
599 * The dpkey struct is used to pass the parsed contents of DPja or DQia
600 * keyrecords to disset() via the disprm struct. A disprm struct must hold
601 * only DPja or DQia keyvalues, not both.
602 *
603 * All members of this struct are to be set by the user.
604 *
605 * char field[72]
606 * (Given) The full field name of the record, including the keyword name.
607 * Note that the colon delimiter separating the field name and the value in
608 * record-valued keyvalues is not part of the field name. For example, in
609 * the following:
610 *
611 = DP3A = 'AXIS.1: 2'
612 *
613 * the full record field name is "DP3A.AXIS.1", and the record's value
614 * is 2.
615 *
616 * int j
617 * (Given) Axis number (1-relative), i.e. the j in DPja or i in DQia.
618 *
619 * int type
620 * (Given) The data type of the record's value
621 * - 0: Integer (stored as an int),
622 * - 1: Floating point (stored as a double).
623 *
624 * union value
625 * (Given) A union comprised of
626 * - dpkey::ival,
627 * - dpkey::fval,
628 *
629 * the record's value.
630 *
631 *
632 * Global variable: const char *dis_errmsg[] - Status return messages
633 * ------------------------------------------------------------------
634 * Error messages to match the status value returned from each function.
635 *
636 *===========================================================================*/
637 
638 #ifndef WCSLIB_DIS
639 #define WCSLIB_DIS
640 
641 #ifdef __cplusplus
642 extern "C" {
643 #endif
644 
645 
646 extern const char *dis_errmsg[];
647 
649  DISERR_SUCCESS = 0, /* Success. */
650  DISERR_NULL_POINTER = 1, /* Null disprm pointer passed. */
651  DISERR_MEMORY = 2, /* Memory allocation failed. */
652  DISERR_BAD_PARAM = 3, /* Invalid parameter value. */
653  DISERR_DISTORT = 4, /* Distortion error. */
654  DISERR_DEDISTORT = 5 /* De-distortion error. */
655 };
656 
657 /* For use in declaring distortion function prototypes (= DISX2P_ARGS). */
658 #define DISP2X_ARGS const int iparm[], const double dparm[], \
659 int ncrd, const double rawcrd[], double *discrd
660 
661 /* For use in declaring de-distortion function prototypes (= DISP2X_ARGS). */
662 #define DISX2P_ARGS const int iparm[], const double dparm[], \
663 int ncrd, const double discrd[], double *rawcrd
664 
665 
666 /* Struct used for storing DPja and DQia keyvalues. */
667 struct dpkey {
668  char field[72]; /* Full record field name (no colon). */
669  int j; /* Axis number, as in DPja (1-relative). */
670  int type; /* Data type of value. */
671  union {
672  int i; /* Integer record value. */
673  double f; /* Floating point record value. */
674  } value; /* Record value. */
675 };
676 
677 /* Size of the dpkey struct in int units, used by the Fortran wrappers. */
678 #define DPLEN (sizeof(struct dpkey)/sizeof(int))
679 
680 
681 struct disprm {
682  /* Initialization flag (see the prologue above). */
683  /*------------------------------------------------------------------------*/
684  int flag; /* Set to zero to force initialization. */
685 
686  /* Parameters to be provided (see the prologue above). */
687  /*------------------------------------------------------------------------*/
688  int naxis; /* The number of pixel coordinate elements, */
689  /* given by NAXIS. */
690  char (*dtype)[72]; /* For each axis, the distortion type. */
691  int ndp; /* Number of DPja or DQia keywords, and the */
692  int ndpmax; /* number for which space was allocated. */
693  struct dpkey *dp; /* DPja or DQia keyvalues (not both). */
694  double *maxdis; /* For each axis, the maximum distortion. */
695  double totdis; /* The maximum combined distortion. */
696 
697  /* Information derived from the parameters supplied. */
698  /*------------------------------------------------------------------------*/
699  int **axmap; /* For each axis, the axis mapping array. */
700  int *Nhat; /* For each axis, the number of coordinate */
701  /* axes that form the independent variables */
702  /* of the distortion function. */
703  double **offset; /* For each axis, renormalization offsets. */
704  double **scale; /* For each axis, renormalization scales. */
705  int **iparm; /* For each axis, the array of integer */
706  /* distortion parameters. */
707  double **dparm; /* For each axis, the array of floating */
708  /* point distortion parameters. */
709  int i_naxis; /* Dimension of the internal arrays. */
710  int ndis; /* The number of distortion functions. */
711 
712  /* Error handling, if enabled. */
713  /*------------------------------------------------------------------------*/
714  struct wcserr *err;
715 
716  /* Private - the remainder are for internal use. */
717  /*------------------------------------------------------------------------*/
718  int (**disp2x)(DISP2X_ARGS); /* For each axis, pointers to the */
719  int (**disx2p)(DISX2P_ARGS); /* distortion function and its inverse. */
720 
721  double *tmpmem;
722 
723  int m_flag, m_naxis; /* The remainder are for memory management. */
724  char (*m_dtype)[72];
725  struct dpkey *m_dp;
726  double *m_maxdis;
727 };
728 
729 /* Size of the disprm struct in int units, used by the Fortran wrappers. */
730 #define DISLEN (sizeof(struct disprm)/sizeof(int))
731 
732 
733 int disndp(int n);
734 
735 int dpfill(struct dpkey *dp, const char *keyword, const char *field, int j,
736  int type, int ival, double fval);
737 
738 int disini(int alloc, int naxis, struct disprm *dis);
739 
740 int discpy(int alloc, const struct disprm *dissrc, struct disprm *disdst);
741 
742 int disfree(struct disprm *dis);
743 
744 int disprt(const struct disprm *dis);
745 
746 int disset(struct disprm *dis);
747 
748 int disp2x(struct disprm *dis, const double rawcrd[], double discrd[]);
749 
750 int disx2p(struct disprm *dis, const double discrd[], double rawcrd[]);
751 
752 int diswarp(struct disprm *dis, const double pixblc[], const double pixtrc[],
753  const double pixsamp[], int *nsamp,
754  double maxdis[], double *maxtot,
755  double avgdis[], double *avgtot,
756  double rmsdis[], double *rmstot);
757 
758 
759 /* Specialist distortion functions (internal use only). */
760 int polyset(int j, struct disprm *dis);
761 int dispoly(DISP2X_ARGS);
762 
763 int tpvset(int j, struct disprm *dis);
764 
765 int tpv1(DISP2X_ARGS);
766 int tpv2(DISP2X_ARGS);
767 int tpv3(DISP2X_ARGS);
768 int tpv4(DISP2X_ARGS);
769 int tpv5(DISP2X_ARGS);
770 int tpv6(DISP2X_ARGS);
771 int tpv7(DISP2X_ARGS);
772 
773 #ifdef __cplusplus
774 }
775 #endif
776 
777 #endif /* WCSLIB_DIS */
int type
Definition: dis.h:670
int flag
Definition: dis.h:684
Store for DPja and DQia keyvalues.
Definition: dis.h:667
int discpy(int alloc, const struct disprm *dissrc, struct disprm *disdst)
Copy routine for the disprm struct.
int ** iparm
Definition: dis.h:705
Definition: dis.h:653
const char * dis_errmsg[]
Status return messages.
int ** axmap
Definition: dis.h:699
int disp2x(struct disprm *dis, const double rawcrd[], double discrd[])
Apply distortion function.
double ** scale
Definition: dis.h:704
Error message handling.
Definition: wcserr.h:221
int disx2p(struct disprm *dis, const double discrd[], double rawcrd[])
Apply de-distortion function.
Definition: dis.h:652
int dpfill(struct dpkey *dp, const char *keyword, const char *field, int j, int type, int ival, double fval)
Fill the contents of a dpkey struct.
int disset(struct disprm *dis)
Setup routine for the disprm struct.
int naxis
Definition: dis.h:688
int tpv5(DISP2X_ARGS)
(Internal use only.)
struct dpkey * dp
Definition: dis.h:693
int tpv1(DISP2X_ARGS)
(Internal use only.)
int m_flag
Definition: dis.h:723
Definition: dis.h:654
int ndis
Definition: dis.h:710
Distortion parameters.
Definition: dis.h:681
char field[72]
Definition: dis.h:668
int tpv3(DISP2X_ARGS)
(Internal use only.)
int ndp
Definition: dis.h:691
char(* m_dtype)[72]
Definition: dis.h:724
int j
Definition: dis.h:669
Definition: dis.h:650
int * Nhat
Definition: dis.h:700
int disfree(struct disprm *dis)
Destructor for the disprm struct.
int tpv4(DISP2X_ARGS)
(Internal use only.)
dis_errmsg_enum
Definition: dis.h:648
int m_naxis
Definition: dis.h:723
int disprt(const struct disprm *dis)
Print routine for the disprm struct.
double * tmpmem
Definition: dis.h:721
int i_naxis
Definition: dis.h:709
double * maxdis
Definition: dis.h:694
double totdis
Definition: dis.h:695
int(** disx2p)(DISX2P_ARGS)
Definition: dis.h:719
Definition: dis.h:649
int tpvset(int j, struct disprm *dis)
(Internal use only.)
struct wcserr * err
Definition: dis.h:714
char(* dtype)[72]
Definition: dis.h:690
int disini(int alloc, int naxis, struct disprm *dis)
Default constructor for the disprm struct.
int tpv6(DISP2X_ARGS)
(Internal use only.)
union dpkey::@0 value
double f
Definition: dis.h:673
Definition: dis.h:651
int polyset(int j, struct disprm *dis)
int tpv2(DISP2X_ARGS)
(Internal use only.)
struct dpkey * m_dp
Definition: dis.h:725
double * m_maxdis
Definition: dis.h:726
int diswarp(struct disprm *dis, const double pixblc[], const double pixtrc[], const double pixsamp[], int *nsamp, double maxdis[], double *maxtot, double avgdis[], double *avgtot, double rmsdis[], double *rmstot)
Compute measures of distortion.
double ** offset
Definition: dis.h:703
#define DISX2P_ARGS
Definition: dis.h:662
int(** disp2x)(DISP2X_ARGS)
Definition: dis.h:718
int ndpmax
Definition: dis.h:692
int disndp(int n)
Memory allocation for DPja and DQia.
int i
Definition: dis.h:672
int dispoly(DISP2X_ARGS)
int tpv7(DISP2X_ARGS)
(Internal use only.)
#define DISP2X_ARGS
Definition: dis.h:658
double ** dparm
Definition: dis.h:707