# Geometry Constructors

ST_Collect

Creates a GeometryCollection or Multi* geometry from a set of geometries.

    				geometry ST_Collect
    					geometry g1
    					geometry g2

    				geometry ST_Collect
    					geometry[] g1_array

    				geometry ST_Collect
    					geometry set g1field

### Description

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.

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 returns a GeometryCollection (since that is the only type which can contain nested collections). To prevent this, use ST_Dump in a subquery to expand the input collections to their atomic elements (see example below).

ST_Collect and ST_Union 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;

### 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 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)

Collect curves.

    SELECT ST_AsText( ST_Collect( 'CIRCULARSTRING(220268 150415,220227 150505,220227 150406)',
    		'CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)'));

    		st_astext
    ------------------------------------------------------------------------------------
    MULTICURVE(CIRCULARSTRING(220268 150415,220227 150505,220227 150406),
     CIRCULARSTRING(220227 150406,2220227 150407,220227 150406))

### 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

ST_Dump, ST_Union

ST_LineFromMultiPoint

Creates a LineString from a MultiPoint geometry.

    			geometry ST_LineFromMultiPoint
    			geometry  aMultiPoint

### Description

Creates a LineString from a MultiPoint geometry.

Use ST_MakeLine to create lines from Point or LineString inputs.

&Z_support;

### Examples

Create a 3D line string from a 3D MultiPoint

    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_AsEWKT, ST_MakeLine

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_MakePoint, ST_MakeLine, ST_MakePolygon, ST_TileEnvelope

ST_MakeLine

Creates a Linestring from Point, MultiPoint, or LineString geometries.

    				geometry ST_MakeLine
    				geometry geom1
    				geometry geom2

    				geometry ST_MakeLine
    				geometry[] geoms_array

    				geometry ST_MakeLine
    				geometry set geoms

### Description

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.

Repeated nodes at the beginning of input LineStrings are collapsed to a single point. Repeated points in Point and MultiPoint inputs are not collapsed. ST_RemoveRepeatedPoints can be used to collapse repeated points from the output LineString.

&Z_support;

Availability: 2.3.0 - Support for multipoint input elements was introduced

Availability: 2.0.0 - Support for linestring input elements was introduced

Availability: 1.4.0 - ST_MakeLine(geomarray) was introduced. ST_MakeLine aggregate functions was enhanced to handle more points faster.

### Examples: Two-input variant

Create a line composed of two points.

    SELECT ST_AsText( ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4)) );

    	  st_astext
    ---------------------
     LINESTRING(1 2,3 4)

Create a 3D line from two 3D points.

    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: 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) );

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) ]  ));

    		st_asewkt
    -------------------------
    LINESTRING(1 2 3,3 4 5,6 6 6)

### 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.

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;

### See Also

ST_RemoveRepeatedPoints, ST_AsEWKT, ST_AsText, ST_GeomFromText, ST_MakePoint

ST_MakePoint

Creates a 2D, 3DZ or 4D Point.

    			geometry ST_MakePoint
    			float x
    			float y

    			geometry ST_MakePoint
    			float x
    			float y
    			float z

    			geometry ST_MakePoint
    			float x
    			float y
    			float z
    			float m

### Description

Creates a 2D, 3D Z or 4D ZM Point geometry.

Use ST_MakePointM to make points with XYM coordinates.

While not OGC-compliant, `ST_MakePoint` is faster and more precise than ST_GeomFromText and ST_PointFromText. It is also easier to use for numeric coordinate values.

For geodetic coordinates, `X` is longitude and `Y` is latitude

&Z_support;

### Examples

    --Return point with unknown SRID
    SELECT ST_MakePoint(-71.1043443253471, 42.3150676015829);

    --Return point marked as WGS 84 long lat
    SELECT ST_SetSRID(ST_MakePoint(-71.1043443253471, 42.3150676015829),4326);

    --Return a 3D point (e.g. has altitude)
    SELECT ST_MakePoint(1, 2,1.5);

    --Get z of point
    SELECT ST_Z(ST_MakePoint(1, 2,1.5));
    result
    -------
    1.5

### See Also

ST_GeomFromText, ST_PointFromText, ST_SetSRID, ST_MakePointM

ST_MakePointM

Creates a Point from X, Y and M values.

    				geometry ST_MakePointM
    				float x
    				float y
    				float m

### Description

Creates a point with X, Y and M (measure) coordinates.

Use ST_MakePoint to make points with XY, XYZ, or XYZM coordinates.

For geodetic coordinates, `X` is longitude and `Y` is latitude

### Examples

ST_AsEWKT is used for text output because ST_AsText does not support M values.

Create point with unknown SRID.

    SELECT ST_AsEWKT(  ST_MakePointM(-71.1043443253471, 42.3150676015829, 10)  );

    				   st_asewkt
    -----------------------------------------------
     POINTM(-71.1043443253471 42.3150676015829 10)

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.104 42.315 10)

Get measure of created point.

    SELECT ST_M(  ST_MakePointM(-71.104, 42.315, 10)  );

    result
    -------
    10

### See Also

ST_AsEWKT, ST_MakePoint, ST_SetSRID

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 ST_LineMerge to generate a LineString, or ST_Dump 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 ST_StartPoint and ST_AddPoint 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_Boundary, ST_AddPoint, ST_IsClosed, ST_LineMerge, ST_StartPoint, ST_BuildArea

ST_Point

Creates a Point with the given coordinate values. Alias for ST_MakePoint.

    			geometry ST_Point
    			float x
    			float y

### Description

Returns an Point with the given X and Y coordinate values. This is the SQL-MM alias for ST_MakePoint that takes just X and Y.

For geodetic coordinates, `X` is longitude and `Y` is latitude

&sqlmm_compliant; SQL-MM 3: 6.1.2

### Examples: Geometry

    SELECT ST_SetSRID( ST_Point( -71.104, 42.315), 4326)

### Examples: Geography

    SELECT CAST(ST_SetSRID( ST_Point( -71.104, 42.315), 4326) AS 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;

### See Also

Geography_Basics, ST_MakePoint, ST_SetSRID, ST_Transform

ST_Polygon

Creates a Polygon from a LineString with a specified SRID.

    			geometry ST_Polygon
    			geometry  lineString
    			integer  srid

### Description

Returns a polygon built from the given LineString and sets the spatial reference system from the `srid`.

ST_Polygon is similar to ST_MakePolygon Variant 1 with the addition of setting the SRID.

To create polygons with holes use ST_MakePolygon Variant 2 and then ST_SetSRID.

This function does not accept MultiLineStrings. Use ST_LineMerge to generate a LineString, or ST_Dump to extract LineStrings.

&sfs_compliant;

&sqlmm_compliant; SQL-MM 3: 8.3.2

&Z_support;

### Examples

Create a 2D polygon.

    SELECT ST_AsText( ST_Polygon('LINESTRING(75 29, 77 29, 77 29, 75 29)'::geometry, 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 29 1, 77 29 2, 77 29 3, 75 29 1))

### See Also

ST_AsEWKT, ST_AsText, ST_GeomFromEWKT, ST_GeomFromText, ST_LineMerge, ST_MakePolygon

ST_TileEnvelope

Creates a rectangular Polygon in Web Mercator (SRID:3857) using the XYZ tile system.

    			geometry ST_TileEnvelope
    			integer tileZoom
    			integer tileX
    			integer tileY
    			geometry bounds=SRID=3857;LINESTRING(-20037508.342789 -20037508.342789,20037508.342789 20037508.342789)

### Description

Creates a rectangular Polygon in Web Mercator (SRID:3857) using the XYZ tile system. By default, the bounds are the in EPSG:3857 using the standard range of the Web Mercator system (-20037508.342789, 20037508.342789). The optional bounds parameter can be used to generate envelopes for any tiling scheme: provide a geometry that has the SRID and extent of the initial "zoom level zero" square within which the tile system is to be inscribed.

Availability: 3.0

### Example: Building a tile envelope

    SELECT ST_AsText( ST_TileEnvelope(2, 1, 1) );

     st_astext
    ------------------------------
     POLYGON((-10018754.1713945 0,-10018754.1713945 10018754.1713945,0 10018754.1713945,0 0,-10018754.1713945 0))

    SELECT ST_AsText( ST_TileEnvelope(3, 1, 1, ST_MakeEnvelope(-180, -90, 180, 90, 4326) ) );

                          st_astext
    ------------------------------------------------------
     POLYGON((-135 45,-135 67.5,-90 67.5,-90 45,-135 45))

### See Also

ST_MakeEnvelope