Skip to main content

prepare

Prepares geometry to optimize the performance of repeated calls to specific geometric operations.

The "prepared geometry" is conceptually similar to a database "prepared statement": by doing up-front work to create an optimized object, you reap a performance benefit when executing repeated function calls on that object.

List of functions that benefit from geometry preparation:

Modifies the geometry in-place.

Type Parameters​

  • G - The type of prepared geometry, for example, Geometry or more specific Polygon

Parameters​

NameTypeDescription
geometryGGeometry to prepare

Returns​

Prepared<G>

Exactly the same geometry object, but with prepared internal spatial indexes

Throws​

  • GEOSError on unsupported geometry types (curved)

See also​

Examples​

lifecycle of the prepared geometry
const regularPolygon = buffer(point([ 0, 0 ]), 10, { quadrantSegments: 1000 });
const preparedPolygon = prepare(regularPolygon);
const regularPolygonAgain = unprepare(preparedPolygon);
// `regularPolygon`, `preparedPolygon` and `regularPolygonAgain` are exactly the same object
// so if you do not care about TypeScript, the above can be simplified to:
const p = buffer(point([ 0, 0 ]), 10, { quadrantSegments: 1000 });
prepare(p);
unprepare(p);
to improve performance of repeated calls against a single geometry
const a = buffer(point([ 0, 0 ]), 10, { quadrantSegments: 1000 });
// `a` is a polygon with many vertices (4000 in this example)
prepare(a);
// the preparation of geometry `a` will improve the performance of repeated
// supported functions (see list above) calls, but only those where `a` is
// the first geometry
const d1 = distance(a, point([ 10, 0 ]));
const d2 = distance(a, point([ 10, 1 ]));
const d3 = distance(point([ 10, 2 ]), a); // no benefit from prepared geometry
const i1 = intersects(a, lineString([ [ 0, 22 ], [ 11, 0 ] ]));
const i2 = intersects(a, lineString([ [ 0, 24 ], [ 11, 0 ] ]));
const i3 = intersects(lineString([ [ 0, 26 ], [ 11, 0 ] ]), a); // no benefit