pgSphere 1.1.5
Prev |  | Next

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

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

Example 17. 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;

## 4.2. 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 Section 3.3.

Example 18. 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');

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

Example 19. 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)

## 4.4. Line

The input of spherical lines using Euler transformation and length is quite circumstantial (see Section 3.5). 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° (π), 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.

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

Example 21. A line created with its transformation and length

The same line as in Example 20, 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)

## 4.5. 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 Section 3.6.

Example 22. 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)

## 4.6. Polygon

The aggregate function

``spoly`(spoint edge);`

can be used to create a polygon from a set of spherical points. There are the same restrictions as for using the input function of spherical polygon (see Section 3.8). The function returns `NULL`, if the polygon couldn't be created.

Example 23. 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)

## 4.7. 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 Section 3.7). The function returns `NULL` if the path couldn't be created.

Example 24. 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)

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

Example 25. 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)' );

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

Prev | Home | Next
Data types |  | Operators