Coordinate Functions
[Astronomy Functions]

Collaboration diagram for Coordinate Functions:

Files
file	psCoord.h
	Contains basic coordinate transformation definitions and operations.
Data Structures
struct	psPlane
	Euclidiean Coordinate System. More...
struct	psSphere
	Angular Coordinate System. More...
struct	psPlaneTransform
	2D Polynomial Transform More...
struct	psPlaneDistort
	4D Polynomial Transform More...
struct	psSphereTransform
	Spherical Transform Definition. More...
struct	psProjection
	Parameter set for projection/deprojection. More...
Typedefs
typedef psSphere	psSphere
	Angular Coordinate System.
Enumerations
enum	psProjectionType { PS_PROJ_TAN, PS_PROJ_SIN, PS_PROJ_AIT, PS_PROJ_PAR, PS_PROJ_NTYPE }
	Projection type for projection/deprojection. More...
enum	psSphereOffsetMode { PS_SPHERICAL, PS_LINEAR }
	Mode for Offset calculation between two sky positions. More...
enum	psSphereOffsetUnit { PS_ARCSEC, PS_ARCMIN, PS_DEGREE, PS_RADIAN }
	The units of the offset. More...
Functions
psPlane *	psPlaneAlloc (void)
	Allocates a psPlane.
psSphere *	psSphereAlloc (void)
	Allocates a psSphere.
psPlaneTransform *	psPlaneTransformAlloc (psS32 n1, psS32 n2)
	Allocates a psPlaneTransform transform.
psPlane *	psPlaneTransformApply (psPlane *out, const psPlaneTransform *transform, const psPlane *coords)
	Applies the psPlaneTransform transform to a specified coordinate.
psPlaneDistort *	psPlaneDistortAlloc (psS32 n1, psS32 n2, psS32 n3, psS32 n4)
	Allocates a psPlaneDistort transform.
psPlane *	psPlaneDistortApply (psPlane *out, const psPlaneDistort *transform, const psPlane *coords, float term3, float term4)
	Applies the psPlaneDistort transform to a specified coordinate.
psSphereTransform *	psSphereTransformAlloc (double alphaP, double deltaP, double phiP)
	Allocator for psSphereTransform.
psSphere *	psSphereTransformApply (psSphere *out, const psSphereTransform *transform, const psSphere *coord)
	Applies the psSphereTransform transform for a specified coordinate.
psSphereTransform *	psSphereTransformICRSToEcliptic (psTime *time)
	Creates the appropriate transform for converting from ICRS to Ecliptic coordinate systems.
psSphereTransform *	psSphereTransformEclipticToICRS (psTime *time)
	Creates the appropriate transform for converting from Ecliptic to ICRS coordinate systems.
psSphereTransform *	psSphereTransformICRSToGalactic (void)
	Creates the appropriate transform for converting from ICRS to Galactic coordinate systems.
psSphereTransform *	psSphereTransformGalacticToICRS (void)
	Creates the appropriate transform for converting from Galactic to ICRS coordinate systems.
psProjection *	psProjectionAlloc (psF64 R, psF64 D, psF64 Xs, psF64 Ys, psProjectionType type)
	Allocates memory for a psProjection structure.
psPlane *	psProject (const psSphere *coord, const psProjection *projection)
	Projects a spherical coordinate to a linear coordinate system.
psSphere *	psDeproject (const psPlane *coord, const psProjection *projection)
	Reverse projection of a linear coordinate to a spherical coordinate system.
psSphere *	psSphereGetOffset (const psSphere *position1, const psSphere *position2, psSphereOffsetMode mode, psSphereOffsetUnit unit)
	Determines the offset (RA,Dec) on the sky between two positions.
psSphere *	psSphereSetOffset (const psSphere *position, const psSphere *offset, psSphereOffsetMode mode, psSphereOffsetUnit unit)
	Applies the given offset to a coordinate.
psSphere *	psSpherePrecess (psSphere *coords, const psTime *fromTime, const psTime *toTime)
	Generates the complete spherical rotation to account for precession between two times.
psPlaneTransform *	p_psPlaneTransformLinearInvert (psPlaneTransform *transform)
	Takes a given transform and inverts it linearly if possible.
psS32	p_psIsProjectionLinear (psPlaneTransform *transform)
	Takes a transform and tests whether or not it is a linear projection.
psPlaneTransform *	psPlaneTransformInvert (psPlaneTransform *out, const psPlaneTransform *in, psRegion region, int nSamples)
	inverts a given transformation.
psPlaneTransform *	psPlaneTransformCombine (psPlaneTransform *out, const psPlaneTransform *trans1, const psPlaneTransform *trans2, psRegion region, int nSamples)
	Creates a single transformation that has the effect of performing trans1 followed by trans2.
bool	psPlaneTransformFit (psPlaneTransform *trans, const psArray *source, const psArray *dest, int nRejIter, float sigmaClip)
	takes two arrays containing matched coordinates and returns the best-fitting transformation.

---

Typedef Documentation

typedef struct psSphere psSphere

Angular Coordinate System. Both detector and sky positions will be used extensively in the IPP. One coordinate system to be used is angular coordinates for which additional care must often be taken in comparison to a euclidiean coordinate system.

---

Enumeration Type Documentation

enum psProjectionType

Projection type for projection/deprojection. See also: psProject, psDeproject Enumeration values: PS_PROJ_TAN  Tangent projection. PS_PROJ_SIN  Sine projection. PS_PROJ_AIT  Aitoff projection. PS_PROJ_PAR  Par projection. PS_PROJ_NTYPE  Number of types; must be last. Definition at line 121 of file psCoord.h.

enum psSphereOffsetMode

Mode for Offset calculation between two sky positions. See also: psSphereGetOffset, psSphereSetOffset Enumeration values: PS_SPHERICAL  offset corresponds to an angular offset PS_LINEAR  offset corresponds to a linear offset Definition at line 152 of file psCoord.h.

enum psSphereOffsetUnit

The units of the offset. See also: psSphereGetOffset, psSphereSetOffset Enumeration values: PS_ARCSEC  Arcseconds. PS_ARCMIN  Arcminutes. PS_DEGREE  Degrees. PS_RADIAN  Radians. Definition at line 162 of file psCoord.h.

---

Function Documentation

psS32 p_psIsProjectionLinear (  psPlaneTransform *  transform  )

Takes a transform and tests whether or not it is a linear projection. Returns: psS32 the order of the projection Parameters: transform  transform to test for linearity

psPlaneTransform* p_psPlaneTransformLinearInvert (  psPlaneTransform *  transform  )

Takes a given transform and inverts it linearly if possible. Returns: psPlaneTransform the linearly inverted transform Parameters: transform  transform to invert

psSphere* psDeproject (  const psPlane *  coord, const psProjection *  projection )

Reverse projection of a linear coordinate to a spherical coordinate system. Returns: psPlane* projected coordinate Parameters: coord  coordinate to project projection  parameters of the projection

psPlane* psPlaneAlloc (  void   )

Allocates a psPlane. Returns: psPlane* resulting plane structure.

psPlaneDistort* psPlaneDistortAlloc (  psS32  n1, psS32  n2, psS32  n3, psS32  n4 )

Allocates a psPlaneDistort transform. Returns: psPlaneDistort* resulting plane distort transform Parameters: n1  The order of the w term in the transform. n2  The order of the x term in the transform. n3  The order of the y term in the transform. n4  The order of the z term in the transform.

psPlane* psPlaneDistortApply (  psPlane *  out, const psPlaneDistort *  transform, const psPlane *  coords, float  term3, float  term4 )

Applies the psPlaneDistort transform to a specified coordinate. Returns: psPlane* resulting coordinate based on transform Parameters: out  a psPlane to recycle. If NULL, a new one is generated. transform  the transform to apply coords  the coordinate to apply the transform above. term3  third term -- maybe magnitude term4  forth term -- maybe color

psPlaneTransform* psPlaneTransformAlloc (  psS32  n1, psS32  n2 )

Allocates a psPlaneTransform transform. Returns: psPlaneTransform* resulting plane transform Parameters: n1  The order of the x term in the transform. n2  The order of the y term in the transform.

psPlane* psPlaneTransformApply (  psPlane *  out, const psPlaneTransform *  transform, const psPlane *  coords )

Applies the psPlaneTransform transform to a specified coordinate. Returns: psPlane* resulting coordinate based on transform Parameters: out  a psPlane to recycle. If NULL, a new one is generated. transform  the transform to apply coords  the coordinate to apply the transform above.

psPlaneTransform* psPlaneTransformCombine (  psPlaneTransform *  out, const psPlaneTransform *  trans1, const psPlaneTransform *  trans2, psRegion  region, int  nSamples )

Creates a single transformation that has the effect of performing trans1 followed by trans2. psPlaneTransformCombine takes two transformations (trans1 and trans2) and returns a single transformation that has the effect of performing trans1 followed by trans2. In the event that the input transformation is linear, an exact solution may be calculated; otherwise nSamples samples in each axis, covering the region specified by region shall be used as a grid to fit the best inverse transformation. The function shall return NULL if it was unable to generate the transformation; otherwise it shall return the transformation. Returns: psPlaneTransform* resulting transformation Parameters: out  a transform to recycle, or NULL if one is to be created. trans1  first transform to combine trans2  first transform to combine region  region to cover (for non-linear transforms) nSamples  number of samples on each axis (for non-linear transforms)

bool psPlaneTransformFit (  psPlaneTransform *  trans, const psArray *  source, const psArray *  dest, int  nRejIter, float  sigmaClip )

takes two arrays containing matched coordinates and returns the best-fitting transformation. psPlaneTransformFit takes two arrays containing matched coordinates (i.e., coordinates in the source array correspond to the coordinates in the dest array) and returns the best-fitting transformation. The source and dest will contain psCoords. In the event that the number of coordinates in each is not identical, the function shall generate a warning, and extra coordinates in the longer of the two shall be ignored. The trans transform may not be NULL, since it specifies the desired order, polynomial type and any polynomial terms to mask. nRejIter rejection iterations shall be performed, wherein coordinates lying more than sigmaClip standard deviations from the fit shall be rejected. Returns: bool TRUE if successful, otherwise FALSE.

psPlaneTransform* psPlaneTransformInvert (  psPlaneTransform *  out, const psPlaneTransform *  in, psRegion  region, int  nSamples )

inverts a given transformation. It may assume that the input transformation is one-to-one, and that the inverse transformation may be specified through using polynomials of the same type and order as the forward transformation. In the event that the input transformation is linear, an exact solution may be calculated; otherwise nSamples samples in each axis, covering the region specified by region shall be used as a grid to fit the best inverse transformation. The function shall return NULL if it was unable to generate the inverse transformation; otherwise it shall return the inverse transformation. In the event that out is NULL, a new psPlaneTransform shall be allocated and returned. Returns: psPlaneTransform* the resulting inverted transform Parameters: out  a transform to recycle, or NULL if one is to be created. in  transform to invert region  region to fit for non-linear transform inversion nSamples  number of samples in each axis for fit

psPlane* psProject (  const psSphere *  coord, const psProjection *  projection )

Projects a spherical coordinate to a linear coordinate system. Returns: psPlane* projected coordinate Parameters: coord  coordinate to project projection  parameters of the projection

psProjection* psProjectionAlloc (  psF64  R, psF64  D, psF64  Xs, psF64  Ys, psProjectionType  type )

Allocates memory for a psProjection structure. Returns: psProjection* psProjection structure Parameters: R  Right-ascension of projection center. D  Declination of projection center. Xs  Scale in x-dimension Ys  Scale in y-dimension

psSphere* psSphereAlloc (  void   )

Allocates a psSphere. Returns: psSphere* resulting sphere structure.

psSphere* psSphereGetOffset (  const psSphere *  position1, const psSphere *  position2, psSphereOffsetMode  mode, psSphereOffsetUnit  unit )

Determines the offset (RA,Dec) on the sky between two positions. Both an offset mode and an offset unit may be defined. The mode may be either PS_SPHERICAL, in which case the specified offset corresponds to an offset in angles, or it may be PS_LINEAR, in which case the offset corresponds to a linear offset in a local projection. The offset unit may be in one of PS_ARCSEC, PS_ARCMIN, PS_DEGREE, and PS_RADIAN, which specifies the units of the offset only. Returns: psSphere* the offset between position1 and position2 Parameters: position1  first position for calculating offset position2  second position for calculating offset mode  type of offset can be PS_SPHERICAL or PS_LINEAR unit  specifies the units of offset only

psSphere* psSpherePrecess (  psSphere *  coords, const psTime *  fromTime, const psTime *  toTime )

Generates the complete spherical rotation to account for precession between two times. The equinoxes shall be Julian equinoxes. Returns: psSphere* the resulting spherical rotation Parameters: coords  coordinates (modified in-place) fromTime  equinox of coords input toTime  equinox of coords output

psSphere* psSphereSetOffset (  const psSphere *  position, const psSphere *  offset, psSphereOffsetMode  mode, psSphereOffsetUnit  unit )

Applies the given offset to a coordinate. Both an offset mode and an offset unit may be defined. The mode may be either PS_SPHERICAL, in which case the specified offset corresponds to an offset in angles, or it may be PS_LINEAR, in which case the offset corresponds to a linear offset in a local projection. The offset unit may be in one of PS_ARCSEC, PS_ARCMIN, PS_DEGREE, and PS_RADIAN, which specifies the units of the offset only. Returns: psSphere* the original position with the given offset applied. Parameters: position  coordinate of origin offset  coordinate of offset to apply mode  corresponds to an offset in angles or local projection unit  specifies the units of offset only

psSphereTransform* psSphereTransformAlloc (  double  alphaP, double  deltaP, double  phiP )

Allocator for psSphereTransform. Returns: psSphereTransform* newly allocated struct Parameters: alphaP  north pole latitude deltaP  north pole longitude? phiP  defines the longitude in the input system of the equatorial intersection between the two systems (e.g, the first point of Ares).

psSphere* psSphereTransformApply (  psSphere *  out, const psSphereTransform *  transform, const psSphere *  coord )

Applies the psSphereTransform transform for a specified coordinate. Returns: psSphere* resulting coordinate based on transform Parameters: out  a psSphere to recycle. If NULL, a new one is generated. transform  the transform to apply coord  the coordinate to apply the transform above.x

psSphereTransform* psSphereTransformEclipticToICRS (  psTime *  time  )

Creates the appropriate transform for converting from Ecliptic to ICRS coordinate systems. Returns: psSphereTransform* transform for Ecliptic->ICRS coordinate systems Parameters: time  the time for which the resulting transform will be valid

psSphereTransform* psSphereTransformGalacticToICRS (  void   )

Creates the appropriate transform for converting from Galactic to ICRS coordinate systems.

psSphereTransform* psSphereTransformICRSToEcliptic (  psTime *  time  )

Creates the appropriate transform for converting from ICRS to Ecliptic coordinate systems. Returns: psSphereTransform* transform for ICRS->Ecliptic coordinate systems Parameters: time  the time for which the resulting transform will be valid

psSphereTransform* psSphereTransformICRSToGalactic (  void   )

Creates the appropriate transform for converting from ICRS to Galactic coordinate systems.

---