CoordinateTransform

Files
file	psCoord.h
	Contains basic coordinate transformation definitions and operations.
file	psSphereOps.h
	Contains spherical rotation and offset operations.
Data Structures
struct	psPlane
	Euclidiean Coordinate System. More...
struct	psSphere
	Angular Coordinate System. More...
struct	psCube
	3-Dimensional Euclidean Coordinate System More...
struct	psPlaneTransform
	2D Polynomial Transform More...
struct	psPlaneDistort
	4D Polynomial Transform More...
struct	psProjection
	Parameter set for projection/deprojection. More...
struct	psSphereRot
	Spherical Rotation Definition. More...
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.
psCube *	psCubeAlloc (void)
	Allocates a psCube.
psPlaneTransform *	psPlaneTransformAlloc (int n1, int 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 (int n1, int n2, int n3, int n4)
	Allocates a psPlaneDistort transform.
psPlane *	psPlaneDistortApply (psPlane *out, const psPlaneDistort *distort, const psPlane *coords, float mag, float color)
	Applies the psPlaneDistort transform to a specified coordinate.
psProjection *	psProjectionAlloc (double R, double D, double Xs, double Ys, psProjectionType type)
	Allocates memory for a psProjection structure.
bool	psMemCheckPlane (psPtr ptr)
	Checks the type of a particular pointer.
bool	psMemCheckSphere (psPtr ptr)
	Checks the type of a particular pointer.
bool	psMemCheckCube (psPtr ptr)
	Checks the type of a particular pointer.
bool	psMemCheckPlaneTransform (psPtr ptr)
	Checks the type of a particular pointer.
bool	psMemCheckPlaneDistort (psPtr ptr)
	Checks the type of a particular pointer.
bool	psMemCheckProjection (psPtr ptr)
	Checks the type of a particular pointer.
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.
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.
psSphere *	psCubeToSphere (const psCube *cube)
	Converts from a 3-dimensional coordinate system to an angular coordinate system.
psCube *	psSphereToCube (const psSphere *sphere)
	Converts from an angular coordinate system to a 3-dimensional coordinate system.
psPlane *	psPlaneTransformDeriv (psPlane *out, const psPlaneTransform *transformation, const psPlane *coord)
	Calculates the derivative of the specified psPlaneTransform with respect to x and y.
psSphereRot *	psSphereRotAlloc (double alphaP, double deltaP, double phiP)
	Allocator for psSphereRot.
bool	psMemCheckSphereRot (psPtr ptr)
	Checks the type of a particular pointer.
psSphereRot *	psSphereRotQuat (double q0, double q1, double q2, double q3)
	Allocator for psSphereRot given quaternions.
psSphere *	psSphereRotApply (psSphere *out, const psSphereRot *transform, const psSphere *coord)
	Applies the psSphereTransform transform for a specified coordinate.
psSphereRot *	psSphereRotCombine (psSphereRot *out, const psSphereRot *rot1, const psSphereRot *rot2)
	Combines two rotations.
psSphereRot *	psSphereRotInvert (psSphereRot *rot)
	Inverts the rotation.
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.
psSphereRot *	psSphereRotICRSToEcliptic (const psTime *time)
	Creates the appropriate transform for converting from ICRS to Ecliptic coordinate systems.
psSphereRot *	psSphereRotEclipticToICRS (const psTime *time)
	Creates the appropriate transform for converting from Ecliptic to ICRS coordinate systems.
psSphereRot *	psSphereRotICRSToGalactic (void)
	Creates the appropriate transform for converting from ICRS to Galactic coordinate systems.
psSphereRot *	psSphereRotGalacticToICRS (void)
	Creates the appropriate transform for converting from Galactic to ICRS coordinate systems.
psSphere *	psSpherePrecess (psSphere *coords, const psTime *fromTime, const psTime *toTime)
	Generates the complete spherical rotation to account for precession between two times.

---

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 46 of file psSphereOps.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 56 of file psSphereOps.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

psCube* psCubeAlloc (  void   )

Allocates a psCube. Returns: psCube* resulting cubic structure.

psSphere * psCubeToSphere (  const psCube *  cube  )

Converts from a 3-dimensional coordinate system to an angular coordinate system. Returns: psSphere* The former psCube in terms of a psSphere. Parameters: cube  psCube to convert

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

bool psMemCheckCube (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psCube structure, false otherwise. Parameters: ptr  the pointer whose type to check

bool psMemCheckPlane (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psPlane structure, false otherwise. Parameters: ptr  the pointer whose type to check

bool psMemCheckPlaneDistort (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psPlaneDistort structure, false otherwise. Parameters: ptr  the pointer whose type to check

bool psMemCheckPlaneTransform (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psPlaneTransform structure, false otherwise. Parameters: ptr  the pointer whose type to check

bool psMemCheckProjection (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psProjection structure, false otherwise. Parameters: ptr  the pointer whose type to check

bool psMemCheckSphere (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psSphere structure, false otherwise. Parameters: ptr  the pointer whose type to check

bool psMemCheckSphereRot (  psPtr  ptr  )

Checks the type of a particular pointer. Uses the appropriate deallocation function in psMemBlock to check the ptr datatype. Returns: bool: True if the pointer matches a psSphereRot structure, false otherwise. Parameters: ptr  the pointer whose type to check

psPlane* psPlaneAlloc (  void   )

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

psPlaneDistort* psPlaneDistortAlloc (  int  n1, int  n2, int  n3, int  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 *  distort, const psPlane *  coords, float  mag, float  color )

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. distort  the transform to apply coords  the coordinate to apply the transform above. mag  third term -- maybe magnitude color  forth term -- maybe color

psPlaneTransform* psPlaneTransformAlloc (  int  n1, int  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)

psPlane* psPlaneTransformDeriv (  psPlane *  out, const psPlaneTransform *  transformation, const psPlane *  coord )

Calculates the derivative of the specified psPlaneTransform with respect to x and y. Returns: psPlane* The derivative.

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. Parameters: trans  desired order, polynomial type, & polynomial mask terms source  coordinates matching those in dest dest  coordinates matching those in source nRejIter  number of rejection iterations to be performed sigmaClip  coordinates above this number of standard deviations will be rejected

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 (  double  R, double  D, double  Xs, double  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

psSphereRot* psSphereRotAlloc (  double  alphaP, double  deltaP, double  phiP )

Allocator for psSphereRot. Returns: psSphereRot* newly allocated psSphereRot 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* psSphereRotApply (  psSphere *  out, const psSphereRot *  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

psSphereRot* psSphereRotCombine (  psSphereRot *  out, const psSphereRot *  rot1, const psSphereRot *  rot2 )

Combines two rotations. Combines two rotations to produce a single rotation which is the equivalent of applying the first rotation and then the second. The output rotation may be supplied, or will be allocated if NULL. Returns: psSphereRot* New psSphereRot that is the combination of the input psSphereRots Parameters: out  a psSphereRot to recycle or NULL rot1  first rotation to combine rot2  second rotation to combine

psSphereRot* psSphereRotEclipticToICRS (  const 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

psSphereRot* psSphereRotGalacticToICRS (  void   )

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

psSphereRot* psSphereRotICRSToEcliptic (  const 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

psSphereRot* psSphereRotICRSToGalactic (  void   )

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

psSphereRot* psSphereRotInvert (  psSphereRot *  rot  )

Inverts the rotation. Returns: psSphereRot* Inverted input psSphereRot

psSphereRot* psSphereRotQuat (  double  q0, double  q1, double  q2, double  q3 )

Allocator for psSphereRot given quaternions. Normalizes a given quaternion and returns the cooresponding newly allocated psSphereRot object. Returns: psSphereRot* newly allocated psSphereRot Parameters: q0  q0 q1  q1 q2  q2 q3  q3

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

psCube * psSphereToCube (  const psSphere *  sphere  )

Converts from an angular coordinate system to a 3-dimensional coordinate system. Returns: psCube* The former psSphere in terms of a psCube. Parameters: sphere  psSphere to convert

---