WCSLIB  7.12
lin.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.12 - an implementation of the FITS WCS standard.
3  Copyright (C) 1995-2022, Mark Calabretta
4 
5  This file is part of WCSLIB.
6 
7  WCSLIB is free software: you can redistribute it and/or modify it under the
8  terms of the GNU Lesser General Public License as published by the Free
9  Software Foundation, either version 3 of the License, or (at your option)
10  any later version.
11 
12  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15  more details.
16 
17  You should have received a copy of the GNU Lesser General Public License
18  along with WCSLIB. If not, see http://www.gnu.org/licenses.
19 
20  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21  http://www.atnf.csiro.au/people/Mark.Calabretta
22  $Id: lin.h,v 7.12 2022/09/09 04:57:58 mcalabre Exp $
23 *=============================================================================
24 *
25 * WCSLIB 7.12 - C routines that implement the FITS World Coordinate System
26 * (WCS) standard. Refer to the README file provided with WCSLIB for an
27 * overview of the library.
28 *
29 *
30 * Summary of the lin routines
31 * ---------------------------
32 * Routines in this suite apply the linear transformation defined by the FITS
33 * World Coordinate System (WCS) standard, as described in
34 *
35 = "Representations of world coordinates in FITS",
36 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
37 *
38 * These routines are based on the linprm struct which contains all information
39 * needed for the computations. The struct contains some members that must be
40 * set by the user, and others that are maintained by these routines, somewhat
41 * like a C++ class but with no encapsulation.
42 *
43 * Six routines, linini(), lininit(), lindis(), lindist() lincpy(), and
44 * linfree() are provided to manage the linprm struct, linsize() computes its
45 * total size including allocated memory, and linprt() prints its contents.
46 *
47 * linperr() prints the error message(s) (if any) stored in a linprm struct,
48 * and the disprm structs that it may contain.
49 *
50 * A setup routine, linset(), computes intermediate values in the linprm struct
51 * from parameters in it that were supplied by the user. The struct always
52 * needs to be set up by linset() but need not be called explicitly - refer to
53 * the explanation of linprm::flag.
54 *
55 * linp2x() and linx2p() implement the WCS linear transformations.
56 *
57 * An auxiliary routine, linwarp(), computes various measures of the distortion
58 * over a specified range of pixel coordinates.
59 *
60 * An auxiliary matrix inversion routine, matinv(), is included. It uses
61 * LU-triangular factorization with scaled partial pivoting.
62 *
63 *
64 * linini() - Default constructor for the linprm struct
65 * ----------------------------------------------------
66 * linini() is a thin wrapper on lininit(). It invokes it with ndpmax set
67 * to -1 which causes it to use the value of the global variable NDPMAX. It
68 * is thereby potentially thread-unsafe if NDPMAX is altered dynamically via
69 * disndp(). Use lininit() for a thread-safe alternative in this case.
70 *
71 *
72 * lininit() - Default constructor for the linprm struct
73 * -----------------------------------------------------
74 * lininit() allocates memory for arrays in a linprm struct and sets all
75 * members of the struct to default values.
76 *
77 * PLEASE NOTE: every linprm struct must be initialized by lininit(), possibly
78 * repeatedly. On the first invokation, and only the first invokation,
79 * linprm::flag must be set to -1 to initialize memory management, regardless
80 * of whether lininit() will actually be used to allocate memory.
81 *
82 * Given:
83 * alloc int If true, allocate memory unconditionally for arrays in
84 * the linprm struct.
85 *
86 * If false, it is assumed that pointers to these arrays
87 * have been set by the user except if they are null
88 * pointers in which case memory will be allocated for
89 * them regardless. (In other words, setting alloc true
90 * saves having to initalize these pointers to zero.)
91 *
92 * naxis int The number of world coordinate axes, used to determine
93 * array sizes.
94 *
95 * Given and returned:
96 * lin struct linprm*
97 * Linear transformation parameters. Note that, in order
98 * to initialize memory management linprm::flag should be
99 * set to -1 when lin is initialized for the first time
100 * (memory leaks may result if it had already been
101 * initialized).
102 *
103 * Given:
104 * ndpmax int The number of DPja or DQia keywords to allocate space
105 * for. If set to -1, the value of the global variable
106 * NDPMAX will be used. This is potentially
107 * thread-unsafe if disndp() is being used dynamically to
108 * alter its value.
109 *
110 * Function return value:
111 * int Status return value:
112 * 0: Success.
113 * 1: Null linprm pointer passed.
114 * 2: Memory allocation failed.
115 *
116 * For returns > 1, a detailed error message is set in
117 * linprm::err if enabled, see wcserr_enable().
118 *
119 *
120 * lindis() - Assign a distortion to a linprm struct
121 * -------------------------------------------------
122 * lindis() is a thin wrapper on lindist(). It invokes it with ndpmax set
123 * to -1 which causes the value of the global variable NDPMAX to be used (by
124 * disinit()). It is thereby potentially thread-unsafe if NDPMAX is altered
125 * dynamically via disndp(). Use lindist() for a thread-safe alternative in
126 * this case.
127 *
128 *
129 * lindist() - Assign a distortion to a linprm struct
130 * --------------------------------------------------
131 * lindist() may be used to assign the address of a disprm struct to
132 * linprm::dispre or linprm::disseq. The linprm struct must already have been
133 * initialized by lininit().
134 *
135 * The disprm struct must have been allocated from the heap (e.g. using
136 * malloc(), calloc(), etc.). lindist() will immediately initialize it via a
137 * call to disini() using the value of linprm::naxis. Subsequently, it will be
138 * reinitialized by calls to lininit(), and freed by linfree(), neither of
139 * which would happen if the disprm struct was assigned directly.
140 *
141 * If the disprm struct had previously been assigned via lindist(), it will be
142 * freed before reassignment. It is also permissable for a null disprm pointer
143 * to be assigned to disable the distortion correction.
144 *
145 * Given:
146 * sequence int Is it a prior or sequent distortion?
147 * 1: Prior, the assignment is to linprm::dispre.
148 * 2: Sequent, the assignment is to linprm::disseq.
149 *
150 * Anything else is an error.
151 *
152 * Given and returned:
153 * lin struct linprm*
154 * Linear transformation parameters.
155 *
156 * dis struct disprm*
157 * Distortion function parameters.
158 *
159 * Given:
160 * ndpmax int The number of DPja or DQia keywords to allocate space
161 * for. If set to -1, the value of the global variable
162 * NDPMAX will be used. This is potentially
163 * thread-unsafe if disndp() is being used dynamically to
164 * alter its value.
165 *
166 * Function return value:
167 * int Status return value:
168 * 0: Success.
169 * 1: Null linprm pointer passed.
170 * 4: Invalid sequence.
171 *
172 *
173 * lincpy() - Copy routine for the linprm struct
174 * ---------------------------------------------
175 * lincpy() does a deep copy of one linprm struct to another, using lininit()
176 * to allocate memory for its arrays if required. Only the "information to be
177 * provided" part of the struct is copied; a call to linset() is required to
178 * initialize the remainder.
179 *
180 * Given:
181 * alloc int If true, allocate memory for the crpix, pc, and cdelt
182 * arrays in the destination. Otherwise, it is assumed
183 * that pointers to these arrays have been set by the
184 * user except if they are null pointers in which case
185 * memory will be allocated for them regardless.
186 *
187 * linsrc const struct linprm*
188 * Struct to copy from.
189 *
190 * Given and returned:
191 * lindst struct linprm*
192 * Struct to copy to. linprm::flag should be set to -1
193 * if lindst was not previously initialized (memory leaks
194 * may result if it was previously initialized).
195 *
196 * Function return value:
197 * int Status return value:
198 * 0: Success.
199 * 1: Null linprm pointer passed.
200 * 2: Memory allocation failed.
201 *
202 * For returns > 1, a detailed error message is set in
203 * linprm::err if enabled, see wcserr_enable().
204 *
205 *
206 * linfree() - Destructor for the linprm struct
207 * --------------------------------------------
208 * linfree() frees memory allocated for the linprm arrays by lininit() and/or
209 * linset(). lininit() keeps a record of the memory it allocates and linfree()
210 * will only attempt to free this.
211 *
212 * PLEASE NOTE: linfree() must not be invoked on a linprm struct that was not
213 * initialized by lininit().
214 *
215 * Given:
216 * lin struct linprm*
217 * Linear transformation parameters.
218 *
219 * Function return value:
220 * int Status return value:
221 * 0: Success.
222 * 1: Null linprm pointer passed.
223 *
224 *
225 * linsize() - Compute the size of a linprm struct
226 * -----------------------------------------------
227 * linsize() computes the full size of a linprm struct, including allocated
228 * memory.
229 *
230 * Given:
231 * lin const struct linprm*
232 * Linear transformation parameters.
233 *
234 * If NULL, the base size of the struct and the allocated
235 * size are both set to zero.
236 *
237 * Returned:
238 * sizes int[2] The first element is the base size of the struct as
239 * returned by sizeof(struct linprm).
240 *
241 * The second element is the total size of memory
242 * allocated in the struct, in bytes, assuming that the
243 * allocation was done by linini(). This figure includes
244 * memory allocated for members of constituent structs,
245 * such as linprm::dispre.
246 *
247 * It is not an error for the struct not to have been set
248 * up via linset(), which normally results in additional
249 * memory allocation.
250 *
251 * Function return value:
252 * int Status return value:
253 * 0: Success.
254 *
255 *
256 * linprt() - Print routine for the linprm struct
257 * ----------------------------------------------
258 * linprt() prints the contents of a linprm struct using wcsprintf(). Mainly
259 * intended for diagnostic purposes.
260 *
261 * Given:
262 * lin const struct linprm*
263 * Linear transformation parameters.
264 *
265 * Function return value:
266 * int Status return value:
267 * 0: Success.
268 * 1: Null linprm pointer passed.
269 *
270 *
271 * linperr() - Print error messages from a linprm struct
272 * -----------------------------------------------------
273 * linperr() prints the error message(s) (if any) stored in a linprm struct,
274 * and the disprm structs that it may contain. If there are no errors then
275 * nothing is printed. It uses wcserr_prt(), q.v.
276 *
277 * Given:
278 * lin const struct linprm*
279 * Coordinate transformation parameters.
280 *
281 * prefix const char *
282 * If non-NULL, each output line will be prefixed with
283 * this string.
284 *
285 * Function return value:
286 * int Status return value:
287 * 0: Success.
288 * 1: Null linprm pointer passed.
289 *
290 *
291 * linset() - Setup routine for the linprm struct
292 * ----------------------------------------------
293 * linset(), if necessary, allocates memory for the linprm::piximg and
294 * linprm::imgpix arrays and sets up the linprm struct according to information
295 * supplied within it - refer to the explanation of linprm::flag.
296 *
297 * Note that this routine need not be called directly; it will be invoked by
298 * linp2x() and linx2p() if the linprm::flag is anything other than a
299 * predefined magic value.
300 *
301 * Given and returned:
302 * lin struct linprm*
303 * Linear transformation parameters.
304 *
305 * Function return value:
306 * int Status return value:
307 * 0: Success.
308 * 1: Null linprm pointer passed.
309 * 2: Memory allocation failed.
310 * 3: PCi_ja matrix is singular.
311 * 4: Failed to initialise distortions.
312 *
313 * For returns > 1, a detailed error message is set in
314 * linprm::err if enabled, see wcserr_enable().
315 *
316 *
317 * linp2x() - Pixel-to-world linear transformation
318 * -----------------------------------------------
319 * linp2x() transforms pixel coordinates to intermediate world coordinates.
320 *
321 * Given and returned:
322 * lin struct linprm*
323 * Linear transformation parameters.
324 *
325 * Given:
326 * ncoord,
327 * nelem int The number of coordinates, each of vector length nelem
328 * but containing lin.naxis coordinate elements.
329 *
330 * pixcrd const double[ncoord][nelem]
331 * Array of pixel coordinates.
332 *
333 * Returned:
334 * imgcrd double[ncoord][nelem]
335 * Array of intermediate world coordinates.
336 *
337 * Function return value:
338 * int Status return value:
339 * 0: Success.
340 * 1: Null linprm pointer passed.
341 * 2: Memory allocation failed.
342 * 3: PCi_ja matrix is singular.
343 * 4: Failed to initialise distortions.
344 * 5: Distort error.
345 *
346 * For returns > 1, a detailed error message is set in
347 * linprm::err if enabled, see wcserr_enable().
348 *
349 * Notes:
350 * 1. Historically, the API to linp2x() did not have a stat[] vector because
351 * a valid linear transformation should always succeed. However, now that
352 * it invokes disp2x() if distortions are present, it does have the
353 * potential to fail. Consequently, when distortions are present and a
354 * status return (stat[]) is required for each coordinate, then linp2x()
355 * should be invoked separately for each of them.
356 *
357 *
358 * linx2p() - World-to-pixel linear transformation
359 * -----------------------------------------------
360 * linx2p() transforms intermediate world coordinates to pixel coordinates.
361 *
362 * Given and returned:
363 * lin struct linprm*
364 * Linear transformation parameters.
365 *
366 * Given:
367 * ncoord,
368 * nelem int The number of coordinates, each of vector length nelem
369 * but containing lin.naxis coordinate elements.
370 *
371 * imgcrd const double[ncoord][nelem]
372 * Array of intermediate world coordinates.
373 *
374 * Returned:
375 * pixcrd double[ncoord][nelem]
376 * Array of pixel coordinates.
377 *
378 * int Status return value:
379 * 0: Success.
380 * 1: Null linprm pointer passed.
381 * 2: Memory allocation failed.
382 * 3: PCi_ja matrix is singular.
383 * 4: Failed to initialise distortions.
384 * 6: De-distort error.
385 *
386 * For returns > 1, a detailed error message is set in
387 * linprm::err if enabled, see wcserr_enable().
388 *
389 * Notes:
390 * 1. Historically, the API to linx2p() did not have a stat[] vector because
391 * a valid linear transformation should always succeed. However, now that
392 * it invokes disx2p() if distortions are present, it does have the
393 * potential to fail. Consequently, when distortions are present and a
394 * status return (stat[]) is required for each coordinate, then linx2p()
395 * should be invoked separately for each of them.
396 *
397 *
398 * linwarp() - Compute measures of distortion
399 * ------------------------------------------
400 * linwarp() computes various measures of the distortion over a specified range
401 * of pixel coordinates.
402 *
403 * All distortion measures are specified as an offset in pixel coordinates,
404 * as given directly by prior distortions. The offset in intermediate pixel
405 * coordinates given by sequent distortions is translated back to pixel
406 * coordinates by applying the inverse of the linear transformation matrix
407 * (PCi_ja or CDi_ja). The difference may be significant if the matrix
408 * introduced a scaling.
409 *
410 * If all distortions are prior, then linwarp() uses diswarp(), q.v.
411 *
412 * Given and returned:
413 * lin struct linprm*
414 * Linear transformation parameters plus distortions.
415 *
416 * Given:
417 * pixblc const double[naxis]
418 * Start of the range of pixel coordinates (i.e. "bottom
419 * left-hand corner" in the conventional FITS image
420 * display orientation). May be specified as a NULL
421 * pointer which is interpreted as (1,1,...).
422 *
423 * pixtrc const double[naxis]
424 * End of the range of pixel coordinates (i.e. "top
425 * right-hand corner" in the conventional FITS image
426 * display orientation).
427 *
428 * pixsamp const double[naxis]
429 * If positive or zero, the increment on the particular
430 * axis, starting at pixblc[]. Zero is interpreted as a
431 * unit increment. pixsamp may also be specified as a
432 * NULL pointer which is interpreted as all zeroes, i.e.
433 * unit increments on all axes.
434 *
435 * If negative, the grid size on the particular axis (the
436 * absolute value being rounded to the nearest integer).
437 * For example, if pixsamp is (-128.0,-128.0,...) then
438 * each axis will be sampled at 128 points between
439 * pixblc[] and pixtrc[] inclusive. Use caution when
440 * using this option on non-square images.
441 *
442 * Returned:
443 * nsamp int* The number of pixel coordinates sampled.
444 *
445 * Can be specified as a NULL pointer if not required.
446 *
447 * maxdis double[naxis]
448 * For each individual distortion function, the
449 * maximum absolute value of the distortion.
450 *
451 * Can be specified as a NULL pointer if not required.
452 *
453 * maxtot double* For the combination of all distortion functions, the
454 * maximum absolute value of the distortion.
455 *
456 * Can be specified as a NULL pointer if not required.
457 *
458 * avgdis double[naxis]
459 * For each individual distortion function, the
460 * mean value of the distortion.
461 *
462 * Can be specified as a NULL pointer if not required.
463 *
464 * avgtot double* For the combination of all distortion functions, the
465 * mean value of the distortion.
466 *
467 * Can be specified as a NULL pointer if not required.
468 *
469 * rmsdis double[naxis]
470 * For each individual distortion function, the
471 * root mean square deviation of the distortion.
472 *
473 * Can be specified as a NULL pointer if not required.
474 *
475 * rmstot double* For the combination of all distortion functions, the
476 * root mean square deviation of the distortion.
477 *
478 * Can be specified as a NULL pointer if not required.
479 *
480 * Function return value:
481 * int Status return value:
482 * 0: Success.
483 * 1: Null linprm pointer passed.
484 * 2: Memory allocation failed.
485 * 3: Invalid parameter.
486 * 4: Distort error.
487 *
488 *
489 * linprm struct - Linear transformation parameters
490 * ------------------------------------------------
491 * The linprm struct contains all of the information required to perform a
492 * linear transformation. It consists of certain members that must be set by
493 * the user ("given") and others that are set by the WCSLIB routines
494 * ("returned").
495 *
496 * int flag
497 * (Given and returned) This flag must be set to zero whenever any of the
498 * following members of the linprm struct are set or modified:
499 *
500 * - linprm::naxis (q.v., not normally set by the user),
501 * - linprm::pc,
502 * - linprm::cdelt,
503 * - linprm::dispre.
504 * - linprm::disseq.
505 *
506 * This signals the initialization routine, linset(), to recompute the
507 * returned members of the linprm struct. linset() will reset flag to
508 * indicate that this has been done.
509 *
510 * PLEASE NOTE: flag should be set to -1 when lininit() is called for the
511 * first time for a particular linprm struct in order to initialize memory
512 * management. It must ONLY be used on the first initialization otherwise
513 * memory leaks may result.
514 *
515 * int naxis
516 * (Given or returned) Number of pixel and world coordinate elements.
517 *
518 * If lininit() is used to initialize the linprm struct (as would normally
519 * be the case) then it will set naxis from the value passed to it as a
520 * function argument. The user should not subsequently modify it.
521 *
522 * double *crpix
523 * (Given) Pointer to the first element of an array of double containing
524 * the coordinate reference pixel, CRPIXja.
525 *
526 * It is not necessary to reset the linprm struct (via linset()) when
527 * linprm::crpix is changed.
528 *
529 * double *pc
530 * (Given) Pointer to the first element of the PCi_ja (pixel coordinate)
531 * transformation matrix. The expected order is
532 *
533 = struct linprm lin;
534 = lin.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
535 *
536 * This may be constructed conveniently from a 2-D array via
537 *
538 = double m[2][2] = {{PC1_1, PC1_2},
539 = {PC2_1, PC2_2}};
540 *
541 * which is equivalent to
542 *
543 = double m[2][2];
544 = m[0][0] = PC1_1;
545 = m[0][1] = PC1_2;
546 = m[1][0] = PC2_1;
547 = m[1][1] = PC2_2;
548 *
549 * The storage order for this 2-D array is the same as for the 1-D array,
550 * whence
551 *
552 = lin.pc = *m;
553 *
554 * would be legitimate.
555 *
556 * double *cdelt
557 * (Given) Pointer to the first element of an array of double containing
558 * the coordinate increments, CDELTia.
559 *
560 * struct disprm *dispre
561 * (Given) Pointer to a disprm struct holding parameters for prior
562 * distortion functions, or a null (0x0) pointer if there are none.
563 *
564 * Function lindist() may be used to assign a disprm pointer to a linprm
565 * struct, allowing it to take control of any memory allocated for it, as
566 * in the following example:
567 *
568 = void add_distortion(struct linprm *lin)
569 = {
570 = struct disprm *dispre;
571 =
572 = dispre = malloc(sizeof(struct disprm));
573 = dispre->flag = -1;
574 = lindist(1, lin, dispre, ndpmax);
575 = :
576 = (Set up dispre.)
577 = :
578 =
579 = return;
580 = }
581 *
582 * Here, after the distortion function parameters etc. are copied into
583 * dispre, dispre is assigned using lindist() which takes control of the
584 * allocated memory. It will be freed later when linfree() is invoked on
585 * the linprm struct.
586 *
587 * Consider also the following erroneous code:
588 *
589 = void bad_code(struct linprm *lin)
590 = {
591 = struct disprm dispre;
592 =
593 = dispre.flag = -1;
594 = lindist(1, lin, &dispre, ndpmax); // WRONG.
595 = :
596 =
597 = return;
598 = }
599 *
600 * Here, dispre is declared as a struct, rather than a pointer. When the
601 * function returns, dispre will go out of scope and its memory will most
602 * likely be reused, thereby trashing its contents. Later, a segfault will
603 * occur when linfree() tries to free dispre's stale address.
604 *
605 * struct disprm *disseq
606 * (Given) Pointer to a disprm struct holding parameters for sequent
607 * distortion functions, or a null (0x0) pointer if there are none.
608 *
609 * Refer to the comments and examples given for disprm::dispre.
610 *
611 * double *piximg
612 * (Returned) Pointer to the first element of the matrix containing the
613 * product of the CDELTia diagonal matrix and the PCi_ja matrix.
614 *
615 * double *imgpix
616 * (Returned) Pointer to the first element of the inverse of the
617 * linprm::piximg matrix.
618 *
619 * int i_naxis
620 * (Returned) The dimension of linprm::piximg and linprm::imgpix (normally
621 * equal to naxis).
622 *
623 * int unity
624 * (Returned) True if the linear transformation matrix is unity.
625 *
626 * int affine
627 * (Returned) True if there are no distortions.
628 *
629 * int simple
630 * (Returned) True if unity and no distortions.
631 *
632 * struct wcserr *err
633 * (Returned) If enabled, when an error status is returned, this struct
634 * contains detailed information about the error, see wcserr_enable().
635 *
636 * double *tmpcrd
637 * (For internal use only.)
638 * int m_flag
639 * (For internal use only.)
640 * int m_naxis
641 * (For internal use only.)
642 * double *m_crpix
643 * (For internal use only.)
644 * double *m_pc
645 * (For internal use only.)
646 * double *m_cdelt
647 * (For internal use only.)
648 * struct disprm *m_dispre
649 * (For internal use only.)
650 * struct disprm *m_disseq
651 * (For internal use only.)
652 *
653 *
654 * Global variable: const char *lin_errmsg[] - Status return messages
655 * ------------------------------------------------------------------
656 * Error messages to match the status value returned from each function.
657 *
658 *===========================================================================*/
659 
660 #ifndef WCSLIB_LIN
661 #define WCSLIB_LIN
662 
663 #ifdef __cplusplus
664 extern "C" {
665 #endif
666 
667 
668 extern const char *lin_errmsg[];
669 
671  LINERR_SUCCESS = 0, // Success.
672  LINERR_NULL_POINTER = 1, // Null linprm pointer passed.
673  LINERR_MEMORY = 2, // Memory allocation failed.
674  LINERR_SINGULAR_MTX = 3, // PCi_ja matrix is singular.
675  LINERR_DISTORT_INIT = 4, // Failed to initialise distortions.
676  LINERR_DISTORT = 5, // Distort error.
677  LINERR_DEDISTORT = 6 // De-distort error.
678 };
679 
680 struct linprm {
681  // Initialization flag (see the prologue above).
682  //--------------------------------------------------------------------------
683  int flag; // Set to zero to force initialization.
684 
685  // Parameters to be provided (see the prologue above).
686  //--------------------------------------------------------------------------
687  int naxis; // The number of axes, given by NAXIS.
688  double *crpix; // CRPIXja keywords for each pixel axis.
689  double *pc; // PCi_ja linear transformation matrix.
690  double *cdelt; // CDELTia keywords for each coord axis.
691  struct disprm *dispre; // Prior distortion parameters, if any.
692  struct disprm *disseq; // Sequent distortion parameters, if any.
693 
694  // Information derived from the parameters supplied.
695  //--------------------------------------------------------------------------
696  double *piximg; // Product of CDELTia and PCi_ja matrices.
697  double *imgpix; // Inverse of the piximg matrix.
698  int i_naxis; // Dimension of piximg and imgpix.
699  int unity; // True if the PCi_ja matrix is unity.
700  int affine; // True if there are no distortions.
701  int simple; // True if unity and no distortions.
702 
703  // Error handling, if enabled.
704  //--------------------------------------------------------------------------
705  struct wcserr *err;
706 
707  // Private - the remainder are for internal use.
708  //--------------------------------------------------------------------------
709  double *tmpcrd;
710 
712  double *m_crpix, *m_pc, *m_cdelt;
714 };
715 
716 // Size of the linprm struct in int units, used by the Fortran wrappers.
717 #define LINLEN (sizeof(struct linprm)/sizeof(int))
718 
719 
720 int linini(int alloc, int naxis, struct linprm *lin);
721 
722 int lininit(int alloc, int naxis, struct linprm *lin, int ndpmax);
723 
724 int lindis(int sequence, struct linprm *lin, struct disprm *dis);
725 
726 int lindist(int sequence, struct linprm *lin, struct disprm *dis, int ndpmax);
727 
728 int lincpy(int alloc, const struct linprm *linsrc, struct linprm *lindst);
729 
730 int linfree(struct linprm *lin);
731 
732 int linsize(const struct linprm *lin, int sizes[2]);
733 
734 int linprt(const struct linprm *lin);
735 
736 int linperr(const struct linprm *lin, const char *prefix);
737 
738 int linset(struct linprm *lin);
739 
740 int linp2x(struct linprm *lin, int ncoord, int nelem, const double pixcrd[],
741  double imgcrd[]);
742 
743 int linx2p(struct linprm *lin, int ncoord, int nelem, const double imgcrd[],
744  double pixcrd[]);
745 
746 int linwarp(struct linprm *lin, const double pixblc[], const double pixtrc[],
747  const double pixsamp[], int *nsamp,
748  double maxdis[], double *maxtot,
749  double avgdis[], double *avgtot,
750  double rmsdis[], double *rmstot);
751 
752 int matinv(int n, const double mat[], double inv[]);
753 
754 
755 // Deprecated.
756 #define linini_errmsg lin_errmsg
757 #define lincpy_errmsg lin_errmsg
758 #define linfree_errmsg lin_errmsg
759 #define linprt_errmsg lin_errmsg
760 #define linset_errmsg lin_errmsg
761 #define linp2x_errmsg lin_errmsg
762 #define linx2p_errmsg lin_errmsg
763 
764 #ifdef __cplusplus
765 }
766 #endif
767 
768 #endif // WCSLIB_LIN
int linwarp(struct linprm *lin, 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.
int linsize(const struct linprm *lin, int sizes[2])
Compute the size of a linprm struct.
int linx2p(struct linprm *lin, int ncoord, int nelem, const double imgcrd[], double pixcrd[])
World-to-pixel linear transformation.
int linset(struct linprm *lin)
Setup routine for the linprm struct.
lin_errmsg_enum
Definition: lin.h:670
@ LINERR_SUCCESS
Definition: lin.h:671
@ LINERR_MEMORY
Definition: lin.h:673
@ LINERR_DEDISTORT
Definition: lin.h:677
@ LINERR_DISTORT
Definition: lin.h:676
@ LINERR_NULL_POINTER
Definition: lin.h:672
@ LINERR_DISTORT_INIT
Definition: lin.h:675
@ LINERR_SINGULAR_MTX
Definition: lin.h:674
int linperr(const struct linprm *lin, const char *prefix)
Print error messages from a linprm struct.
const char * lin_errmsg[]
Status return messages.
int linini(int alloc, int naxis, struct linprm *lin)
Default constructor for the linprm struct.
int linprt(const struct linprm *lin)
Print routine for the linprm struct.
int lincpy(int alloc, const struct linprm *linsrc, struct linprm *lindst)
Copy routine for the linprm struct.
int matinv(int n, const double mat[], double inv[])
Matrix inversion.
int lindist(int sequence, struct linprm *lin, struct disprm *dis, int ndpmax)
Assign a distortion to a linprm struct.
int lindis(int sequence, struct linprm *lin, struct disprm *dis)
Assign a distortion to a linprm struct.
int linp2x(struct linprm *lin, int ncoord, int nelem, const double pixcrd[], double imgcrd[])
Pixel-to-world linear transformation.
int linfree(struct linprm *lin)
Destructor for the linprm struct.
int lininit(int alloc, int naxis, struct linprm *lin, int ndpmax)
Default constructor for the linprm struct.
Distortion parameters.
Definition: dis.h:1093
int naxis
Definition: dis.h:1100
int ndpmax
Definition: dis.h:1104
double * maxdis
Definition: dis.h:1106
Linear transformation parameters.
Definition: lin.h:680
double * m_crpix
Definition: lin.h:712
double * cdelt
Definition: lin.h:690
double * imgpix
Definition: lin.h:697
struct wcserr * err
Definition: lin.h:705
struct disprm * disseq
Definition: lin.h:692
double * crpix
Definition: lin.h:688
int affine
Definition: lin.h:700
double * pc
Definition: lin.h:689
int i_naxis
Definition: lin.h:698
double * m_cdelt
Definition: lin.h:712
int flag
Definition: lin.h:683
int m_flag
Definition: lin.h:711
double * m_pc
Definition: lin.h:712
struct disprm * dispre
Definition: lin.h:691
struct disprm * m_disseq
Definition: lin.h:713
struct disprm * m_dispre
Definition: lin.h:713
double * tmpcrd
Definition: lin.h:709
int naxis
Definition: lin.h:687
double * piximg
Definition: lin.h:696
int m_naxis
Definition: lin.h:711
int unity
Definition: lin.h:699
int simple
Definition: lin.h:701
Error message handling.
Definition: wcserr.h:243