From 965c2cc40596a39fa725d25383d2765e2dbc41cd Mon Sep 17 00:00:00 2001 From: Darafei Praliaskouski Date: Sat, 21 Jul 2018 16:35:59 +0000 Subject: [PATCH] Clarify eps units on DBSCAN. Add ST_Distance examples. Closes https://github.com/postgis/postgis/pull/261 git-svn-id: http://svn.osgeo.org/postgis/trunk@16655 b70326c6-7e19-0410-871a-916f4a2858ee --- doc/reference_measure.xml | 53 +++++++++++++++++++++++++++------------ doc/reference_type.xml | 3 ++- 2 files changed, 39 insertions(+), 17 deletions(-) diff --git a/doc/reference_measure.xml b/doc/reference_measure.xml index 388b91467..1f2837e7b 100644 --- a/doc/reference_measure.xml +++ b/doc/reference_measure.xml @@ -1158,7 +1158,7 @@ SELECT ST_AsText( Returns cluster number for each input geometry, based on a 2D implementation of the Density-based spatial clustering of applications with noise (DBSCAN) algorithm. Unlike , it does not require the number of clusters to be specified, but instead - uses the desired distance (eps) and density(minpoints) parameters to construct each cluster. + uses the desired distance (eps) and density (minpoints) parameters to construct each cluster. @@ -1166,12 +1166,12 @@ SELECT ST_AsText( - A "core" geometry, that is within eps distance (Cartesian) of at least minpoints input geometries (including itself) or + A "core" geometry, that is within eps distance of at least minpoints input geometries (including itself) or - A "border" geometry, that is within eps distance of a core geometry. + A "border" geometry, that is within eps distance of a core geometry. @@ -2385,7 +2385,7 @@ SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry); See Also - ST_Intersects + @@ -2393,8 +2393,9 @@ SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry); ST_Distance - For geometry type Returns the 2D Cartesian distance between two geometries in - projected units (based on spatial ref). For geography type defaults to return minimum geodesic distance between two geographies in meters. + For geometry type returns the 2D Cartesian distance between two geometries in + projected units (based on spatial reference system). + For geography type defaults to return minimum geodesic distance between two geographies in meters. @@ -2435,8 +2436,8 @@ SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry); Description - For geometry type returns the minimum 2D Cartesian distance between two geometries in - projected units (spatial ref units). For geography type defaults to return the minimum geodesic distance between two geographies in meters. If use_spheroid is + For type returns the minimum 2D Cartesian distance between two geometries in + projected units (spatial ref units). For type defaults to return the minimum geodesic distance between two geographies in meters. If use_spheroid is false, a faster sphere calculation is used instead of a spheroid. &sfs_compliant; @@ -2456,17 +2457,37 @@ SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry); --Geometry example - units in planar degrees 4326 is WGS 84 long lat unit=degrees SELECT ST_Distance( - ST_GeomFromText('POINT(-72.1235 42.3521)',4326), - ST_GeomFromText('LINESTRING(-72.1260 42.45, -72.123 42.1546)', 4326) + 'SRID=4326;POINT(-72.1235 42.3521)'::geometry, + 'SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)'::geometry ); st_distance ----------------- 0.00150567726382282 +-- Geometry example - units in meters (SRID: 3857, proportional to pixels on popular web maps) +-- although the value is off, nearby ones can be compared correctly, +-- which makes it a good choice for algorithms like KNN or KMeans. +SELECT ST_Distance( + ST_Transform('SRID=4326;POINT(-72.1235 42.3521)'::geometry, 3857), + ST_Transform('SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)'::geometry, 3857) + ); +st_distance +----------------- +167.441410065196 + +-- Geometry example - units in meters (SRID: 3857 as above, but corrected by cos(lat) to account for distortion) +SELECT ST_Distance( + ST_Transform('SRID=4326;POINT(-72.1235 42.3521)'::geometry, 3857), + ST_Transform('SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)'::geometry, 3857) + ) * cosd(42.3521); +st_distance +----------------- +123.742351254151 + -- Geometry example - units in meters (SRID: 26986 Massachusetts state plane meters) (most accurate for Massachusetts) SELECT ST_Distance( - ST_Transform(ST_GeomFromText('POINT(-72.1235 42.3521)',4326),26986), - ST_Transform(ST_GeomFromText('LINESTRING(-72.1260 42.45, -72.123 42.1546)', 4326),26986) + ST_Transform('SRID=4326;POINT(-72.1235 42.3521)'::geometry, 26986), + ST_Transform('SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)'::geometry, 26986) ); st_distance ----------------- @@ -2474,8 +2495,8 @@ st_distance -- Geometry example - units in meters (SRID: 2163 US National Atlas Equal area) (least accurate) SELECT ST_Distance( - ST_Transform(ST_GeomFromText('POINT(-72.1235 42.3521)',4326),2163), - ST_Transform(ST_GeomFromText('LINESTRING(-72.1260 42.45, -72.123 42.1546)', 4326),2163) + ST_Transform('SRID=4326;POINT(-72.1235 42.3521)'::geometry, 2163), + ST_Transform('SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)'::geometry, 2163) ); st_distance @@ -2488,8 +2509,8 @@ st_distance -- same as geometry example but note units in meters - use sphere for slightly faster less accurate SELECT ST_Distance(gg1, gg2) As spheroid_dist, ST_Distance(gg1, gg2, false) As sphere_dist FROM (SELECT - ST_GeogFromText('SRID=4326;POINT(-72.1235 42.3521)') As gg1, - ST_GeogFromText('SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)') As gg2 + 'SRID=4326;POINT(-72.1235 42.3521)'::geography as gg1, + 'SRID=4326;LINESTRING(-72.1260 42.45, -72.123 42.1546)'::geography as gg2 ) As foo ; spheroid_dist | sphere_dist diff --git a/doc/reference_type.xml b/doc/reference_type.xml index 7ca281e4d..476db0cd0 100644 --- a/doc/reference_type.xml +++ b/doc/reference_type.xml @@ -77,7 +77,8 @@ Description - geometry is a fundamental postgis spatial data type used to represent a feature in the Euclidean coordinate system. + geometry is a fundamental PostGIS spatial data type used to represent a feature in the Euclidean coordinate system. + All spatial operations on geometry are using units of the Spatial Reference System the geomtry is in. -- 2.40.0