WCSLIB 4.8.2: lin.h File Reference

# lin.h File Reference

`#include "wcserr.h"`

Go to the source code of this file.

## Data Structures
struct | linprm
| Linear transformation parameters. More...
## Defines
#define | LINLEN (sizeof(struct linprm)/sizeof(int))
| Size of the linprm struct in int units.
#define | linini_errmsg lin_errmsg
| Deprecated.
#define | lincpy_errmsg lin_errmsg
| Deprecated.
#define | linfree_errmsg lin_errmsg
| Deprecated.
#define | linprt_errmsg lin_errmsg
| Deprecated.
#define | linset_errmsg lin_errmsg
| Deprecated.
#define | linp2x_errmsg lin_errmsg
| Deprecated.
#define | linx2p_errmsg lin_errmsg
| Deprecated.
## 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.
int | lincpy (int alloc, const struct linprm *linsrc, struct linprm *lindst)
| Copy routine for the linprm struct.
int | linfree (struct linprm *lin)
| Destructor for the linprm struct.
int | linprt (const struct linprm *lin)
| Print routine for the linprm struct.
int | linset (struct linprm *lin)
| Setup routine for the linprm struct.
int | linp2x (struct linprm *lin, int ncoord, int nelem, const double pixcrd[], double imgcrd[])
| Pixel-to-world linear transformation.
int | linx2p (struct linprm *lin, int ncoord, int nelem, const double imgcrd[], double pixcrd[])
| World-to-pixel linear transformation.
int | matinv (int n, const double mat[], double inv[])
| Matrix inversion.
## Variables
const char * | lin_errmsg []
| Status return messages.

## 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.

## Define 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.