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 14. 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 15. 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 16. 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 17. 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 18. A line created with its transformation and length

The same line as in Example 17, 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 19. 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 20. 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 21. 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 22. 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)' );