ST_RemoveIrrelevantPointsForView
Prev  7.5. Geometry Editors  Next

Name

ST_RemoveIrrelevantPointsForView — Removes points that are irrelevant for rendering a specific rectangluar view of a geometry.

Synopsis

geometry ST_RemoveIrrelevantPointsForView(geometry geom, box2d bounds, boolean cartesian_hint = false);

Description

Returns a geometry without points being irrelevant for rendering the geometry within a given rectangluar view.

This function can be used to quickly preprocess geometries that should be rendered only within certain bounds.

Only geometries of type (MULTI)POLYGON and (MULTI)LINESTRING are evaluated. Other geometries keep unchanged.

In contrast to ST_ClipByBox2D() this function

  • sorts out points without computing new intersection points which avoids rounding errors and usually increases performance,

  • returns a geometry with equal or similar point number,

  • leads to the same rendering result within the specified view, and

  • may introduce self-intersections which would make the resulting geometry invalid (see example below).

If cartesian_hint is set to true, the algorithm applies additional optimizations involving cartesian math to further reduce the resulting point number. Please note that using this option might introduce rendering artifacts if the resulting coordinates are projected into another (non-cartesian) coordinate system before rendering.

[Warning]

For polygons, this function does currently not ensure that the result is valid. This situation can be checked with ST_IsValid and repaired with ST_MakeValid.

Example: ST_RemoveIrrelevantPointsForView() applied to a polygon. Blue points remain, the rendering result (light-blue area) within the grey view box remains as well.

Example: Due to the fact that points are just sorted out and no new points are computed, the result of ST_RemoveIrrelevantPointsForView() may contain self-intersections.

Availability: 3.5.0

Examples

			SELECT ST_AsText(
			ST_RemoveIrrelevantPointsForView(
			ST_GeomFromText('MULTIPOLYGON(((10 10, 20 10, 30 10, 40 10, 20 20, 10 20, 10 10)),((10 10, 20 10, 20 20, 10 20, 10 10)))'),
			ST_MakeEnvelope(12,12,18,18), true));
		
		st_astext
		---------
		    MULTIPOLYGON(((10 10,40 10,20 20,10 20,10 10)),((10 10,20 10,20 20,10 20,10 10)))
		
			SELECT ST_AsText(
			ST_RemoveIrrelevantPointsForView(
			ST_GeomFromText('MULTILINESTRING((0 0, 10 0,20 0,30 0), (0 15, 5 15, 10 15, 15 15, 20 15, 25 15, 30 15, 40 15), (13 13,15 15,17 17))'),
			ST_MakeEnvelope(12,12,18,18), true));
		
		st_astext
		---------
			MULTILINESTRING((10 15,15 15,20 15),(13 13,15 15,17 17))
		
			SELECT ST_AsText(
			ST_RemoveIrrelevantPointsForView(
			ST_GeomFromText('LINESTRING(0 0, 10 0,20 0,30 0)'),
			ST_MakeEnvelope(12,12,18,18), true));
		
		st_astext
		---------
		    LINESTRING EMPTY
		
			SELECT ST_AsText(
			ST_RemoveIrrelevantPointsForView(
			ST_GeomFromText('POLYGON((0 30, 15 30, 30 30, 30 0, 0 0, 0 30))'),
			ST_MakeEnvelope(12,12,18,18), true));
		
		st_astext
		---------
		    POLYGON((15 30,30 0,0 0,15 30))
		
			SELECT ST_AsText(
			ST_RemoveIrrelevantPointsForView(
			ST_GeomFromText('POLYGON((0 30, 15 30, 30 30, 30 0, 0 0, 0 30))'),
			ST_MakeEnvelope(12,12,18,18)));
		
		st_astext
		---------
		    POLYGON((0 30,30 30,30 0,0 0,0 30))