### 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 $\ast$ ( $\ast$ ) (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 $\ast$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 $\ast$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 $\ast$status" .