WCSLIB: lin.h Source File

WCSLIB 4.25.1

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

lin.h
Go to the documentation of this file.
1 /*============================================================================
2
3 WCSLIB 4.25 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2015, Mark Calabretta
5
6 This file is part of WCSLIB.
7
8 WCSLIB is free software: you can redistribute it and/or modify it under the
9 terms of the GNU Lesser General Public License as published by the Free
10 Software Foundation, either version 3 of the License, or (at your option)
11 any later version.
12
13 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16 more details.
17
18 You should have received a copy of the GNU Lesser General Public License
19 along with WCSLIB. If not, see http://www.gnu.org/licenses.
20
21 Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22
23 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24 http://www.atnf.csiro.au/people/Mark.Calabretta
25 $Id: lin.h,v 4.25.1.2 2015/01/06 01:01:06 mcalabre Exp mcalabre $
26 *=============================================================================
27 *
28 * WCSLIB 4.25 - C routines that implement the FITS World Coordinate System
29 * (WCS) standard. Refer to
30 *
31 * "Representations of world coordinates in FITS",
32 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
33 *
34 * Refer to the README file provided with WCSLIB for an overview of the
35 * library.
36 *
37 *
38 * Summary of the lin routines
39 * ---------------------------
40 * These routines apply the linear transformation defined by the FITS WCS
41 * standard. They are based on the linprm struct which contains all
42 * information needed for the computations. The struct contains some members
43 * that must be set by the user, and others that are maintained by these
44 * routines, somewhat like a C++ class but with no encapsulation.
45 *
46 * Three routines, linini(), lincpy(), and linfree() are provided to manage the
47 * linprm struct, and another, linprt(), prints its contents.
48 *
49 * A setup routine, linset(), computes intermediate values in the linprm struct
50 * from parameters in it that were supplied by the user. The struct always
51 * needs to be set up by linset() but need not be called explicitly - refer to
52 * the explanation of linprm::flag.
53 *
54 * linp2x() and linx2p() implement the WCS linear transformations.
55 *
56 * An auxiliary matrix inversion routine, matinv(), is included. It uses
57 * LU-triangular factorization with scaled partial pivoting.
58 *
59 *
60 * linini() - Default constructor for the linprm struct
61 * ----------------------------------------------------
62 * linini() allocates memory for arrays in a linprm struct and sets all members
63 * of the struct to default values.
64 *
65 * PLEASE NOTE: every linprm struct should be initialized by linini(), possibly
66 * repeatedly. On the first invokation, and only the first invokation,
67 * linprm::flag must be set to -1 to initialize memory management, regardless
68 * of whether linini() will actually be used to allocate memory.
69 *
70 * Given:
71 * alloc int If true, allocate memory unconditionally for arrays in
72 * the linprm struct.
73 *
74 * If false, it is assumed that pointers to these arrays
75 * have been set by the user except if they are null
76 * pointers in which case memory will be allocated for
77 * them regardless. (In other words, setting alloc true
78 * saves having to initalize these pointers to zero.)
79 *
80 * naxis int The number of world coordinate axes, used to determine
81 * array sizes.
82 *
83 * Given and returned:
84 * lin struct linprm*
85 * Linear transformation parameters. Note that, in order
86 * to initialize memory management linprm::flag should be
87 * set to -1 when lin is initialized for the first time
88 * (memory leaks may result if it had already been
89 * initialized).
90 *
91 * Function return value:
92 * int Status return value:
93 * 0: Success.
94 * 1: Null linprm pointer passed.
95 * 2: Memory allocation failed.
96 *
97 * For returns > 1, a detailed error message is set in
98 * linprm::err if enabled, see wcserr_enable().
99 *
100 *
101 * lincpy() - Copy routine for the linprm struct
102 * ---------------------------------------------
103 * lincpy() does a deep copy of one linprm struct to another, using linini() to
104 * allocate memory for its arrays if required. Only the "information to be
105 * provided" part of the struct is copied; a call to linset() is required to
106 * initialize the remainder.
107 *
108 * Given:
109 * alloc int If true, allocate memory for the crpix, pc, and cdelt
110 * arrays in the destination. Otherwise, it is assumed
111 * that pointers to these arrays have been set by the
112 * user except if they are null pointers in which case
113 * memory will be allocated for them regardless.
114 *
115 * linsrc const struct linprm*
116 * Struct to copy from.
117 *
118 * Given and returned:
119 * lindst struct linprm*
120 * Struct to copy to. linprm::flag should be set to -1
121 * if lindst was not previously initialized (memory leaks
122 * may result if it was previously initialized).
123 *
124 * Function return value:
125 * int Status return value:
126 * 0: Success.
127 * 1: Null linprm pointer passed.
128 * 2: Memory allocation failed.
129 *
130 * For returns > 1, a detailed error message is set in
131 * linprm::err if enabled, see wcserr_enable().
132 *
133 *
134 * linfree() - Destructor for the linprm struct
135 * --------------------------------------------
136 * linfree() frees memory allocated for the linprm arrays by linini() and/or
137 * linset(). linini() keeps a record of the memory it allocates and linfree()
138 * will only attempt to free this.
139 *
140 * PLEASE NOTE: linfree() must not be invoked on a linprm struct that was not
141 * initialized by linini().
142 *
143 * Given:
144 * lin struct linprm*
145 * Linear transformation parameters.
146 *
147 * Function return value:
148 * int Status return value:
149 * 0: Success.
150 * 1: Null linprm pointer passed.
151 *
152 *
153 * linprt() - Print routine for the linprm struct
154 * ----------------------------------------------
155 * linprt() prints the contents of a linprm struct using wcsprintf(). Mainly
156 * intended for diagnostic purposes.
157 *
158 * Given:
159 * lin const struct linprm*
160 * Linear transformation parameters.
161 *
162 * Function return value:
163 * int Status return value:
164 * 0: Success.
165 * 1: Null linprm pointer passed.
166 *
167 *
168 * linset() - Setup routine for the linprm struct
169 * ----------------------------------------------
170 * linset(), if necessary, allocates memory for the linprm::piximg and
171 * linprm::imgpix arrays and sets up the linprm struct according to information
172 * supplied within it - refer to the explanation of linprm::flag.
173 *
174 * Note that this routine need not be called directly; it will be invoked by
175 * linp2x() and linx2p() if the linprm::flag is anything other than a
176 * predefined magic value.
177 *
178 * Given and returned:
179 * lin struct linprm*
180 * Linear transformation parameters.
181 *
182 * Function return value:
183 * int Status return value:
184 * 0: Success.
185 * 1: Null linprm pointer passed.
186 * 2: Memory allocation failed.
187 * 3: PCi_ja matrix is singular.
188 *
189 * For returns > 1, a detailed error message is set in
190 * linprm::err if enabled, see wcserr_enable().
191 *
192 *
193 * linp2x() - Pixel-to-world linear transformation
194 * -----------------------------------------------
195 * linp2x() transforms pixel coordinates to intermediate world coordinates.
196 *
197 * Given and returned:
198 * lin struct linprm*
199 * Linear transformation parameters.
200 *
201 * Given:
202 * ncoord,
203 * nelem int The number of coordinates, each of vector length nelem
204 * but containing lin.naxis coordinate elements.
205 *
206 * pixcrd const double[ncoord][nelem]
207 * Array of pixel coordinates.
208 *
209 * Returned:
210 * imgcrd double[ncoord][nelem]
211 * Array of intermediate world coordinates.
212 *
213 * Function return value:
214 * int Status return value:
215 * 0: Success.
216 * 1: Null linprm pointer passed.
217 * 2: Memory allocation failed.
218 * 3: PCi_ja matrix is singular.
219 *
220 * For returns > 1, a detailed error message is set in
221 * linprm::err if enabled, see wcserr_enable().
222 *
223 *
224 * linx2p() - World-to-pixel linear transformation
225 * -----------------------------------------------
226 * linx2p() transforms intermediate world coordinates to pixel coordinates.
227 *
228 * Given and returned:
229 * lin struct linprm*
230 * Linear transformation parameters.
231 *
232 * Given:
233 * ncoord,
234 * nelem int The number of coordinates, each of vector length nelem
235 * but containing lin.naxis coordinate elements.
236 *
237 * imgcrd const double[ncoord][nelem]
238 * Array of intermediate world coordinates.
239 *
240 * Returned:
241 * pixcrd double[ncoord][nelem]
242 * Array of pixel coordinates.
243 *
244 * int Status return value:
245 * 0: Success.
246 * 1: Null linprm pointer passed.
247 * 2: Memory allocation failed.
248 * 3: PCi_ja matrix is singular.
249 *
250 * For returns > 1, a detailed error message is set in
251 * linprm::err if enabled, see wcserr_enable().
252 *
253 *
254 * linprm struct - Linear transformation parameters
255 * ------------------------------------------------
256 * The linprm struct contains all of the information required to perform a
257 * linear transformation. It consists of certain members that must be set by
258 * the user ("given") and others that are set by the WCSLIB routines
259 * ("returned").
260 *
261 * int flag
262 * (Given and returned) This flag must be set to zero whenever any of the
263 * following members of the linprm struct are set or modified:
264 *
265 * - linprm::naxis (q.v., not normally set by the user),
266 * - linprm::pc,
267 * - linprm::cdelt.
268 *
269 * This signals the initialization routine, linset(), to recompute the
270 * returned members of the linprm struct. linset() will reset flag to
271 * indicate that this has been done.
272 *
273 * PLEASE NOTE: flag should be set to -1 when linini() is called for the
274 * first time for a particular linprm struct in order to initialize memory
275 * management. It must ONLY be used on the first initialization otherwise
276 * memory leaks may result.
277 *
278 * int naxis
279 * (Given or returned) Number of pixel and world coordinate elements.
280 *
281 * If linini() is used to initialize the linprm struct (as would normally
282 * be the case) then it will set naxis from the value passed to it as a
283 * function argument. The user should not subsequently modify it.
284 *
285 * double *crpix
286 * (Given) Pointer to the first element of an array of double containing
287 * the coordinate reference pixel, CRPIXja.
288 *
289 * double *pc
290 * (Given) Pointer to the first element of the PCi_ja (pixel coordinate)
291 * transformation matrix. The expected order is
292 *
293 = struct linprm lin;
294 = lin.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
295 *
296 * This may be constructed conveniently from a 2-D array via
297 *
298 = double m[2][2] = {{PC1_1, PC1_2},
299 = {PC2_1, PC2_2}};
300 *
301 * which is equivalent to
302 *
303 = double m[2][2];
304 = m[0][0] = PC1_1;
305 = m[0][1] = PC1_2;
306 = m[1][0] = PC2_1;
307 = m[1][1] = PC2_2;
308 *
309 * The storage order for this 2-D array is the same as for the 1-D array,
310 * whence
311 *
312 = lin.pc = *m;
313 *
314 * would be legitimate.
315 *
316 * double *cdelt
317 * (Given) Pointer to the first element of an array of double containing
318 * the coordinate increments, CDELTia.
319 *
320 * int unity
321 * (Returned) True if the linear transformation matrix is unity.
322 *
323 * int padding
324 * (An unused variable inserted for alignment purposes only.)
325 *
326 * double *piximg
327 * (Returned) Pointer to the first element of the matrix containing the
328 * product of the CDELTia diagonal matrix and the PCi_ja matrix.
329 *
330 * double *imgpix
331 * (Returned) Pointer to the first element of the inverse of the
332 * linprm::piximg matrix.
333 *
334 * struct wcserr *err
335 * (Returned) If enabled, when an error status is returned this struct
336 * contains detailed information about the error, see wcserr_enable().
337 *
338 * int i_naxis
339 * (For internal use only.)
340 * int m_flag
341 * (For internal use only.)
342 * int m_naxis
343 * (For internal use only.)
344 * int m_padding
345 * (For internal use only.)
346 * double *m_crpix
347 * (For internal use only.)
348 * double *m_pc
349 * (For internal use only.)
350 * double *m_cdelt
351 * (For internal use only.)
352 * void *padding2
353 * (For internal use only.)
354 *
355 *
356 * Global variable: const char *lin_errmsg[] - Status return messages
357 * ------------------------------------------------------------------
358 * Error messages to match the status value returned from each function.
359 *
360 *===========================================================================*/
361
362 #ifndef WCSLIB_LIN
363 #define WCSLIB_LIN
364
365 #include "wcserr.h"
366
367 #ifdef __cplusplus
368 extern "C" {
369 #endif
370
371
372 extern const char *lin_errmsg[];
373
374 enum lin_errmsg_enum {
375 LINERR_SUCCESS = 0, /* Success. */
376 LINERR_NULL_POINTER = 1, /* Null linprm pointer passed. */
377 LINERR_MEMORY = 2, /* Memory allocation failed. */
378 LINERR_SINGULAR_MTX = 3 /* PCi_ja matrix is singular. */
379 };
380
381 struct linprm {
382 /* Initialization flag (see the prologue above). */
383 /*------------------------------------------------------------------------*/
384 int flag; /* Set to zero to force initialization. */
385
386 /* Parameters to be provided (see the prologue above). */
387 /*------------------------------------------------------------------------*/
388 int naxis; /* The number of axes, given by NAXIS. */
389 double *crpix; /* CRPIXja keywords for each pixel axis. */
390 double *pc; /* PCi_ja linear transformation matrix. */
391 double *cdelt; /* CDELTia keywords for each coord axis. */
392
393 /* Information derived from the parameters supplied. */
394 /*------------------------------------------------------------------------*/
395 double *piximg; /* Product of CDELTia and PCi_ja matrices. */
396 double *imgpix; /* Inverse of the piximg matrix. */
397 int unity; /* True if the PCi_ja matrix is unity. */
398
399 /* Error handling */
400 /*------------------------------------------------------------------------*/
401 int padding; /* (Dummy inserted for alignment purposes.) */
402 struct wcserr *err;
403
404 /* Private - the remainder are for memory management. */
405 /*------------------------------------------------------------------------*/
406 int i_naxis;
407 int m_flag, m_naxis, m_padding;
408 double *m_crpix, *m_pc, *m_cdelt;
409 void *padding2;
410 };
411
412 /* Size of the linprm struct in int units, used by the Fortran wrappers. */
413 #define LINLEN (sizeof(struct linprm)/sizeof(int))
414
415
416 int linini(int alloc, int naxis, struct linprm *lin);
417
418 int lincpy(int alloc, const struct linprm *linsrc, struct linprm *lindst);
419
420 int linfree(struct linprm *lin);
421
422 int linprt(const struct linprm *lin);
423
424 int linset(struct linprm *lin);
425
426 int linp2x(struct linprm *lin, int ncoord, int nelem, const double pixcrd[],
427 double imgcrd[]);
428
429 int linx2p(struct linprm *lin, int ncoord, int nelem, const double imgcrd[],
430 double pixcrd[]);
431
432 int matinv(int n, const double mat[], double inv[]);
433
434
435 /* Deprecated. */
436 #define linini_errmsg lin_errmsg
437 #define lincpy_errmsg lin_errmsg
438 #define linfree_errmsg lin_errmsg
439 #define linprt_errmsg lin_errmsg
440 #define linset_errmsg lin_errmsg
441 #define linp2x_errmsg lin_errmsg
442 #define linx2p_errmsg lin_errmsg
443
444 #ifdef __cplusplus
445 }
446 #endif
447
448 #endif /* WCSLIB_LIN */
linprm::m_pc
double * m_pc
Definition: lin.h:408
linp2x
int linp2x(struct linprm *lin, int ncoord, int nelem, const double pixcrd[], double imgcrd[])
Pixel-to-world linear transformation.
linprm::naxis
int naxis
Definition: lin.h:388
linprm::crpix
double * crpix
Definition: lin.h:389
LINERR_MEMORY
Definition: lin.h:377
linprm::m_flag
int m_flag
Definition: lin.h:407
linprm::unity
int unity
Definition: lin.h:397
wcserr
Error message handling.
Definition: wcserr.h:221
linprm::m_naxis
int m_naxis
Definition: lin.h:407
linprm::padding2
void * padding2
Definition: lin.h:409
linprm::err
struct wcserr * err
Definition: lin.h:402
matinv
int matinv(int n, const double mat[], double inv[])
Matrix inversion.
linprm::padding
int padding
Definition: lin.h:401
linprm
Linear transformation parameters.
Definition: lin.h:381
lin_errmsg
const char * lin_errmsg[]
Status return messages.
linprm::piximg
double * piximg
Definition: lin.h:395
linprm::m_padding
int m_padding
Definition: lin.h:407
linprm::i_naxis
int i_naxis
Definition: lin.h:406
linprm::m_crpix
double * m_crpix
Definition: lin.h:408
linfree
int linfree(struct linprm *lin)
Destructor for the linprm struct.
linset
int linset(struct linprm *lin)
Setup routine for the linprm struct.
LINERR_SUCCESS
Definition: lin.h:375
linini
int linini(int alloc, int naxis, struct linprm *lin)
Default constructor for the linprm struct.
linprm::cdelt
double * cdelt
Definition: lin.h:391
lin_errmsg_enum
lin_errmsg_enum
Definition: lin.h:374
linprm::flag
int flag
Definition: lin.h:384
lincpy
int lincpy(int alloc, const struct linprm *linsrc, struct linprm *lindst)
Copy routine for the linprm struct.
linprm::pc
double * pc
Definition: lin.h:390
linx2p
int linx2p(struct linprm *lin, int ncoord, int nelem, const double imgcrd[], double pixcrd[])
World-to-pixel linear transformation.
wcserr.h
linprm::imgpix
double * imgpix
Definition: lin.h:396
linprm::m_cdelt
double * m_cdelt
Definition: lin.h:408
LINERR_SINGULAR_MTX
Definition: lin.h:378
linprt
int linprt(const struct linprm *lin)
Print routine for the linprm struct.
LINERR_NULL_POINTER
Definition: lin.h:376