next up previous 264
Next: AST_STCCATALOGENTRYLOCATION - Create a StcCatalogEntryLocation
Up: AST Routine Descriptions
Previous: AST_SPECMAP - Create a SpecMap


AST_SPHMAP - Create a SphMap

Description:
This function creates a new SphMap and optionally initialises its attributes.

A SphMap is a Mapping which transforms points from a 3-dimensional Cartesian coordinate system into a 2-dimensional spherical coordinate system (longitude and latitude on a unit sphere centred at the origin). It works by regarding the input coordinates as position vectors and finding their intersection with the sphere surface. The inverse transformation always produces points which are a unit distance from the origin (i.e. unit vectors).

Invocation:
RESULT = AST_SPHMAP( OPTIONS, STATUS )
Arguments:
OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new SphMap. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_SPHMAP = INTEGER
A pointer to the new SphMap.
Notes:
  • The spherical coordinates are longitude (positive anti-clockwise looking from the positive latitude pole) and latitude. The Cartesian coordinates are right-handed, with the x axis (axis 1) at zero longitude and latitude, and the z axis (axis 3) at the positive latitude pole.

  • At either pole, the longitude is set to the value of the PolarLong attribute.

  • If the Cartesian coordinates are all zero, then the longitude and latitude are set to the value AST__BAD.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".


next up previous 264
Next: AST_STCCATALOGENTRYLOCATION - Create a StcCatalogEntryLocation
Up: AST Routine Descriptions
Previous: AST_SPECMAP - Create a SpecMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council