# Geometry Editors

ST_AddPoint

Add a point to a LineString.

    				geometry ST_AddPoint
    				geometry linestring
    				geometry point

    				geometry ST_AddPoint
    				geometry linestring
    				geometry point
    				integer position

### Description

Adds a point to a LineString before point <position> (0-based index). Third parameter can be omitted or set to -1 for appending.

Availability: 1.1.0

&Z_support;

### Examples

    		--guarantee all linestrings in a table are closed
    		--by adding the start point of each linestring to the end of the line string
    		--only for those that are not closed
    		UPDATE sometable
    		SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))
    		FROM sometable
    		WHERE ST_IsClosed(the_geom) = false;

    		--Adding point to a 3-d line
    		SELECT ST_AsEWKT(ST_AddPoint(ST_GeomFromEWKT('LINESTRING(0 0 1, 1 1 1)'), ST_MakePoint(1, 2, 3)));

    		--result
    		st_asewkt
    		----------
    		LINESTRING(0 0 1,1 1 1,1 2 3)

### See Also

ST_RemovePoint, ST_SetPoint

ST_Affine

Apply a 3d affine transformation to a geometry.

    			geometry ST_Affine
    			geometry  geomA
    			float  a
    			float  b
    			float  c
    			float  d
    			float  e
    			float  f
    			float  g
    			float  h
    			float  i
    			float  xoff
    			float  yoff
    			float  zoff

    			geometry ST_Affine
    			geometry  geomA
    			float  a
    			float  b
    			float  d
    			float  e
    			float  xoff
    			float  yoff

### Description

Applies a 3d affine transformation to the geometry to do things like translate, rotate, scale in one step.

Version 1: The call

    ST_Affine(geom, a, b, c, d, e, f, g, h, i, xoff, yoff, zoff)

represents the transformation matrix

    / a  b  c  xoff \
    | d  e  f  yoff |
    | g  h  i  zoff |
    \ 0  0  0     1 /

and the vertices are transformed as follows:

    x' = a*x + b*y + c*z + xoff
    y' = d*x + e*y + f*z + yoff
    z' = g*x + h*y + i*z + zoff

All of the translate / scale functions below are expressed via such an affine transformation.

Version 2: Applies a 2d affine transformation to the geometry. The call

    ST_Affine(geom, a, b, d, e, xoff, yoff)

represents the transformation matrix

    /  a  b  0  xoff  \       /  a  b  xoff  \
    |  d  e  0  yoff  | rsp.  |  d  e  yoff  |
    |  0  0  1     0  |       \  0  0     1  /
    \  0  0  0     1  /

and the vertices are transformed as follows:

    x' = a*x + b*y + xoff
    y' = d*x + e*y + yoff
    z' = z

This method is a subcase of the 3D method above.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Availability: 1.1.2. Name changed from Affine to ST_Affine in 1.2.2

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

&P_support;

&T_support;

&Z_support;

&curve_support;

### Examples

    --Rotate a 3d line 180 degrees about the z axis.  Note this is long-hand for doing ST_Rotate();
     SELECT ST_AsEWKT(ST_Affine(the_geom,  cos(pi()), -sin(pi()), 0,  sin(pi()), cos(pi()), 0,  0, 0, 1,  0, 0, 0)) As using_affine,
    	 ST_AsEWKT(ST_Rotate(the_geom, pi())) As using_rotate
    	FROM (SELECT ST_GeomFromEWKT('LINESTRING(1 2 3, 1 4 3)') As the_geom) As foo;
            using_affine         |        using_rotate
    -----------------------------+-----------------------------
     LINESTRING(-1 -2 3,-1 -4 3) | LINESTRING(-1 -2 3,-1 -4 3)
    (1 row)

    --Rotate a 3d line 180 degrees in both the x and z axis
    SELECT ST_AsEWKT(ST_Affine(the_geom, cos(pi()), -sin(pi()), 0, sin(pi()), cos(pi()), -sin(pi()), 0, sin(pi()), cos(pi()), 0, 0, 0))
    	FROM (SELECT ST_GeomFromEWKT('LINESTRING(1 2 3, 1 4 3)') As the_geom) As foo;
               st_asewkt
    -------------------------------
     LINESTRING(-1 -2 -3,-1 -4 -3)
    (1 row)

### See Also

ST_Rotate, ST_Scale, ST_Translate, ST_TransScale

ST_Force2D

Force the geometries into a "2-dimensional mode".

    			geometry ST_Force2D
    			geometry  geomA

### Description

Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. This is useful for force OGC-compliant output (since OGC only specifies 2-D geometries).

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

Changed: 2.1.0. Up to 2.0.x this was called ST_Force_2D.

&curve_support;

&P_support;

&Z_support;

### Examples

    SELECT ST_AsEWKT(ST_Force2D(ST_GeomFromEWKT('CIRCULARSTRING(1 1 2, 2 3 2, 4 5 2, 6 7 2, 5 6 2)')));
    		st_asewkt
    -------------------------------------
    CIRCULARSTRING(1 1,2 3,4 5,6 7,5 6)

    SELECT  ST_AsEWKT(ST_Force2D('POLYGON((0 0 2,0 5 2,5 0 2,0 0 2),(1 1 2,3 1 2,1 3 2,1 1 2))'));

    				  st_asewkt
    ----------------------------------------------
     POLYGON((0 0,0 5,5 0,0 0),(1 1,3 1,1 3,1 1))

### See Also

ST_Force_3D

ST_Force3D

Force the geometries into XYZ mode. This is an alias for ST_Force3DZ.

    			geometry ST_Force3D
    			geometry  geomA

### Description

Forces the geometries into XYZ mode. This is an alias for ST_Force_3DZ. If a geometry has no Z component, then a 0 Z coordinate is tacked on.

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

Changed: 2.1.0. Up to 2.0.x this was called ST_Force_3D.

&P_support;

&curve_support;

&Z_support;

### Examples

    		--Nothing happens to an already 3D geometry
    		SELECT ST_AsEWKT(ST_Force3D(ST_GeomFromEWKT('CIRCULARSTRING(1 1 2, 2 3 2, 4 5 2, 6 7 2, 5 6 2)')));
    				   st_asewkt
    -----------------------------------------------
     CIRCULARSTRING(1 1 2,2 3 2,4 5 2,6 7 2,5 6 2)

    SELECT  ST_AsEWKT(ST_Force3D('POLYGON((0 0,0 5,5 0,0 0),(1 1,3 1,1 3,1 1))'));

    						 st_asewkt
    --------------------------------------------------------------
     POLYGON((0 0 0,0 5 0,5 0 0,0 0 0),(1 1 0,3 1 0,1 3 0,1 1 0))

### See Also

ST_AsEWKT, ST_Force2D, ST_Force_3DM, ST_Force_3DZ

ST_Force3DZ

Force the geometries into XYZ mode.

    			geometry ST_Force3DZ
    			geometry  geomA

### Description

Forces the geometries into XYZ mode. This is a synonym for ST_Force3DZ. If a geometry has no Z component, then a 0 Z coordinate is tacked on.

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

Changed: 2.1.0. Up to 2.0.x this was called ST_Force_3DZ.

&P_support;

&Z_support;

&curve_support;

### Examples

    --Nothing happens to an already 3D geometry
    SELECT ST_AsEWKT(ST_Force3DZ(ST_GeomFromEWKT('CIRCULARSTRING(1 1 2, 2 3 2, 4 5 2, 6 7 2, 5 6 2)')));
    				   st_asewkt
    -----------------------------------------------
     CIRCULARSTRING(1 1 2,2 3 2,4 5 2,6 7 2,5 6 2)

    SELECT  ST_AsEWKT(ST_Force3DZ('POLYGON((0 0,0 5,5 0,0 0),(1 1,3 1,1 3,1 1))'));

    						 st_asewkt
    --------------------------------------------------------------
     POLYGON((0 0 0,0 5 0,5 0 0,0 0 0),(1 1 0,3 1 0,1 3 0,1 1 0))

### See Also

ST_AsEWKT, ST_Force2D, ST_Force_3DM, ST_Force_3D

ST_Force3DM

Force the geometries into XYM mode.

    			geometry ST_Force3DM
    			geometry  geomA

### Description

Forces the geometries into XYM mode. If a geometry has no M component, then a 0 M coordinate is tacked on. If it has a Z component, then Z is removed

Changed: 2.1.0. Up to 2.0.x this was called ST_Force_3DM.

&curve_support;

### Examples

    --Nothing happens to an already 3D geometry
    SELECT ST_AsEWKT(ST_Force3DM(ST_GeomFromEWKT('CIRCULARSTRING(1 1 2, 2 3 2, 4 5 2, 6 7 2, 5 6 2)')));
    				   st_asewkt
    ------------------------------------------------
     CIRCULARSTRINGM(1 1 0,2 3 0,4 5 0,6 7 0,5 6 0)

    SELECT  ST_AsEWKT(ST_Force3DM('POLYGON((0 0 1,0 5 1,5 0 1,0 0 1),(1 1 1,3 1 1,1 3 1,1 1 1))'));

    						  st_asewkt
    ---------------------------------------------------------------
     POLYGONM((0 0 0,0 5 0,5 0 0,0 0 0),(1 1 0,3 1 0,1 3 0,1 1 0))

### See Also

ST_AsEWKT, ST_Force2D, ST_Force_3DM, ST_Force_3D, ST_GeomFromEWKT

ST_Force4D

Force the geometries into XYZM mode.

    			geometry ST_Force4D
    			geometry  geomA

### Description

Forces the geometries into XYZM mode. 0 is tacked on for missing Z and M dimensions.

Changed: 2.1.0. Up to 2.0.x this was called ST_Force_4D.

&Z_support;

&curve_support;

### Examples

    --Nothing happens to an already 3D geometry
    SELECT ST_AsEWKT(ST_Force4D(ST_GeomFromEWKT('CIRCULARSTRING(1 1 2, 2 3 2, 4 5 2, 6 7 2, 5 6 2)')));
    						st_asewkt
    ---------------------------------------------------------
     CIRCULARSTRING(1 1 2 0,2 3 2 0,4 5 2 0,6 7 2 0,5 6 2 0)

    SELECT  ST_AsEWKT(ST_Force4D('MULTILINESTRINGM((0 0 1,0 5 2,5 0 3,0 0 4),(1 1 1,3 1 1,1 3 1,1 1 1))'));

    									  st_asewkt
    --------------------------------------------------------------------------------------
     MULTILINESTRING((0 0 0 1,0 5 0 2,5 0 0 3,0 0 0 4),(1 1 0 1,3 1 0 1,1 3 0 1,1 1 0 1))

### See Also

ST_AsEWKT, ST_Force2D, ST_Force_3DM, ST_Force_3D

ST_ForcePolygonCCW

Orients all exterior rings counter-clockwise and all interior rings clockwise.

    						geometry
    						ST_ForcePolygonCCW

    						geometry
    						geom

### Description

Forces (Multi)Polygons to use a counter-clockwise orientation for their exterior ring, and a clockwise orientation for their interior rings. Non-polygonal geometries are returned unchanged.

&Z_support;

&M_support;

### See Also

ST_ForcePolygonCW, ST_IsPolygonCCW, ST_IsPolygonCW

ST_ForceCollection

Convert the geometry into a GEOMETRYCOLLECTION.

    			geometry ST_ForceCollection
    			geometry  geomA

### Description

Converts the geometry into a GEOMETRYCOLLECTION. This is useful for simplifying the WKB representation.

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

Availability: 1.2.2, prior to 1.3.4 this function will crash with Curves. This is fixed in 1.3.4+

Changed: 2.1.0. Up to 2.0.x this was called ST_Force_Collection.

&P_support;

&Z_support;

&curve_support;

### Examples

    SELECT  ST_AsEWKT(ST_ForceCollection('POLYGON((0 0 1,0 5 1,5 0 1,0 0 1),(1 1 1,3 1 1,1 3 1,1 1 1))'));

    								   st_asewkt
    ----------------------------------------------------------------------------------
     GEOMETRYCOLLECTION(POLYGON((0 0 1,0 5 1,5 0 1,0 0 1),(1 1 1,3 1 1,1 3 1,1 1 1)))

      SELECT ST_AsText(ST_ForceCollection('CIRCULARSTRING(220227 150406,2220227 150407,220227 150406)'));
    								   st_astext
    --------------------------------------------------------------------------------
     GEOMETRYCOLLECTION(CIRCULARSTRING(220227 150406,2220227 150407,220227 150406))
    (1 row)

    -- POLYHEDRAL example --
    SELECT ST_AsEWKT(ST_ForceCollection('POLYHEDRALSURFACE(((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
     ((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),
     ((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
     ((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
     ((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),
     ((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1)))'))

    								   st_asewkt
    ----------------------------------------------------------------------------------
    GEOMETRYCOLLECTION(
      POLYGON((0 0 0,0 0 1,0 1 1,0 1 0,0 0 0)),
      POLYGON((0 0 0,0 1 0,1 1 0,1 0 0,0 0 0)),
      POLYGON((0 0 0,1 0 0,1 0 1,0 0 1,0 0 0)),
      POLYGON((1 1 0,1 1 1,1 0 1,1 0 0,1 1 0)),
      POLYGON((0 1 0,0 1 1,1 1 1,1 1 0,0 1 0)),
      POLYGON((0 0 1,1 0 1,1 1 1,0 1 1,0 0 1))
    )

### See Also

ST_AsEWKT, ST_Force2D, ST_Force_3DM, ST_Force_3D, ST_GeomFromEWKT

ST_ForcePolygonCW

Orients all exterior rings clockwise and all interior rings counter-clockwise.

    						geometry
    						ST_ForcePolygonCW

    						geometry
    						geom

### Description

Forces (Multi)Polygons to use a clockwise orientation for their exterior ring, and a counter-clockwise orientation for their interior rings. Non-polygonal geometries are returned unchanged.

&Z_support;

&M_support;

### See Also

ST_ForcePolygonCCW, ST_IsPolygonCCW, ST_IsPolygonCW

ST_ForceSFS

Force the geometries to use SFS 1.1 geometry types only.

    			geometry ST_ForceSFS
    			geometry  geomA

    			geometry ST_ForceSFS
    			geometry  geomA
    			text  version

### Description

&P_support;

&T_support;

&curve_support;

&Z_support;

ST_ForceRHR

Force the orientation of the vertices in a polygon to follow the Right-Hand-Rule.

    					geometry
    						ST_ForceRHR
    						geometry g

### Description

Forces the orientation of the vertices in a polygon to follow a Right-Hand-Rule, in which the area that is bounded by the polygon is to the right of the boundary. In particular, the exterior ring is orientated in a clockwise direction and the interior rings in a counter-clockwise direction. This function is a synonym for ST_ForcePolygonCW

The above definition of the Right-Hand-Rule conflicts with definitions used in other contexts. To avoid confusion, it is recommended to use ST_ForcePolygonCW.

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

&Z_support;

&P_support;

### Examples

    SELECT ST_AsEWKT(
      ST_ForceRHR(
    	'POLYGON((0 0 2, 5 0 2, 0 5 2, 0 0 2),(1 1 2, 1 3 2, 3 1 2, 1 1 2))'
      )
    );
    						  st_asewkt
    --------------------------------------------------------------
     POLYGON((0 0 2,0 5 2,5 0 2,0 0 2),(1 1 2,3 1 2,1 3 2,1 1 2))
    (1 row)

### See Also

ST_ForcePolygonCCW, ST_ForcePolygonCW, ST_IsPolygonCCW, ST_IsPolygonCW, ST_BuildArea, ST_Polygonize, ST_Reverse

ST_ForceCurve

Upcast a geometry into its curved type, if applicable.

    					geometry
    						ST_ForceCurve
    						geometry g

### Description

Turns a geometry into its curved representation, if applicable: lines become compoundcurves, multilines become multicurves polygons become curvepolygons multipolygons become multisurfaces. If the geometry input is already a curved representation returns back same as input.

Availability: 2.2.0

&Z_support;

&curve_support;

### Examples

    SELECT ST_AsText(
      ST_ForceCurve(
    	'POLYGON((0 0 2, 5 0 2, 0 5 2, 0 0 2),(1 1 2, 1 3 2, 3 1 2, 1 1 2))'::geometry
      )
    );
                                  st_astext
    ----------------------------------------------------------------------
     CURVEPOLYGON Z ((0 0 2,5 0 2,0 5 2,0 0 2),(1 1 2,1 3 2,3 1 2,1 1 2))
    (1 row)

### See Also

ST_LineToCurve

ST_LineMerge

Return a (set of) LineString(s) formed by sewing together a MULTILINESTRING.

    				geometry ST_LineMerge
    				geometry  amultilinestring

### Description

Returns a (set of) LineString(s) formed by sewing together the constituent line work of a MULTILINESTRING.

Only use with MULTILINESTRING/LINESTRINGs. If you feed a polygon or geometry collection into this function, it will return an empty GEOMETRYCOLLECTION

Availability: 1.1.0

requires GEOS >= 2.1.0

Will strip the M dimension.

### Examples

    SELECT ST_AsText(ST_LineMerge(
    ST_GeomFromText('MULTILINESTRING((-29 -27,-30 -29.7,-36 -31,-45 -33),(-45 -33,-46 -32))')
    		)
    );
    st_astext
    --------------------------------------------------------------------------------------------------
    LINESTRING(-29 -27,-30 -29.7,-36 -31,-45 -33,-46 -32)
    (1 row)

    --If can't be merged - original MULTILINESTRING is returned
    SELECT ST_AsText(ST_LineMerge(
    ST_GeomFromText('MULTILINESTRING((-29 -27,-30 -29.7,-36 -31,-45 -33),(-45.2 -33.2,-46 -32))')
    )
    );
    st_astext
    ----------------
    MULTILINESTRING((-45.2 -33.2,-46 -32),(-29 -27,-30 -29.7,-36 -31,-45 -33))

    -- example with Z dimension
    SELECT ST_AsText(ST_LineMerge(
    ST_GeomFromText('MULTILINESTRING((-29 -27 11,-30 -29.7 10,-36 -31 5,-45 -33 6), (-29 -27 12,-30 -29.7 5), (-45 -33 1,-46 -32 11))')
    		)
    );
    st_astext
    --------------------------------------------------------------------------------------------------
    LINESTRING Z (-30 -29.7 5,-29 -27 11,-30 -29.7 10,-36 -31 5,-45 -33 1,-46 -32 11)
    (1 row)

### See Also

ST_Segmentize, ST_LineSubstring

ST_CollectionExtract

Given a (multi)geometry, return a (multi)geometry consisting only of elements of the specified type.

    				geometry ST_CollectionExtract
    				geometry  collection
    				integer  type

### Description

Given a (multi)geometry, returns a (multi)geometry consisting only of elements of the specified type. Sub-geometries that are not the specified type are ignored. If there are no sub-geometries of the right type, an EMPTY geometry will be returned. Only points, lines and polygons are supported. Type numbers are 1 == POINT, 2 == LINESTRING, 3 == POLYGON.

Availability: 1.5.0

Prior to 1.5.3 this function returned non-collection inputs untouched, no matter type. In 1.5.3 non-matching single geometries result in a NULL return. In of 2.0.0 every case of missing match results in a typed EMPTY return.

When specifying 3 == POLYGON a multipolygon is returned even when the edges are shared. This results in an invalid multipolygon for many cases such as applying this function on an ST_Split result.

### Examples

    -- Constants: 1 == POINT, 2 == LINESTRING, 3 == POLYGON
    SELECT ST_AsText(ST_CollectionExtract(ST_GeomFromText('GEOMETRYCOLLECTION(GEOMETRYCOLLECTION(POINT(0 0)))'),1));
    st_astext
    ---------------
    MULTIPOINT(0 0)
    (1 row)

    SELECT ST_AsText(ST_CollectionExtract(ST_GeomFromText('GEOMETRYCOLLECTION(GEOMETRYCOLLECTION(LINESTRING(0 0, 1 1)),LINESTRING(2 2, 3 3))'),2));
    st_astext
    ---------------
    MULTILINESTRING((0 0, 1 1), (2 2, 3 3))
    (1 row)

### See Also

ST_Multi, ST_Dump, ST_CollectionHomogenize

ST_CollectionHomogenize

Given a geometry collection, return the "simplest" representation of the contents.

    					geometry ST_CollectionHomogenize
    					geometry  collection

### Description

Given a geometry collection, returns the "simplest" representation of the contents. Singletons will be returned as singletons. Collections that are homogeneous will be returned as the appropriate multi-type.

When specifying 3 == POLYGON a multipolygon is returned even when the edges are shared. This results in an invalid multipolygon for many cases such as applying this function on an ST_Split result.

Availability: 2.0.0

### Examples

      SELECT ST_AsText(ST_CollectionHomogenize('GEOMETRYCOLLECTION(POINT(0 0))'));

    	st_astext
    	------------
    	 POINT(0 0)
    	(1 row)

      SELECT ST_AsText(ST_CollectionHomogenize('GEOMETRYCOLLECTION(POINT(0 0),POINT(1 1))'));

    	st_astext
    	---------------------
    	 MULTIPOINT(0 0,1 1)
    	(1 row)

### See Also

ST_Multi, ST_CollectionExtract

ST_Multi

Return the geometry as a MULTI* geometry.

    				geometry ST_Multi
    				geometry  g1

### Description

Returns the geometry as a MULTI* geometry. If the geometry is already a MULTI*, it is returned unchanged.

### Examples

    SELECT ST_AsText(ST_Multi(ST_GeomFromText('POLYGON((743238 2967416,743238 2967450,
    			743265 2967450,743265.625 2967416,743238 2967416))')));
    			st_astext
    			--------------------------------------------------------------------------------------------------
    			MULTIPOLYGON(((743238 2967416,743238 2967450,743265 2967450,743265.625 2967416,
    			743238 2967416)))
    			(1 row)

### See Also

ST_AsText

ST_Normalize

Return the geometry in its canonical form.

    				geometry ST_Normalize
    				geometry  geom

### Description

Returns the geometry in its normalized/canonical form. May reorder vertices in polygon rings, rings in a polygon, elements in a multi-geometry complex.

Mostly only useful for testing purposes (comparing expected and obtained results).

Availability: 2.3.0

### Examples

    SELECT ST_AsText(ST_Normalize(ST_GeomFromText(
      'GEOMETRYCOLLECTION(
        POINT(2 3),
        MULTILINESTRING((0 0, 1 1),(2 2, 3 3)),
        POLYGON(
          (0 10,0 0,10 0,10 10,0 10),
          (4 2,2 2,2 4,4 4,4 2),
          (6 8,8 8,8 6,6 6,6 8)
        )
      )'
    )));
                                                                         st_astext
    ----------------------------------------------------------------------------------------------------------------------------------------------------
     GEOMETRYCOLLECTION(POLYGON((0 0,0 10,10 10,10 0,0 0),(6 6,8 6,8 8,6 8,6 6),(2 2,4 2,4 4,2 4,2 2)),MULTILINESTRING((2 2,3 3),(0 0,1 1)),POINT(2 3))
    (1 row)

### See Also

ST_Equals,

ST_QuantizeCoordinates

Sets least significant bits of coordinates to zero

    						geometry
    						ST_QuantizeCoordinates

    						geometry
    						g

    						int
    						prec_x

    						int
    						prec_y

    						int
    						prec_z

    						int
    						prec_m

### Description

`ST_QuantizeCoordinates` determines the number of bits (`N`) required to represent a coordinate value with a specified number of digits after the decimal point, and then sets all but the `N` most significant bits to zero. The resulting coordinate value will still round to the original value, but will have improved compressiblity. This can result in a significant disk usage reduction provided that the geometry column is using a compressible storage type. The function allows specification of a different number of digits after the decimal point in each dimension; unspecified dimensions are assumed to have the precsion of the `x` dimension. Negative digits are interpreted to refer digits to the left of the decimal point, (i.e., `prec_x=-2` will preserve coordinate values to the nearest 100.

The coordinates produced by `ST_QuantizeCoordinates` are independent of the geometry that contains those coordinates and the relative position of those coordinates within the geometry. As a result, existing topological relationships between geometries are unaffected by use of this function. The function may produce invalid geometry when it is called with a number of digits lower than the intrinsic precision of the geometry.

Availability: 2.5.0

### Technical Background

PostGIS stores all coordinate values as double-precision floating point integers, which can reliably represent 15 significant digits. However, PostGIS may be used to manage data that intrinsically has fewer than 15 significant digits. An example is TIGER data, which is provided as geographic coordinates with six digits of precision after the decimal point (thus requiring only nine significant digits of longitude and eight significant digits of latitude.)

When 15 significant digits are available, there are many possible representations of a number with 9 significant digits. A double precision floating point number uses 52 explicit bits to represent the significand (mantissa) of the coordinate. Only 30 bits are needed to represent a mantissa with 9 significant digits, leaving 22 insignificant bits; we can set their value to anything we like and still end up with a number that rounds to our input value. For example, the value 100.123456 can be represented by the floating point numbers closest to 100.123456000000, 100.123456000001, and 100.123456432199. All are equally valid, in that `ST_AsText(geom, 6)` will return the same result with any of these inputs. As we can set these bits to any value, `ST_QuantizeCoordinates` sets the 22 insignificant bits to zero. For a long coordinate sequence this creates a pattern of blocks of consecutive zeros that is compressed by PostgreSQL more effeciently.

Only the on-disk size of the geometry is potentially affected by `ST_QuantizeCoordinates`. ST_MemSize, which reports the in-memory usage of the geometry, will return the the same value regardless of the disk space used by a geometry.

### Examples

    SELECT ST_AsText(ST_QuantizeCoordinates('POINT (100.123456 0)'::geometry, 4));
    st_astext
    -------------------------
    POINT(100.123455047607 0)

    WITH test AS (SELECT 'POINT (123.456789123456 123.456789123456)'::geometry AS geom)
    SELECT
      digits,
      encode(ST_QuantizeCoordinates(geom, digits), 'hex'),
      ST_AsText(ST_QuantizeCoordinates(geom, digits))
    FROM test, generate_series(15, -15, -1) AS digits;

    digits  |                   encode                   |                st_astext
    --------+--------------------------------------------+------------------------------------------
    15      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
    14      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
    13      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
    12      | 01010000005c9a72083cdd5e405c9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
    11      | 0101000000409a72083cdd5e40409a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
    10      | 0101000000009a72083cdd5e40009a72083cdd5e40 | POINT(123.456789123455 123.456789123455)
    9       | 0101000000009072083cdd5e40009072083cdd5e40 | POINT(123.456789123418 123.456789123418)
    8       | 0101000000008072083cdd5e40008072083cdd5e40 | POINT(123.45678912336 123.45678912336)
    7       | 0101000000000070083cdd5e40000070083cdd5e40 | POINT(123.456789121032 123.456789121032)
    6       | 0101000000000040083cdd5e40000040083cdd5e40 | POINT(123.456789076328 123.456789076328)
    5       | 0101000000000000083cdd5e40000000083cdd5e40 | POINT(123.456789016724 123.456789016724)
    4       | 0101000000000000003cdd5e40000000003cdd5e40 | POINT(123.456787109375 123.456787109375)
    3       | 0101000000000000003cdd5e40000000003cdd5e40 | POINT(123.456787109375 123.456787109375)
    2       | 01010000000000000038dd5e400000000038dd5e40 | POINT(123.45654296875 123.45654296875)
    1       | 01010000000000000000dd5e400000000000dd5e40 | POINT(123.453125 123.453125)
    0       | 01010000000000000000dc5e400000000000dc5e40 | POINT(123.4375 123.4375)
    -1      | 01010000000000000000c05e400000000000c05e40 | POINT(123 123)
    -2      | 01010000000000000000005e400000000000005e40 | POINT(120 120)
    -3      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -4      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -5      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -6      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -7      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -8      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -9      | 010100000000000000000058400000000000005840 | POINT(96 96)
    -10     | 010100000000000000000058400000000000005840 | POINT(96 96)
    -11     | 010100000000000000000058400000000000005840 | POINT(96 96)
    -12     | 010100000000000000000058400000000000005840 | POINT(96 96)
    -13     | 010100000000000000000058400000000000005840 | POINT(96 96)
    -14     | 010100000000000000000058400000000000005840 | POINT(96 96)
    -15     | 010100000000000000000058400000000000005840 | POINT(96 96)

### See Also

ST_SnapToGrid

ST_RemovePoint

Remove point from a linestring.

    			geometry ST_RemovePoint
    			geometry linestring
    			integer offset

### Description

Remove a point from a linestring, given its 0-based index. Useful for turning a closed ring into an open line string

Availability: 1.1.0

&Z_support;

### Examples

    --guarantee no LINESTRINGS are closed
    --by removing the end point.  The below assumes the_geom is of type LINESTRING
    UPDATE sometable
    	SET the_geom = ST_RemovePoint(the_geom, ST_NPoints(the_geom) - 1)
    	FROM sometable
    	WHERE ST_IsClosed(the_geom) = true;

### See Also

ST_AddPoint, ST_NPoints, ST_NumPoints

ST_Reverse

Return the geometry with vertex order reversed.

    			geometry ST_Reverse
    			geometry  g1

### Description

Can be used on any geometry and reverses the order of the vertexes.

Enhanced: 2.4.0 support for curves was introduced.

&Z_support;

&P_support;

### Examples

    SELECT ST_AsText(the_geom) as line, ST_AsText(ST_Reverse(the_geom)) As reverseline
    FROM
    (SELECT ST_MakeLine(ST_MakePoint(1,2),
    		ST_MakePoint(1,10)) As the_geom) as foo;
    --result
    		line         |     reverseline
    ---------------------+----------------------
    LINESTRING(1 2,1 10) | LINESTRING(1 10,1 2)

ST_Rotate

Rotate a geometry rotRadians counter-clockwise about an origin.

    			geometry ST_Rotate
    			geometry geomA
    			float rotRadians

                            geometry ST_Rotate
                            geometry geomA
                            float rotRadians
                            float x0
                            float y0

                            geometry ST_Rotate
                            geometry geomA
                            float rotRadians
                            geometry pointOrigin

### Description

Rotates geometry rotRadians counter-clockwise about the origin. The rotation origin can be specified either as a POINT geometry, or as x and y coordinates. If the origin is not specified, the geometry is rotated about POINT(0 0).

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Enhanced: 2.0.0 additional parameters for specifying the origin of rotation were added.

Availability: 1.1.2. Name changed from Rotate to ST_Rotate in 1.2.2

&Z_support;

&curve_support;

&P_support;

&T_support;

### Examples

    --Rotate 180 degrees
    SELECT ST_AsEWKT(ST_Rotate('LINESTRING (50 160, 50 50, 100 50)', pi()));
                   st_asewkt
    ---------------------------------------
     LINESTRING(-50 -160,-50 -50,-100 -50)
    (1 row)

    --Rotate 30 degrees counter-clockwise at x=50, y=160
    SELECT ST_AsEWKT(ST_Rotate('LINESTRING (50 160, 50 50, 100 50)', pi()/6, 50, 160));
                                     st_asewkt
    ---------------------------------------------------------------------------
     LINESTRING(50 160,105 64.7372055837117,148.301270189222 89.7372055837117)
    (1 row)

    --Rotate 60 degrees clockwise from centroid
    SELECT ST_AsEWKT(ST_Rotate(geom, -pi()/3, ST_Centroid(geom)))
    FROM (SELECT 'LINESTRING (50 160, 50 50, 100 50)'::geometry AS geom) AS foo;
                               st_asewkt
    --------------------------------------------------------------
     LINESTRING(116.4225 130.6721,21.1597 75.6721,46.1597 32.3708)
    (1 row)

### See Also

ST_Affine, ST_RotateX, ST_RotateY, ST_RotateZ

ST_RotateX

Rotate a geometry rotRadians about the X axis.

    			geometry ST_RotateX
    			geometry geomA
    			float rotRadians

### Description

Rotate a geometry geomA - rotRadians about the X axis.

`ST_RotateX(geomA, rotRadians)` is short-hand for `ST_Affine(geomA, 1, 0, 0, 0, cos(rotRadians), -sin(rotRadians), 0, sin(rotRadians), cos(rotRadians), 0, 0, 0)`.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Availability: 1.1.2. Name changed from RotateX to ST_RotateX in 1.2.2

&P_support;

&Z_support;

&T_support;

### Examples

    --Rotate a line 90 degrees along x-axis
    SELECT ST_AsEWKT(ST_RotateX(ST_GeomFromEWKT('LINESTRING(1 2 3, 1 1 1)'), pi()/2));
    		 st_asewkt
    ---------------------------
     LINESTRING(1 -3 2,1 -1 1)

### See Also

ST_Affine, ST_RotateY, ST_RotateZ

ST_RotateY

Rotate a geometry rotRadians about the Y axis.

    			geometry ST_RotateY
    			geometry geomA
    			float rotRadians

### Description

Rotate a geometry geomA - rotRadians about the y axis.

`ST_RotateY(geomA, rotRadians)` is short-hand for `ST_Affine(geomA, cos(rotRadians), 0, sin(rotRadians), 0, 1, 0, -sin(rotRadians), 0, cos(rotRadians), 0, 0, 0)`.

Availability: 1.1.2. Name changed from RotateY to ST_RotateY in 1.2.2

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

&P_support;

&Z_support;

&T_support;

### Examples

    --Rotate a line 90 degrees along y-axis
     SELECT ST_AsEWKT(ST_RotateY(ST_GeomFromEWKT('LINESTRING(1 2 3, 1 1 1)'), pi()/2));
    		 st_asewkt
    ---------------------------
     LINESTRING(3 2 -1,1 1 -1)

### See Also

ST_Affine, ST_RotateX, ST_RotateZ

ST_RotateZ

Rotate a geometry rotRadians about the Z axis.

    			geometry ST_RotateZ
    			geometry geomA
    			float rotRadians

### Description

Rotate a geometry geomA - rotRadians about the Z axis.

This is a synonym for ST_Rotate

`ST_RotateZ(geomA, rotRadians)` is short-hand for `SELECT ST_Affine(geomA, cos(rotRadians), -sin(rotRadians), 0, sin(rotRadians), cos(rotRadians), 0, 0, 0, 1, 0, 0, 0)`.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Availability: 1.1.2. Name changed from RotateZ to ST_RotateZ in 1.2.2

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

&Z_support;

&curve_support;

&P_support;

&T_support;

### Examples

    --Rotate a line 90 degrees along z-axis
    SELECT ST_AsEWKT(ST_RotateZ(ST_GeomFromEWKT('LINESTRING(1 2 3, 1 1 1)'), pi()/2));
    		 st_asewkt
    ---------------------------
     LINESTRING(-2 1 3,-1 1 1)

     --Rotate a curved circle around z-axis
    SELECT ST_AsEWKT(ST_RotateZ(the_geom, pi()/2))
    FROM (SELECT ST_LineToCurve(ST_Buffer(ST_GeomFromText('POINT(234 567)'), 3)) As the_geom) As foo;

    													   st_asewkt
    ----------------------------------------------------------------------------------------------------------------------------
     CURVEPOLYGON(CIRCULARSTRING(-567 237,-564.87867965644 236.12132034356,-564 234,-569.12132034356 231.87867965644,-567 237))

### See Also

ST_Affine, ST_RotateX, ST_RotateY

ST_Scale

Scale a geometry by given factors.

    			geometry ST_Scale
    			geometry  geomA
    			float XFactor
    			float YFactor
    			float ZFactor

    			geometry ST_Scale
    			geometry  geomA
    			float XFactor
    			float YFactor

    			geometry ST_Scale
    			geometry  geom
    			geometry factor

    			geometry ST_Scale
    			geometry  geom
    			geometry factor
    			geometry origin

### Description

Scales the geometry to a new size by multiplying the ordinates with the corresponding factor parameters.

The version taking a geometry as the `factor` parameter allows passing a 2d, 3dm, 3dz or 4d point to set scaling factor for all supported dimensions. Missing dimensions in the `factor` point are equivalent to no scaling the corresponding dimension.

The three-geometry variant allows a "false origin" for the scaling to be passed in. This allows "scaling in place", for example using the centroid of the geometry as the false origin. Without a false origin, scaling takes place relative to the actual origin, so all coordinates are just multipled by the scale factor.

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

Availability: 1.1.0.

Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.

Enhanced: 2.2.0 support for scaling all dimension (`factor` parameter) was introduced.

Enhanced: 2.5.0 support for scaling relative to a local origin (`origin` parameter) was introduced.

&P_support;

&Z_support;

&curve_support;

&T_support;

&M_support;

### Examples

    --Version 1: scale X, Y, Z
    SELECT ST_AsEWKT(ST_Scale(ST_GeomFromEWKT('LINESTRING(1 2 3, 1 1 1)'), 0.5, 0.75, 0.8));
    			  st_asewkt
    --------------------------------------
     LINESTRING(0.5 1.5 2.4,0.5 0.75 0.8)

    --Version 2: Scale X Y
     SELECT ST_AsEWKT(ST_Scale(ST_GeomFromEWKT('LINESTRING(1 2 3, 1 1 1)'), 0.5, 0.75));
    			st_asewkt
    ----------------------------------
     LINESTRING(0.5 1.5 3,0.5 0.75 1)

    --Version 3: Scale X Y Z M
     SELECT ST_AsEWKT(ST_Scale(ST_GeomFromEWKT('LINESTRING(1 2 3 4, 1 1 1 1)'),
       ST_MakePoint(0.5, 0.75, 2, -1)));
    			       st_asewkt
    ----------------------------------------
     LINESTRING(0.5 1.5 6 -4,0.5 0.75 2 -1)

    --Version 4: Scale X Y using false origin
    SELECT ST_AsText(ST_Scale('LINESTRING(1 1, 2 2)', 'POINT(2 2)', 'POINT(1 1)'::geometry));
          st_astext
    ---------------------
     LINESTRING(1 1,3 3)

### See Also

ST_Affine, ST_TransScale

ST_Segmentize

Return a modified geometry/geography having no segment longer than the given distance.

    				geometry ST_Segmentize
    				geometry  geom
    				float  max_segment_length

    				geography ST_Segmentize
    				geography  geog
    				float  max_segment_length

### Description

Returns a modified geometry having no segment longer than the given `max_segment_length`. Distance computation is performed in 2d only. For geometry, length units are in units of spatial reference. For geography, units are in meters.

Availability: 1.2.2

Enhanced: 3.0.0 Segmentize geometry now uses equal length segments

Enhanced: 2.3.0 Segmentize geography now uses equal length segments

Enhanced: 2.1.0 support for geography was introduced.

Changed: 2.1.0 As a result of the introduction of geography support: The construct `SELECT ST_Segmentize('LINESTRING(1 2, 3 4)',0.5);` will result in ambiguous function error. You need to have properly typed object e.g. a geometry/geography column, use ST_GeomFromText, ST_GeogFromText or `SELECT ST_Segmentize('LINESTRING(1 2, 3 4)'::geometry,0.5);`

This will only increase segments. It will not lengthen segments shorter than max length

### Examples

    SELECT ST_AsText(ST_Segmentize(
    ST_GeomFromText('MULTILINESTRING((-29 -27,-30 -29.7,-36 -31,-45 -33),(-45 -33,-46 -32))')
    		,5)
    );
    st_astext
    --------------------------------------------------------------------------------------------------
    MULTILINESTRING((-29 -27,-30 -29.7,-34.886615700134 -30.758766735029,-36 -31,
    -40.8809353009198 -32.0846522890933,-45 -33),
    (-45 -33,-46 -32))
    (1 row)

    SELECT ST_AsText(ST_Segmentize(ST_GeomFromText('POLYGON((-29 28, -30 40, -29 28))'),10));
    st_astext
    -----------------------
    POLYGON((-29 28,-29.8304547985374 37.9654575824488,-30 40,-29.1695452014626 30.0345424175512,-29 28))
    (1 row)

### See Also

ST_LineSubstring

ST_SetPoint

Replace point of a linestring with a given point.

    				geometry ST_SetPoint
    				geometry linestring
    				integer zerobasedposition
    				geometry point

### Description

Replace point N of linestring with given point. Index is 0-based.Negative index are counted backwards, so that -1 is last point. This is especially useful in triggers when trying to maintain relationship of joints when one vertex moves.

Availability: 1.1.0

Updated 2.3.0 : negative indexing

&Z_support;

### Examples

    --Change first point in line string from -1 3 to -1 1
    SELECT ST_AsText(ST_SetPoint('LINESTRING(-1 2,-1 3)', 0, 'POINT(-1 1)'));
    	   st_astext
    -----------------------
     LINESTRING(-1 1,-1 3)

    ---Change last point in a line string (lets play with 3d linestring this time)
    SELECT ST_AsEWKT(ST_SetPoint(foo.the_geom, ST_NumPoints(foo.the_geom) - 1, ST_GeomFromEWKT('POINT(-1 1 3)')))
    FROM (SELECT ST_GeomFromEWKT('LINESTRING(-1 2 3,-1 3 4, 5 6 7)') As the_geom) As foo;
    	   st_asewkt
    -----------------------
    LINESTRING(-1 2 3,-1 3 4,-1 1 3)

    SELECT ST_AsText(ST_SetPoint(g, -3, p))
    FROM ST_GEomFromText('LINESTRING(0 0, 1 1, 2 2, 3 3, 4 4)') AS g
    	, ST_PointN(g,1) as p;
    	   st_astext
    -----------------------
    LINESTRING(0 0,1 1,0 0,3 3,4 4)

### See Also

ST_AddPoint, ST_NPoints, ST_NumPoints, ST_PointN, ST_RemovePoint

ST_SetSRID

Set the SRID on a geometry to a particular integer value.

    			geometry ST_SetSRID

    			geometry
    			geom

    			integer
    			srid

### Description

Sets the SRID on a geometry to a particular integer value. Useful in constructing bounding boxes for queries.

This function does not transform the geometry coordinates in any way - it simply sets the meta data defining the spatial reference system the geometry is assumed to be in. Use ST_Transform if you want to transform the geometry into a new projection.

&sfs_compliant;

&curve_support;

### Examples

-- Mark a point as WGS 84 long lat --

    SELECT ST_SetSRID(ST_Point(-123.365556, 48.428611),4326) As wgs84long_lat;
    -- the ewkt representation (wrap with ST_AsEWKT) -
    SRID=4326;POINT(-123.365556 48.428611)

-- Mark a point as WGS 84 long lat and then transform to web mercator (Spherical Mercator) --

    SELECT ST_Transform(ST_SetSRID(ST_Point(-123.365556, 48.428611),4326),3785) As spere_merc;
    -- the ewkt representation (wrap with ST_AsEWKT) -
    SRID=3785;POINT(-13732990.8753491 6178458.96425423)

### See Also

spatial_ref_sys, ST_AsEWKT, ST_Point, ST_SRID, ST_Transform, UpdateGeometrySRID

ST_SnapToGrid

Snap all points of the input geometry to a regular grid.

    			geometry ST_SnapToGrid
    			geometry  geomA
    			float  originX
    			float  originY
    			float  sizeX
    			float  sizeY

    			geometry ST_SnapToGrid
    			geometry  geomA
    			float  sizeX
    			float  sizeY

    			geometry ST_SnapToGrid
    			geometry  geomA
    			float  size

    			geometry ST_SnapToGrid
    			geometry  geomA
    			geometry  pointOrigin
    			float  sizeX
    			float  sizeY
    			float  sizeZ
    			float  sizeM

### Description

Variant 1,2,3: Snap all points of the input geometry to the grid defined by its origin and cell size. Remove consecutive points falling on the same cell, eventually returning NULL if output points are not enough to define a geometry of the given type. Collapsed geometries in a collection are stripped from it. Useful for reducing precision.

Variant 4: Introduced 1.1.0 - Snap all points of the input geometry to the grid defined by its origin (the second argument, must be a point) and cell sizes. Specify 0 as size for any dimension you don't want to snap to a grid.

The returned geometry might lose its simplicity (see ST_IsSimple).

Before release 1.1.0 this function always returned a 2d geometry. Starting at 1.1.0 the returned geometry will have same dimensionality as the input one with higher dimension values untouched. Use the version taking a second geometry argument to define all grid dimensions.

Availability: 1.0.0RC1

Availability: 1.1.0 - Z and M support

&Z_support;

### Examples

    --Snap your geometries to a precision grid of 10^-3
    UPDATE mytable
       SET the_geom = ST_SnapToGrid(the_geom, 0.001);

    SELECT ST_AsText(ST_SnapToGrid(
    			ST_GeomFromText('LINESTRING(1.1115678 2.123, 4.111111 3.2374897, 4.11112 3.23748667)'),
    			0.001)
    		);
    			  st_astext
    -------------------------------------
     LINESTRING(1.112 2.123,4.111 3.237)
     --Snap a 4d geometry
    SELECT ST_AsEWKT(ST_SnapToGrid(
    	ST_GeomFromEWKT('LINESTRING(-1.1115678 2.123 2.3456 1.11111,
    		4.111111 3.2374897 3.1234 1.1111, -1.11111112 2.123 2.3456 1.1111112)'),
     ST_GeomFromEWKT('POINT(1.12 2.22 3.2 4.4444)'),
     0.1, 0.1, 0.1, 0.01) );
    								  st_asewkt
    ------------------------------------------------------------------------------
     LINESTRING(-1.08 2.12 2.3 1.1144,4.12 3.22 3.1 1.1144,-1.08 2.12 2.3 1.1144)

    --With a 4d geometry - the ST_SnapToGrid(geom,size) only touches x and y coords but keeps m and z the same
    SELECT ST_AsEWKT(ST_SnapToGrid(ST_GeomFromEWKT('LINESTRING(-1.1115678 2.123 3 2.3456,
    		4.111111 3.2374897 3.1234 1.1111)'),
    	   0.01)      );
    						st_asewkt
    ---------------------------------------------------------
     LINESTRING(-1.11 2.12 3 2.3456,4.11 3.24 3.1234 1.1111)

### See Also

ST_Snap, ST_AsEWKT, ST_AsText, ST_GeomFromText, ST_GeomFromEWKT, ST_Simplify

ST_Snap

Snap segments and vertices of input geometry to vertices of a reference geometry.

    			geometry ST_Snap
    			geometry  input
    			geometry  reference
    			float  tolerance

### Description

Snaps the vertices and segments of a geometry another Geometry's vertices. A snap distance tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. If no snapping occurs then the input geometry is returned unchanged.

Snapping one geometry to another can improve robustness for overlay operations by eliminating nearly-coincident edges (which cause problems during noding and intersection calculation).

Too much snapping can result in invalid topology being created, so the number and location of snapped vertices is decided using heuristics to determine when it is safe to snap. This can result in some potential snaps being omitted, however.

The returned geometry might lose its simplicity (see ST_IsSimple) and validity (see ST_IsValid).

Availability: 2.0.0 requires GEOS >= 3.3.0.

### Examples

A multipolygon shown with a linestring (before any snapping)
A multipolygon snapped to linestring to tolerance: 1.01 of distance. The new multipolygon is shown with reference linestring
    SELECT ST_AsText(ST_Snap(poly,line, ST_Distance(poly,line)*1.01)) AS polysnapped
    FROM (SELECT
       ST_GeomFromText('MULTIPOLYGON(
         ((26 125, 26 200, 126 200, 126 125, 26 125 ),
          ( 51 150, 101 150, 76 175, 51 150 )),
          (( 151 100, 151 200, 176 175, 151 100 )))') As poly,
           ST_GeomFromText('LINESTRING (5 107, 54 84, 101 100)') As line

    	) As foo;

                                 polysnapped
    ---------------------------------------------------------------------
     MULTIPOLYGON(((26 125,26 200,126 200,126 125,101 100,26 125),
     (51 150,101 150,76 175,51 150)),((151 100,151 200,176 175,151 100)))
| A multipolygon snapped to linestring to tolerance: 1.25 of distance. The new multipolygon is shown with reference linestring
    SELECT ST_AsText(
        ST_Snap(poly,line, ST_Distance(poly,line)*1.25)
      ) AS polysnapped
    FROM (SELECT
      ST_GeomFromText('MULTIPOLYGON(
        (( 26 125, 26 200, 126 200, 126 125, 26 125 ),
          ( 51 150, 101 150, 76 175, 51 150 )),
          (( 151 100, 151 200, 176 175, 151 100 )))') As poly,
           ST_GeomFromText('LINESTRING (5 107, 54 84, 101 100)') As line

    	) As foo;

                                 polysnapped
    ---------------------------------------------------------------------
    MULTIPOLYGON(((5 107,26 200,126 200,126 125,101 100,54 84,5 107),
    (51 150,101 150,76 175,51 150)),((151 100,151 200,176 175,151 100)))
The linestring snapped to the original multipolygon at tolerance 1.01 of distance. The new linestring is shown with reference multipolygon
    SELECT ST_AsText(
       ST_Snap(line, poly, ST_Distance(poly,line)*1.01)
      ) AS linesnapped
    FROM (SELECT
      ST_GeomFromText('MULTIPOLYGON(
         ((26 125, 26 200, 126 200, 126 125, 26 125),
          (51 150, 101 150, 76 175, 51 150 )),
          ((151 100, 151 200, 176 175, 151 100)))') As poly,
           ST_GeomFromText('LINESTRING (5 107, 54 84, 101 100)') As line
    	) As foo;

                  linesnapped
    ----------------------------------------
     LINESTRING(5 107,26 125,54 84,101 100)
| The linestring snapped to the original multipolygon at tolerance 1.25 of distance. The new linestring is shown with reference multipolygon
    SELECT ST_AsText(
     ST_Snap(line, poly, ST_Distance(poly,line)*1.25)
      ) AS linesnapped
    FROM (SELECT
      ST_GeomFromText('MULTIPOLYGON(
         (( 26 125, 26 200, 126 200, 126 125, 26 125 ),
          (51 150, 101 150, 76 175, 51 150 )),
          ((151 100, 151 200, 176 175, 151 100 )))') As poly,
           ST_GeomFromText('LINESTRING (5 107, 54 84, 101 100)') As line
    	) As foo;
                  linesnapped
    ---------------------------------------
    LINESTRING(26 125,54 84,101 100)

### See Also

ST_SnapToGrid

ST_Transform

Return a new geometry with its coordinates transformed to a different spatial reference.

    			geometry ST_Transform
    			geometry  g1
    			integer  srid

                  geometry ST_Transform
                  geometry  geom
                  text  to_proj

                  geometry ST_Transform
                  geometry  geom
                  text  from_proj
                  text  to_proj

                  geometry ST_Transform
                  geometry  geom
                  text  from_proj
                  integer  to_srid

### Description

Returns a new geometry with its coordinates transformed to a different spatial reference system. The destination spatial reference `to_srid` may be identified by a valid SRID integer parameter (i.e. it must exist in the `spatial_ref_sys` table). Alternatively, a spatial reference defined as a PROJ.4 string can be used for `to_proj` and/or `from_proj`, however these methods are not optimized. If the destination spatial reference system is expressed with a PROJ.4 string instead of an SRID, the SRID of the output geometry will be set to zero. With the exception of functions with `from_proj`, input geometries must have a defined SRID.

ST_Transform is often confused with ST_SetSRID(). ST_Transform actually changes the coordinates of a geometry from one spatial reference system to another, while ST_SetSRID() simply changes the SRID identifier of the geometry.

Requires PostGIS be compiled with Proj support. Use PostGIS_Full_Version to confirm you have proj support compiled in.

If using more than one transformation, it is useful to have a functional index on the commonly used transformations to take advantage of index usage.

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

Enhanced: 2.0.0 support for Polyhedral surfaces was introduced.

Enhanced: 2.3.0 support for direct PROJ.4 text was introduced.

&sqlmm_compliant; SQL-MM 3: 5.1.6

&curve_support;

&P_support;

### Examples

Change Massachusetts state plane US feet geometry to WGS 84 long lat

    SELECT ST_AsText(ST_Transform(ST_GeomFromText('POLYGON((743238 2967416,743238 2967450,
    	743265 2967450,743265.625 2967416,743238 2967416))',2249),4326)) As wgs_geom;

     wgs_geom
    ---------------------------
     POLYGON((-71.1776848522251 42.3902896512902,-71.1776843766326 42.3903829478009,
    -71.1775844305465 42.3903826677917,-71.1775825927231 42.3902893647987,-71.177684
    8522251 42.3902896512902));
    (1 row)

    --3D Circular String example
    SELECT ST_AsEWKT(ST_Transform(ST_GeomFromEWKT('SRID=2249;CIRCULARSTRING(743238 2967416 1,743238 2967450 2,743265 2967450 3,743265.625 2967416 3,743238 2967416 4)'),4326));

    				 st_asewkt
    --------------------------------------------------------------------------------------
     SRID=4326;CIRCULARSTRING(-71.1776848522251 42.3902896512902 1,-71.1776843766326 42.3903829478009 2,
     -71.1775844305465 42.3903826677917 3,
     -71.1775825927231 42.3902893647987 3,-71.1776848522251 42.3902896512902 4)

Example of creating a partial functional index. For tables where you are not sure all the geometries will be filled in, its best to use a partial index that leaves out null geometries which will both conserve space and make your index smaller and more efficient.

    CREATE INDEX idx_the_geom_26986_parcels
      ON parcels
      USING gist
      (ST_Transform(the_geom, 26986))
      WHERE the_geom IS NOT NULL;

Examples of using PROJ.4 text to transform with custom spatial references.

    -- Find intersection of two polygons near the North pole, using a custom Gnomic projection
    -- See http://boundlessgeo.com/2012/02/flattening-the-peel/
     WITH data AS (
       SELECT
         ST_GeomFromText('POLYGON((170 50,170 72,-130 72,-130 50,170 50))', 4326) AS p1,
         ST_GeomFromText('POLYGON((-170 68,-170 90,-141 90,-141 68,-170 68))', 4326) AS p2,
         '+proj=gnom +ellps=WGS84 +lat_0=70 +lon_0=-160 +no_defs'::text AS gnom
     )
     SELECT ST_AsText(
       ST_Transform(
         ST_Intersection(ST_Transform(p1, gnom), ST_Transform(p2, gnom)),
       gnom, 4326))
     FROM data;
                                              st_astext
     --------------------------------------------------------------------------------
      POLYGON((-170 74.053793645338,-141 73.4268621378904,-141 68,-170 68,-170 74.053793645338))

### Configuring transformation behaviour

Sometimes coordinate transformation involving a grid-shift can fail, for example if PROJ.4 has not been built with grid-shift files or the coordinate does not lie within the range for which the grid shift is defined. By default, PostGIS will throw an error if a grid shift file is not present, but this behaviour can be configured on a per-SRID basis either by testing different `to_proj` values of PROJ.4 text, or altering the `proj4text` value within the `spatial_ref_sys` table.

For example, the proj4text parameter +datum=NAD87 is a shorthand form for the following +nadgrids parameter:

    +nadgrids=@conus,@alaska,@ntv2_0.gsb,@ntv1_can.dat

The @ prefix means no error is reported if the files are not present, but if the end of the list is reached with no file having been appropriate (ie. found and overlapping) then an error is issued.

If, conversely, you wanted to ensure that at least the standard files were present, but that if all files were scanned without a hit a null transformation is applied you could use:

    +nadgrids=@conus,@alaska,@ntv2_0.gsb,@ntv1_can.dat,null

The null grid shift file is a valid grid shift file covering the whole world and applying no shift. So for a complete example, if you wanted to alter PostGIS so that transformations to SRID 4267 that didn't lie within the correct range did not throw an ERROR, you would use the following:

    UPDATE spatial_ref_sys SET proj4text = '+proj=longlat +ellps=clrk66 +nadgrids=@conus,@alaska,@ntv2_0.gsb,@ntv1_can.dat,null +no_defs' WHERE srid = 4267;

### See Also

PostGIS_Full_Version, ST_AsText, ST_SetSRID, UpdateGeometrySRID

ST_Translate

Translate a geometry by given offsets.

    			geometry ST_Translate
    			geometry  g1
    			float  deltax
    			float  deltay

    			geometry ST_Translate
    			geometry  g1
    			float  deltax
    			float  deltay
    			float  deltaz

### Description

Returns a new geometry whose coordinates are translated delta x,delta y,delta z units. Units are based on the units defined in spatial reference (SRID) for this geometry.

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

Availability: 1.2.2

&Z_support;

&curve_support;

### Examples

Move a point 1 degree longitude

    	SELECT ST_AsText(ST_Translate(ST_GeomFromText('POINT(-71.01 42.37)',4326),1,0)) As wgs_transgeomtxt;

    	wgs_transgeomtxt
    	---------------------
    	POINT(-70.01 42.37)

Move a linestring 1 degree longitude and 1/2 degree latitude

    SELECT ST_AsText(ST_Translate(ST_GeomFromText('LINESTRING(-71.01 42.37,-71.11 42.38)',4326),1,0.5)) As wgs_transgeomtxt;
    		   wgs_transgeomtxt
    	---------------------------------------
    	LINESTRING(-70.01 42.87,-70.11 42.88)

Move a 3d point

    SELECT ST_AsEWKT(ST_Translate(CAST('POINT(0 0 0)' As geometry), 5, 12,3));
    	st_asewkt
    	---------
    	POINT(5 12 3)

Move a curve and a point

    SELECT ST_AsText(ST_Translate(ST_Collect('CURVEPOLYGON(CIRCULARSTRING(4 3,3.12 0.878,1 0,-1.121 5.1213,6 7, 8 9,4 3))','POINT(1 3)'),1,2));
    														 st_astext
    ------------------------------------------------------------------------------------------------------------
     GEOMETRYCOLLECTION(CURVEPOLYGON(CIRCULARSTRING(5 5,4.12 2.878,2 2,-0.121 7.1213,7 9,9 11,5 5)),POINT(2 5))

### See Also

ST_Affine, ST_AsText, ST_GeomFromText

ST_TransScale

Translate a geometry by given factors and offsets.

    			geometry ST_TransScale
    			geometry  geomA
    			float deltaX
    			float deltaY
    			float XFactor
    			float YFactor

### Description

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

`ST_TransScale(geomA, deltaX, deltaY, XFactor, YFactor)` is short-hand for `ST_Affine(geomA, XFactor, 0, 0, 0, YFactor, 0, 0, 0, 1, deltaX*XFactor, deltaY*YFactor, 0)`.

Prior to 1.3.4, this function crashes if used with geometries that contain CURVES. This is fixed in 1.3.4+

Availability: 1.1.0.

&Z_support;

&curve_support;

### Examples

    SELECT ST_AsEWKT(ST_TransScale(ST_GeomFromEWKT('LINESTRING(1 2 3, 1 1 1)'), 0.5, 1, 1, 2));
    		  st_asewkt
    -----------------------------
     LINESTRING(1.5 6 3,1.5 4 1)

    --Buffer a point to get an approximation of a circle, convert to curve and then translate 1,2 and scale it 3,4
      SELECT ST_AsText(ST_Transscale(ST_LineToCurve(ST_Buffer('POINT(234 567)', 3)),1,2,3,4));
    														  st_astext
    ------------------------------------------------------------------------------------------------------------------------------
     CURVEPOLYGON(CIRCULARSTRING(714 2276,711.363961030679 2267.51471862576,705 2264,698.636038969321 2284.48528137424,714 2276))

### See Also

ST_Affine, ST_Translate