H2GIS

Fork me on GitHub

ST_Envelope

Signatures

GEOMETRY ST_Envelope(GEOMETRY geom);
GEOMETRY ST_Envelope(GEOMETRY geom, INT srid);
GEOMETRY ST_Envelope(GEOMETRYCOLLECTION geom);
GEOMETRY ST_Envelope(GEOMETRYCOLLECTION geom, INT srid);

Description

Returns the envelope of geom as a Geometry, optionally setting its SRID to srid. The default SRID is the same as that of geom.

Input type Return type
A POINT POINT
A line parallel to an axis A two-vertex LINESTRING
Otherwise A POLYGON whose coordinates are (minx miny, maxx miny, maxx maxy, minx maxy, minx miny)
Implements the OpenGIS Simple Features Implementation Specification for SQL version 1.2.1.

Examples

-- The envelope of a point is a point.
SELECT ST_Envelope('POINT(1 2)', 2154);
-- Answer: POINT(1 2)

-- This is a line parallel to the x-axis, so only the endpoints are
-- conserved.
SELECT ST_Envelope('LINESTRING(1 1, 5 1, 9 1)');
-- Answer: LINESTRING(1 1, 9 1)

-- (minx miny, maxx miny, maxx maxy, minx maxy, minx miny)
SELECT ST_Envelope('MULTIPOINT(1 2, 3 1, 2 2, 5 1, 1 -1)');
-- Answer: POLYGON((1 -1, 1 2, 5 2, 5 -1, 1 -1))

-- (minx miny, maxx miny, maxx maxy, minx maxy, minx miny)
SELECT ST_Envelope('LINESTRING(1 2, 5 3, 2 6)');
-- Answer: POLYGON((1 2, 1 6, 5 6, 5 2, 1 2))

Setting or preserving the SRID
-- This shows that ST_Envelope preserves the SRID of the input
-- geometry.
SELECT ST_SRID(ST_Envelope(
    ST_GeomFromText('LINESTRING(1 1, 5 5)', 27572)))
-- Answer: 27572

-- This shows that ST_Envelope can set the SRID of Envelope.
SELECT ST_SRID(ST_Envelope(
    ST_GeomFromText('LINESTRING(1 1, 5 5)', 27572), 2154))
-- Answer: 2154
Comparison with ST_Extent
CREATE TABLE input_table(geom GEOMETRY);
INSERT INTO input_table VALUES
     ('POLYGON((0 0, 3 -1, 1.5 2, 0 0))'),
     ('POLYGON((2 0, 3 3, 4 2, 2 0))'),
     ('POINT(5 6)'),
     ('LINESTRING(1 1, 1 6)');

-- ST_Envelope is a scalar function.
SELECT ST_Envelope(geom) ENV FROM input_table;
-- Answer:
--     |                  ENV                   |
--     |----------------------------------------|
--     | POLYGON((0 -1, 0 6, 5 6, 5 -1, 0 -1))  |
--     | POLYGON((2 0, 2 3, 4 3, 4 0, 2 0))     |
--     | POINT(5 6)                             |
--     | LINESTRING(1 1, 1 6)                   |

-- ST_Extent is an aggregate function.
SELECT ST_Extent(geom) EXT FROM input_table;
-- Answer: POLYGON((0 -1, 0 2, 3 2, 3 -1, 0 -1))

-- However, we can make ST_Envelope behave like ST_Extent as follows:
SELECT ST_Equals(ST_Envelope(ST_Accum(geom)),
                 ST_Extent(geom)) FROM input_table;
-- Answer: TRUE

Comparison with ST_MinimumRectangle
CREATE TABLE input_table(geom GEOMETRY);
INSERT INTO input_table VALUES
     ('POLYGON((0 0, 3 -1, 3 1, 2 1, 0 0))'),
     ('POLYGON((2 0, 3 3, 4 2, 2 0))'),
     ('POINT(5 6)'),
     ('LINESTRING(1 1, 1 6)');

SELECT ST_Envelope(geom) ENV, ST_MinimumRectangle(geom) MinRect
      FROM input_table;
-- Answer:
-- |            ENV           |          MinRect            |
-- |--------------------------|-----------------------------|
-- | POLYGON((0 -1, 0 1, 3 1, | POLYGON((3 -1, 3.59 0.80,   |
-- |     3 -1, 0 -1))         |     0.6 1.79, 0 -0, 3 -1))  |
-- | POLYGON((2 0, 2 3, 4 3,  | POLYGON((2 -0, 3.2 -0.40,   |
-- |     4 0, 2 0))           |    4.20 2.59, 3 2.99, 2 0)) |
-- | POINT(5 6)               | POINT(5 6)                  |
-- | LINESTRING(1 1, 1 6)     | LINESTRING(1 1, 1 6)        |

See also