# Constructors

Constructors within pgSphere are functions needed to create spherical data types from other data types. For actual use, there isn't a difference to usual PostgreSQL functions. pgSphere constructor functions are named by returned data type. Constructor functions expecting one parameter only are implemented as casting operators, too. These are not mentioned here.

## Point

There is only one constructor function for spherical points.

                  spoint
                    float8 lng
                    float8 lat

where `lng` is the longitude of the spherical point in radians, `lng` is the latitude of the spherical point in radians.

### A spherical point from longitude and latitude

Get a spherical position with 270° of longitude and -30° of latitude.

    sql> SELECT spoint ( 270.0*pi()/180.0,-30.0*pi()/180.0 ) AS spoint;

## Euler transformation

There are two constructor functions for an Euler transformation:

                  strans
                    float8 phi
                    float8 theta
                    float8 psi

                  strans
                    float8 phi
                    float8 theta
                    float8 psi
                    character axis

where `phi`, `theta` and `psi` are the three angles of Euler transformation. The fourth parameter is the three letter code of Euler the transformation axis. If that parameter is omitted, pgSphere will assume `ZXZ`. For more information about that parameter, see dt.strans.

### Create an Euler 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 ( 20.0*pi()/180.0, -270.0*pi()/180.0, 70.5*pi()/180.0, 'XZY');

## Circle

The function

                  scircle
                    spoint center
                    float8 radius

returns a spherical circle with center at `center` and a radius `radius` in radians. The circle radius has to be larger than or equal to zero but less or equal to 90°. Otherwise, this function returns an error.

### A circle around the north pole

Get a spherical circle around the North Pole with a radius of 30°.

    sql> SELECT set_sphere_output('DEG');
     set_sphere_output
    -------------------
     SET DEG
    (1 row)

    sql> SELECT scircle ( spoint '(0d,90d)', 30.0*pi()/180.0 );
          scircle
    --------------------
     <(0d , 90d) , 30d>
    (1 row)

## Line

The input of spherical lines using Euler transformation and length is quite circumstantial (see dt.sline). For short lines it is easier to input a line specifying the beginning and the end of the line.

                  sline
                    spoint begin
                    spoint end

If the distance between `begin` and `end` is 180° (&pg_pgr;), this function returns an error because the location of the line is undefined. However, if longitudes of `begin` and `end` are equal, pgSphere assumes a meridian and returns the corresponding spherical line.

### A line created using begin and end of line

A line starting at `spoint '(270d,10d)'` and ending at `spoint '(270d,30d)'`:

    sql> SELECT set_sphere_output('DEG')
     set_sphere_output
    -------------------
      SET DEG
     (1 row)

    sql> SELECT sline( spoint '(270d,10d)', spoint '(270d,30d)');
              sline
     ----------------------------
      ( 10d, 90d, 270d, ZXZ ), 20d
     (1 row)

Furthermore, there is a function for inputing a line using Euler transformation `trans` and line length `length`

                  sline
                    strans trans
                    float8 length

where the line length `length` must be given in radians.

### A line created with its transformation and length

The same line as in const.line.1, but using transformation and line length.

    sql> SELECT sline ( strans '10d, 90d, 270d, ZXZ', 20.0*pi()/180.0 );
              sline
    ------------------------------
     ( 10d, 90d, 270d, ZXZ ), 20d
    (1 row)

## Ellipse

You can use the function

                  sellipse
                    spoint center
                    float8 major_rad
                    float8 minor_rad
                    float8 incl

to create a spherical ellipse. The first parameter `center` is the center of ellipse. The parameter `major_rad` and `minor_rad` are the major and the minor radii of the ellipse in radians. If the major radius is smaller than minor radius, pgSphere swaps the values automatically. The last parameter `incl` is the inclination angle in radians. For more informations about ellipses, see dt.sellipse.

### Create an ellipse

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

    sql> SELECT set_sphere_output('DEG');
     set_sphere_output
    -------------------
     SET DEG
    (1 row)
    sql> SELECT sellipse ( spoint '( 20d, 0d )', 10.0*pi()/180.0, 5.0*pi()/180.0,
           pi()/2.0 );
                sellipse
    -----------------------------------
     <{ 10d , 5d }, (20d , -0d) , 90d>
    (1 row)

## Polygon

The functions `spoly` and `spoly_deg` can be used to create spherical polygons. Function `spoly` is overloaded and can accept arrays of float8 or spoint elements. There are the same restrictions as for using the input function of spherical polygon (see dt.spoly).

Create a spherical polygon from an array of pair-consecutive numbers (lng, lat). The coordinates are specified in radians.

    sql> SELECT spoly(ARRAY[0, 0, 0, 0.5, 0.5, 0.5, 0.5, 0])

Create a spherical polygon from an array of spoint elements.

    sql> SELECT spoly(ARRAY[spoint(0, 0), spoint(0, 0.5), spoint(0.5, 0.5), spoint(0.5, 0)])

Create a spherical polygon from an array of pair-consecutive numbers (lng, lat). The coordinates are specified in degrees.

    sql> SELECT spoly_deg(ARRAY[0, 0, 0, 10, 10, 10, 10, 0])

The aggregate function `spoly` can be used to create a polygon from a set of spherical points. The function returns `NULL`, if the polygon could not be created.

### Create a spherical polygon using a set of spherical points

Create a table and put in some spherical points with a unique ID. Then, create two polygons with different edge sequences.

    sql> SELECT set_sphere_output('DEG');
     set_sphere_output
    -------------------
     SET DEG
    (1 row)

    sql> CREATE TABLE points ( i int PRIMARY KEY, p spoint );
    sql> INSERT INTO points VALUES (1, '( 0d, 0d)');
    sql> INSERT INTO points VALUES (2, '(10d, 0d)');
    sql> INSERT INTO points VALUES (3, '( 0d,10d)');
    sql> SELECT spoly(data.p) FROM ( SELECT p FROM points ORDER BY i ASC ) AS data ;
                   spoly
    -----------------------------------
     {(0d , 0d),(10d , 0d),(0d , 10d)}
    (1 row)

    sql> SELECT spoly(data.p) FROM ( SELECT p FROM points ORDER BY i DESC ) AS data ;
                   spoly
    -----------------------------------
     {(0d , 10d),(10d , 0d),(0d , 0d)}
    (1 row)

## Path

Similar to spherical polygons, you can use the aggregate function

                  spath
                    spoint edge

to create a spherical path using a set of spherical points. There are the same restrictions as with the input function of spherical path (see dt.spath). The function returns `NULL` if the path couldn't be created.

### Create a spherical path using a set of spherical points

Create a table and put in some spherical points with a unique ID. Then, create a spherical path from it.

    sql> SELECT set_sphere_output('DEG');
     set_sphere_output
    -------------------
     SET DEG
    (1 row)

    sql> CREATE TABLE points ( i int PRIMARY KEY, p spoint );
    sql> INSERT INTO points VALUES (1, '( 0d, 10d)');
    sql> INSERT INTO points VALUES (2, '( 0d,  0d)');
    sql> INSERT INTO points VALUES (3, '( 0d,-10d)');
    sql> SELECT spath(data.p) FROM ( SELECT p FROM points ORDER BY i ASC ) AS data ;
                           spath
    ---------------------------------------------------
     {(0d , 10d),(0d , 0d),(0d , -10d)}
    (1 row)
    sql> SELECT spath(data.p) FROM ( SELECT p FROM points ORDER BY i DESC ) AS data ;
                           spath
    ---------------------------------------------------
     {(0d , -10d),(0d , 0d),(0d , 10d)}
    (1 row)

## Coordinates range

The function

                  sbox
                    spoint south_west
                    spoint north_east

creates an `sbox` object with its first parameter `south_west` as the southwest edge and its second parameter `northeast` as the north-east edge of the coordinates range.

### Create a spherical box using edges

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

    sql> SELECT sbox ( spoint '(0d,0d),(10d,10d)' );

## `smoc`

                  smoc
                    order int
                    spoint

creates a single-pixel `smoc` of the given order at `spoint`

                  smoc_disc
                    order int
                    lng double precision
                    lat double precision
                    radius double precision

                  smoc
                    order int
                    scircle

creates an `smoc` of the given order covering the circle

                  smoc
                    order int
                    spoly

creates an `smoc` of the given order covering the spoly