2303 lines
82 KiB
XML
2303 lines
82 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<sect1 id="Spatial_Relationships">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>These functions determine spatial relationships between geometries.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Spatial Relationships</title>
|
|
|
|
<sect2>
|
|
<title>Topological Relationships</title>
|
|
|
|
<refentry id="ST_3DIntersects">
|
|
<refnamediv>
|
|
<refname>ST_3DIntersects</refname>
|
|
|
|
<refpurpose>Tests if two geometries spatially
|
|
intersect in 3D - only for points, linestrings, polygons, polyhedral surface (area)
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_3DIntersects</function></funcdef>
|
|
<paramdef>
|
|
<type>geometry</type>
|
|
<parameter>geomA</parameter>
|
|
</paramdef>
|
|
<paramdef>
|
|
<type>geometry</type>
|
|
<parameter>geomB</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>Overlaps, Touches, Within all imply spatial intersection. If any of the aforementioned
|
|
returns true, then the geometries also spatially intersect.
|
|
Disjoint implies false for spatial intersection.</para>
|
|
|
|
<note><para>&index_aware;</para></note>
|
|
|
|
<para>Changed: 3.0.0 SFCGAL backend removed, GEOS backend supports TINs.</para>
|
|
<para>Availability: 2.0.0</para>
|
|
|
|
<para>&Z_support;</para>
|
|
<!-- Optionally mention supports Polyhedral Surface -->
|
|
<para>&P_support;</para>
|
|
<para>&T_support;</para>
|
|
<para>&sqlmm_compliant; SQL-MM IEC 13249-3: 5.1</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Geometry Examples</title>
|
|
<programlisting>SELECT ST_3DIntersects(pt, line), ST_Intersects(pt, line)
|
|
FROM (SELECT 'POINT(0 0 2)'::geometry As pt, 'LINESTRING (0 0 1, 0 2 3)'::geometry As line) As foo;
|
|
st_3dintersects | st_intersects
|
|
-----------------+---------------
|
|
f | t
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection><title>TIN Examples</title>
|
|
<programlisting>SELECT ST_3DIntersects('TIN(((0 0 0,1 0 0,0 1 0,0 0 0)))'::geometry, 'POINT(.1 .1 0)'::geometry);
|
|
st_3dintersects
|
|
-----------------
|
|
t</programlisting></refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Intersects"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Contains">
|
|
<refnamediv>
|
|
<refname>ST_Contains</refname>
|
|
|
|
<refpurpose>Tests if every point of B lies in A, and their interiors have a point in common</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Contains</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomA</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomB</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns TRUE if geometry A contains geometry B.
|
|
A contains B if and only if all points of B lie inside (i.e. in the interior or boundary of) A
|
|
(or equivalently, no points of B lie in the exterior of A),
|
|
and the interiors of A and B have at least one point in common.
|
|
</para>
|
|
|
|
<para>The contains relationship is reflexive: every geometry contains itself.
|
|
(In contrast, in the <xref linkend="ST_ContainsProperly" />
|
|
predicate a geometry does <emphasis>not</emphasis> properly contain itself.)
|
|
The relationship is antisymmetric: if <code>ST_Contains(A,B) = true</code> and <code>ST_Contains(B,A) = true</code>, then
|
|
the two geometries must be topologically equal (<code>ST_Equals(A,B) = true</code>).
|
|
</para>
|
|
|
|
<para>ST_Contains is the converse of <xref linkend="ST_Within"/>.
|
|
So, <code>ST_Contains(A,B) = ST_Within(B,A)</code>.</para>
|
|
|
|
<note><para>Because the interiors must have a common point, a subtlety of the definition is that
|
|
polygons and lines do <emphasis>not</emphasis> contain lines and points lying fully in their boundary.
|
|
For further details see <ulink url="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Subtleties of OGC Covers, Contains, Within</ulink>.
|
|
The <xref linkend="ST_Covers" /> predicate provides a more inclusive relationship.
|
|
</para></note>
|
|
|
|
<note><para>&index_aware;
|
|
To avoid index use, use the function <function>_ST_Contains</function>.</para></note>
|
|
|
|
<para>Performed by the GEOS module</para>
|
|
<para>Enhanced: 2.3.0 Enhancement to PIP short-circuit extended to support MultiPoints with few points. Prior versions only supported point in polygon.</para>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<important>
|
|
<para>Do not use this function with invalid geometries. You will get unexpected results.</para>
|
|
</important>
|
|
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
|
|
<para>&sfs_compliant; s2.1.1.2 // s2.1.13.3
|
|
- same as within(geometry B, geometry A)</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.31</para>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<para><function>ST_Contains</function> returns <varname>TRUE</varname> in the following situations:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains01.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>LINESTRING</varname> / <varname>MULTIPOINT</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains02.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>POINT</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains03.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains04.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>POLYGON</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para><function>ST_Contains</function> returns <varname>FALSE</varname> in the following situations:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains05.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>MULTIPOINT</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains06.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Due to the interior intersection condition <function>ST_Contains</function> returns <varname>FALSE</varname> in the following situations
|
|
(whereas <function>ST_Covers</function> returns <varname>TRUE</varname>):</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains07.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>LINESTRING</varname> / <varname>POINT</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_contains08.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<programlisting>
|
|
-- A circle within a circle
|
|
SELECT ST_Contains(smallc, bigc) As smallcontainsbig,
|
|
ST_Contains(bigc,smallc) As bigcontainssmall,
|
|
ST_Contains(bigc, ST_Union(smallc, bigc)) as bigcontainsunion,
|
|
ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion,
|
|
ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
|
|
ST_Contains(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior
|
|
FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
|
|
ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
|
|
|
|
-- Result
|
|
smallcontainsbig | bigcontainssmall | bigcontainsunion | bigisunion | bigcoversexterior | bigcontainsexterior
|
|
------------------+------------------+------------------+------------+-------------------+---------------------
|
|
f | t | t | t | t | f
|
|
|
|
-- Example demonstrating difference between contains and contains properly
|
|
SELECT ST_GeometryType(geomA) As geomtype, ST_Contains(geomA,geomA) AS acontainsa, ST_ContainsProperly(geomA, geomA) AS acontainspropa,
|
|
ST_Contains(geomA, ST_Boundary(geomA)) As acontainsba, ST_ContainsProperly(geomA, ST_Boundary(geomA)) As acontainspropba
|
|
FROM (VALUES ( ST_Buffer(ST_Point(1,1), 5,1) ),
|
|
( ST_MakeLine(ST_Point(1,1), ST_Point(-1,-1) ) ),
|
|
( ST_Point(1,1) )
|
|
) As foo(geomA);
|
|
|
|
geomtype | acontainsa | acontainspropa | acontainsba | acontainspropba
|
|
--------------+------------+----------------+-------------+-----------------
|
|
ST_Polygon | t | f | f | f
|
|
ST_LineString | t | f | f | f
|
|
ST_Point | t | t | f | f
|
|
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Boundary" />, <xref linkend="ST_ContainsProperly" />, <xref linkend="ST_Covers" />, <xref linkend="ST_CoveredBy" />, <xref linkend="ST_Equals"/>, <xref linkend="ST_Within"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_ContainsProperly">
|
|
<refnamediv>
|
|
<refname>ST_ContainsProperly</refname>
|
|
|
|
<refpurpose>Tests if every point of B lies in the interior of A</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_ContainsProperly</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomA</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomB</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns <varname>true</varname> if every point of B lies inside A
|
|
(or equivalently, no point of B lies in the the boundary or exterior of A).</para>
|
|
|
|
<para>A does not properly contain itself, but does contain itself.</para>
|
|
<para>Every point of the other geometry is a point of this geometry's interior. The DE-9IM Intersection Matrix for the two geometries matches
|
|
[T**FF*FF*] used in <xref linkend="ST_Relate" /></para>
|
|
|
|
<para>
|
|
A use for this predicate is computing the intersections of a set of geometries with a large polygonal geometry. Since intersection is a fairly slow operation, it can be more efficient to use containsProperly to filter out test geometries which lie
|
|
fully inside the area. In these cases the intersection is known a priori to be exactly the original test geometry.
|
|
</para>
|
|
|
|
<note><para>&index_aware;
|
|
To avoid index use, use the function <function>_ST_ContainsProperly</function>.</para></note>
|
|
|
|
<note>
|
|
<para>The advantage of this predicate over <xref linkend="ST_Contains" /> and <xref linkend="ST_Intersects" /> is that it can be computed
|
|
more efficiently, with no need to compute topology at individual points.</para>
|
|
</note>
|
|
<para>Performed by the GEOS module.</para>
|
|
<para>Availability: 1.4.0</para>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<important>
|
|
<para>Do not use this function with invalid geometries. You will get unexpected results.</para>
|
|
</important>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
--a circle within a circle
|
|
SELECT ST_ContainsProperly(smallc, bigc) As smallcontainspropbig,
|
|
ST_ContainsProperly(bigc,smallc) As bigcontainspropsmall,
|
|
ST_ContainsProperly(bigc, ST_Union(smallc, bigc)) as bigcontainspropunion,
|
|
ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion,
|
|
ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
|
|
ST_ContainsProperly(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior
|
|
FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
|
|
ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
|
|
--Result
|
|
smallcontainspropbig | bigcontainspropsmall | bigcontainspropunion | bigisunion | bigcoversexterior | bigcontainsexterior
|
|
------------------+------------------+------------------+------------+-------------------+---------------------
|
|
f | t | f | t | t | f
|
|
|
|
--example demonstrating difference between contains and contains properly
|
|
SELECT ST_GeometryType(geomA) As geomtype, ST_Contains(geomA,geomA) AS acontainsa, ST_ContainsProperly(geomA, geomA) AS acontainspropa,
|
|
ST_Contains(geomA, ST_Boundary(geomA)) As acontainsba, ST_ContainsProperly(geomA, ST_Boundary(geomA)) As acontainspropba
|
|
FROM (VALUES ( ST_Buffer(ST_Point(1,1), 5,1) ),
|
|
( ST_MakeLine(ST_Point(1,1), ST_Point(-1,-1) ) ),
|
|
( ST_Point(1,1) )
|
|
) As foo(geomA);
|
|
|
|
geomtype | acontainsa | acontainspropa | acontainsba | acontainspropba
|
|
--------------+------------+----------------+-------------+-----------------
|
|
ST_Polygon | t | f | f | f
|
|
ST_LineString | t | f | f | f
|
|
ST_Point | t | t | f | f
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_GeometryType" />, <xref linkend="ST_Boundary" />, <xref linkend="ST_Contains" />, <xref linkend="ST_Covers" />, <xref linkend="ST_CoveredBy" />, <xref linkend="ST_Equals"/>, <xref linkend="ST_Relate" />, <xref linkend="ST_Within"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_CoveredBy">
|
|
<refnamediv>
|
|
<refname>ST_CoveredBy</refname>
|
|
|
|
<refpurpose>Tests if every point of A lies in B</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_CoveredBy</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomA</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomB</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_CoveredBy</function></funcdef>
|
|
|
|
<paramdef><type>geography </type>
|
|
<parameter>geogA</parameter></paramdef>
|
|
|
|
<paramdef><type>geography </type>
|
|
<parameter>geogB</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns <varname>true</varname> if every point in Geometry/Geography A lies inside
|
|
(i.e. intersects the interior or boundary of)
|
|
Geometry/Geography B.
|
|
Equivalently, tests that no point of A lies outside (in the exterior of) B.
|
|
</para>
|
|
|
|
<para>ST_CoveredBy is the converse of <xref linkend="ST_Covers"/>.
|
|
So, <code>ST_CoveredBy(A,B) = ST_Covers(B,A)</code>.</para>
|
|
|
|
<para>Generally this function should be used instead of <xref linkend="ST_Within"/>,
|
|
since it has a simpler definition
|
|
which does not have the quirk that "boundaries are not within their geometry".</para>
|
|
|
|
<note><para>&index_aware;
|
|
To avoid index use, use the function <function>_ST_CoveredBy</function>.</para></note>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<important>
|
|
<para>Do not use this function with invalid geometries. You will get unexpected results.</para>
|
|
</important>
|
|
<para>Performed by the GEOS module</para>
|
|
<para>Availability: 1.2.2</para>
|
|
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
|
|
<para>Not an OGC standard, but Oracle has it too.</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
--a circle coveredby a circle
|
|
SELECT ST_CoveredBy(smallc,smallc) As smallinsmall,
|
|
ST_CoveredBy(smallc, bigc) As smallcoveredbybig,
|
|
ST_CoveredBy(ST_ExteriorRing(bigc), bigc) As exteriorcoveredbybig,
|
|
ST_Within(ST_ExteriorRing(bigc),bigc) As exeriorwithinbig
|
|
FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
|
|
ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
|
|
--Result
|
|
smallinsmall | smallcoveredbybig | exteriorcoveredbybig | exeriorwithinbig
|
|
--------------+-------------------+----------------------+------------------
|
|
t | t | t | f
|
|
(1 row) </programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Contains"/>, <xref linkend="ST_Covers" />, <xref linkend="ST_ExteriorRing"/>, <xref linkend="ST_Within"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Covers">
|
|
<refnamediv>
|
|
<refname>ST_Covers</refname>
|
|
|
|
<refpurpose>Tests if every point of B lies in A</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Covers</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomA</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>geomB</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Covers</function></funcdef>
|
|
|
|
<paramdef><type>geography </type>
|
|
<parameter>geogpolyA</parameter></paramdef>
|
|
|
|
<paramdef><type>geography </type>
|
|
<parameter>geogpointB</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns <varname>true</varname> if every point in Geometry/Geography B lies inside
|
|
(i.e. intersects the interior or boundary of)
|
|
Geometry/Geography A.
|
|
Equivalently, tests that no point of B lies outside (in the exterior of) A.
|
|
</para>
|
|
|
|
<para>ST_Covers is the converse of <xref linkend="ST_CoveredBy"/>.
|
|
So, <code>ST_Covers(A,B) = ST_CoveredBy(B,A)</code>.</para>
|
|
|
|
<para>Generally this function should be used instead of <xref linkend="ST_Contains"/>,
|
|
since it has a simpler definition
|
|
which does not have the quirk that "geometries do not contain their boundary".</para>
|
|
|
|
|
|
<note><para>&index_aware;
|
|
To avoid index use, use the function <function>_ST_Covers</function>.</para></note>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<important>
|
|
<para>Do not use this function with invalid geometries. You will get unexpected results.</para>
|
|
</important>
|
|
|
|
<para>Performed by the GEOS module</para>
|
|
<para>Enhanced: 2.4.0 Support for polygon in polygon and line in polygon added for geography type</para>
|
|
<para>Enhanced: 2.3.0 Enhancement to PIP short-circuit for geometry extended to support MultiPoints with few points. Prior versions only supported point in polygon.</para>
|
|
<para>Availability: 1.5 - support for geography was introduced. </para>
|
|
<para>Availability: 1.2.2</para>
|
|
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
|
|
<para>Not an OGC standard, but Oracle has it too.</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para> Geometry example </para>
|
|
<programlisting>
|
|
--a circle covering a circle
|
|
SELECT ST_Covers(smallc,smallc) As smallinsmall,
|
|
ST_Covers(smallc, bigc) As smallcoversbig,
|
|
ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
|
|
ST_Contains(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior
|
|
FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
|
|
ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
|
|
--Result
|
|
smallinsmall | smallcoversbig | bigcoversexterior | bigcontainsexterior
|
|
--------------+----------------+-------------------+---------------------
|
|
t | f | t | f
|
|
(1 row) </programlisting>
|
|
<para>Geeography Example</para>
|
|
<programlisting>
|
|
-- a point with a 300 meter buffer compared to a point, a point and its 10 meter buffer
|
|
SELECT ST_Covers(geog_poly, geog_pt) As poly_covers_pt,
|
|
ST_Covers(ST_Buffer(geog_pt,10), geog_pt) As buff_10m_covers_cent
|
|
FROM (SELECT ST_Buffer(ST_GeogFromText('SRID=4326;POINT(-99.327 31.4821)'), 300) As geog_poly,
|
|
ST_GeogFromText('SRID=4326;POINT(-99.33 31.483)') As geog_pt ) As foo;
|
|
|
|
poly_covers_pt | buff_10m_covers_cent
|
|
----------------+------------------
|
|
f | t
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Contains"/>, <xref linkend="ST_CoveredBy" />, <xref linkend="ST_Within"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Crosses">
|
|
<refnamediv>
|
|
<refname>ST_Crosses</refname>
|
|
|
|
<refpurpose>Tests if two geometries have some, but not all, interior points in common</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Crosses</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type><parameter>g1</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type><parameter>g2</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Compares two geometry objects and
|
|
returns <varname>true</varname> if their intersection "spatially cross", that is, the
|
|
geometries have some, but not all interior points in common. The
|
|
intersection of the interiors of the geometries must be non-empty
|
|
and must have dimension less than the maximum dimension
|
|
of the two input geometries. Additionally, the intersection of the two
|
|
geometries must not equal either of the source geometries. Otherwise, it
|
|
returns <varname>false</varname>.</para>
|
|
|
|
<para>In mathematical terms, this is:</para>
|
|
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_crosses-math.gif" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
|
|
<para>Geometries cross if their DE-9IM Intersection Matrix matches:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><code>T*T******</code> for Point/Line, Point/Area, and Line/Area situations</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>T*****T**</code> for Line/Point, Area/Point, and Area/Line situations</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>0********</code> for Line/Line situations</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>For Point/Point and Area/Area situations this predicate returns
|
|
<varname>false</varname>.</para>
|
|
|
|
<para>The OpenGIS Simple Features Specification defines this predicate
|
|
only for Point/Line, Point/Area, Line/Line, and Line/Area situations.
|
|
JTS / GEOS extends the definition to apply to Line/Point, Area/Point and
|
|
Area/Line situations as well. This makes the relation
|
|
symmetric.</para>
|
|
|
|
<note><para>&index_aware;</para></note>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<para>&sfs_compliant; s2.1.13.3</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.29</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<para>The following situations all return <varname>true</varname>.</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_crosses01.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>MULTIPOINT</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_crosses02.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>MULTIPOINT</varname> / <varname>POLYGON</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_crosses03.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>LINESTRING</varname> / <varname>POLYGON</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_crosses04.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>LINESTRING</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Consider a situation where a user has two tables: a table of roads
|
|
and a table of highways.</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><para> <informalexample>
|
|
<programlisting>CREATE TABLE roads (
|
|
id serial NOT NULL,
|
|
geom geometry,
|
|
CONSTRAINT roads_pkey PRIMARY KEY (road_id)
|
|
);</programlisting>
|
|
</informalexample> </para></entry>
|
|
|
|
<entry><para> <informalexample>
|
|
<programlisting>CREATE TABLE highways (
|
|
id serial NOT NULL,
|
|
the_gem geometry,
|
|
CONSTRAINT roads_pkey PRIMARY KEY (road_id)
|
|
);</programlisting>
|
|
</informalexample> </para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>To determine a list of roads that cross a highway, use a query
|
|
similiar to:</para>
|
|
|
|
<para><informalexample>
|
|
<programlisting>SELECT roads.id
|
|
FROM roads, highways
|
|
WHERE ST_Crosses(roads.geom, highways.geom);</programlisting>
|
|
</informalexample></para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_Contains"/>, <xref linkend="ST_Overlaps"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Disjoint">
|
|
<refnamediv>
|
|
<refname>ST_Disjoint</refname>
|
|
|
|
<refpurpose>Tests if two geometries have no points in common </refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Disjoint</function></funcdef>
|
|
<paramdef>
|
|
<type>geometry</type>
|
|
<parameter>A</parameter>
|
|
</paramdef>
|
|
<paramdef>
|
|
<type>geometry</type>
|
|
<parameter>B</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>Overlaps, Touches, Within all imply geometries are not spatially disjoint. If any of the aforementioned
|
|
returns true, then the geometries are not spatially disjoint.
|
|
Disjoint implies false for spatial intersection.</para>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<para>Performed by the GEOS module</para>
|
|
<note>
|
|
<para>This function call does not use indexes. A negated <xref linkend="ST_Intersects" /> predicate
|
|
can be used as a more performant alternative that uses indexes:
|
|
<code>ST_Disjoint(A,B) = NOT ST_Intersects(A,B)</code></para>
|
|
|
|
</note>
|
|
<note>
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
</note>
|
|
<para>&sfs_compliant; s2.1.1.2 //s2.1.13.3
|
|
- a.Relate(b, 'FF*FF****')</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.26</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 2 0, 0 2 )'::geometry);
|
|
st_disjoint
|
|
---------------
|
|
t
|
|
(1 row)
|
|
SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry);
|
|
st_disjoint
|
|
---------------
|
|
f
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Intersects"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Equals">
|
|
<refnamediv>
|
|
<refname>ST_Equals</refname>
|
|
|
|
<refpurpose>Tests if two geometries include the same set of points</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Equals</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>A</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>B</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns <varname>true</varname> if the given geometries are "spatially
|
|
equal". Use this for a 'better' answer than '='.
|
|
Note by spatially equal we mean ST_Within(A,B) = true and ST_Within(B,A) = true and
|
|
also mean ordering of points can be different but
|
|
represent the same geometry structure. To verify the order of points is consistent, use
|
|
ST_OrderingEquals (it must be noted ST_OrderingEquals is a little more stringent than simply verifying order of
|
|
points are the same).</para>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<para>&sfs_compliant; s2.1.1.2</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.24</para>
|
|
<para>Changed: 2.2.0 Returns true even for invalid geometries if they are binary equal</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT ST_Equals(ST_GeomFromText('LINESTRING(0 0, 10 10)'),
|
|
ST_GeomFromText('LINESTRING(0 0, 5 5, 10 10)'));
|
|
st_equals
|
|
-----------
|
|
t
|
|
(1 row)
|
|
|
|
SELECT ST_Equals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
|
|
ST_GeomFromText('LINESTRING(0 0, 5 5, 10 10)'));
|
|
st_equals
|
|
-----------
|
|
t
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_IsValid"/>, <xref linkend="ST_OrderingEquals"/>, <xref linkend="ST_Reverse"/>, <xref linkend="ST_Within" /></para>
|
|
</refsection>
|
|
|
|
</refentry>
|
|
|
|
|
|
<refentry id="ST_Intersects">
|
|
<refnamediv>
|
|
<refname>ST_Intersects</refname>
|
|
|
|
<refpurpose>Tests if two geometries intersect (they have at least one point in common)</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Intersects</function></funcdef>
|
|
<paramdef>
|
|
<type>geometry</type>
|
|
<parameter>geomA</parameter>
|
|
</paramdef>
|
|
<paramdef>
|
|
<type>geometry</type>
|
|
<parameter>geomB</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Intersects</function></funcdef>
|
|
<paramdef>
|
|
<type>geography</type>
|
|
<parameter>geogA</parameter>
|
|
</paramdef>
|
|
<paramdef>
|
|
<type>geography</type>
|
|
<parameter>geogB</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>Compares two geometries and returns <varname>true</varname> if they intersect.
|
|
Geometries intersect if they have any point in common.
|
|
</para>
|
|
|
|
<para>
|
|
For geography, a distance tolerance of 0.00001 meters is used
|
|
(so points that are very close are considered to intersect).</para>
|
|
|
|
<para>Geometries intersect if their DE-9IM Intersection Matrix matches one of:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem> <para><code>T********</code></para> </listitem>
|
|
<listitem> <para><code>*T*******</code></para> </listitem>
|
|
<listitem> <para><code>***T*****</code></para> </listitem>
|
|
<listitem> <para><code>****T****</code></para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Spatial intersection is implied by all the other spatial relationship tests,
|
|
except <xref linkend="ST_Disjoint"/>, which tests that geometries do NOT intersect.</para>
|
|
|
|
<note><para>&index_aware;</para></note>
|
|
|
|
<para>Changed: 3.0.0 SFCGAL version removed and native support for 2D TINS added.</para>
|
|
<para>Enhanced: 2.5.0 Supports GEOMETRYCOLLECTION.</para>
|
|
<para>Enhanced: 2.3.0 Enhancement to PIP short-circuit extended to support MultiPoints with few points. Prior versions only supported point in polygon.</para>
|
|
<para>Performed by the GEOS module (for geometry), geography is native</para>
|
|
<para>Availability: 1.5 support for geography was introduced.</para>
|
|
<note>
|
|
<para>For geography, this function has a distance tolerance of about 0.00001 meters and uses the sphere rather
|
|
than spheroid calculation.</para>
|
|
</note>
|
|
<note>
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
</note>
|
|
<para>&sfs_compliant; s2.1.1.2 //s2.1.13.3
|
|
- ST_Intersects(g1, g2 ) --> Not (ST_Disjoint(g1, g2 ))
|
|
</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.27</para>
|
|
<para>&curve_support;</para>
|
|
<!-- Optionally mention support for Triangles and TINS -->
|
|
<para>&T_support;</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Geometry Examples</title>
|
|
<programlisting>SELECT ST_Intersects('POINT(0 0)'::geometry, 'LINESTRING ( 2 0, 0 2 )'::geometry);
|
|
st_intersects
|
|
---------------
|
|
f
|
|
(1 row)
|
|
SELECT ST_Intersects('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry);
|
|
st_intersects
|
|
---------------
|
|
t
|
|
(1 row)
|
|
|
|
-- Look up in table. Make sure table has a GiST index on geometry column for faster lookup.
|
|
SELECT id, name FROM cities WHERE ST_Intersects(geom, 'SRID=4326;POLYGON((28 53,27.707 52.293,27 52,26.293 52.293,26 53,26.293 53.707,27 54,27.707 53.707,28 53))');
|
|
id | name
|
|
----+-------
|
|
2 | Minsk
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Geography Examples</title>
|
|
<programlisting>SELECT ST_Intersects(
|
|
'SRID=4326;LINESTRING(-43.23456 72.4567,-43.23456 72.4568)'::geography,
|
|
'SRID=4326;POINT(-43.23456 72.4567772)'::geography
|
|
);
|
|
|
|
st_intersects
|
|
---------------
|
|
t
|
|
</programlisting>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="geometry_overlaps" />, <xref linkend="ST_3DIntersects" />, <xref linkend="ST_Disjoint"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_LineCrossingDirection">
|
|
<refnamediv>
|
|
<refname>ST_LineCrossingDirection</refname>
|
|
|
|
<refpurpose>Returns a number indicating the crossing behavior of two LineStrings</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_LineCrossingDirection</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>linestringA</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>linestringB</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Given two linestrings returns an integer between -3 and 3
|
|
indicating what kind of crossing behavior exists between them.
|
|
0 indicates no crossing.
|
|
This is only supported for <varname>LINESTRING</varname>s.
|
|
</para>
|
|
<para>The crossing number has the following meaning:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para> 0: LINE NO CROSS</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>-1: LINE CROSS LEFT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para> 1: LINE CROSS RIGHT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>-2: LINE MULTICROSS END LEFT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para> 2: LINE MULTICROSS END RIGHT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>-3: LINE MULTICROSS END SAME FIRST LEFT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para> 3: LINE MULTICROSS END SAME FIRST RIGHT</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>Availability: 1.4</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<para><emphasis role="bold">Example:</emphasis>
|
|
LINE CROSS LEFT and LINE CROSS RIGHT
|
|
</para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_linecrossingdirection03.png" />
|
|
</imageobject>
|
|
<caption><para>Blue: Line A; Green: Line B</para></caption>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<programlisting>
|
|
SELECT ST_LineCrossingDirection(lineA, lineB) As A_cross_B,
|
|
ST_LineCrossingDirection(lineB, lineA) As B_cross_A
|
|
FROM (SELECT
|
|
ST_GeomFromText('LINESTRING(25 169,89 114,40 70,86 43)') As lineA,
|
|
ST_GeomFromText('LINESTRING (20 140, 71 74, 161 53)') As lineB
|
|
) As foo;
|
|
|
|
A_cross_B | B_cross_A
|
|
-----------+-----------
|
|
-1 | 1
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Example:</emphasis>
|
|
LINE MULTICROSS END SAME FIRST LEFT and LINE MULTICROSS END SAME FIRST RIGHT
|
|
</para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_linecrossingdirection01.png" />
|
|
</imageobject>
|
|
<caption><para>Blue: Line A; Green: Line B</para></caption>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<programlisting>
|
|
SELECT ST_LineCrossingDirection(lineA, lineB) As A_cross_B,
|
|
ST_LineCrossingDirection(lineB, lineA) As B_cross_A
|
|
FROM (SELECT
|
|
ST_GeomFromText('LINESTRING(25 169,89 114,40 70,86 43)') As lineA,
|
|
ST_GeomFromText('LINESTRING(171 154,20 140,71 74,161 53)') As lineB
|
|
) As foo;
|
|
|
|
A_cross_B | B_cross_A
|
|
-----------+-----------
|
|
3 | -3
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Example:</emphasis>
|
|
LINE MULTICROSS END LEFT and LINE MULTICROSS END RIGHT
|
|
</para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_linecrossingdirection04.png" />
|
|
</imageobject>
|
|
<caption><para>Blue: Line A; Green: Line B</para></caption>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<programlisting>
|
|
SELECT ST_LineCrossingDirection(lineA, lineB) As A_cross_B,
|
|
ST_LineCrossingDirection(lineB, lineA) As B_cross_A
|
|
FROM (SELECT
|
|
ST_GeomFromText('LINESTRING(25 169,89 114,40 70,86 43)') As lineA,
|
|
ST_GeomFromText('LINESTRING(5 90, 71 74, 20 140, 171 154)') As lineB
|
|
) As foo;
|
|
|
|
A_cross_B | B_cross_A
|
|
-----------+-----------
|
|
-2 | 2
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Example:</emphasis>
|
|
Finds all streets that cross
|
|
</para>
|
|
<programlisting>
|
|
SELECT s1.gid, s2.gid, ST_LineCrossingDirection(s1.geom, s2.geom)
|
|
FROM streets s1 CROSS JOIN streets s2
|
|
ON (s1.gid != s2.gid AND s1.geom && s2.geom )
|
|
WHERE ST_LineCrossingDirection(s1.geom, s2.geom) > 0;
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Crosses" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_OrderingEquals">
|
|
<refnamediv>
|
|
<refname>ST_OrderingEquals</refname>
|
|
|
|
<refpurpose>Tests if two geometries represent the same geometry and have points in the same directional order</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_OrderingEquals</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>A</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>B</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>ST_OrderingEquals compares two geometries and returns t (TRUE) if the
|
|
geometries are equal and the coordinates are in the same order;
|
|
otherwise it returns f (FALSE).</para>
|
|
|
|
<note>
|
|
<para>This function is implemented as per the ArcSDE SQL
|
|
specification rather than SQL-MM.
|
|
http://edndoc.esri.com/arcsde/9.1/sql_api/sqlapi3.htm#ST_OrderingEquals</para>
|
|
</note>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.43</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT ST_OrderingEquals(ST_GeomFromText('LINESTRING(0 0, 10 10)'),
|
|
ST_GeomFromText('LINESTRING(0 0, 5 5, 10 10)'));
|
|
st_orderingequals
|
|
-----------
|
|
f
|
|
(1 row)
|
|
|
|
SELECT ST_OrderingEquals(ST_GeomFromText('LINESTRING(0 0, 10 10)'),
|
|
ST_GeomFromText('LINESTRING(0 0, 0 0, 10 10)'));
|
|
st_orderingequals
|
|
-----------
|
|
t
|
|
(1 row)
|
|
|
|
SELECT ST_OrderingEquals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
|
|
ST_GeomFromText('LINESTRING(0 0, 0 0, 10 10)'));
|
|
st_orderingequals
|
|
-----------
|
|
f
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="geometry_overlaps" />, <xref linkend="ST_Equals"/>, <xref linkend="ST_Reverse"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Overlaps">
|
|
<refnamediv>
|
|
<refname>ST_Overlaps</refname>
|
|
|
|
<refpurpose>Tests if two geometries have the same dimension and intersect, but each has at least one point not in the other</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Overlaps</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>A</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>B</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns TRUE if geometry A and B "spatially overlap".
|
|
Two geometries overlap if they have the same dimension,
|
|
their interiors intersect in that dimension.
|
|
and each has at least one point inside the other
|
|
(or equivalently, neither one covers the other).
|
|
The overlaps relationship is symmetric and irreflexive.
|
|
</para>
|
|
|
|
<note><para>&index_aware;
|
|
To avoid index use, use the function <function>_ST_Overlaps</function>.</para></note>
|
|
|
|
<para>Performed by the GEOS module</para>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
|
|
<para>&sfs_compliant; s2.1.1.2 // s2.1.13.3</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.32</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para><function>ST_Overlaps</function> returns <varname>TRUE</varname> in the following situations:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_overlaps01.png" />
|
|
</imageobject>
|
|
<caption><para><varname>MULTIPOINT</varname> / <varname>MULTIPOINT</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_overlaps02.png" />
|
|
</imageobject>
|
|
<caption><para><varname>LINESTRING</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_overlaps03.png" />
|
|
</imageobject>
|
|
<caption><para><varname>POLYGON</varname> / <varname>POLYGON</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_overlaps04.png" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para>A Point on a LineString is contained,
|
|
but since it has lower dimension it does not overlap or cross.</para>
|
|
<programlisting>
|
|
SELECT ST_Overlaps(a,b) AS overlaps, ST_Crosses(a,b) AS crosses,
|
|
ST_Intersects(a, b) AS intersects, ST_Contains(b,a) AS b_contains_a
|
|
FROM (SELECT ST_GeomFromText('POINT (100 100)') As a,
|
|
ST_GeomFromText('LINESTRING (30 50, 40 160, 160 40, 180 160)') AS b) AS t
|
|
|
|
overlaps | crosses | intersects | b_contains_a
|
|
---------+----------------------+--------------
|
|
f | f | t | t
|
|
</programlisting>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_overlaps05.png" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para>A LineString that partly covers a Polygon intersects and crosses,
|
|
but does not overlap since it has different dimension.</para>
|
|
<programlisting>
|
|
SELECT ST_Overlaps(a,b) AS overlaps, ST_Crosses(a,b) AS crosses,
|
|
ST_Intersects(a, b) AS intersects, ST_Contains(a,b) AS contains
|
|
FROM (SELECT ST_GeomFromText('POLYGON ((40 170, 90 30, 180 100, 40 170))') AS a,
|
|
ST_GeomFromText('LINESTRING(10 10, 190 190)') AS b) AS t;
|
|
|
|
overlap | crosses | intersects | contains
|
|
---------+---------+------------+--------------
|
|
f | t | t | f
|
|
</programlisting>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_overlaps06.png" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para>Two Polygons that intersect but with neither contained by the other overlap,
|
|
but do not cross because their intersection has the same dimension.</para>
|
|
<programlisting>
|
|
SELECT ST_Overlaps(a,b) AS overlaps, ST_Crosses(a,b) AS crosses,
|
|
ST_Intersects(a, b) AS intersects, ST_Contains(b, a) AS b_contains_a,
|
|
ST_Dimension(a) AS dim_a, ST_Dimension(b) AS dim_b,
|
|
ST_Dimension(ST_Intersection(a,b)) AS dim_int
|
|
FROM (SELECT ST_GeomFromText('POLYGON ((40 170, 90 30, 180 100, 40 170))') AS a,
|
|
ST_GeomFromText('POLYGON ((110 180, 20 60, 130 90, 110 180))') AS b) As t;
|
|
|
|
overlaps | crosses | intersects | b_contains_a | dim_a | dim_b | dim_int
|
|
----------+---------+------------+--------------+-------+-------+-----------
|
|
t | f | t | f | 2 | 2 | 2
|
|
</programlisting>
|
|
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_Contains"/>, <xref linkend="ST_Crosses"/>, <xref linkend="ST_Dimension"/>, <xref linkend="ST_Intersects"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Relate">
|
|
<refnamediv>
|
|
<refname>ST_Relate</refname>
|
|
|
|
<refpurpose>Tests if two geometries have a topological relationship
|
|
matching an Intersection Matrix pattern,
|
|
or computes their Intersection Matrix
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Relate</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>intersectionMatrixPattern</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_Relate</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_Relate</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>geomA</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>geomB</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>boundaryNodeRule</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
These functions allow testing and evaluating the spatial (topological) relationship between two geometries,
|
|
as defined by the <ulink url="http://en.wikipedia.org/wiki/DE-9IM">Dimensionally Extended 9-Intersection Model</ulink> (DE-9IM).
|
|
</para>
|
|
<para>
|
|
The DE-9IM is specified as a 9-element matrix indicating the dimension of the intersections between the
|
|
Interior, Boundary and Exterior of two geometries.
|
|
It is represented by a 9-character text string using the symbols 'F', '0', '1', '2'
|
|
(e.g. <code>'FF1FF0102'</code>).
|
|
</para>
|
|
<para>
|
|
A specific kind of spatial relationship can be tested by matching the intersection
|
|
matrix to an <emphasis>intersection matrix pattern</emphasis>.
|
|
Patterns can include the additional symbols 'T' (meaning "intersection is non-empty")
|
|
and '*' (meaning "any value").
|
|
Common spatial relationships are provided by the named functions
|
|
<xref linkend="ST_Contains" />, <xref linkend="ST_ContainsProperly" />,
|
|
<xref linkend="ST_Covers" />, <xref linkend="ST_CoveredBy" />,
|
|
<xref linkend="ST_Crosses" />, <xref linkend="ST_Disjoint" />, <xref linkend="ST_Equals" />,
|
|
<xref linkend="ST_Intersects" />, <xref linkend="ST_Overlaps" />, <xref linkend="ST_Touches" />,
|
|
and <xref linkend="ST_Within" />.
|
|
Using an explicit pattern allows testing multiple conditions of intersects, crosses, etc in one step.
|
|
It also allows testing spatial relationships which do not have a named spatial relationship function.
|
|
For example, the relationship "Interior-Intersects" has the DE-9IM pattern <code>T********</code>,
|
|
which is not evaluated by any named predicate.
|
|
</para>
|
|
<para>
|
|
For more information refer to <xref linkend="eval_spatial_rel" />.
|
|
</para>
|
|
|
|
<para><emphasis role="bold">Variant 1:</emphasis> Tests if two geometries are spatially related
|
|
according to the given <varname>intersectionMatrixPattern</varname>.
|
|
</para>
|
|
|
|
<note><para>Unlike most of the named spatial relationship predicates,
|
|
this does NOT automatically include an index call.
|
|
The reason is that some relationships are true for geometries
|
|
which do NOT intersect (e.g. Disjoint). If you are
|
|
using a relationship pattern that requires intersection, then include the &&
|
|
index call.
|
|
</para></note>
|
|
|
|
<note><para>It is better to use a named relationship function if available,
|
|
since they automatically use a spatial index where one exists.
|
|
Also, they may implement performance optimizations which are not available
|
|
with full relate evalation.
|
|
</para></note>
|
|
|
|
<para><emphasis role="bold">Variant 2:</emphasis> Returns the DE-9IM matrix string for the
|
|
spatial relationship between the two input geometries.
|
|
The matrix string can be tested for matching a DE-9IM pattern using <xref linkend="ST_RelateMatch" />.
|
|
</para>
|
|
|
|
<para><emphasis role="bold">Variant 3:</emphasis> Like variant 2,
|
|
but allows specifying a <emphasis role="bold">Boundary Node Rule</emphasis>.
|
|
A boundary node rule allows finer control over whether the endpoints of MultiLineStrings
|
|
are considered to lie in the DE-9IM Interior or Boundary.
|
|
The <varname>boundaryNodeRule</varname> values are:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para><code>1</code>: <emphasis role="bold">OGC-Mod2</emphasis> - line endpoints are in the Boundary if they occur an odd number of times.
|
|
This is the rule defined by the OGC SFS standard, and is the default for <function>ST_Relate</function>.
|
|
</para></listitem>
|
|
<listitem><para><code>2</code>: <emphasis role="bold">Endpoint</emphasis> - all endpoints are in the Boundary.
|
|
</para></listitem>
|
|
<listitem><para><code>3</code>: <emphasis role="bold">MultivalentEndpoint</emphasis> - endpoints are in the Boundary if they occur more than once.
|
|
In other words, the boundary is all the "attached" or "inner" endpoints (but not the "unattached/outer" ones).
|
|
</para></listitem>
|
|
<listitem><para><code>4</code>: <emphasis role="bold">MonovalentEndpoint</emphasis> - endpoints are in the Boundary if they occur only once.
|
|
In other words, the boundary is all the "unattached" or "outer" endpoints.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>This function is not in the OGC spec, but is implied. see s2.1.13.2</para>
|
|
<para>&sfs_compliant; s2.1.1.2 // s2.1.13.3</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.25</para>
|
|
<para>Performed by the GEOS module</para>
|
|
<para>Enhanced: 2.0.0 - added support for specifying boundary node rule.</para>
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<para>Using the boolean-valued function to test spatial relationships.</para>
|
|
<programlisting>
|
|
SELECT ST_Relate('POINT(1 2)', ST_Buffer( 'POINT(1 2)', 2), '0FFFFF212');
|
|
st_relate
|
|
-----------
|
|
t
|
|
|
|
SELECT ST_Relate(POINT(1 2)', ST_Buffer( 'POINT(1 2)', 2), '*FF*FF212');
|
|
st_relate
|
|
-----------
|
|
t
|
|
</programlisting>
|
|
|
|
<para>Testing a custom spatial relationship pattern as a query condition,
|
|
with <code>&&</code> to enable using a spatial index.</para>
|
|
<programlisting>
|
|
-- Find compounds that properly intersect (not just touch) a poly (Interior Intersects)
|
|
|
|
SELECT c.* , p.name As poly_name
|
|
FROM polys AS p
|
|
INNER JOIN compounds As c
|
|
ON c.geom && p.geom
|
|
AND ST_Relate(p.geom, c.geom,'T********');
|
|
</programlisting>
|
|
|
|
<para>Computing the intersection matrix for spatial relationships.</para>
|
|
<programlisting>
|
|
SELECT ST_Relate( 'POINT(1 2)',
|
|
ST_Buffer( 'POINT(1 2)', 2));
|
|
-----------
|
|
0FFFFF212
|
|
|
|
SELECT ST_Relate( 'LINESTRING(1 2, 3 4)',
|
|
'LINESTRING(5 6, 7 8)' );
|
|
-----------
|
|
FF1FF0102
|
|
</programlisting>
|
|
|
|
<para>Using different Boundary Node Rules to compute the spatial relationship
|
|
between a LineString and a MultiLineString with a duplicate endpoint <code>(3 3)</code>:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>Using the <emphasis role="bold">OGC-Mod2</emphasis> rule (1)
|
|
the duplicate endpoint is in the <emphasis role="bold">interior</emphasis> of the MultiLineString,
|
|
so the DE-9IM matrix entry [aB:bI] is <code>0</code> and [aB:bB] is <code>F</code>.
|
|
</para></listitem>
|
|
<listitem><para>Using the <emphasis role="bold">Endpoint</emphasis> rule (2)
|
|
the duplicate endpoint is in the <emphasis role="bold">boundary</emphasis> of the MultiLineString,
|
|
so the DE-9IM matrix entry [aB:bI] is <code>F</code> and [aB:bB] is <code>0</code>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<programlisting>
|
|
WITH data AS (SELECT
|
|
'LINESTRING(1 1, 3 3)'::geometry AS a_line,
|
|
'MULTILINESTRING((3 3, 3 5), (3 3, 5 3))':: geometry AS b_multiline
|
|
)
|
|
SELECT ST_Relate( a_line, b_multiline, 1) AS bnr_mod2,
|
|
ST_Relate( a_line, b_multiline, 2) AS bnr_endpoint
|
|
FROM data;
|
|
|
|
bnr_mod2 | bnr_endpoint
|
|
-----------+--------------
|
|
FF10F0102 | FF1F00102
|
|
</programlisting>
|
|
|
|
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="eval_spatial_rel" />, <xref linkend="ST_RelateMatch" />,
|
|
<xref linkend="ST_Contains" />, <xref linkend="ST_ContainsProperly" />,
|
|
<xref linkend="ST_Covers" />, <xref linkend="ST_CoveredBy" />,
|
|
<xref linkend="ST_Crosses" />, <xref linkend="ST_Disjoint" />, <xref linkend="ST_Equals" />,
|
|
<xref linkend="ST_Intersects" />, <xref linkend="ST_Overlaps" />,
|
|
<xref linkend="ST_Touches" />, <xref linkend="ST_Within" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_RelateMatch">
|
|
<refnamediv>
|
|
<refname>ST_RelateMatch</refname>
|
|
|
|
<refpurpose>Tests if a DE-9IM Intersection Matrix matches an Intersection Matrix pattern
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_RelateMatch</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>intersectionMatrix</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>intersectionMatrixPattern</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Tests if a <ulink url="http://en.wikipedia.org/wiki/DE-9IM">Dimensionally Extended 9-Intersection Model</ulink> (DE-9IM)
|
|
<varname>intersectionMatrix</varname> value satisfies
|
|
an <varname>intersectionMatrixPattern</varname>.
|
|
Intersection matrix values can be computed by <xref linkend="ST_Relate" />.
|
|
</para>
|
|
<para>
|
|
For more information refer to <xref linkend="eval_spatial_rel" />.
|
|
</para>
|
|
<para>Performed by the GEOS module</para>
|
|
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
SELECT ST_RelateMatch('101202FFF', 'TTTTTTFFF') ;
|
|
-- result --
|
|
t
|
|
</programlisting>
|
|
<para>Patterns for common spatial relationships
|
|
matched against intersection matrix values,
|
|
for a line in various positions relative to a polygon</para>
|
|
<programlisting>
|
|
SELECT pat.name AS relationship, pat.val AS pattern,
|
|
mat.name AS position, mat.val AS matrix,
|
|
ST_RelateMatch(mat.val, pat.val) AS match
|
|
FROM (VALUES ( 'Equality', 'T1FF1FFF1' ),
|
|
( 'Overlaps', 'T*T***T**' ),
|
|
( 'Within', 'T*F**F***' ),
|
|
( 'Disjoint', 'FF*FF****' )) AS pat(name,val)
|
|
CROSS JOIN
|
|
(VALUES ('non-intersecting', 'FF1FF0212'),
|
|
('overlapping', '1010F0212'),
|
|
('inside', '1FF0FF212')) AS mat(name,val);
|
|
|
|
relationship | pattern | position | matrix | match
|
|
--------------+-----------+------------------+-----------+-------
|
|
Equality | T1FF1FFF1 | non-intersecting | FF1FF0212 | f
|
|
Equality | T1FF1FFF1 | overlapping | 1010F0212 | f
|
|
Equality | T1FF1FFF1 | inside | 1FF0FF212 | f
|
|
Overlaps | T*T***T** | non-intersecting | FF1FF0212 | f
|
|
Overlaps | T*T***T** | overlapping | 1010F0212 | t
|
|
Overlaps | T*T***T** | inside | 1FF0FF212 | f
|
|
Within | T*F**F*** | non-intersecting | FF1FF0212 | f
|
|
Within | T*F**F*** | overlapping | 1010F0212 | f
|
|
Within | T*F**F*** | inside | 1FF0FF212 | t
|
|
Disjoint | FF*FF**** | non-intersecting | FF1FF0212 | t
|
|
Disjoint | FF*FF**** | overlapping | 1010F0212 | f
|
|
Disjoint | FF*FF**** | inside | 1FF0FF212 | f
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="eval_spatial_rel" />, <xref linkend="ST_Relate" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Touches">
|
|
<refnamediv>
|
|
<refname>ST_Touches</refname>
|
|
|
|
<refpurpose>Tests if two geometries have at least one point in common,
|
|
but their interiors do not intersect</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Touches</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>A</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>B</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns <varname>TRUE</varname> if A and B intersect,
|
|
but their interiors do not intersect. Equivalently, A and B have at least one point in common,
|
|
and the common points lie in at least one boundary.
|
|
For Point/Point inputs the relationship is always <varname>FALSE</varname>,
|
|
since points do not have a boundary.</para>
|
|
|
|
<para>In mathematical terms, this relationship is:</para>
|
|
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches-math.gif" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
|
|
<para>This relationship holds if the DE-9IM Intersection Matrix for the two geometries matches one of:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><markup>FT*******</markup></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><markup>F**T*****</markup></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><markup>F***T****</markup></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<note><para>&index_aware;
|
|
To avoid using an index, use <function>_ST_Touches</function> instead.</para>
|
|
</note>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<para>&sfs_compliant; s2.1.1.2 // s2.1.13.3</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.28</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<para>The <function>ST_Touches</function> predicate returns <varname>TRUE</varname> in the following examples.</para>
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<tbody>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches01.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>POLYGON</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches02.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>POLYGON</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches03.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches04.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>LINESTRING</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches05.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>LINESTRING</varname> / <varname>LINESTRING</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
|
|
<entry><para><informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_touches06.png" />
|
|
</imageobject>
|
|
|
|
<caption><para><varname>POLYGON</varname> / <varname>POINT</varname></para></caption>
|
|
</mediaobject>
|
|
</informalfigure></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<programlisting>SELECT ST_Touches('LINESTRING(0 0, 1 1, 0 2)'::geometry, 'POINT(1 1)'::geometry);
|
|
st_touches
|
|
------------
|
|
f
|
|
(1 row)
|
|
|
|
SELECT ST_Touches('LINESTRING(0 0, 1 1, 0 2)'::geometry, 'POINT(0 2)'::geometry);
|
|
st_touches
|
|
------------
|
|
t
|
|
(1 row)</programlisting>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_Within">
|
|
<refnamediv>
|
|
<refname>ST_Within</refname>
|
|
|
|
<refpurpose>Tests if every point of A lies in B, and their interiors have a point in common</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_Within</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>A</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>B</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns TRUE if geometry A is within geometry B.
|
|
A is within B if and only if all points of A lie inside (i.e. in the interior or boundary of) B
|
|
(or equivalently, no points of A lie in the exterior of B),
|
|
and the interiors of A and B have at least one point in common.
|
|
</para>
|
|
<para>For this function to make
|
|
sense, the source geometries must both be of the same coordinate projection,
|
|
having the same SRID.
|
|
</para>
|
|
<para>The within relationship is reflexive: every geometry is within itself.
|
|
The relationship is antisymmetric: if <code>ST_Within(A,B) = true</code> and <code>ST_Within(B,A) = true</code>, then
|
|
the two geometries must be topologically equal (<code>ST_Equals(A,B) = true</code>).</para>
|
|
|
|
<para>ST_Within is the converse of <xref linkend="ST_Contains"/>.
|
|
So, <code>ST_Within(A,B) = ST_Contains(B,A)</code>.</para>
|
|
|
|
<note><para>Because the interiors must have a common point, a subtlety of the definition is that
|
|
lines and points lying fully in the boundary of polygons or lines are <emphasis>not</emphasis> within the geometry.
|
|
For further details see <ulink url="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Subtleties of OGC Covers, Contains, Within</ulink>.
|
|
The <xref linkend="ST_CoveredBy" /> predicate provides a more inclusive relationship.
|
|
</para></note>
|
|
|
|
<note><para>&index_aware;
|
|
To avoid index use, use the function <function>_ST_Within</function>.</para></note>
|
|
|
|
<para>Performed by the GEOS module</para>
|
|
|
|
<para>Enhanced: 2.3.0 Enhancement to PIP short-circuit for geometry extended to support MultiPoints with few points. Prior versions only supported point in polygon.</para>
|
|
|
|
<important>
|
|
<para>Enhanced: 3.0.0 enabled support for <varname>GEOMETRYCOLLECTION</varname></para>
|
|
</important>
|
|
|
|
<important>
|
|
<para>Do not use this function with invalid geometries. You will get unexpected results.</para>
|
|
</important>
|
|
|
|
<para>NOTE: this is the "allowable" version that returns a
|
|
boolean, not an integer.</para>
|
|
|
|
<para>&sfs_compliant; s2.1.1.2 // s2.1.13.3
|
|
- a.Relate(b, 'T*F**F***')
|
|
</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 5.1.30</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
--a circle within a circle
|
|
SELECT ST_Within(smallc,smallc) As smallinsmall,
|
|
ST_Within(smallc, bigc) As smallinbig,
|
|
ST_Within(bigc,smallc) As biginsmall,
|
|
ST_Within(ST_Union(smallc, bigc), bigc) as unioninbig,
|
|
ST_Within(bigc, ST_Union(smallc, bigc)) as biginunion,
|
|
ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion
|
|
FROM
|
|
(
|
|
SELECT ST_Buffer(ST_GeomFromText('POINT(50 50)'), 20) As smallc,
|
|
ST_Buffer(ST_GeomFromText('POINT(50 50)'), 40) As bigc) As foo;
|
|
--Result
|
|
smallinsmall | smallinbig | biginsmall | unioninbig | biginunion | bigisunion
|
|
--------------+------------+------------+------------+------------+------------
|
|
t | t | f | t | t | t
|
|
(1 row)
|
|
</programlisting>
|
|
|
|
<para><inlinemediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="images/st_within01.png" />
|
|
</imageobject>
|
|
</inlinemediaobject> </para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_Contains"/>, <xref linkend="ST_CoveredBy"/>, <xref linkend="ST_Equals"/>, <xref linkend="ST_IsValid"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
</sect2>
|
|
<!-- ============================================================================== -->
|
|
|
|
<sect2>
|
|
<title>Distance Relationships</title>
|
|
|
|
<refentry id="ST_3DDWithin">
|
|
<refnamediv>
|
|
<refname>ST_3DDWithin</refname>
|
|
|
|
<refpurpose>Tests if two 3D geometries are within a given 3D distance</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_3DDWithin</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g1</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g2</parameter></paramdef>
|
|
|
|
<paramdef><type>double precision </type>
|
|
<parameter>distance_of_srid</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns true if the 3D distance between two geometry values is no larger than
|
|
distance <varname>distance_of_srid</varname>.
|
|
The distance is specified in units defined by the spatial reference system of the geometries.
|
|
For this function to make sense
|
|
the source geometries must be in the same coordinate system (have the same SRID).
|
|
</para>
|
|
|
|
<note><para>&index_aware;</para></note>
|
|
|
|
<para>&Z_support;</para>
|
|
<!-- Optionally mention supports Polyhedral Surface -->
|
|
<para>&P_support;</para>
|
|
<para>&sqlmm_compliant; SQL-MM ?</para>
|
|
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
-- Geometry example - units in meters (SRID: 2163 US National Atlas Equal area) (3D point and line compared 2D point and line)
|
|
-- Note: currently no vertical datum support so Z is not transformed and assumed to be same units as final.
|
|
SELECT ST_3DDWithin(
|
|
ST_Transform(ST_GeomFromEWKT('SRID=4326;POINT(-72.1235 42.3521 4)'),2163),
|
|
ST_Transform(ST_GeomFromEWKT('SRID=4326;LINESTRING(-72.1260 42.45 15, -72.123 42.1546 20)'),2163),
|
|
126.8
|
|
) As within_dist_3d,
|
|
ST_DWithin(
|
|
ST_Transform(ST_GeomFromEWKT('SRID=4326;POINT(-72.1235 42.3521 4)'),2163),
|
|
ST_Transform(ST_GeomFromEWKT('SRID=4326;LINESTRING(-72.1260 42.45 15, -72.123 42.1546 20)'),2163),
|
|
126.8
|
|
) As within_dist_2d;
|
|
|
|
within_dist_3d | within_dist_2d
|
|
----------------+----------------
|
|
f | t
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="ST_3DDFullyWithin"/>,
|
|
<xref linkend="ST_DWithin"/>, <xref linkend="ST_DFullyWithin"/>,
|
|
<xref linkend="ST_3DDistance"/>, <xref linkend="ST_Distance"/>,
|
|
<xref linkend="ST_3DMaxDistance" />, <xref linkend="ST_Transform" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_3DDFullyWithin">
|
|
<refnamediv>
|
|
<refname>ST_3DDFullyWithin</refname>
|
|
|
|
<refpurpose>Tests if two 3D geometries are entirely within a given 3D distance</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_3DDFullyWithin</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g1</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g2</parameter></paramdef>
|
|
|
|
<paramdef><type>double precision </type>
|
|
<parameter>distance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns true if the 3D geometries are fully within the specified distance
|
|
of one another. The distance is specified in units defined by the
|
|
spatial reference system of the geometries. For this function to make
|
|
sense, the source geometries must both be of the same coordinate projection,
|
|
having the same SRID.</para>
|
|
|
|
<note><para>&index_aware;</para></note>
|
|
|
|
<para>Availability: 2.0.0</para>
|
|
<para>&Z_support;</para>
|
|
<!-- Optionally mention supports Polyhedral Surface -->
|
|
<para>&P_support;</para>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- This compares the difference between fully within and distance within as well
|
|
-- as the distance fully within for the 2D footprint of the line/point vs. the 3d fully within
|
|
SELECT ST_3DDFullyWithin(geom_a, geom_b, 10) as D3DFullyWithin10, ST_3DDWithin(geom_a, geom_b, 10) as D3DWithin10,
|
|
ST_DFullyWithin(geom_a, geom_b, 20) as D2DFullyWithin20,
|
|
ST_3DDFullyWithin(geom_a, geom_b, 20) as D3DFullyWithin20 from
|
|
(select ST_GeomFromEWKT('POINT(1 1 2)') as geom_a,
|
|
ST_GeomFromEWKT('LINESTRING(1 5 2, 2 7 20, 1 9 100, 14 12 3)') as geom_b) t1;
|
|
d3dfullywithin10 | d3dwithin10 | d2dfullywithin20 | d3dfullywithin20
|
|
------------------+-------------+------------------+------------------
|
|
f | t | t | f </programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_3DDWithin"/>,
|
|
<xref linkend="ST_DWithin"/>, <xref linkend="ST_DFullyWithin"/>,
|
|
<xref linkend="ST_3DMaxDistance"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_DFullyWithin">
|
|
<refnamediv>
|
|
<refname>ST_DFullyWithin</refname>
|
|
|
|
<refpurpose>Tests if two geometries are entirely within a given distance</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_DFullyWithin</function></funcdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g1</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g2</parameter></paramdef>
|
|
|
|
<paramdef><type>double precision </type>
|
|
<parameter>distance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns true if the geometries are entirely within the specified distance
|
|
of one another. The distance is specified in units defined by the
|
|
spatial reference system of the geometries. For this function to make
|
|
sense, the source geometries must both be of the same coordinate projection,
|
|
having the same SRID.</para>
|
|
|
|
<note><para>&index_aware;</para></note>
|
|
|
|
<para>Availability: 1.5.0</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>postgis=# SELECT ST_DFullyWithin(geom_a, geom_b, 10) as DFullyWithin10, ST_DWithin(geom_a, geom_b, 10) as DWithin10, ST_DFullyWithin(geom_a, geom_b, 20) as DFullyWithin20 from
|
|
(select ST_GeomFromText('POINT(1 1)') as geom_a,ST_GeomFromText('LINESTRING(1 5, 2 7, 1 9, 14 12)') as geom_b) t1;
|
|
|
|
-----------------
|
|
DFullyWithin10 | DWithin10 | DFullyWithin20 |
|
|
---------------+----------+---------------+
|
|
f | t | t | </programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_MaxDistance"/>,
|
|
<xref linkend="ST_DWithin"/>, <xref linkend="ST_3DDWithin"/>, <xref linkend="ST_3DDFullyWithin"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_DWithin">
|
|
<refnamediv>
|
|
<refname>ST_DWithin</refname>
|
|
|
|
<refpurpose>Tests if two geometries are within a given distance</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_DWithin</function></funcdef>
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g1</parameter></paramdef>
|
|
|
|
<paramdef><type>geometry </type>
|
|
<parameter>g2</parameter></paramdef>
|
|
|
|
<paramdef><type>double precision </type>
|
|
<parameter>distance_of_srid</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_DWithin</function></funcdef>
|
|
<paramdef><type>geography </type>
|
|
<parameter>gg1</parameter></paramdef>
|
|
|
|
<paramdef><type>geography </type>
|
|
<parameter>gg2</parameter></paramdef>
|
|
|
|
<paramdef><type>double precision </type>
|
|
<parameter>distance_meters</parameter></paramdef>
|
|
|
|
<paramdef choice="opt"><type>boolean </type>
|
|
<parameter>use_spheroid = true</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns true if the geometries are within a given distance</para>
|
|
|
|
<para>For <type>geometry</type>: The distance is specified in units defined by the
|
|
spatial reference system of the geometries. For this function to make
|
|
sense, the source geometries must be in the same coordinate system
|
|
(have the same SRID).</para>
|
|
|
|
<para>For <type>geography</type>: units are in meters and distance measurement
|
|
defaults to <varname>use_spheroid = true</varname>.
|
|
For faster evaluation use <varname>use_spheroid = false</varname> to measure on the sphere.
|
|
</para>
|
|
|
|
<note><para>Use <xref linkend="ST_3DDWithin"/> for 3D geometries.</para></note>
|
|
|
|
<note>
|
|
<para>This function call includes a bounding box
|
|
comparison that makes use of any indexes that are available on
|
|
the geometries.</para>
|
|
</note>
|
|
|
|
<para>&sfs_compliant;</para>
|
|
<para>Availability: 1.5.0 support for geography was introduced</para>
|
|
<para>Enhanced: 2.1.0 improved speed for geography. See <ulink url="http://blog.opengeo.org/2012/07/12/making-geography-faster/">Making Geography faster</ulink> for details.</para>
|
|
<para>Enhanced: 2.1.0 support for curved geometries was introduced.</para>
|
|
|
|
<para>Prior to 1.3, <xref linkend="ST_Expand"/> was commonly used in conjunction with && and ST_Distance to
|
|
test for distance, and in pre-1.3.4 this function used that logic.
|
|
From 1.3.4, ST_DWithin uses a faster short-circuit distance function.</para>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Find the nearest hospital to each school
|
|
-- that is within 3000 units of the school.
|
|
-- We do an ST_DWithin search to utilize indexes to limit our search list
|
|
-- that the non-indexable ST_Distance needs to process
|
|
-- If the units of the spatial reference is meters then units would be meters
|
|
SELECT DISTINCT ON (s.gid) s.gid, s.school_name, s.geom, h.hospital_name
|
|
FROM schools s
|
|
LEFT JOIN hospitals h ON ST_DWithin(s.geom, h.geom, 3000)
|
|
ORDER BY s.gid, ST_Distance(s.geom, h.geom);
|
|
|
|
-- The schools with no close hospitals
|
|
-- Find all schools with no hospital within 3000 units
|
|
-- away from the school. Units is in units of spatial ref (e.g. meters, feet, degrees)
|
|
SELECT s.gid, s.school_name
|
|
FROM schools s
|
|
LEFT JOIN hospitals h ON ST_DWithin(s.geom, h.geom, 3000)
|
|
WHERE h.gid IS NULL;
|
|
|
|
-- Find broadcasting towers that receiver with limited range can receive.
|
|
-- Data is geometry in Spherical Mercator (SRID=3857), ranges are approximate.
|
|
|
|
-- Create geometry index that will check proximity limit of user to tower
|
|
CREATE INDEX ON broadcasting_towers using gist (geom);
|
|
|
|
-- Create geometry index that will check proximity limit of tower to user
|
|
CREATE INDEX ON broadcasting_towers using gist (ST_Expand(geom, sending_range));
|
|
|
|
-- Query towers that 4-kilometer receiver in Minsk Hackerspace can get
|
|
-- Note: two conditions, because shorter LEAST(b.sending_range, 4000) will not use index.
|
|
SELECT b.tower_id, b.geom
|
|
FROM broadcasting_towers b
|
|
WHERE ST_DWithin(b.geom, 'SRID=3857;POINT(3072163.4 7159374.1)', 4000)
|
|
AND ST_DWithin(b.geom, 'SRID=3857;POINT(3072163.4 7159374.1)', b.sending_range);
|
|
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_Distance"/>, <xref linkend="ST_3DDWithin"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_PointInsideCircle">
|
|
<refnamediv>
|
|
<refname>ST_PointInsideCircle</refname>
|
|
|
|
<refpurpose>Tests if a point geometry is inside a circle defined by a center and radius</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>ST_PointInsideCircle</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
|
|
<paramdef><type>float </type> <parameter>center_x</parameter></paramdef>
|
|
<paramdef><type>float </type> <parameter>center_y</parameter></paramdef>
|
|
<paramdef><type>float </type> <parameter>radius</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns true if the geometry is a point and is inside the
|
|
circle with center <varname>center_x</varname>,<varname>center_y</varname>
|
|
and radius <varname>radius</varname>.
|
|
</para>
|
|
<warning><para>Does not use spatial indexes. Use <xref linkend="ST_DWithin" /> instead.</para></warning>
|
|
|
|
<para>Availability: 1.2</para>
|
|
<para>Changed: 2.2.0 In prior versions this was called ST_Point_Inside_Circle</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT ST_PointInsideCircle(ST_Point(1,2), 0.5, 2, 3);
|
|
st_pointinsidecircle
|
|
------------------------
|
|
t
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_DWithin" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|