WCSLIB: linprm Struct Reference

WCSLIB 8.9

Loading...
Searching...
No Matches
Data Fields
linprm Struct Reference

Linear transformation parameters. More...

`#include <lin.h>`

## Data Fields
int | flag
int | naxis
double * | crpix
double * | pc
double * | cdelt
struct disprm * | dispre
struct disprm * | disseq
double * | piximg
double * | imgpix
int | i_naxis
int | unity
int | affine
int | simple
struct wcserr * | err
double * | dummy
int | m_flag
int | m_naxis
double * | m_crpix
double * | m_pc
double * | m_cdelt
struct disprm * | m_dispre
struct disprm * | m_disseq

## Detailed Description

Linear transformation parameters.

The linprm struct contains all of the information required to perform a linear transformation. It consists of certain members that must be set by the user (given) and others that are set by the WCSLIB routines (returned).

## Field Documentation

## ◆ flag

int linprm::flag

(Given and returned) This flag must be set to zero (or 1, see linset()) whenever any of the following linprm members are set or changed:

- linprm::naxis (q.v., not normally set by the user),
- linprm::pc,
- linprm::cdelt,
- linprm::dispre.
- linprm::disseq.

This signals the initialization routine, linset(), to recompute the returned members of the linprm struct. linset() will reset flag to indicate that this has been done.

PLEASE NOTE: flag should be set to -1 when lininit() is called for the first time for a particular linprm struct in order to initialize memory management. It must ONLY be used on the first initialization otherwise memory leaks may result.

## ◆ naxis

int linprm::naxis

(Given or returned) Number of pixel and world coordinate elements.

If lininit() is used to initialize the linprm struct (as would normally be the case) then it will set naxis from the value passed to it as a function argument. The user should not subsequently modify it.

## ◆ crpix

double* linprm::crpix

(Given) Pointer to the first element of an array of double containing the coordinate reference pixel, CRPIXja.

It is not necessary to reset the linprm struct (via linset()) when linprm::crpix is changed.

## ◆ pc

double* linprm::pc

(Given) Pointer to the first element of the PCi_ja (pixel coordinate) transformation matrix. The expected order is

struct linprm lin;
lin.pc = {PC1_1, PC1_2, PC2_1, PC2_2};
linprm
Linear transformation parameters.
Definition lin.h:719
linprm::pc
double * pc
Definition lin.h:728

This may be constructed conveniently from a 2-D array via

double m[2][2] = {{PC1_1, PC1_2},
{PC2_1, PC2_2}};

which is equivalent to

double m[2][2];
m[0][0] = PC1_1;
m[0][1] = PC1_2;
m[1][0] = PC2_1;
m[1][1] = PC2_2;

The storage order for this 2-D array is the same as for the 1-D array, whence

lin.pc = *m;

would be legitimate.

## ◆ cdelt

double* linprm::cdelt

(Given) Pointer to the first element of an array of double containing the coordinate increments, CDELTia.

## ◆ dispre

struct disprm* linprm::dispre

(Given) Pointer to a disprm struct holding parameters for prior distortion functions, or a null (0x0) pointer if there are none.

Function lindist() may be used to assign a disprm pointer to a linprm struct, allowing it to take control of any memory allocated for it, as in the following example:

void add_distortion(struct linprm *lin)
{
struct disprm *dispre;
dispre = malloc(sizeof(struct disprm));
dispre->flag = -1;
lindist(1, lin, dispre, ndpmax);
:
(Set up dispre.)
:
return;
}
lindist
int lindist(int sequence, struct linprm *lin, struct disprm *dis, int ndpmax)
Assign a distortion to a linprm struct.
disprm
Distortion parameters.
Definition dis.h:1129
linprm::dispre
struct disprm * dispre
Definition lin.h:730

Here, after the distortion function parameters etc. are copied into dispre, dispre is assigned using lindist() which takes control of the allocated memory. It will be freed later when linfree() is invoked on the linprm struct.

Consider also the following erroneous code:

void bad_code(struct linprm *lin)
{
struct disprm dispre;
dispre.flag = -1;
lindist(1, lin, &dispre, ndpmax); // WRONG.
:
return;
}

Here, dispre is declared as a struct, rather than a pointer. When the function returns, dispre will go out of scope and its memory will most likely be reused, thereby trashing its contents. Later, a segfault will occur when linfree() tries to free dispre's stale address.

## ◆ disseq

struct disprm* linprm::disseq

(Given) Pointer to a disprm struct holding parameters for sequent distortion functions, or a null (0x0) pointer if there are none.

Refer to the comments and examples given for disprm::dispre.

## ◆ piximg

double* linprm::piximg

(Returned) Pointer to the first element of the matrix containing the product of the CDELTia diagonal matrix and the PCi_ja matrix.

## ◆ imgpix

double* linprm::imgpix

(Returned) Pointer to the first element of the inverse of the linprm::piximg matrix.

## ◆ i_naxis

int linprm::i_naxis

(Returned) The dimension of linprm::piximg and linprm::imgpix (normally equal to naxis).

## ◆ unity

int linprm::unity

(Returned) True if the linear transformation matrix is unity.

## ◆ affine

int linprm::affine

(Returned) True if there are no distortions.

## ◆ simple

int linprm::simple

(Returned) True if unity and no distortions.

## ◆ err

struct wcserr* linprm::err

(Returned) If enabled, when an error status is returned, this struct contains detailed information about the error, see wcserr_enable().

## ◆ dummy

double* linprm::dummy

(For internal use only.)

## ◆ m_flag

int linprm::m_flag

(For internal use only.)

## ◆ m_naxis

int linprm::m_naxis

(For internal use only.)

## ◆ m_crpix

double* linprm::m_crpix

(For internal use only.)

## ◆ m_pc

double * linprm::m_pc

(For internal use only.)

## ◆ m_cdelt

double * linprm::m_cdelt

(For internal use only.)

## ◆ m_dispre

struct disprm* linprm::m_dispre

(For internal use only.)

## ◆ m_disseq

struct disprm * linprm::m_disseq

(For internal use only.)