pgSphere provides spherical data types for storing with PostgreSQL. Furthermore, there is a data type to do transformations.

A spherical point is an object without expanse
but with a position. Usage cases are:

sites on earth

star positions on the sky sphere

spherical positions on planets

A spherical point (or position) is given by two values:
longitude and latitude. Longitude is a floating point
value between `0` and
`2π`. Latitude is a floating point
value, too, but between `-π/2` and
`π/2`. It is possible to give a
spherical position in degrees (`DEG`) or
with a triple value of degrees, minutes and seconds
(`DMS`). Degrees and minutes are integer
values. The seconds are represented using a floating point
value. A fourth method is specifying a longitude value as
a triple value of hours, minutes and seconds
(`HMS`). But, you can not use it with
latitude values.

**Example 1.
A position specified using longitude and latitude in radians
**

sql> SELECT spoint '(0.1,-0.2)'; |

**Example 2.
A position specified using longitude and latitude in degrees
**

sql> SELECT spoint '( 10.1d, -90d)'; |

**Example 3.
A position specified using longitude and latitude
( DMS)
**

sql> SELECT spoint '( 10d 12m 11.3s, -13d 14m)'; |

**Example 4.
A position specified using longitude in
HMS, and latitude in
RAD
**

sql> SELECT spoint '( 23h 44m 10s, -1.4321 )'; |

As you can see you can combine the input format for longitude and latitude. The value pairs are always enclosed within braces. Spaces are optional.

A Euler transformation is done with three counterclockwise
object rotations around following the axes:

spherical object transformations

spherical coordinates transformations

The input syntax of a Euler transformation is:

angle1, angle2, angle3 [, axes ] |

where `axes`

is an optional 3 letter code
with letters : `X`, `Y`, or
`Z`. Default is `ZXZ`.
`angleN`

is any valid angle with the input
format `RAD`, `DEG`, or
`DMS`.

To do a transformation, you have to use a transformation operator (see Section 5.10).

A spherical circle is an area
around a point, where all points inside the circle have a
distance less than or equal to the radius of the circle. Usage
cases are:

sites on earth having a maximum distance from another site

round cluster or nebula on sky sphere

a position with an undirected position error

A circle is specified using a spherical point (spoint) and a radius :

< point , radius > |

Valid radius units are `RAD`,
`DEG`, and `DMS`. The
circle radius must be less than or equal to 90° and cannot
be less than zero.

A spherical line is part of a great circle (meridian) that has
a beginning and an end and hence, a direction. Usage cases are:

direct connection of two points

meteors on the sky sphere

To allow lines with a length larger than 180°, the input i syntax is a somewhat complex.

A general located line with a length
`length`

is defined as a line starting at
position `(0d,0d)` and ending at position
`(length,0d)` transformed with a Euler
transformation `euler`

. The input syntax
is :

( euler ), length |

**Note:**

For a simpler line input, use casting operators (Section 5.1) or constructor functions (Section 4).

If the length is larger than 360°, the line length is truncated to 360°.

The transformation

`euler`

will always be converted to a Euler transformation using axes`Z`,`X`, and`Z`.

Within pgSphere, ellipses are
defined as :

If the center of any spherical ellipse is the North Pole, the perpendicular projection into thex-y-plane gives an ellipse as in two-dimensional space.

Usage cases are:

cluster or nebula on the sky sphere where the `height' is lower than the `width'

to describe a position error

An ellipse always has:

a major radius

`rad_1`

a minor radius

`rad_2`

a center

`center`

a position angle

`pos`

(inclination)

Hence, the input syntax is:

< { rad_1, rad_2 }, center, pos > |

**Note:**

The radii

`rad_1`

and`rad_2`

have to be less than 90°.If

`rad_1`

is less than`rad_2`

, the values will be swapped.The position angle

`pos`

is defined within pgSphere as a counterclockwise rotation around the ellipse center and is zero, if the ellipse is “parallel to the equator”

A spherical path is a
concatination of spherical lines. Usage cases are:

rivers on earth

trajectories of planets or comets on the sky plane

Paths within pgSphere are simplified lists of positions. The input syntax is :

{pos1,pos2[,pos3[,pos4[,...]]]} |

**Note:**

The distance between 2 sequent positions has to be less than 180° and greater than zero.

At least 2 positions are required.

A spherical polygon is a
closed spherical path where line segments cannot be crossed.
One main usage case are areas on the earth and sky sphere.
Polygons within pgSphere
have the same input syntax as paths:

{pos1,pos2,pos3[,pos4[,... ]]} |

**Note:**

A spherical polygon has the same restrictions as a spherical path (see Section 3.7). Except that a polygon needs at least 3 positions.

The line segments can not be crossed.

The maximum dimension of a polygon must be less than 180°.

A spherical box is a
coordinates range. Hence, you can select objects within a
longitude range and latitude range. The box is represented
using two spherical points: the southwest
(

`pos_sw`

) and the northeast
(`pos_ne`

) edge of the box. The input
syntax is:
( pos_sw, pos_ne ) |

or

pos_sw, pos_ne |

**Note:**

If the latitude of the southwest edge is larger than the latitude of the northeast edge, pgSphere swaps the edges.

If the longitude of the southwest edge is equal to the longitude of the northeast edge, pgSphere assumes a full latitude range, except that the latitudes are equal, too.