[postgis-commits] svn - r2869 - trunk/doc
postgis-commits at postgis.refractions.net
postgis-commits at postgis.refractions.net
Fri Jul 18 05:23:08 PDT 2008
Author: robe
Date: 2008-07-18 05:23:07 -0700 (Fri, 18 Jul 2008)
New Revision: 2869
Modified:
trunk/doc/reference.xml
trunk/doc/reference_new.xml
Log:
Move over ST_AddPoint, ST_RemovePoint, ST_Npoints, ST_NumPoints and provide examples.
Modified: trunk/doc/reference.xml
===================================================================
--- trunk/doc/reference.xml 2008-07-17 14:16:17 UTC (rev 2868)
+++ trunk/doc/reference.xml 2008-07-18 12:23:07 UTC (rev 2869)
@@ -1814,40 +1814,8 @@
</listitem>
</varlistentry>
+
<varlistentry>
- <term>ST_AddPoint(linestring geometry, point geometry)</term>
-
- <term>ST_AddPoint(linestring geometry, point geometry, position
- integer)</term>
-
- <listitem>
- <para>Adds a point to a LineString before point <position>
- (0-based index). Third parameter can be omitted or set to -1 for
- appending.</para>
-
- <programlisting>
---guarantee all linestrings in a table are closed
---by adding the start point of each linestring to the end of the line string
---only for those that are not closed
-UPDATE sometable
- SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))
- FROM sometable
- WHERE ST_IsClosed(the_geom) = false;
- </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_RemovePoint(linestring, offset)</term>
-
- <listitem>
- <para>Removes point from a linestring. Offset is 0-based.</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term>ST_SetPoint(linestring, N, point)</term>
<listitem>
@@ -2332,14 +2300,6 @@
</listitem>
</varlistentry>
- <varlistentry>
- <term>ST_npoints(geometry)</term>
-
- <listitem>
- <para>Returns the number of points in the geometry.</para>
- </listitem>
- </varlistentry>
-
<varlistentry id="IsValid">
<term>ST_isvalid(geometry)</term>
@@ -2982,18 +2942,6 @@
</varlistentry>
<varlistentry>
- <term>ST_NumPoints</term>
-
- <listitem>
- <para>Return the number of points in an ST_LineString or
- ST_CircularString value.</para>
-
- <para>SQL-MM 3: 7.2.4</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
<term>ST_Overlaps</term>
<listitem>
Modified: trunk/doc/reference_new.xml
===================================================================
--- trunk/doc/reference_new.xml 2008-07-17 14:16:17 UTC (rev 2868)
+++ trunk/doc/reference_new.xml 2008-07-18 12:23:07 UTC (rev 2869)
@@ -583,105 +583,282 @@
</sect1>
<sect1>
- <title>Geometry Accessors</title>
-
- <refentry id="ST_Envelope">
- <refnamediv>
- <refname>ST_Envelope</refname>
+ <title>Geometry Accessors</title>
+ <refentry id="ST_Envelope">
+ <refnamediv>
+ <refname>ST_Envelope</refname>
+
+ <refpurpose>Returns a geometry representing the bounding box of the
+ supplied geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>boolean <function>ST_Envelope</function></funcdef>
+
+ <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the minimum bounding box for the supplied geometry, as a geometry.
+ The polygon is defined by the corner points of the bounding box
+ ((<varname>MINX</varname>, <varname>MINY</varname>),
+ (<varname>MINX</varname>, <varname>MAXY</varname>),
+ (<varname>MAXX</varname>, <varname>MAXY</varname>),
+ (<varname>MAXX</varname>, <varname>MINY</varname>),
+ (<varname>MINX</varname>, <varname>MINY</varname>)). (PostGIS will add a
+ <varname>ZMIN</varname>/<varname>ZMAX</varname> coordinate as
+ well).</para>
+
+ <para>Degenerate cases (vertical lines, points) will return a geometry of
+ lower dimension than <varname>POLYGON</varname>, ie.
+ <varname>POINT</varname> or <varname>LINESTRING</varname>.</para>
+
+ <caution>
+ <para>In PostGIS, the bounding box of a geometry is represented internally using
+ <varname>float4</varname>s instead of <varname>float8</varname>s that are used
+ to store geometries. The bounding box coordinates are floored, guarenteeing
+ that the geometry is contained entirely within its bounds. This has the
+ advantage that a geometry's bounding box is half the size as the minimum
+ bounding rectangle, which means significantly faster indexes and general performance.
+ But it also means that the bounding box is NOT the same as the minimum bounding
+ rectangle that bounds the geometry.</para>
+ </caution>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the <ulink
+ url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
+ Implementation Specification for SQL: v1.1: s2.1.1.1</ulink></para>
+
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the SQL/MM specification:
+ SQL-MM 3: 5.1.15</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+ SELECT ST_AsText(ST_Envelope('POINT(1 3)'::geometry));
+ st_astext
+ ------------
+ POINT(1 3)
+ (1 row)
+
+
+ SELECT ST_AsText(ST_Envelope('LINESTRING(0 0, 1 3)'::geometry));
+ st_astext
+ --------------------------------
+ POLYGON((0 0,0 3,1 3,1 0,0 0))
+ (1 row)
+
+
+ SELECT ST_AsText(ST_Envelope('POLYGON((0 0, 0 1, 1.0000001 1, 1.0000001 0, 0 0))'::geometry));
+ st_astext
+ --------------------------------------------------------------
+ POLYGON((0 0,0 1,1.00000011920929 1,1.00000011920929 0,0 0))
+ (1 row)
+ SELECT ST_AsText(ST_Envelope('POLYGON((0 0, 0 1, 1.0000000001 1, 1.0000000001 0, 0 0))'::geometry));
+ st_astext
+ --------------------------------------------------------------
+ POLYGON((0 0,0 1,1.00000011920929 1,1.00000011920929 0,0 0))
+ (1 row)</programlisting>
+ </refsection>
+ </refentry>
+ <refentry id="ST_NPoints">
+ <refnamediv>
+ <refname>ST_NPoints</refname>
+ <refpurpose>Return the number of points (vertexes) in a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>integer <function>ST_NPoints</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Return the number of points in a geometry. Works for all geometries.</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_NPoints(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
+ --result
+ 4
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_NumPoints" /></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_NumPoints">
+ <refnamediv>
+ <refname>ST_NumPoints</refname>
+ <refpurpose>Return the number of points in an ST_LineString or
+ ST_CircularString value.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>integer <function>ST_NumPoints</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Return the number of points in an ST_LineString or
+ ST_CircularString value. Only works with Linestrings. Consider using ST_NPoints instead which is multi-purpose
+ and works with many geometry types.</para>
- <refpurpose>Returns a geometry representing the bounding box of the
- supplied geometry.</refpurpose>
- </refnamediv>
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the <ulink
+ url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
+ Implementation Specification for SQL.</ulink></para>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>boolean <function>ST_Envelope</function></funcdef>
-
- <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Returns the minimum bounding box for the supplied geometry, as a geometry.
- The polygon is defined by the corner points of the bounding box
- ((<varname>MINX</varname>, <varname>MINY</varname>),
- (<varname>MINX</varname>, <varname>MAXY</varname>),
- (<varname>MAXX</varname>, <varname>MAXY</varname>),
- (<varname>MAXX</varname>, <varname>MINY</varname>),
- (<varname>MINX</varname>, <varname>MINY</varname>)). (PostGIS will add a
- <varname>ZMIN</varname>/<varname>ZMAX</varname> coordinate as
- well).</para>
-
- <para>Degenerate cases (vertical lines, points) will return a geometry of
- lower dimension than <varname>POLYGON</varname>, ie.
- <varname>POINT</varname> or <varname>LINESTRING</varname>.</para>
-
- <caution>
- <para>In PostGIS, the bounding box of a geometry is represented internally using
- <varname>float4</varname>s instead of <varname>float8</varname>s that are used
- to store geometries. The bounding box coordinates are floored, guarenteeing
- that the geometry is contained entirely within its bounds. This has the
- advantage that a geometry's bounding box is half the size as the minimum
- bounding rectangle, which means significantly faster indexes and general performance.
- But it also means that the bounding box is NOT the same as the minimum bounding
- rectangle that bounds the geometry.</para>
- </caution>
-
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This method implements the <ulink
- url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
- Implementation Specification for SQL: v1.1: s2.1.1.1</ulink></para>
-
- <para><inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/check.png" />
- </imageobject>
- </inlinemediaobject> This method implements the SQL/MM specification:
- SQL-MM 3: 5.1.15</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>
-SELECT ST_AsText(ST_Envelope('POINT(1 3)'::geometry));
- st_astext
-------------
- POINT(1 3)
-(1 row)
-
-
-SELECT ST_AsText(ST_Envelope('LINESTRING(0 0, 1 3)'::geometry));
- st_astext
---------------------------------
- POLYGON((0 0,0 3,1 3,1 0,0 0))
-(1 row)
-
-
-SELECT ST_AsText(ST_Envelope('POLYGON((0 0, 0 1, 1.0000001 1, 1.0000001 0, 0 0))'::geometry));
- st_astext
---------------------------------------------------------------
- POLYGON((0 0,0 1,1.00000011920929 1,1.00000011920929 0,0 0))
-(1 row)
-SELECT ST_AsText(ST_Envelope('POLYGON((0 0, 0 1, 1.0000000001 1, 1.0000000001 0, 0 0))'::geometry));
- st_astext
---------------------------------------------------------------
- POLYGON((0 0,0 1,1.00000011920929 1,1.00000011920929 0,0 0))
-(1 row)</programlisting>
- </refsection>
-</refentry>
-
+ <para><inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/check.png" />
+ </imageobject>
+ </inlinemediaobject> This method implements the SQL/MM specification:
+ SQL-MM 3: 7.2.4</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>SELECT ST_NumPoints(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
+ --result
+ 4
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+
+ <para><xref linkend="ST_NPoints" /></para>
+ </refsection>
+ </refentry>
</sect1>
<sect1>
<title>Geometry Editors</title>
+ <refentry id="ST_AddPoint">
+ <refnamediv>
+ <refname>ST_AddPoint</refname>
+ <refpurpose>Adds a point to a LineString before point <position>
+ (0-based index).</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_AddPoint</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>linestring</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>point</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_AddPoint</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>linestring</parameter></paramdef>
+ <paramdef><type>geometry</type> <parameter>point</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>position</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Adds a point to a LineString before point <position>
+ (0-based index). Third parameter can be omitted or set to -1 for
+ appending.</para>
+ <para>Availability: 1.1.0</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+ --guarantee all linestrings in a table are closed
+ --by adding the start point of each linestring to the end of the line string
+ --only for those that are not closed
+ UPDATE sometable
+ SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))
+ FROM sometable
+ WHERE ST_IsClosed(the_geom) = false;
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_RemovePoint"/></para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_RemovePoint">
+ <refnamediv>
+ <refname>ST_RemovePoint</refname>
+ <refpurpose>Removes point from a linestring. Offset is 0-based.</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_RemovePoint</function></funcdef>
+ <paramdef><type>geometry</type> <parameter>linestring</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>offset</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Removes point from a linestring. Useful for turning a closed ring into an open line string</para>
+ <para>Availability: 1.1.0</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+--guarantee no LINESTRINGS are closed
+--by removing the end point. The below assumes the_geom is of type LINESTRING
+UPDATE sometable
+ SET the_geom = ST_RemovePoint(the_geom, ST_NPoints(the_geom) - 1)
+ FROM sometable
+ WHERE ST_IsClosed(the_geom) = true;
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>See Also</title>
+ <para><xref linkend="ST_AddPoint"/>, <xref linkend="ST_NPoints"/>, <xref linkend="ST_NumPoints"/></para>
+ </refsection>
+ </refentry>
+
<refentry id="ST_Reverse">
<refnamediv>
<refname>ST_Reverse</refname>
More information about the postgis-commits
mailing list