SFCGAL is a C++ wrapper library around CGAL that provides advanced 2D and 3D spatial functions. For robustness, geometry coordinates have an exact rational number representation.

Installation instructions for the library can be found on the SFCGAL home page (http://www.sfcgal.org). To enable the functions use `create extension postgis_sfcgal`.

# 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 PostGIS ST_AsX3D and rendering in HTML using X3Dom HTML Javascript rendering 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_AsX3D

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_StraightSkeleton

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_Point(10, 10),ST_Point(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_ConstrainedDelaunayTriangles

Return a constrained Delaunay triangulation around the given input geometry.

    				geometry ST_ConstrainedDelaunayTriangles
    				geometry  g1

### Description

Return a Constrained Delaunay triangulation around the vertices of the input geometry. Output is a TIN.

&sfcgal_required;

Availability: 3.0.0

&Z_support;

### Examples

ST_ConstrainedDelaunayTriangles of 2 polygons
    select ST_ConstrainedDelaunayTriangles(
                   ST_Union(
                           'POLYGON((175 150, 20 40, 50 60, 125 100, 175 150))'::geometry,
                           ST_Buffer('POINT(110 170)'::geometry, 20)
                       )
               );
| ST_DelaunayTriangles of 2 polygons. Triangle edges cross polygon boundaries.
    select ST_DelaunayTriangles(
                   ST_Union(
                           'POLYGON((175 150, 20 40, 50 60, 125 100, 175 150))'::geometry,
                           ST_Buffer('POINT(110 170)'::geometry, 20)
                       )
    	   );

### See Also

ST_DelaunayTriangles, ST_Tesselate, ST_ConcaveHull, ST_Dump

ST_3DIntersection

Perform 3D intersection

    			geometry ST_3DIntersection
    			geometry geom1
    			geometry geom2

### Description

Return a geometry that is the shared portion between geom1 and geom2.

Availability: 2.1.0

&sfcgal_required;

&Z_support;

&P_support;

&T_support;

### Examples

3D images were generated using PostGIS ST_AsX3D and rendering in HTML using X3Dom HTML Javascript rendering library.

    SELECT ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
     50, 'quad_segs=2'),0,0,30) AS geom1,
            ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(80 80)'),
     50, 'quad_segs=1'),0,0,30) AS geom2;
Original 3D geometries overlaid. geom2 is shown semi-transparent |
    SELECT ST_3DIntersection(geom1,geom2)
    FROM ( SELECT ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
     50, 'quad_segs=2'),0,0,30) AS geom1,
            ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(80 80)'),
     50, 'quad_segs=1'),0,0,30) AS geom2 ) As t;
Intersection of geom1 and geom2

3D linestrings and polygons

    	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

Returns that part of geom1 that is not part of geom2.

Availability: 2.2.0

&sfcgal_required;

&Z_support;

&P_support;

&T_support;

### Examples

3D images were generated using PostGIS ST_AsX3D and rendering in HTML using X3Dom HTML Javascript rendering library.

    SELECT ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
     50, 'quad_segs=2'),0,0,30) AS geom1,
            ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(80 80)'),
     50, 'quad_segs=1'),0,0,30) AS geom2;
Original 3D geometries overlaid. geom2 is the part that will be removed. |
    SELECT ST_3DDifference(geom1,geom2)
    FROM ( SELECT ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
     50, 'quad_segs=2'),0,0,30) AS geom1,
            ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(80 80)'),
     50, 'quad_segs=1'),0,0,30) AS geom2 ) As t;
What's left after removing geom2

### See Also

ST_Extrude, ST_AsX3D, ST_3DIntersection ST_3DUnion

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;

### Examples

3D images were generated using PostGIS ST_AsX3D and rendering in HTML using X3Dom HTML Javascript rendering library.

    SELECT ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
     50, 'quad_segs=2'),0,0,30) AS geom1,
            ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(80 80)'),
     50, 'quad_segs=1'),0,0,30) AS geom2;
Original 3D geometries overlaid. geom2 is the one with transparency. |
    SELECT ST_3DUnion(geom1,geom2)
    FROM ( SELECT ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
     50, 'quad_segs=2'),0,0,30) AS geom1,
            ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(80 80)'),
     50, 'quad_segs=1'),0,0,30) AS geom2 ) As t;
Union of geom1 and geom2

### See Also

ST_Extrude, ST_AsX3D, ST_3DIntersection ST_3DDifference

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_Area, ST_MakeSolid, ST_IsSolid, ST_Area

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 tessellation 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

### See Also

ST_ConstrainedDelaunayTriangles, ST_DelaunayTriangles

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 ST_MakeSolid. 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_3DArea, ST_MakeSolid, ST_IsSolid

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;