From: Martin Davis Date: Fri, 3 May 2019 22:05:26 +0000 (+0000) Subject: Improve doc Reference Constructors X-Git-Tag: 3.0.0alpha1~12 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=68b4d67071929a6e84347bcbdd4a90a44727ba38;p=postgis Improve doc Reference Constructors git-svn-id: http://svn.osgeo.org/postgis/trunk@17431 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference_constructor.xml b/doc/reference_constructor.xml index 094bc5dd2..5cb7da34f 100644 --- a/doc/reference_constructor.xml +++ b/doc/reference_constructor.xml @@ -5,7 +5,7 @@ ST_Collect - Creates a GeometryCollection or Multi* value from a set of other geometries. + Creates a GeometryCollection or Multi* geometry from a set of geometries. @@ -28,102 +28,97 @@ Description - Collects geometries into an appropriate geometry collection type. - The output geometry is either a MULTI* or a - GEOMETRYCOLLECTION, depending on whether the input geometries have the same or different types + Collects geometries into a geometry collection. + The result is either a Multi* or a + GeometryCollection, depending on whether the input geometries have the same or different types (homogeneous or heterogeneous). The input geometries are left unchanged within the collection. - - Comes in 3 variants. - Variant 1 collects 2 geometries. - Variant 2 takes an array of geometries. - Variant 3 is an aggregate function that takes a set of geometries. - - - Two-argument and array variants: Returns a geometry which is a collection of the - input geometries. - Aggregate variant: Returns a GEOMETRYCOLLECTION or a MULTI geometry - from a set of geometries. The function is an "aggregate" - function in the terminology of PostgreSQL. That means that it - operates on rows of data, in the same way the SUM() and AVG() - functions do. For example, "SELECT ST_Collect(GEOM) FROM GEOMTABLE - GROUP BY ATTRCOLUMN" returns a separate collection geometry for - each distinct value of ATTRCOLUMN. + Variant 1: accepts two input geometries + Variant 2: accepts an array of geometries + Variant 3: aggregate function accepting a rowset of geometries. - If any of the input geometries are collections (MULTI* or GEOMETRYCOLLECTION) - ST_Collect will return a GEOMETRYCOLLECTION (since that is the only type - which can contain nested collections). - To prevent this, use to expand the - input collections to their elements, and then collect the atomic geometries (see example below). - - - ST_Collect and ST_Union are superficially similar, but in fact operate very differently. - ST_Collect simply aggregates geometries into a collection without changing them in any way. + If any of the input geometries are collections (Multi* or GeometryCollection) + ST_Collect returns a GeometryCollection (since that is the only type + which can contain nested collections). + To prevent this, use in a subquery to expand the + input collections to their atomic elements (see example below). + + + ST_Collect and appear similar, but in fact operate quite differently. + ST_Collect aggregates geometries into a collection without changing them in any way. ST_Union geometrically merges geometries where they overlap, and splits linestrings at intersections. It may return single geometries when it dissolves boundaries. Availability: 1.4.0 - ST_Collect(geomarray) was introduced. ST_Collect was enhanced to handle more geometries faster. - &Z_support; - &curve_support; This method supports Circular Strings - and Curves, but will never return a MULTICURVE or MULTI as one - would expect and PostGIS does not currently support those. + &Z_support; + &curve_support; - Examples - Aggregate example - SELECT stusps, ST_Collect(f.the_geom) as singlegeom - FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom - FROM - somestatetable ) As f -GROUP BY stusps - Non-Aggregate example - SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'), + Examples - Two-input variant + Collect 2D points. + +SELECT ST_AsText( ST_Collect( ST_GeomFromText('POINT(1 2)'), ST_GeomFromText('POINT(-2 3)') )); st_astext ---------- MULTIPOINT(1 2,-2 3) + ---Collect 2 d points -SELECT ST_AsText(ST_Collect(ST_GeomFromText('POINT(1 2)'), - ST_GeomFromText('POINT(1 2)') ) ); - -st_astext ----------- -MULTIPOINT(1 2,1 2) - ---Collect 3d points -SELECT ST_AsEWKT(ST_Collect(ST_GeomFromEWKT('POINT(1 2 3)'), +Collect 3D points. + +SELECT ST_AsEWKT( ST_Collect( ST_GeomFromEWKT('POINT(1 2 3)'), ST_GeomFromEWKT('POINT(1 2 4)') ) ); st_asewkt ------------------------- MULTIPOINT(1 2 3,1 2 4) + - --Example with curves -SELECT ST_AsText(ST_Collect(ST_GeomFromText('CIRCULARSTRING(220268 150415,220227 150505,220227 150406)'), -ST_GeomFromText('CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)'))); - st_astext +Collect curves. + +SELECT ST_AsText( ST_Collect( 'CIRCULARSTRING(220268 150415,220227 150505,220227 150406)', + 'CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)')); + + st_astext ------------------------------------------------------------------------------------ - GEOMETRYCOLLECTION(CIRCULARSTRING(220268 150415,220227 150505,220227 150406), +MULTICURVE(CIRCULARSTRING(220268 150415,220227 150505,220227 150406), CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)) - ---New ST_Collect array construct -SELECT ST_Collect(ARRAY(SELECT the_geom FROM sometable)); - -SELECT ST_AsText(ST_Collect(ARRAY[ST_GeomFromText('LINESTRING(1 2, 3 4)'), - ST_GeomFromText('LINESTRING(3 4, 4 5)')])) As wktcollect; + + + +Examples - Array variant +Using an array constructor for a subquery. + +SELECT ST_Collect( ARRAY( SELECT the_geom FROM sometable ) ); + +Using an array constructor for values. + +SELECT ST_AsText( ST_Collect( + ARRAY[ ST_GeomFromText('LINESTRING(1 2, 3 4)'), + ST_GeomFromText('LINESTRING(3 4, 4 5)') ] )) As wktcollect; --wkt collect -- MULTILINESTRING((1 2,3 4),(3 4,4 5)) - + + + Examples - Aggregate variant + Creating multiple collections by grouping geometries in a table. + +SELECT stusps, ST_Collect(f.the_geom) as geom + FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom + FROM + somestatetable ) As f + GROUP BY stusps + + See Also @@ -151,29 +146,80 @@ MULTILINESTRING((1 2,3 4),(3 4,4 5)) Description Creates a LineString from a MultiPoint geometry. + + Use to create lines from Point or LineString inputs. + &Z_support; Examples - + Create a 3D line string from a 3D MultiPoint ---Create a 3d line string from a 3d multipoint -SELECT ST_AsEWKT(ST_LineFromMultiPoint(ST_GeomFromEWKT('MULTIPOINT(1 2 3, 4 5 6, 7 8 9)'))); +SELECT ST_AsEWKT( ST_LineFromMultiPoint('MULTIPOINT(1 2 3, 4 5 6, 7 8 9)') )); + --result-- LINESTRING(1 2 3,4 5 6,7 8 9) - + See Also - , , + , + + + ST_MakeEnvelope + + Creates a rectangular Polygon from minimum and maximum coordinates. + + + + + + geometry ST_MakeEnvelope + float xmin + float ymin + float xmax + float ymax + integer srid=unknown + + + + + + Description + + Creates a rectangular Polygon from the minimum and maximum values for X and Y. + Input values must be in the spatial reference system specified by the SRID. + If no SRID is specified the unknown spatial reference system (SRID 0) is used. + + Availability: 1.5 + Enhanced: 2.0: Ability to specify an envelope without specifying an SRID was introduced. + + + + + Example: Building a bounding box polygon + +SELECT ST_AsText( ST_MakeEnvelope(10, 10, 11, 11, 4326) ); + +st_asewkt +----------- +POLYGON((10 10, 10 11, 11 11, 11 10, 10 10)) + + + + See Also + , , + + + ST_MakeLine @@ -185,18 +231,18 @@ LINESTRING(1 2 3,4 5 6,7 8 9) geometry ST_MakeLine - geometry set geoms + geometry geom1 + geometry geom2 geometry ST_MakeLine - geometry geom1 - geometry geom2 + geometry[] geoms_array geometry ST_MakeLine - geometry[] geoms_array + geometry set geoms @@ -204,16 +250,19 @@ LINESTRING(1 2 3,4 5 6,7 8 9) Description - ST_MakeLine comes in 3 forms: a spatial aggregate that takes - rows of point, multipoint, or line geometries and returns a line string, a - function that takes an array of point, multipoint, or line, and a regular - function that takes two point, multipoint, or line geometries. You - might want to use a subselect to order points before feeding them - to the aggregate version of this function. + Creates a LineString containing the points of Point, MultiPoint, or LineString geometries. + Other geometry types cause an error. + + Variant 1: accepts two input geometries + Variant 2: accepts an array of geometries + Variant 3: aggregate function accepting a rowset of geometries. + To ensure the order of the input geometries use ORDER BY in the function call, + or a subquery with an ORDER BY clause. - Inputs other than point, multipoint, or lines are ignored. - When adding line components common nodes at the beginning of lines are removed from the output. Common nodes in point and multipoint inputs are not removed. + Repeated nodes at the beginning of input LineStrings are collapsed to a single point. + Repeated points in Point and MultiPoint inputs are not collapsed. + can be used to collapse repeated points from the output LineString. &Z_support; @@ -225,247 +274,82 @@ LINESTRING(1 2 3,4 5 6,7 8 9) - Examples: Spatial Aggregate version - This example takes a sequence of GPS points and creates one record for each - gps travel where the geometry field is a line string composed of the gps points - in the order of the travel. + Examples: Two-input variant - --- For pre-PostgreSQL 9.0 - this usually works, --- but the planner may on occasion choose not to respect the order of the subquery -SELECT gps.gps_track, ST_MakeLine(gps.the_geom) As newgeom - FROM (SELECT gps_track, gps_time, the_geom - FROM gps_points ORDER BY gps_track, gps_time) As gps - GROUP BY gps.gps_track; - - --- If you are using PostgreSQL 9.0+ --- (you can use the new ORDER BY support for aggregates) --- this is a guaranteed way to get a correctly ordered linestring --- Your order by part can order by more than one column if needed -SELECT gps.gps_track, ST_MakeLine(gps.the_geom ORDER BY gps_time) As newgeom - FROM gps_points As gps - GROUP BY gps.gps_track; - - - Examples: Non-Spatial Aggregate version +Create a line composed of two points. + +SELECT ST_AsText( ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4)) ); - First example is a simple one off line string composed of 2 points. The second formulates - line strings from 2 points a user draws. The third is a one-off that joins 2 3d points to create a line in 3d space. - -SELECT ST_AsText(ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4))); st_astext --------------------- LINESTRING(1 2,3 4) + -SELECT userpoints.id, ST_MakeLine(startpoint, endpoint) As drawn_line - FROM userpoints ; +Create a 3D line from two 3D points. + +SELECT ST_AsEWKT( ST_MakeLine(ST_MakePoint(1,2,3), ST_MakePoint(3,4,5) )); -SELECT ST_AsEWKT(ST_MakeLine(ST_MakePoint(1,2,3), ST_MakePoint(3,4,5))); st_asewkt ------------------------- LINESTRING(1 2 3,3 4 5) - + + +Create a line from two disjoint LineStrings. + + select ST_AsText( ST_MakeLine( 'LINESTRING(0 0, 1 1)', 'LINESTRING(2 2, 3 3)' ) ); + + st_astext +----------------------------- + LINESTRING(0 0,1 1,2 2,3 3) + - Examples: Using Array version + Examples: Array variant + + Create a line from an array formed by a subquery with ordering. + +SELECT ST_MakeLine( ARRAY( SELECT ST_Centroid(the_geom) FROM visit_locations ORDER BY visit_time) ); + - -SELECT ST_MakeLine(ARRAY(SELECT ST_Centroid(the_geom) FROM visit_locations ORDER BY visit_time)); + Create a 3D line from an array of 3D points + +SELECT ST_AsEWKT( ST_MakeLine( + ARRAY[ ST_MakePoint(1,2,3), ST_MakePoint(3,4,5), ST_MakePoint(6,6,6) ] )); ---Making a 3d line with 3 3-d points -SELECT ST_AsEWKT(ST_MakeLine(ARRAY[ST_MakePoint(1,2,3), - ST_MakePoint(3,4,5), ST_MakePoint(6,6,6)])); st_asewkt ------------------------- LINESTRING(1 2 3,3 4 5,6 6 6) - - - - - - - See Also - , , , + - - - - - - ST_MakeEnvelope - - Creates a rectangular Polygon from the given minimum and maximum ordinates. - - - - - - geometry ST_MakeEnvelope - double precision xmin - double precision ymin - double precision xmax - double precision ymax - integer srid=unknown - - - - Description + Examples: Aggregate variant + This example queries time-based sequences of GPS points from a set of tracks + and creates one record for each track. + The result geometries are LineStrings composed of the GPS track points in the order of travel. - Creates a rectangular Polygon formed from the minima and maxima. by the given shell. Input - values must be in SRS specified by the SRID. If no SRID is specified the unknown spatial reference system is assumed - - Availability: 1.5 - Enhanced: 2.0: Ability to specify an envelope without specifying an SRID was introduced. +Using aggregate ORDER BY provides a correctly-ordered linestring. + +SELECT gps.track_id, ST_MakeLine(gps.geom ORDER BY gps_time) As geom + FROM gps_points As gps + GROUP BY track_id; +Prior to PostgreSQL 9, ordering in a subquery can be used. +However, sometimes the query plan may not respect the order of the subquery. + +SELECT gps.track_id, ST_MakeLine(gps.geom) As geom + FROM ( SELECT track_id, gps_time, geom + FROM gps_points ORDER BY track_id, gps_time ) As gps + GROUP BY track_id; - - Example: Building a bounding box polygon - -SELECT ST_AsText(ST_MakeEnvelope(10, 10, 11, 11, 4326)); - -st_asewkt ------------ -POLYGON((10 10, 10 11, 11 11, 11 10, 10 10)) - - See Also - , , + , , , , - - - ST_MakePolygon - - Creates a Polygon from a shell and optional list of holes. - - - - - - geometry ST_MakePolygon - geometry linestring - - - - - geometry ST_MakePolygon - geometry outerlinestring - geometry[] interiorlinestrings - - - - - - Description - - Creates a Polygon formed by the given shell. Input - geometries must be closed LINESTRINGS. Comes in 2 variants. - Variant 1: Takes one closed linestring. - Variant 2: Creates a Polygon formed by the given shell and array of - holes. You can construct a geometry array using the PostgreSQL array_agg, ARRAY[] and - ARRAY() constructs. Input geometries must be closed LINESTRINGS. - - This function will not accept a MULTILINESTRING. Use or to generate line strings. - - - &Z_support; - - - - Examples: Single closed LINESTRING - ---2d line -SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)')); ---If linestring is not closed ---you can add the start point to close it -SELECT ST_MakePolygon(ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line))) -FROM ( -SELECT ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5)') As open_line) As foo; - ---3d closed line -SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53 1,77 29 1,77.6 29.5 1, 75.15 29.53 1)')); - -st_asewkt ------------ -POLYGON((75.15 29.53 1,77 29 1,77.6 29.5 1,75.15 29.53 1)) - ---measured line -- -SELECT ST_MakePolygon(ST_GeomFromText('LINESTRINGM(75.15 29.53 1,77 29 1,77.6 29.5 2, 75.15 29.53 2)')); - -st_asewkt ----------- -POLYGONM((75.15 29.53 1,77 29 1,77.6 29.5 2,75.15 29.53 2)) - - - - Examples: Outer shell with inner shells - - Build a donut with an ant hole - -SELECT ST_MakePolygon( - ST_ExteriorRing(ST_Buffer(foo.line,10)), - ARRAY[ST_Translate(foo.line,1,1), - ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ] - ) -FROM - (SELECT ST_ExteriorRing(ST_Buffer(ST_MakePoint(10,10),10,10)) - As line ) - As foo; - - Build province boundaries with holes - representing lakes in the province from a set of - province polygons/multipolygons and water linestrings. - The CASE construct is used because feeding a null array into - ST_MakePolygon results in NULL. - A left join is used to guarantee we get all provinces back even if they have no lakes. - - SELECT p.gid, p.province_name, - CASE WHEN - array_agg(w.the_geom) IS NULL THEN p.the_geom - ELSE ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), array_agg(w.the_geom)) END - FROM - provinces p LEFT JOIN waterlines w - ON (ST_Within(w.the_geom, p.the_geom) AND ST_IsClosed(w.the_geom)) - GROUP BY p.gid, p.province_name, p.the_geom; - - --Same example above but utilizing a correlated subquery - --and PostgreSQL built-in ARRAY() function that converts a row set to an array - - SELECT p.gid, p.province_name, CASE WHEN - EXISTS(SELECT w.the_geom - FROM waterlines w - WHERE ST_Within(w.the_geom, p.the_geom) - AND ST_IsClosed(w.the_geom)) - THEN - ST_MakePolygon(ST_LineMerge(ST_Boundary(p.the_geom)), - ARRAY(SELECT w.the_geom - FROM waterlines w - WHERE ST_Within(w.the_geom, p.the_geom) - AND ST_IsClosed(w.the_geom))) - ELSE p.the_geom END As the_geom - FROM - provinces p; - - - - See Also - - , - , - , - , - , - - - - @@ -478,25 +362,25 @@ FROM geometry ST_MakePoint - double precision x - double precision y + float x + float y geometry ST_MakePoint - double precision x - double precision y - double precision z + float x + float y + float z geometry ST_MakePoint - double precision x - double precision y - double precision z - double precision m + float x + float y + float z + float m @@ -504,18 +388,19 @@ FROM Description - Creates a 2D, 3DZ or 4D point geometry (geometry with measure). - ST_MakePoint while not being OGC compliant is - generally faster and more precise than - and . It is also easier to use if - you have raw coordinates rather than WKT. + Creates a 2D, 3D Z or 4D ZM Point geometry. - For geodetic coordinates, x is longitude and y is latitude + Use to make points with XYM coordinates. - Use if you need to make a point with x, y and m. + + While not OGC-compliant, ST_MakePoint is + faster and more precise than + and . + It is also easier to use for numeric coordinate values. - &Z_support; + For geodetic coordinates, X is longitude and Y is latitude + &Z_support; @@ -562,39 +447,45 @@ result Description - Creates a point with x, y and measure coordinates. - Note x is longitude and y is latitude. + Creates a point with X, Y and M (measure) coordinates. + + Use to make points with XY, XYZ, or XYZM coordinates. + + For geodetic coordinates, X is longitude and Y is latitude + Examples - We use ST_AsEWKT in these examples to show the text representation instead of ST_AsText because ST_AsText does not - support returning M. + is used for text output + because does not support M values. + + Create point with unknown SRID. ---Return EWKT representation of point with unknown SRID -SELECT ST_AsEWKT(ST_MakePointM(-71.1043443253471, 42.3150676015829, 10)); +SELECT ST_AsEWKT( ST_MakePointM(-71.1043443253471, 42.3150676015829, 10) ); ---result st_asewkt ----------------------------------------------- POINTM(-71.1043443253471 42.3150676015829 10) + ---Return EWKT representation of point with measure marked as WGS 84 long lat -SELECT ST_AsEWKT(ST_SetSRID(ST_MakePointM(-71.1043443253471, 42.3150676015829,10),4326)); +Create point with a measure in the WGS 84 geodetic coordinate system. + +SELECT ST_AsEWKT( ST_SetSRID( ST_MakePointM(-71.104, 42.315, 10), 4326)); st_asewkt --------------------------------------------------------- -SRID=4326;POINTM(-71.1043443253471 42.3150676015829 10) +SRID=4326;POINTM(-71.104 42.315 10) + ---Return a 3d point (e.g. has altitude) -SELECT ST_MakePoint(1, 2,1.5); +Get measure of created point. + +SELECT ST_M( ST_MakePointM(-71.104, 42.315, 10) ); ---Get m of point -SELECT ST_M(ST_MakePointM(-71.1043443253471, 42.3150676015829,10)); result ------- 10 - + See Also @@ -602,19 +493,156 @@ result + + + ST_MakePolygon + + Creates a Polygon from a shell and optional list of holes. + + + + + + geometry ST_MakePolygon + geometry linestring + + + + + geometry ST_MakePolygon + geometry outerlinestring + geometry[] interiorlinestrings + + + + + + Description + + Creates a Polygon formed by the given shell and optional array of holes. + Input geometries must be closed LineStrings (rings). + + Variant 1: Accepts one shell LineString. + Variant 2: Accepts a shell LineString and an array of + inner (hole) LineStrings. A geometry array can be constructed using the PostgreSQL array_agg(), ARRAY[] or + ARRAY() constructs. + + This function does not accept MultiLineStrings. + Use to generate a LineString, or to extract LineStrings. + + + &Z_support; + + + + Examples: Single input variant + Create a Polygon from a 2D LineString. + +SELECT ST_MakePolygon( ST_GeomFromText('LINESTRING(75 29,77 29,77 29, 75 29)')); + + +Create a Polygon from an open LineString, +using and to close it. + +SELECT ST_MakePolygon( ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)) ) +FROM ( + SELECT ST_GeomFromText('LINESTRING(75 29,77 29,77 29, 75 29)') As open_line) As foo; + + +Create a Polygon from a 3D LineString + +SELECT ST_AsEWKT( ST_MakePolygon( 'LINESTRING(75.15 29.53 1,77 29 1,77.6 29.5 1, 75.15 29.53 1)')); + +st_asewkt +----------- +POLYGON((75.15 29.53 1,77 29 1,77.6 29.5 1,75.15 29.53 1)) + +Create a Polygon from a LineString with measures + +SELECT ST_AsEWKT( ST_MakePolygon( 'LINESTRINGM(75.15 29.53 1,77 29 1,77.6 29.5 2, 75.15 29.53 2)' )); + +st_asewkt +---------- +POLYGONM((75.15 29.53 1,77 29 1,77.6 29.5 2,75.15 29.53 2)) + + + + Examples: Outer shell with inner holes variant + + Create a donut Polygon with an extra hole + +SELECT ST_MakePolygon( ST_ExteriorRing( ST_Buffer(ring.line,10)), + ARRAY[ ST_Translate(ring.line, 1, 1), + ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ] + ) +FROM (SELECT ST_ExteriorRing( + ST_Buffer(ST_MakePoint(10,10),10,10)) AS line ) AS ring; + + Create a set of province boundaries with holes + representing lakes. The input is a table of + province Polygons/MultiPolygons and a table of water linestrings. + Using a LEFT JOIN ensures all provinces are included even if they have no lakes. + + + The CASE construct is used because passing a null array into + ST_MakePolygon results in a NULL return value. + + + SELECT p.gid, p.province_name, + CASE WHEN array_agg(w.the_geom) IS NULL + THEN p.the_geom + ELSE ST_MakePolygon( ST_LineMerge(ST_Boundary(p.the_geom)), array_agg(w.the_geom)) END + FROM + provinces p LEFT JOIN waterlines w + ON (ST_Within(w.the_geom, p.the_geom) AND ST_IsClosed(w.the_geom)) + GROUP BY p.gid, p.province_name, p.the_geom; + + + Another technique is to utilize a correlated subquery + and the ARRAY() constructor that converts a row set to an array. + + SELECT p.gid, p.province_name, + CASE WHEN EXISTS( SELECT w.the_geom + FROM waterlines w + WHERE ST_Within(w.the_geom, p.the_geom) + AND ST_IsClosed(w.the_geom)) + THEN ST_MakePolygon( + ST_LineMerge(ST_Boundary(p.the_geom)), + ARRAY( SELECT w.the_geom + FROM waterlines w + WHERE ST_Within(w.the_geom, p.the_geom) + AND ST_IsClosed(w.the_geom))) + ELSE p.the_geom + END AS the_geom + FROM provinces p; + + + + See Also + + , + , + , + , + , + + + + + ST_Point - Creates a Point with the given coordinate values. OGC alias for ST_MakePoint. + Creates a Point with the given coordinate values. Alias for ST_MakePoint. geometry ST_Point - float x_lon - float y_lat + float x + float y @@ -622,8 +650,9 @@ result Description - Returns an Point with the given coordinate values. SQL-MM alias for ST_MakePoint that takes just an x and y. + Returns an Point with the given X and Y coordinate values. This is the SQL-MM alias for that takes just X and Y. + For geodetic coordinates, X is longitude and Y is latitude &sqlmm_compliant; SQL-MM 3: 6.1.2 @@ -633,19 +662,24 @@ result Examples: Geometry - SELECT ST_SetSRID(ST_Point(-71.1043443253471, 42.3150676015829),4326) + SELECT ST_SetSRID( ST_Point( -71.104, 42.315), 4326) Examples: Geography - SELECT CAST(ST_SetSRID(ST_Point(-71.1043443253471, 42.3150676015829),4326) As geography); - -- the :: is PostgreSQL short-hand for casting. -SELECT ST_SetSRID(ST_Point(-71.1043443253471, 42.3150676015829),4326)::geography; + SELECT CAST(ST_SetSRID( ST_Point( -71.104, 42.315), 4326) AS geography); - --If your point coordinates are in a different spatial reference from WGS-84 long lat, then you need to transform before casting --- This example we convert a point in Pennsylvania State Plane feet to WGS 84 and then geography -SELECT ST_Transform(ST_SetSRID(ST_Point(3637510, 3014852),2273),4326)::geography; + PostgreSQL also provides the :: short-hand for casting + +SELECT ST_SetSRID( ST_Point( -71.104, 42.315), 4326)::geography; + +If the point coordinates are not in a geodetic coordinate system (such as WGS84), +then they must be reprojected before casting to a geography. +In this example a point in Pennsylvania State Plane feet (SRID 2273) +is projected to WGS84 (SRID 4326). + +SELECT ST_Transform(ST_SetSRID( ST_Point( 3637510, 3014852 ), 2273), 4326)::geography; @@ -660,14 +694,14 @@ SELECT ST_Transform(ST_SetSRID(ST_Point(3637510, 3014852),2273),4326)::geography ST_Polygon - Creates a Polygon from a LineString, with a specified SRID. + Creates a Polygon from a LineString with a specified SRID. geometry ST_Polygon - geometry aLineString + geometry lineString integer srid @@ -676,12 +710,17 @@ SELECT ST_Transform(ST_SetSRID(ST_Point(3637510, 3014852),2273),4326)::geography Description - Returns a polygon built from the specified linestring and SRID. + Returns a polygon built from the given LineString + and sets the spatial reference system from the srid. - - - ST_Polygon is similar to first version of ST_MakePolygon except it also sets the spatial ref sys (SRID) of the polygon. Will not work with MULTILINESTRINGS - so use LineMerge to merge multilines. Also does not create polygons with holes. Use ST_MakePolygon for that. + ST_Polygon is similar to Variant 1 + with the addition of setting the SRID. + To create polygons with holes + use Variant 2 and then . + + + This function does not accept MultiLineStrings. + Use to generate a LineString, or to extract LineStrings. &sfs_compliant; @@ -690,23 +729,23 @@ SELECT ST_Transform(ST_SetSRID(ST_Point(3637510, 3014852),2273),4326)::geography - Examples +Create a 2D polygon. ---a 2d polygon -SELECT ST_Polygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'), 4326); +SELECT ST_AsText( ST_Polygon('LINESTRING(75 29, 77 29, 77 29, 75 29)'::geometry, 4326) ); ---result-- -POLYGON((75.15 29.53,77 29,77.6 29.5,75.15 29.53)) ---a 3d polygon -SELECT ST_AsEWKT(ST_Polygon(ST_GeomFromEWKT('LINESTRING(75.15 29.53 1,77 29 1,77.6 29.5 1, 75.15 29.53 1)'), 4326)); +-- result -- +POLYGON((75 29, 77 29, 77 29, 75 29)) + +Create a 3D polygon. + +SELECT ST_AsEWKT( ST_Polygon( ST_GeomFromEWKT('LINESTRING(75 29 1, 77 29 2, 77 29 3, 75 29 1)'), 4326) ); -result ------- -SRID=4326;POLYGON((75.15 29.53 1,77 29 1,77.6 29.5 1,75.15 29.53 1)) - +-- result -- +SRID=4326;POLYGON((75 29 1, 77 29 2, 77 29 3, 75 29 1)) +