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.
There is only one constructor function for spherical points.
where lng is the longitude of the spherical
point in radians, lng is the latitude of
the spherical point in radians.
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');
The function
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)
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.
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
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)
You can use the function
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)
The aggregate function
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)
Similar to spherical polygons, you can use the aggregate function
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)
The function
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.
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
creates an smoc of the given order covering the spoly