# Data Types

## Overview

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

## Data types

`SQL` type name | spherical type
`spoint` | point (position)
`strans` | Euler transformation
`scircle` | circle
`sline` | line
`sellipse` | ellipse
`spoly` | polygon
`spath` | path
`sbox` | coordinate range
`smoc` | HEALPix Multi-Order Coverage map

## Point

A spherical point is an object without expanse but with a position. Use 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&pg_pgr;`. Latitude is a floating point value, too, but between `-&pg_pgr;/2` and `&pg_pgr;/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.

### A position specified using longitude and latitude in radians

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

### A position specified using longitude and latitude in degrees

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

### A position specified using longitude and latitude (`DMS`)

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

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

## Euler transformation

An Euler transformation is done with three counterclockwise object rotations around following the axes: `x`-axis, `y`-axis, or `z`-axis. Use cases are:

- spherical object transformations

- spherical coordinates transformations

The input syntax of an 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 op.trans).

### Create a transformation object

Create a transformation object to rotate a spherical object counterclockwise, first 20° around the `x`-axis, second -270° around the `z`-axis and last 70.5° around the `y`-axis.

    sql> SELECT strans '20d, -270d, 70.5d, XZY';

### Create a second transformation object

Create a transformation object to rotate a spherical object counterclockwise, first 2° 20' around the `z`-axis, second 10° around the `x`-axis, and last 0° around the `z`-axis.

    sql> SELECT strans '2d 20m, 10d, 0';

## Circle

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. Use 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 circle around the North Pole with a radius of 5°.

    sql> SELECT scircle '< (0d, 90d), 5d >';

## Line

A spherical line is part of a great circle (meridian) that has a beginning and an end and hence, a direction. Use 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 an Euler transformation `euler`. The input syntax is :

    ( euler ), length

- For a simpler line input, use casting operators (op.casting) or constructor functions (construct).

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

- The transformation `euler` will always be converted to an Euler transformation using axes `Z`, `X`, and `Z`.

### A line input

A line starting at position `(200d,+20d)` and ending at position `(200d,-10d)`.

    sql> SELECT sline '( -90d, -20d, 200d, XYZ ), 30d ';

## Ellipses

Within pgSphere, ellipses are defined as :

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

Use 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 >

- 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”

### Input of a spherical ellipse

An ellipse has a center at 20° longitude and 0° latitude. The minor radius is part of the equator. The major radius is 10°, the minor radius is 5°.

    sql> SELECT sellipse '< { 10d, 5d } , ( 20d, 0d ), 90d >';

## Path

A spherical path is a concatenation of spherical lines. Use 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[,...]]]}

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

- At least 2 positions are required.

### Path input example

A path going from `(10d,0d)` to `(80d,30d)` via `(45d,15d)`.

    sql> SELECT spath '{ (10d,0d),(45d,15d),(80d,30d) } ';

## Polygon

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

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

- A spherical polygon has the same restrictions as a spherical path (see dt.spath). 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°.

### Input of polygon

A polygon going from `(270d,-10d)`. via `(270d,30d)` to `(290d,10d)` back to `(270d,-10d)`

    sql> SELECT spoly '{ (270d,-10d), (270d,30d), (290d,10d) } ';

## Coordinates range

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

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

### Input of a full latitude range

A full latitude range between +20° and +23°.

    sql> SELECT sbox '( (0d,20d), (0d,23d) )';

### A simple coordinates range

A coordinate range between -10° and +10° in latitude and 350° and 10° in longitude.

    sql> SELECT sbox '( (350d,-10d), (10d,+10d) )';

## `smoc`: HEALPix Multi-Order Coverage map

The datatype smoc allows one to define and manipulate any region of the sky in such a way that basic operations like union, intersection can be performed very efficiently. It is dedicated to VO applications or VO data servers for building efficient procedures for which mapping knowledge is required like generic catalog cross-match, computation of data set intersections, etc. This encoding method is called "Multi-Order Coverage map" or "MOC".

The goal behind the MOC is to get a spherical geometry description for any sky region in order to provide very fast and accurate union, intersection and equality operations between them. In order to accomplish this task, we based the system on a regular and hierarchical partitioning of the sphere, a process called tessellation, yielding pixels of different size. At level 0, the sky is divided into 12 pixels numbered 0 to 11. At the maximally defined level 29, there are 12 * 4^29 = 3458764513820540928 pixels.

The MOC standard is described at http://www.ivoa.net/documents/MOC/

    level/pixel1-pixel2 [...] level/pixel1-pixel2 [...]

### The empty set

    sql> SELECT smoc '0/';

### The whole sky

    sql> SELECT smoc '0/0-11';

### A disk around the point (0, 0) with radius 1 at MOC level 2

    sql> SELECT smoc '0/4 1/0 2 12-13 34-35 45 47 2/4 6 12 14 56-57 60-61 88 90-91 116-117 119 130-131 134-135 177 179 185 187';