Computes the portion of a geometry object that falls within a 2D box.
Syntax
geometry ST_ClipByBox2D(geometry geom, box2d box);Parameters
| Parameter | Type | Description |
|---|---|---|
geom | geometry | The geometry object to clip. |
box | box2d | The 2D box used as the clipping boundary. |
Usage notes
ST_ClipByBox2D clips geometry in a fast but tolerant way: topologically invalid input geometries do not cause errors, and the output is not guaranteed to be valid. In particular, self-intersections may be introduced in polygon output. If you need a valid output geometry, use ST_Intersection instead.
Examples
Clip a line by an envelope
The following example clips a LINESTRING using ST_MakeEnvelope to define the clipping box.
SELECT ST_AsText(ST_ClipByBox2D('LINESTRING(0 1,2 1)'::geometry, ST_MakeEnvelope(0,0,1,2)));
st_astext
---------------------
LINESTRING(0 1,1 1)
(1 row)
Clip geometry objects in a table
Apply ST_ClipByBox2D to a geometry column to clip all rows against a fixed bounding box.
SELECT ST_ClipByBox2D(geom, ST_MakeEnvelope(0, 0, 10, 10)) FROM mytab;See also
ST_Intersection: Returns the exact intersection of two geometry objects. Use this function when a valid output geometry is required.
ST_MakeEnvelope: Creates a rectangular polygon from bounding box coordinates. Use the result as the
boxparameter forST_ClipByBox2D.