WCSLIB 8.4

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