postgis/doc/reference_sfcgal.xml
2014-08-23 05:50:54 +00:00

524 lines
17 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="reference_sfcgal">
<sect1info>
<abstract>
<para>
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.
</para>
<para>
Installation instructions of the library can be found on SFCGAL home page <ulink url="http://www.sfcgal.org">http://www.sfcgal.org</ulink>.
To load the functions execute postgis/sfcgal.sql
</para>
</abstract>
</sect1info>
<title>SFCGAL Functions</title>
<refentry id="postgis_sfcgal_version">
<refnamediv>
<refname>postgis_sfcgal_version</refname>
<refpurpose>Returns the version of SFCGAL in use</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>text <function>postgis_sfcgal_version</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
</refentry>
<refentry id="ST_Extrude">
<refnamediv>
<refname>ST_Extrude</refname>
<refpurpose>Extrude a surface to a related volume</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Extrude</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
<paramdef><type>float</type> <parameter>x</parameter></paramdef>
<paramdef><type>float</type> <parameter>y</parameter></paramdef>
<paramdef><type>float</type> <parameter>z</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection><title>Examples</title>
<para>3D images were generated using the PostGIS <xref linkend="ST_AsX3D" /> and rendering in HTML using <ulink url="http://www.x3dom.org">X3Dom HTML Javascript redering library</ulink>.</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry><para>
<programlisting>SELECT ST_Buffer(ST_GeomFromText('POINT(100 90)'),
50, 'quad_segs=2'),0,0,30);</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_extrude01.png" />
</imageobject>
<caption><para>Original octagon formed from buffering point</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
<entry><para>
<programlisting>ST_Extrude(ST_Buffer(ST_GeomFromText('POINT(100 90)'),
50, 'quad_segs=2'),0,0,30);</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_extrude02.png" />
</imageobject>
<caption><para>Hexagon extruded 30 units along Z produces a PolyhedralSurfaceZ</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
</row>
<row>
<entry><para>
<programlisting>SELECT ST_GeomFromText('LINESTRING(50 50, 100 90, 95 150)')</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_extrude03.png" />
</imageobject>
<caption><para>Original linestring</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
<entry><para>
<programlisting>SELECT ST_Extrude(
ST_GeomFromText('LINESTRING(50 50, 100 90, 95 150)'),0,0,10));</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_extrude04.png" />
</imageobject>
<caption><para>LineString Extruded along Z produces a PolyhedralSurfaceZ</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="ST_AsX3D" /></para>
</refsection>
</refentry>
<refentry id="ST_StraightSkeleton">
<refnamediv>
<refname>ST_StraightSkeleton</refname>
<refpurpose>Compute a straight skeleton from a geometry</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_StraightSkeleton</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection><title>Examples</title>
<programlisting>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 ))'));</programlisting>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry><para><informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_straightskeleton01.png" />
</imageobject>
<caption><para>Original polygon</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
<entry><para><informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_straightskeleton02.png" />
</imageobject>
<caption><para>Straight Skeleton of polygon</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
</refentry>
<refentry id="ST_IsPlanar">
<refnamediv>
<refname>ST_IsPlanar</refname>
<refpurpose>Check if a surface is or not planar</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ST_IsPlanar</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.2.0: This was documented in 2.1.0 but got accidentally left out in 2.1 release.</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
</refentry>
<refentry id="ST_Orientation">
<refnamediv>
<refname>ST_Orientation</refname>
<refpurpose>Determine surface orientation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>integer <function>ST_Orientation</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
</refentry>
<refentry id="ST_ForceLHR">
<refnamediv>
<refname>ST_ForceLHR</refname>
<refpurpose>Force LHR orientation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_ForceLHR</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
</refentry>
<refentry id="ST_MinkowskiSum">
<refnamediv>
<refname>ST_MinkowskiSum</refname>
<refpurpose>Performs Minkowski sum</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_MinkowskiSum</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom1</parameter></paramdef>
<paramdef><type>geometry</type> <parameter>geom2</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>This function performs a 2D minkowski sum of a point, line or polygon with a polygon.</para>
<para>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.</para>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
</refsection>
</refentry>
<refentry id="ST_3DIntersection">
<refnamediv>
<refname>ST_3DIntersection</refname>
<refpurpose>Perform 3D intersection</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_3DIntersection</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom1</parameter></paramdef>
<paramdef><type>geometry</type> <parameter>geom2</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection>
<title>Examples: 3D linestring and Polygon</title>
<programlisting> 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)
</programlisting>
<para>Cube (closed Polyhedral Surface) and Polygon Z</para>
<programlisting>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))</programlisting>
<screen>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)))</screen>
<para>Intersection of 2 solids that result in volumetric intersection is also a solid (ST_Dimension returns 3)</para>
<programlisting>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) ));</programlisting>
<screen>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)))</screen>
</refsection>
</refentry>
<refentry id="ST_3DArea">
<refnamediv>
<refname>ST_3DArea</refname>
<refpurpose>Computes area of 3D geometries</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>float<function>ST_3DArea</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
</refentry>
<refentry id="ST_Tesselate">
<refnamediv>
<refname>ST_Tesselate</refname>
<refpurpose>Perform surface Tesselation of a polygon or polyhedralsurface and returns as a TIN or collection of TINS</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>geometry <function>ST_Tesselate</function></funcdef>
<paramdef><type>geometry</type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Takes as input a surface such a MULTI(POLYGON) or POLYHEDRALSURFACE and returns a TIN representation via the process of tesselation using triangles.</para>
<para>Availability: 2.1.0</para>
<para>&sfcgal_required;</para>
<para>&Z_support;</para>
<para>&P_support;</para>
<para>&T_support;</para>
</refsection>
<refsection><title>Examples</title>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry><para>
<programlisting>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)) )');</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_tesselate01.png" />
</imageobject>
<caption><para>Original Cube</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
<entry><para>
<programlisting>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)) )'));</programlisting></para>
<para>ST_AsText output:</para>
<screen>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)))</screen>
<para> <informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_tesselate02.png" />
</imageobject>
<caption><para>Tesselated Cube with triangles colored</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
</row>
<row>
<entry><para>
<programlisting>SELECT 'POLYGON (( 10 190, 10 70, 80 70, 80 130, 50 160, 120 160, 120 190, 10 190 ))'::geometry;</programlisting>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_tesselate03.png" />
</imageobject>
<caption><para>Original polygon</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
<entry><para>
<programlisting>SELECT
ST_Tesselate('POLYGON (( 10 190, 10 70, 80 70, 80 130, 50 160, 120 160, 120 190, 10 190 ))'::geometry);</programlisting>
</para>
<para>ST_AsText output</para>
<screen>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)))</screen>
<para><informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/st_tesselate04.png" />
</imageobject>
<caption><para>Tesselated Polygon</para></caption>
</mediaobject>
</informalfigure></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
</refentry>
</sect1>