#### 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).

#### Synopsis

AstSphMap ∗astSphMap( const char ∗options, ... )

#### Parameters:

##### options

Pointer to a null-terminated 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 astSet function and may include `"` printf`"` format specifiers identified by `"` %`"` symbols in the normal way.

##### ...

If the `"` options`"` string contains `"` %`"` format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C `"` printf`"` function).

#### Returned Value

##### astSphMap()

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 the AST error status set, 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`"` .
Copyright (C) 2021 East Asian Observatory