lin.h File Reference

#include "wcserr.h"

Go to the source code of this file.

Data Structures
struct	linprm
	Linear transformation parameters. More...

Macros
#define	LINLEN   (sizeof(struct linprm)/sizeof(int))
	Size of the linprm struct in int units. More...
#define	linini_errmsg   lin_errmsg
	Deprecated. More...
#define	lincpy_errmsg   lin_errmsg
	Deprecated. More...
#define	linfree_errmsg   lin_errmsg
	Deprecated. More...
#define	linprt_errmsg   lin_errmsg
	Deprecated. More...
#define	linset_errmsg   lin_errmsg
	Deprecated. More...
#define	linp2x_errmsg   lin_errmsg
	Deprecated. More...
#define	linx2p_errmsg   lin_errmsg
	Deprecated. More...

Enumerations
enum	lin_errmsg_enum { LINERR_SUCCESS = 0, LINERR_NULL_POINTER = 1, LINERR_MEMORY = 2, LINERR_SINGULAR_MTX = 3 }

Functions
int	linini (int alloc, int naxis, struct linprm *lin)
	Default constructor for the linprm struct. More...
int	lincpy (int alloc, const struct linprm *linsrc, struct linprm *lindst)
	Copy routine for the linprm struct. More...
int	linfree (struct linprm *lin)
	Destructor for the linprm struct. More...
int	linprt (const struct linprm *lin)
	Print routine for the linprm struct. More...
int	linset (struct linprm *lin)
	Setup routine for the linprm struct. More...
int	linp2x (struct linprm *lin, int ncoord, int nelem, const double pixcrd[], double imgcrd[])
	Pixel-to-world linear transformation. More...
int	linx2p (struct linprm *lin, int ncoord, int nelem, const double imgcrd[], double pixcrd[])
	World-to-pixel linear transformation. More...
int	matinv (int n, const double mat[], double inv[])
	Matrix inversion. More...

Variables
const char *	lin_errmsg []
	Status return messages. More...

Detailed Description

These routines apply the linear transformation defined by the FITS WCS standard. They are based on the linprm struct which contains all information needed for the computations. The struct contains some members that must be set by the user, and others that are maintained by these routines, somewhat like a C++ class but with no encapsulation.

Three routines, linini(), lincpy(), and linfree() are provided to manage the linprm struct, and another, linprt(), prints its contents.

A setup routine, linset(), computes intermediate values in the linprm struct from parameters in it that were supplied by the user. The struct always needs to be set up by linset() but need not be called explicitly - refer to the explanation of linprm::flag.

linp2x() and linx2p() implement the WCS linear transformations.

An auxiliary matrix inversion routine, matinv(), is included. It uses LU-triangular factorization with scaled partial pivoting.

Macro Definition Documentation

#define LINLEN   (sizeof(struct linprm)/sizeof(int))

Size of the linprm struct in int units, used by the Fortran wrappers.

#define linini_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

#define lincpy_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

#define linfree_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

#define linprt_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

#define linset_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

#define linp2x_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

#define linx2p_errmsg   lin_errmsg

Deprecated:

Added for backwards compatibility, use lin_errmsg directly now instead.

Enumeration Type Documentation

enum lin_errmsg_enum

Enumerator
LINERR_SUCCESS
LINERR_NULL_POINTER
LINERR_MEMORY
LINERR_SINGULAR_MTX

Function Documentation

int linini	(	int	alloc,
		int	naxis,
		struct linprm *	lin
	)

linini() allocates memory for arrays in a linprm struct and sets all members of the struct to default values.

PLEASE NOTE: every linprm struct should be initialized by linini(), possibly repeatedly. On the first invokation, and only the first invokation, linprm::flag must be set to -1 to initialize memory management, regardless of whether linini() will actually be used to allocate memory.

Parameters

[in]	alloc	If true, allocate memory unconditionally for arrays in the linprm struct. If false, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless. (In other words, setting alloc true saves having to initalize these pointers to zero.)
[in]	naxis	The number of world coordinate axes, used to determine array sizes.
[in,out]	lin	Linear transformation parameters. Note that, in order to initialize memory management linprm::flag should be set to -1 when lin is initialized for the first time (memory leaks may result if it had already been initialized).

Returns

Status return value:

• 0: Success.
• 1: Null linprm pointer passed.
• 2: Memory allocation failed.

For returns > 1, a detailed error message is set in linprm::err if enabled, see wcserr_enable().

int lincpy	(	int	alloc,
		const struct linprm *	linsrc,
		struct linprm *	lindst
	)

lincpy() does a deep copy of one linprm struct to another, using linini() to allocate memory for its arrays if required. Only the "information to be provided" part of the struct is copied; a call to linset() is required to initialize the remainder.

Parameters

[in]	alloc	If true, allocate memory for the crpix, pc, and cdelt arrays in the destination. Otherwise, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless.
[in]	linsrc	Struct to copy from.
[in,out]	lindst	Struct to copy to. linprm::flag should be set to -1 if lindst was not previously initialized (memory leaks may result if it was previously initialized).

Returns

Status return value:

• 0: Success.
• 1: Null linprm pointer passed.
• 2: Memory allocation failed.

For returns > 1, a detailed error message is set in linprm::err if enabled, see wcserr_enable().

int linfree

(

struct linprm *

lin)

linfree() frees memory allocated for the linprm arrays by linini() and/or linset(). linini() keeps a record of the memory it allocates and linfree() will only attempt to free this.

PLEASE NOTE: linfree() must not be invoked on a linprm struct that was not initialized by linini().

Parameters

[in]

lin

Linear transformation parameters.

Returns

Status return value:

• 0: Success.
• 1: Null linprm pointer passed.

int linprt

(

const struct linprm *

lin)

linprt() prints the contents of a linprm struct using wcsprintf(). Mainly intended for diagnostic purposes.

Parameters

[in]

lin

Linear transformation parameters.

Returns

Status return value:

• 0: Success.
• 1: Null linprm pointer passed.

int linset

(

struct linprm *

lin)

linset(), if necessary, allocates memory for the linprm::piximg and linprm::imgpix arrays and sets up the linprm struct according to information supplied within it - refer to the explanation of linprm::flag.

Note that this routine need not be called directly; it will be invoked by linp2x() and linx2p() if the linprm::flag is anything other than a predefined magic value.

Parameters

[in,out]

lin

Linear transformation parameters.

Returns

Status return value:

• 0: Success.
• 1: Null linprm pointer passed.
• 2: Memory allocation failed.
• 3: PCi_ja matrix is singular.

For returns > 1, a detailed error message is set in linprm::err if enabled, see wcserr_enable().

int linp2x	(	struct linprm *	lin,
		int	ncoord,
		int	nelem,
		const double	pixcrd[],
		double	imgcrd[]
	)

linp2x() transforms pixel coordinates to intermediate world coordinates.

Parameters

[in,out]	lin	Linear transformation parameters.
[in]	ncoord,nelem	The number of coordinates, each of vector length nelem but containing lin.naxis coordinate elements.
[in]	pixcrd	Array of pixel coordinates.
[out]	imgcrd	Array of intermediate world coordinates.

Returns

Status return value:

• 0: Success.
• 1: Null linprm pointer passed.
• 2: Memory allocation failed.
• 3: PCi_ja matrix is singular.

For returns > 1, a detailed error message is set in linprm::err if enabled, see wcserr_enable().

int linx2p	(	struct linprm *	lin,
		int	ncoord,
		int	nelem,
		const double	imgcrd[],
		double	pixcrd[]
	)

linx2p() transforms intermediate world coordinates to pixel coordinates.

Parameters

[in,out]	lin	Linear transformation parameters.
[in]	ncoord,nelem	The number of coordinates, each of vector length nelem but containing lin.naxis coordinate elements.
[in]	imgcrd	Array of intermediate world coordinates.
[out]	pixcrd	Array of pixel coordinates. Status return value: 0: Success. 1: Null linprm pointer passed. 2: Memory allocation failed. 3: PCi_ja matrix is singular. For returns > 1, a detailed error message is set in linprm::err if enabled, see wcserr_enable().

matinv	(	int	n,
		const double	mat[],
		double	inv[]
	)

matinv() performs matrix inversion using LU-triangular factorization with scaled partial pivoting.

Parameters

[in]	n	Order of the matrix ( ).
[in]	mat	Matrix to be inverted, stored as mat[ ] where and are the row and column indices respectively.
[out]	inv	Inverse of mat with the same storage convention.

Returns

Status return value:

• 0: Success.
• 2: Memory allocation failed.
• 3: Singular matrix.

Variable Documentation

const char * lin_errmsg[]

Error messages to match the status value returned from each function.