SFCGAL is a C++ wrapper library around CGAL that provides advanced 2D and 3D functions.
For robustness, geometry coordinates have an exact rational number representation.
Installation instructions of the library can be found on SFCGAL home page http://www.sfcgal.org.
To load the functions create extension postgis_sfcgal.
Some SFCGAL functions replace standard ones (ST_Intersects, ST_Intersection, ST_Difference, ST_Union, ST_Area and ST_Distance), to switch between standard functions and SFCGAL function use:
SET postgis.backend = sfcgal;
and
SET postgis.backend = geos;
SFCGAL Functions
postgis_sfcgal_version
Returns the version of SFCGAL in use
text postgis_sfcgal_version
Description
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
ST_Extrude
Extrude a surface to a related volume
geometry ST_Extrude
geometry geom
float x
float y
float z
Description
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Examples
3D images were generated using the PostGIS and rendering in HTML using X3Dom HTML Javascript redering library.
SELECT ST_Buffer(ST_GeomFromText('POINT(100 90)'),
50, 'quad_segs=2'),0,0,30);
Original octagon formed from buffering point
ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
50, 'quad_segs=2'),0,0,30);
Hexagon extruded 30 units along Z produces a PolyhedralSurfaceZ
SELECT ST_GeomFromText('LINESTRING(50 50, 100 90, 95 150)')
Original linestring
SELECT ST_Extrude(
ST_GeomFromText('LINESTRING(50 50, 100 90, 95 150)'),0,0,10));
LineString Extruded along Z produces a PolyhedralSurfaceZ
See Also
ST_StraightSkeleton
Compute a straight skeleton from a geometry
geometry ST_StraightSkeleton
geometry geom
Description
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Examples
SELECT ST_StraightSkeleton(ST_GeomFromText('POLYGON (( 190 190, 10 190, 10 10, 190 10, 190 20, 160 30, 60 30, 60 130, 190 140, 190 190 ))'));
Original polygon
Straight Skeleton of polygon
ST_ApproximateMedialAxis
Compute the approximate medial axis of an areal geometry.
geometry ST_ApproximateMedialAxis
geometry geom
Description
Return an approximate medial axis for the areal input based on
its straight skeleton. Uses an SFCGAL specific API when built against
a capable version (1.2.0+). Otherwise the function is just a wrapper
around ST_StraightSkeleton (slower case).
Availability: 2.2.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Examples
SELECT ST_ApproximateMedialAxis(ST_GeomFromText('POLYGON (( 190 190, 10 190, 10 10, 190 10, 190 20, 160 30, 60 30, 60 130, 190 140, 190 190 ))'));
A polygon and its approximate medial axis
See Also
ST_IsPlanar
Check if a surface is or not planar
boolean ST_IsPlanar
geometry geom
Description
Availability: 2.2.0: This was documented in 2.1.0 but got accidentally left out in 2.1 release.
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
ST_Orientation
Determine surface orientation
integer ST_Orientation
geometry geom
Description
The function only applies to polygons. It returns -1 if the polygon is counterclockwise oriented and 1 if the polygon is clockwise oriented.
Availability: 2.1.0
&sfcgal_required;
&Z_support;
ST_ForceLHR
Force LHR orientation
geometry ST_ForceLHR
geometry geom
Description
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
ST_MinkowskiSum
Performs Minkowski sum
geometry ST_MinkowskiSum
geometry geom1
geometry geom2
Description
This function performs a 2D minkowski sum of a point, line or polygon with a polygon.
A minkowski sum of two geometries A and B is the set of all points that are the sum of any point in A and B. Minkowski sums are often used in motion planning and computer-aided design. More details on Wikipedia Minkowski addition.
The first parameter can be any 2D geometry (point, linestring, polygon). If a 3D geometry is passed, it will be converted to 2D by forcing Z to 0, leading to possible cases of invalidity. The second parameter must be a 2D polygon.
Implementation utilizes CGAL 2D Minkowskisum.
Availability: 2.1.0
&sfcgal_required;
Examples
Minkowski Sum of Linestring and circle polygon where Linestring cuts thru the circle
Before Summing
After summing
SELECT ST_MinkowskiSum(line, circle))
FROM (SELECT
ST_MakeLine(ST_MakePoint(10, 10),ST_MakePoint(100, 100)) As line,
ST_Buffer(ST_GeomFromText('POINT(50 50)'), 30) As circle) As foo;
-- wkt --
MULTIPOLYGON(((30 59.9999999999999,30.5764415879031 54.1472903395161,32.2836140246614 48.5194970290472,35.0559116309237 43.3328930094119,38.7867965644036 38.7867965644035,43.332893009412 35.0559116309236,48.5194970290474 32.2836140246614,54.1472903395162 30.5764415879031,60.0000000000001 30,65.8527096604839 30.5764415879031,71.4805029709527 32.2836140246614,76.6671069905881 35.0559116309237,81.2132034355964 38.7867965644036,171.213203435596 128.786796564404,174.944088369076 133.332893009412,177.716385975339 138.519497029047,179.423558412097 144.147290339516,180 150,179.423558412097 155.852709660484,177.716385975339 161.480502970953,174.944088369076 166.667106990588,171.213203435596 171.213203435596,166.667106990588 174.944088369076,
161.480502970953 177.716385975339,155.852709660484 179.423558412097,150 180,144.147290339516 179.423558412097,138.519497029047 177.716385975339,133.332893009412 174.944088369076,128.786796564403 171.213203435596,38.7867965644035 81.2132034355963,35.0559116309236 76.667106990588,32.2836140246614 71.4805029709526,30.5764415879031 65.8527096604838,30 59.9999999999999)))
Minkowski Sum of a polygon and multipoint
Before Summing
After summing: polygon is duplicated and translated to position of points
SELECT ST_MinkowskiSum(mp, poly)
FROM (SELECT 'MULTIPOINT(25 50,70 25)'::geometry As mp,
'POLYGON((130 150, 20 40, 50 60, 125 100, 130 150))'::geometry As poly
) As foo
-- wkt --
MULTIPOLYGON(
((70 115,100 135,175 175,225 225,70 115)),
((120 65,150 85,225 125,275 175,120 65))
)
ST_3DIntersection
Perform 3D intersection
geometry ST_3DIntersection
geometry geom1
geometry geom2
Description
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Examples: 3D linestring and Polygon
SELECT ST_AsText(ST_3DIntersection(linestring, polygon)) As wkt
FROM ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') AS linestring
CROSS JOIN ST_GeomFromText('POLYGON((0 0 8, 0 1 8, 1 1 8, 1 0 8, 0 0 8))') AS polygon;
wkt
--------------------------------
LINESTRING Z (1 1 8,0.5 0.5 8)
Cube (closed Polyhedral Surface) and Polygon Z
SELECT ST_AsText(ST_3DIntersection(
ST_GeomFromText('POLYHEDRALSURFACE Z( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)),
((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),
((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)),
((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)), ((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )'),
'POLYGON Z ((0 0 0, 0 0 0.5, 0 0.5 0.5, 0 0.5 0, 0 0 0))'::geometry))
TIN Z (((0 0 0,0 0 0.5,0 0.5 0.5,0 0 0)),((0 0.5 0,0 0 0,0 0.5 0.5,0 0.5 0)))
Intersection of 2 solids that result in volumetric intersection is also a solid (ST_Dimension returns 3)
SELECT ST_AsText(ST_3DIntersection( ST_Extrude(ST_Buffer('POINT(10 20)'::geometry,10,1),0,0,30),
ST_Extrude(ST_Buffer('POINT(10 20)'::geometry,10,1),2,0,10) ));
POLYHEDRALSURFACE Z (((13.3333333333333 13.3333333333333 10,20 20 0,20 20 10,13.3333333333333 13.3333333333333 10)),
((20 20 10,16.6666666666667 23.3333333333333 10,13.3333333333333 13.3333333333333 10,20 20 10)),
((20 20 0,16.6666666666667 23.3333333333333 10,20 20 10,20 20 0)),
((13.3333333333333 13.3333333333333 10,10 10 0,20 20 0,13.3333333333333 13.3333333333333 10)),
((16.6666666666667 23.3333333333333 10,12 28 10,13.3333333333333 13.3333333333333 10,16.6666666666667 23.3333333333333 10)),
((20 20 0,9.99999999999995 30 0,16.6666666666667 23.3333333333333 10,20 20 0)),
((10 10 0,9.99999999999995 30 0,20 20 0,10 10 0)),((13.3333333333333 13.3333333333333 10,12 12 10,10 10 0,13.3333333333333 13.3333333333333 10)),
((12 28 10,12 12 10,13.3333333333333 13.3333333333333 10,12 28 10)),
((16.6666666666667 23.3333333333333 10,9.99999999999995 30 0,12 28 10,16.6666666666667 23.3333333333333 10)),
((10 10 0,0 20 0,9.99999999999995 30 0,10 10 0)),
((12 12 10,11 11 10,10 10 0,12 12 10)),((12 28 10,11 11 10,12 12 10,12 28 10)),
((9.99999999999995 30 0,11 29 10,12 28 10,9.99999999999995 30 0)),((0 20 0,2 20 10,9.99999999999995 30 0,0 20 0)),
((10 10 0,2 20 10,0 20 0,10 10 0)),((11 11 10,2 20 10,10 10 0,11 11 10)),((12 28 10,11 29 10,11 11 10,12 28 10)),
((9.99999999999995 30 0,2 20 10,11 29 10,9.99999999999995 30 0)),((11 11 10,11 29 10,2 20 10,11 11 10)))
ST_3DDifference
Perform 3D difference
geometry ST_3DDifference
geometry geom1
geometry geom2
Description
Availability: 2.2.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
ST_3DUnion
Perform 3D union
geometry ST_3DUnion
geometry geom1
geometry geom2
Description
Availability: 2.2.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
ST_3DArea
Computes area of 3D surface geometries. Will return 0 for solids.
floatST_3DArea
geometry geom1
Description
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Examples
Note: By default a PolyhedralSurface built from WKT is a surface geometry, not solid. It therefore has surface area. Once converted to a solid, no area.
SELECT ST_3DArea(geom) As cube_surface_area,
ST_3DArea(ST_MakeSolid(geom)) As solid_surface_area
FROM (SELECT 'POLYHEDRALSURFACE( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)),
((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)),
((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),
((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)),
((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)),
((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )'::geometry) As f(geom);
cube_surface_area | solid_surface_area
-------------------+--------------------
6 | 0
See Also
, , ,
ST_Tesselate
Perform surface Tesselation of a polygon or polyhedralsurface and returns as a TIN or collection of TINS
geometry ST_Tesselate
geometry geom
Description
Takes as input a surface such a MULTI(POLYGON) or POLYHEDRALSURFACE and returns a TIN representation via the process of tesselation using triangles.
Availability: 2.1.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Examples
SELECT ST_GeomFromText('POLYHEDRALSURFACE Z( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)),
((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),
((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)),
((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)), ((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )');
Original Cube
SELECT ST_Tesselate(ST_GeomFromText('POLYHEDRALSURFACE Z( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)),
((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),
((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)),
((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)), ((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )'));
ST_AsText output:
TIN Z (((0 0 0,0 0 1,0 1 1,0 0 0)),((0 1 0,0 0 0,0 1 1,0 1 0)),
((0 0 0,0 1 0,1 1 0,0 0 0)),
((1 0 0,0 0 0,1 1 0,1 0 0)),((0 0 1,1 0 0,1 0 1,0 0 1)),
((0 0 1,0 0 0,1 0 0,0 0 1)),
((1 1 0,1 1 1,1 0 1,1 1 0)),((1 0 0,1 1 0,1 0 1,1 0 0)),
((0 1 0,0 1 1,1 1 1,0 1 0)),((1 1 0,0 1 0,1 1 1,1 1 0)),
((0 1 1,1 0 1,1 1 1,0 1 1)),((0 1 1,0 0 1,1 0 1,0 1 1)))
Tesselated Cube with triangles colored
SELECT 'POLYGON (( 10 190, 10 70, 80 70, 80 130, 50 160, 120 160, 120 190, 10 190 ))'::geometry;
Original polygon
SELECT
ST_Tesselate('POLYGON (( 10 190, 10 70, 80 70, 80 130, 50 160, 120 160, 120 190, 10 190 ))'::geometry);
ST_AsText output
TIN(((80 130,50 160,80 70,80 130)),((50 160,10 190,10 70,50 160)),
((80 70,50 160,10 70,80 70)),((120 160,120 190,50 160,120 160)),
((120 190,10 190,50 160,120 190)))
Tesselated Polygon
ST_Volume
Computes the volume of a 3D solid. If applied to surface (even closed) geometries will return 0.
float ST_Volume
geometry geom1
Description
Availability: 2.2.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
Example
When closed surfaces are created with WKT, they are treated as areal rather than solid. To make them solid, you need to use .
Areal geometries have no volume. Here is an example to demonstrate.
SELECT ST_Volume(geom) As cube_surface_vol,
ST_Volume(ST_MakeSolid(geom)) As solid_surface_vol
FROM (SELECT 'POLYHEDRALSURFACE( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)),
((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)),
((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)),
((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)),
((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)),
((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )'::geometry) As f(geom);
cube_surface_vol | solid_surface_vol
------------------+-------------------
0 | 1
See Also
, ,
ST_MakeSolid
Cast the geometry into a solid. No check is performed. To obtain a valid solid, the input geometry must be a closed Polyhedral Surface or a closed TIN.
geometryST_MakeSolid
geometry geom1
Description
Availability: 2.2.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;
ST_IsSolid
Test if the geometry is a solid. No validity check is performed.
booleanST_IsSolid
geometry geom1
Description
Availability: 2.2.0
&sfcgal_required;
&Z_support;
&P_support;
&T_support;