GEOS for WebAssembly
v3.15.0WebAssemblyGEOS 3.15.0 for browsers, Node.js and edge runtimes, precompiled for wasm32, single-threaded and multi-threaded as @crossbind/port-geos-wasm.
npm install @crossbind/port-geos-wasm@betaInstall
shell
npm install @crossbind/port-geos-wasm@beta
crossbind.config.js
import geosWasm from '@crossbind/port-geos-wasm/crossbind.config.js';
export default {
dependencies: [geosWasm],
paths: { config: import.meta.url },
};
crossbind itself arrives with your bundler plugin, or with a new project from npm create crossbind@beta; Bundlers has Vite, Webpack, Rspack and Rollup.
Usage
Each example runs here, in this tab, and prints what the site build checked.
Each example also has a JavaScript only tab: the same task with no C++ file, calling GEOS's own headers from @crossbind/port-geos directly. All 5 work that way.
Intersect, unite and subtract two polygons
Overlay is the most used part of GEOS: GEOSIntersection_r, GEOSUnion_r and GEOSDifference_r on shapes read from WKT, with GEOSArea_r to measure the result.
src/native/overlay.h
#pragma once
#include <geos_c.h>
#include <memory>
#include <stdexcept>
#include <string>
// Overlay of two geometries written as WKT. Every result is normalised, so the same shape always
// prints the same WKT whatever order its vertices came in.
class Overlay {
public:
static std::string version() { return GEOSversion(); }
static std::string intersection(const std::string& a, const std::string& b) { return apply(GEOSIntersection_r, a, b); }
static std::string unite(const std::string& a, const std::string& b) { return apply(GEOSUnion_r, a, b); }
static std::string difference(const std::string& a, const std::string& b) { return apply(GEOSDifference_r, a, b); }
static double area(const std::string& wkt) {
Session geos;
double value = 0;
if (!GEOSArea_r(geos.context, geos.read(wkt).get(), &value)) geos.fail();
return value;
}
private:
using Operation = GEOSGeometry* (*)(GEOSContextHandle_t, const GEOSGeometry*, const GEOSGeometry*);
static std::string apply(Operation operation, const std::string& a, const std::string& b) {
Session geos;
const auto left = geos.read(a);
const auto right = geos.read(b);
return geos.result(operation(geos.context, left.get(), right.get()));
}
// GEOS's reentrant C API: each call gets its own context, which also holds the last error message.
struct Session {
struct Destroy {
GEOSContextHandle_t context;
void operator()(GEOSGeometry* geometry) const { GEOSGeom_destroy_r(context, geometry); }
};
using Geometry = std::unique_ptr<GEOSGeometry, Destroy>;
GEOSContextHandle_t context = GEOS_init_r();
std::string error;
Session() { GEOSContext_setErrorMessageHandler_r(context, remember, &error); }
~Session() { GEOS_finish_r(context); }
Session(const Session&) = delete;
Session& operator=(const Session&) = delete;
Geometry own(GEOSGeometry* geometry) {
if (!geometry) fail();
return Geometry(geometry, Destroy{context});
}
Geometry read(const std::string& wkt) {
GEOSWKTReader* reader = GEOSWKTReader_create_r(context);
GEOSGeometry* geometry = GEOSWKTReader_read_r(context, reader, wkt.c_str());
GEOSWKTReader_destroy_r(context, reader);
return own(geometry);
}
std::string write(const GEOSGeometry* geometry) {
GEOSWKTWriter* writer = GEOSWKTWriter_create_r(context);
char* text = GEOSWKTWriter_write_r(context, writer, geometry);
GEOSWKTWriter_destroy_r(context, writer);
if (!text) fail();
const std::string wkt = text;
GEOSFree_r(context, text);
return wkt;
}
// Takes ownership of a result and writes it normalised.
std::string result(GEOSGeometry* geometry) {
const Geometry owned = own(geometry);
if (GEOSNormalize_r(context, owned.get()) != 0) fail();
return write(owned.get());
}
[[noreturn]] void fail() const { throw std::runtime_error(error.empty() ? "GEOS operation failed" : error); }
static void remember(const char* message, void* error) { *static_cast<std::string*>(error) = message; }
};
};
main.js
import { initNative, Overlay } from './native/overlay.h';
await initNative();
const parcel = 'POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))';
const floodZone = 'POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))';
const flooded = await Overlay.intersection(parcel, floodZone);
console.log(await Overlay.version());
console.log(flooded, await Overlay.area(flooded));
console.log(await Overlay.area(await Overlay.unite(parcel, floodZone)), await Overlay.area(await Overlay.difference(parcel, floodZone)));
PRINTSfirst run downloads 1.7 MB
3.15.0-CAPI-1.21.0 POLYGON ((5 5, 5 10, 10 10, 10 5, 5 5)) 25 175 75
The same reentrant calls the C++ makes, on geos_c.h as GEOS ships it. What the wrapper did is now yours: the context, a WKT reader and writer (the shorter GEOSGeomToWKT_r pads every number to 5.0000000000000000), the double * of GEOSArea_r as an 8-byte allocBuffer read with readNumberAt, the char * WKT read with readCString and returned to GEOSFree_r, and every geometry destroyed by hand. GEOS hands its error text only to a callback and a JavaScript function cannot cross into the worker, so a failed call gives only its failure value (null for bad WKT) and no message.
main.js
import {
initNative, GEOSversion, GEOS_init_r, GEOS_finish_r, GEOSWKTReader_create_r,
GEOSWKTReader_read_r, GEOSWKTReader_destroy_r, GEOSWKTWriter_create_r, GEOSWKTWriter_write_r,
GEOSWKTWriter_destroy_r, GEOSIntersection_r, GEOSUnion_r, GEOSDifference_r, GEOSNormalize_r,
GEOSArea_r, GEOSGeom_destroy_r, GEOSFree_r, allocBuffer, readNumberAt, readCString,
} from '@crossbind/port-geos/geos_c.h';
await initNative();
const ctx = await GEOS_init_r();
const reader = await GEOSWKTReader_create_r(ctx);
const writer = await GEOSWKTWriter_create_r(ctx);
const parcel = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))');
const floodZone = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))');
if (!parcel || !floodZone) throw new Error('not a WKT geometry');
const out = await allocBuffer(8); // GEOSArea_r writes the area here, as a double
const area = async (geometry) => {
if (!(await GEOSArea_r(ctx, geometry, out))) throw new Error('GEOS could not measure the geometry');
return readNumberAt(out, 0, 'float64');
};
const flooded = await GEOSIntersection_r(ctx, parcel, floodZone);
await GEOSNormalize_r(ctx, flooded); // the same shape always prints the same WKT
const wkt = await GEOSWKTWriter_write_r(ctx, writer, flooded); // a char * GEOS allocated
console.log(await GEOSversion());
console.log(await readCString(wkt), await area(flooded));
await GEOSFree_r(ctx, wkt);
const united = await GEOSUnion_r(ctx, parcel, floodZone);
const dry = await GEOSDifference_r(ctx, parcel, floodZone);
console.log(await area(united), await area(dry));
for (const geometry of [parcel, floodZone, flooded, united, dry]) await GEOSGeom_destroy_r(ctx, geometry);
await GEOSWKTReader_destroy_r(ctx, reader);
await GEOSWKTWriter_destroy_r(ctx, writer);
await GEOS_finish_r(ctx);
PRINTSfirst run downloads 2.5 MB
3.15.0-CAPI-1.21.0 POLYGON ((5 5, 5 10, 10 10, 10 5, 5 5)) 25 175 75
Test points against a prepared polygon
Point in polygon is the most common spatial question. GEOSPrepare_r indexes the polygon once; GEOSPreparedContainsXY_r and GEOSPreparedIntersectsXY_r then answer per point and differ only on the boundary, and GEOSPreparedRelate_r gives the full DE-9IM matrix.
src/native/zone.h
#pragma once
#include <geos_c.h>
#include <memory>
#include <stdexcept>
#include <string>
// A polygon prepared once and then asked about many points: GEOSPrepare_r indexes its edges on the
// first question, so the later ones do not walk every edge again.
class Zone {
public:
explicit Zone(const std::string& wkt) : shape(geos.read(wkt)), prepared(GEOSPrepare_r(geos.context, shape.get())) {
if (!prepared) geos.fail();
}
~Zone() { GEOSPreparedGeom_destroy_r(geos.context, prepared); }
Zone(const Zone&) = delete;
Zone& operator=(const Zone&) = delete;
// Strictly inside: a point on the boundary is not contained.
bool contains(double x, double y) { return answer(GEOSPreparedContainsXY_r(geos.context, prepared, x, y)); }
// Inside or on the boundary.
bool intersects(double x, double y) { return answer(GEOSPreparedIntersectsXY_r(geos.context, prepared, x, y)); }
// The DE-9IM matrix: the dimension where the interior, boundary and exterior of this shape meet
// those of the other, row by row.
std::string relate(const std::string& wkt) {
char* matrix = GEOSPreparedRelate_r(geos.context, prepared, geos.read(wkt).get());
if (!matrix) geos.fail();
const std::string text = matrix;
GEOSFree_r(geos.context, matrix);
return text;
}
private:
bool answer(char result) {
if (result == 2) geos.fail();
return result == 1;
}
// GEOS's reentrant C API: each call gets its own context, which also holds the last error message.
struct Session {
struct Destroy {
GEOSContextHandle_t context;
void operator()(GEOSGeometry* geometry) const { GEOSGeom_destroy_r(context, geometry); }
};
using Geometry = std::unique_ptr<GEOSGeometry, Destroy>;
GEOSContextHandle_t context = GEOS_init_r();
std::string error;
Session() { GEOSContext_setErrorMessageHandler_r(context, remember, &error); }
~Session() { GEOS_finish_r(context); }
Session(const Session&) = delete;
Session& operator=(const Session&) = delete;
Geometry own(GEOSGeometry* geometry) {
if (!geometry) fail();
return Geometry(geometry, Destroy{context});
}
Geometry read(const std::string& wkt) {
GEOSWKTReader* reader = GEOSWKTReader_create_r(context);
GEOSGeometry* geometry = GEOSWKTReader_read_r(context, reader, wkt.c_str());
GEOSWKTReader_destroy_r(context, reader);
return own(geometry);
}
std::string write(const GEOSGeometry* geometry) {
GEOSWKTWriter* writer = GEOSWKTWriter_create_r(context);
char* text = GEOSWKTWriter_write_r(context, writer, geometry);
GEOSWKTWriter_destroy_r(context, writer);
if (!text) fail();
const std::string wkt = text;
GEOSFree_r(context, text);
return wkt;
}
// Takes ownership of a result and writes it normalised.
std::string result(GEOSGeometry* geometry) {
const Geometry owned = own(geometry);
if (GEOSNormalize_r(context, owned.get()) != 0) fail();
return write(owned.get());
}
[[noreturn]] void fail() const { throw std::runtime_error(error.empty() ? "GEOS operation failed" : error); }
static void remember(const char* message, void* error) { *static_cast<std::string*>(error) = message; }
};
Session geos;
Session::Geometry shape;
const GEOSPreparedGeometry* prepared;
};
main.js
import { initNative, Zone } from './native/zone.h';
await initNative();
const zone = await new Zone('POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4))');
const points = [[2, 2], [5, 5], [10, 5], [12, 5]]; // inside, in the hole, on the edge, outside
for (const [x, y] of points) {
console.log(`${x} ${y}: contains ${await zone.contains(x, y)}, intersects ${await zone.intersects(x, y)}`);
}
console.log(await zone.relate('POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))'));
PRINTSfirst run downloads 1.7 MB
2 2: contains true, intersects true 5 5: contains false, intersects false 10 5: contains false, intersects true 12 5: contains false, intersects false 212101212
The prepared geometry and the XY predicates work as they are. Each predicate returns a C char, which arrives as the number 1, 0 or 2 (GEOS failed), so JavaScript turns it into a boolean itself. The DE-9IM matrix is a char * to read with readCString and return to GEOSFree_r, and the prepared geometry is destroyed before the polygon it indexes.
main.js
import {
initNative, GEOS_init_r, GEOS_finish_r, GEOSWKTReader_create_r, GEOSWKTReader_read_r,
GEOSWKTReader_destroy_r, GEOSPrepare_r, GEOSPreparedContainsXY_r, GEOSPreparedIntersectsXY_r,
GEOSPreparedRelate_r, GEOSPreparedGeom_destroy_r, GEOSGeom_destroy_r, GEOSFree_r, readCString,
} from '@crossbind/port-geos/geos_c.h';
await initNative();
const ctx = await GEOS_init_r();
const reader = await GEOSWKTReader_create_r(ctx);
const zone = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (4 4, 6 4, 6 6, 4 6, 4 4))');
const other = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((5 5, 15 5, 15 15, 5 15, 5 5))');
if (!zone || !other) throw new Error('not a WKT geometry');
const prepared = await GEOSPrepare_r(ctx, zone); // indexes the edges on the first question
const answer = (result) => {
if (result === 2) throw new Error('GEOS could not evaluate the predicate');
return result === 1;
};
const points = [[2, 2], [5, 5], [10, 5], [12, 5]]; // inside, in the hole, on the edge, outside
for (const [x, y] of points) {
const contains = answer(await GEOSPreparedContainsXY_r(ctx, prepared, x, y));
const intersects = answer(await GEOSPreparedIntersectsXY_r(ctx, prepared, x, y));
console.log(`${x} ${y}: contains ${contains}, intersects ${intersects}`);
}
const matrix = await GEOSPreparedRelate_r(ctx, prepared, other); // a char * GEOS allocated
console.log(await readCString(matrix));
await GEOSFree_r(ctx, matrix);
await GEOSPreparedGeom_destroy_r(ctx, prepared);
await GEOSGeom_destroy_r(ctx, zone);
await GEOSGeom_destroy_r(ctx, other);
await GEOSWKTReader_destroy_r(ctx, reader);
await GEOS_finish_r(ctx);
PRINTSfirst run downloads 2.5 MB
2 2: contains true, intersects true 5 5: contains false, intersects false 10 5: contains false, intersects true 12 5: contains false, intersects false 212101212
Measure area, length and distance
GEOSArea_r, GEOSLength_r and GEOSDistance_r in the units of the coordinates, GEOSNearestPoints_r for where two shapes come closest, and GEOSGetCentroid_r. GEOS works in the plane, so project longitude and latitude before measuring.
src/native/measure.h
#pragma once
#include <geos_c.h>
#include <memory>
#include <stdexcept>
#include <string>
// Measurements in the plane, in the units of the coordinates: metres for most projected data.
// GEOS does not measure on the ellipsoid, so longitude and latitude need projecting first.
class Measure {
public:
static double area(const std::string& wkt) { return measure(GEOSArea_r, wkt); }
// A line's length or a polygon's perimeter. Not named length: every JavaScript function, a
// bound class included, already has a length property, and a static method cannot replace it.
static double lengthOf(const std::string& wkt) { return measure(GEOSLength_r, wkt); }
static double distance(const std::string& a, const std::string& b) {
Session geos;
const auto left = geos.read(a);
const auto right = geos.read(b);
double value = 0;
if (!GEOSDistance_r(geos.context, left.get(), right.get(), &value)) geos.fail();
return value;
}
// The shortest line between the two shapes, from its end on a to its end on b.
static std::string nearestPoints(const std::string& a, const std::string& b) {
Session geos;
const auto left = geos.read(a);
const auto right = geos.read(b);
GEOSCoordSequence* ends = GEOSNearestPoints_r(geos.context, left.get(), right.get());
if (!ends) geos.fail();
return geos.write(geos.own(GEOSGeom_createLineString_r(geos.context, ends)).get());
}
static std::string centroid(const std::string& wkt) {
Session geos;
return geos.result(GEOSGetCentroid_r(geos.context, geos.read(wkt).get()));
}
private:
using Metric = int (*)(GEOSContextHandle_t, const GEOSGeometry*, double*);
static double measure(Metric metric, const std::string& wkt) {
Session geos;
double value = 0;
if (!metric(geos.context, geos.read(wkt).get(), &value)) geos.fail();
return value;
}
// GEOS's reentrant C API: each call gets its own context, which also holds the last error message.
struct Session {
struct Destroy {
GEOSContextHandle_t context;
void operator()(GEOSGeometry* geometry) const { GEOSGeom_destroy_r(context, geometry); }
};
using Geometry = std::unique_ptr<GEOSGeometry, Destroy>;
GEOSContextHandle_t context = GEOS_init_r();
std::string error;
Session() { GEOSContext_setErrorMessageHandler_r(context, remember, &error); }
~Session() { GEOS_finish_r(context); }
Session(const Session&) = delete;
Session& operator=(const Session&) = delete;
Geometry own(GEOSGeometry* geometry) {
if (!geometry) fail();
return Geometry(geometry, Destroy{context});
}
Geometry read(const std::string& wkt) {
GEOSWKTReader* reader = GEOSWKTReader_create_r(context);
GEOSGeometry* geometry = GEOSWKTReader_read_r(context, reader, wkt.c_str());
GEOSWKTReader_destroy_r(context, reader);
return own(geometry);
}
std::string write(const GEOSGeometry* geometry) {
GEOSWKTWriter* writer = GEOSWKTWriter_create_r(context);
char* text = GEOSWKTWriter_write_r(context, writer, geometry);
GEOSWKTWriter_destroy_r(context, writer);
if (!text) fail();
const std::string wkt = text;
GEOSFree_r(context, text);
return wkt;
}
// Takes ownership of a result and writes it normalised.
std::string result(GEOSGeometry* geometry) {
const Geometry owned = own(geometry);
if (GEOSNormalize_r(context, owned.get()) != 0) fail();
return write(owned.get());
}
[[noreturn]] void fail() const { throw std::runtime_error(error.empty() ? "GEOS operation failed" : error); }
static void remember(const char* message, void* error) { *static_cast<std::string*>(error) = message; }
};
};
main.js
import { initNative, Measure } from './native/measure.h';
await initNative();
const field = 'POLYGON ((0 0, 40 0, 40 30, 0 30, 0 0))';
const well = 'POINT (52 39)';
const track = 'LINESTRING (0 0, 30 40, 30 50)';
console.log(await Measure.area(field), await Measure.lengthOf(field), await Measure.lengthOf(track));
console.log(await Measure.distance(field, well), await Measure.nearestPoints(field, well));
console.log(await Measure.centroid(field));
PRINTSfirst run downloads 1.7 MB
1200 140 60 15 LINESTRING (40 30, 52 39) POINT (20 15)
Area, length and distance come back through a double *: one 8-byte allocBuffer serves every call and readNumberAt(out, 0, 'float64') reads it after each. GEOSNearestPoints_r returns a coordinate sequence handle and GEOSGeom_createLineString_r takes ownership of it, so only the line is destroyed.
main.js
import {
initNative, GEOS_init_r, GEOS_finish_r, GEOSWKTReader_create_r, GEOSWKTReader_read_r,
GEOSWKTReader_destroy_r, GEOSWKTWriter_create_r, GEOSWKTWriter_write_r, GEOSWKTWriter_destroy_r,
GEOSArea_r, GEOSLength_r, GEOSDistance_r, GEOSNearestPoints_r, GEOSGeom_createLineString_r,
GEOSGetCentroid_r, GEOSGeom_destroy_r, GEOSFree_r, allocBuffer, readNumberAt, readCString,
} from '@crossbind/port-geos/geos_c.h';
await initNative();
const ctx = await GEOS_init_r();
const reader = await GEOSWKTReader_create_r(ctx);
const writer = await GEOSWKTWriter_create_r(ctx);
const field = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((0 0, 40 0, 40 30, 0 30, 0 0))');
const well = await GEOSWKTReader_read_r(ctx, reader, 'POINT (52 39)');
const track = await GEOSWKTReader_read_r(ctx, reader, 'LINESTRING (0 0, 30 40, 30 50)');
if (!field || !well || !track) throw new Error('not a WKT geometry');
const out = await allocBuffer(8); // each measurement writes its result here, as a double
const measured = async (status) => {
if (!status) throw new Error('GEOS could not measure the geometry');
return readNumberAt(out, 0, 'float64');
};
const wkt = async (geometry) => {
const text = await GEOSWKTWriter_write_r(ctx, writer, geometry); // a char * GEOS allocated
const copy = await readCString(text);
await GEOSFree_r(ctx, text);
return copy;
};
const area = await measured(await GEOSArea_r(ctx, field, out));
const perimeter = await measured(await GEOSLength_r(ctx, field, out));
const length = await measured(await GEOSLength_r(ctx, track, out));
console.log(area, perimeter, length);
const distance = await measured(await GEOSDistance_r(ctx, field, well, out));
const ends = await GEOSNearestPoints_r(ctx, field, well); // from the field to the well
const shortest = await GEOSGeom_createLineString_r(ctx, ends);
console.log(distance, await wkt(shortest));
const centroid = await GEOSGetCentroid_r(ctx, field);
console.log(await wkt(centroid));
for (const geometry of [field, well, track, shortest, centroid]) await GEOSGeom_destroy_r(ctx, geometry);
await GEOSWKTReader_destroy_r(ctx, reader);
await GEOSWKTWriter_destroy_r(ctx, writer);
await GEOS_finish_r(ctx);
PRINTSfirst run downloads 2.5 MB
1200 140 60 15 LINESTRING (40 30, 52 39) POINT (20 15)
Buffer points, lines and polygons
GEOSBuffer_r turns a point into a circle of straight segments, GEOSBufferWithStyle_r sets the caps and joins of a line's corridor, a negative distance shrinks a polygon, and GEOSOffsetCurve_r draws a parallel line.
src/native/buffer.h
#pragma once
#include <geos_c.h>
#include <memory>
#include <stdexcept>
#include <string>
// Buffers grow a shape by a distance, or shrink it with a negative one; an offset curve runs parallel
// to a line. Curves become straight segments: quadrantSegments of them for each quarter circle.
class BufferOp {
public:
static std::string around(const std::string& wkt, double distance, int quadrantSegments) {
Session geos;
return geos.result(GEOSBuffer_r(geos.context, geos.read(wkt).get(), distance, quadrantSegments));
}
// cap: "round", "flat" or "square"; join: "round", "mitre" or "bevel".
static std::string withStyle(const std::string& wkt, double distance, const std::string& cap, const std::string& join) {
Session geos;
const auto geometry = geos.read(wkt);
return geos.result(GEOSBufferWithStyle_r(geos.context, geometry.get(), distance, 8, capStyle(cap), joinStyle(join), 5.0));
}
// A positive distance offsets to the left of the line's direction, a negative one to the right.
static std::string offsetCurve(const std::string& wkt, double distance) {
Session geos;
return geos.result(GEOSOffsetCurve_r(geos.context, geos.read(wkt).get(), distance, 8, GEOSBUF_JOIN_ROUND, 5.0));
}
private:
static int capStyle(const std::string& name) {
if (name == "round") return GEOSBUF_CAP_ROUND;
if (name == "flat") return GEOSBUF_CAP_FLAT;
if (name == "square") return GEOSBUF_CAP_SQUARE;
throw std::invalid_argument("cap must be round, flat or square");
}
static int joinStyle(const std::string& name) {
if (name == "round") return GEOSBUF_JOIN_ROUND;
if (name == "mitre") return GEOSBUF_JOIN_MITRE;
if (name == "bevel") return GEOSBUF_JOIN_BEVEL;
throw std::invalid_argument("join must be round, mitre or bevel");
}
// GEOS's reentrant C API: each call gets its own context, which also holds the last error message.
struct Session {
struct Destroy {
GEOSContextHandle_t context;
void operator()(GEOSGeometry* geometry) const { GEOSGeom_destroy_r(context, geometry); }
};
using Geometry = std::unique_ptr<GEOSGeometry, Destroy>;
GEOSContextHandle_t context = GEOS_init_r();
std::string error;
Session() { GEOSContext_setErrorMessageHandler_r(context, remember, &error); }
~Session() { GEOS_finish_r(context); }
Session(const Session&) = delete;
Session& operator=(const Session&) = delete;
Geometry own(GEOSGeometry* geometry) {
if (!geometry) fail();
return Geometry(geometry, Destroy{context});
}
Geometry read(const std::string& wkt) {
GEOSWKTReader* reader = GEOSWKTReader_create_r(context);
GEOSGeometry* geometry = GEOSWKTReader_read_r(context, reader, wkt.c_str());
GEOSWKTReader_destroy_r(context, reader);
return own(geometry);
}
std::string write(const GEOSGeometry* geometry) {
GEOSWKTWriter* writer = GEOSWKTWriter_create_r(context);
char* text = GEOSWKTWriter_write_r(context, writer, geometry);
GEOSWKTWriter_destroy_r(context, writer);
if (!text) fail();
const std::string wkt = text;
GEOSFree_r(context, text);
return wkt;
}
// Takes ownership of a result and writes it normalised.
std::string result(GEOSGeometry* geometry) {
const Geometry owned = own(geometry);
if (GEOSNormalize_r(context, owned.get()) != 0) fail();
return write(owned.get());
}
[[noreturn]] void fail() const { throw std::runtime_error(error.empty() ? "GEOS operation failed" : error); }
static void remember(const char* message, void* error) { *static_cast<std::string*>(error) = message; }
};
};
main.js
import { initNative, BufferOp } from './native/buffer.h';
import { Measure } from './native/measure.h';
await initNative();
const circle = await BufferOp.around('POINT (0 0)', 10, 8); // 8 segments per quarter circle
console.log((await Measure.area(circle)).toFixed(4));
const road = 'LINESTRING (0 0, 100 0)';
const flat = await BufferOp.withStyle(road, 5, 'flat', 'round');
const round = await BufferOp.withStyle(road, 5, 'round', 'round');
console.log(await Measure.area(flat), (await Measure.area(round)).toFixed(4));
const setback = await BufferOp.around('POLYGON ((0 0, 20 0, 20 20, 0 20, 0 0))', -2, 8);
console.log(setback, await Measure.area(setback));
console.log(await BufferOp.offsetCurve(road, 5));
PRINTSfirst run downloads 1.7 MB
312.1445 1000 1078.0361 POLYGON ((2 2, 2 18, 18 18, 18 2, 2 2)) 256 LINESTRING (0 5, 100 5)
GEOS declares the cap and join styles as int parameters and names them in the GEOSBufCapStyles and GEOSBufJoinStyles enums, so pass the member's .value: the member itself crosses as 0 without an error, and the flat-capped corridor then comes back as POLYGON EMPTY.
main.js
import {
initNative, GEOS_init_r, GEOS_finish_r, GEOSWKTReader_create_r, GEOSWKTReader_read_r,
GEOSWKTReader_destroy_r, GEOSWKTWriter_create_r, GEOSWKTWriter_write_r, GEOSWKTWriter_destroy_r,
GEOSBuffer_r, GEOSBufferWithStyle_r, GEOSOffsetCurve_r, GEOSBufCapStyles, GEOSBufJoinStyles,
GEOSNormalize_r, GEOSArea_r, GEOSGeom_destroy_r, GEOSFree_r, allocBuffer, readNumberAt,
readCString,
} from '@crossbind/port-geos/geos_c.h';
await initNative();
const ctx = await GEOS_init_r();
const reader = await GEOSWKTReader_create_r(ctx);
const writer = await GEOSWKTWriter_create_r(ctx);
const point = await GEOSWKTReader_read_r(ctx, reader, 'POINT (0 0)');
const road = await GEOSWKTReader_read_r(ctx, reader, 'LINESTRING (0 0, 100 0)');
const lot = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((0 0, 20 0, 20 20, 0 20, 0 0))');
if (!point || !road || !lot) throw new Error('not a WKT geometry');
const out = await allocBuffer(8); // GEOSArea_r writes the area here, as a double
const area = async (geometry) => {
if (!(await GEOSArea_r(ctx, geometry, out))) throw new Error('GEOS could not measure the geometry');
return readNumberAt(out, 0, 'float64');
};
const wkt = async (geometry) => {
await GEOSNormalize_r(ctx, geometry); // the same shape always prints the same WKT
const text = await GEOSWKTWriter_write_r(ctx, writer, geometry); // a char * GEOS allocated
const copy = await readCString(text);
await GEOSFree_r(ctx, text);
return copy;
};
const circle = await GEOSBuffer_r(ctx, point, 10, 8); // 8 segments per quarter circle
console.log((await area(circle)).toFixed(4));
const flatCap = (await GEOSBufCapStyles.GEOSBUF_CAP_FLAT).value;
const roundCap = (await GEOSBufCapStyles.GEOSBUF_CAP_ROUND).value;
const roundJoin = (await GEOSBufJoinStyles.GEOSBUF_JOIN_ROUND).value;
const flat = await GEOSBufferWithStyle_r(ctx, road, 5, 8, flatCap, roundJoin, 5);
const round = await GEOSBufferWithStyle_r(ctx, road, 5, 8, roundCap, roundJoin, 5);
console.log(await area(flat), (await area(round)).toFixed(4));
const setback = await GEOSBuffer_r(ctx, lot, -2, 8);
console.log(await wkt(setback), await area(setback));
const offset = await GEOSOffsetCurve_r(ctx, road, 5, 8, roundJoin, 5); // positive: to the left
console.log(await wkt(offset));
for (const geometry of [point, road, lot, circle, flat, round, setback, offset]) await GEOSGeom_destroy_r(ctx, geometry);
await GEOSWKTReader_destroy_r(ctx, reader);
await GEOSWKTWriter_destroy_r(ctx, writer);
await GEOS_finish_r(ctx);
PRINTSfirst run downloads 2.5 MB
312.1445 1000 1078.0361 POLYGON ((2 2, 2 18, 18 18, 18 2, 2 2)) 256 LINESTRING (0 5, 100 5)
Find why a polygon is invalid and repair it
GEOSisValid_r and GEOSisValidReason_r say whether a shape breaks the OGC rules, what is wrong and where. GEOSMakeValidWithParams_r repairs it two ways, which agree on a bowtie and differ on a hole that leaks out of its shell.
src/native/validity.h
#pragma once
#include <geos_c.h>
#include <memory>
#include <stdexcept>
#include <string>
// OGC validity: whether a shape is valid, what is wrong and where if it is not, and a repair.
class Validity {
public:
static bool isValid(const std::string& wkt) {
Session geos;
const char valid = GEOSisValid_r(geos.context, geos.read(wkt).get());
if (valid == 2) geos.fail();
return valid == 1;
}
// "Valid Geometry", or the problem and its location, such as "Self-intersection[5 5]".
static std::string reason(const std::string& wkt) {
Session geos;
char* text = GEOSisValidReason_r(geos.context, geos.read(wkt).get());
if (!text) geos.fail();
const std::string reason = text;
GEOSFree_r(geos.context, text);
return reason;
}
// "linework" rebuilds the shape from all of its noded edges; "structure" repairs each ring,
// then keeps shells as shells and subtracts the holes from them.
static std::string makeValid(const std::string& wkt, const std::string& method) {
if (method != "linework" && method != "structure") throw std::invalid_argument("method must be linework or structure");
Session geos;
const auto geometry = geos.read(wkt);
GEOSMakeValidParams* params = GEOSMakeValidParams_create_r(geos.context);
GEOSMakeValidParams_setMethod_r(geos.context, params, method == "structure" ? GEOS_MAKE_VALID_STRUCTURE : GEOS_MAKE_VALID_LINEWORK);
GEOSGeometry* repaired = GEOSMakeValidWithParams_r(geos.context, geometry.get(), params);
GEOSMakeValidParams_destroy_r(geos.context, params);
return geos.result(repaired);
}
private:
// GEOS's reentrant C API: each call gets its own context, which also holds the last error message.
struct Session {
struct Destroy {
GEOSContextHandle_t context;
void operator()(GEOSGeometry* geometry) const { GEOSGeom_destroy_r(context, geometry); }
};
using Geometry = std::unique_ptr<GEOSGeometry, Destroy>;
GEOSContextHandle_t context = GEOS_init_r();
std::string error;
Session() { GEOSContext_setErrorMessageHandler_r(context, remember, &error); }
~Session() { GEOS_finish_r(context); }
Session(const Session&) = delete;
Session& operator=(const Session&) = delete;
Geometry own(GEOSGeometry* geometry) {
if (!geometry) fail();
return Geometry(geometry, Destroy{context});
}
Geometry read(const std::string& wkt) {
GEOSWKTReader* reader = GEOSWKTReader_create_r(context);
GEOSGeometry* geometry = GEOSWKTReader_read_r(context, reader, wkt.c_str());
GEOSWKTReader_destroy_r(context, reader);
return own(geometry);
}
std::string write(const GEOSGeometry* geometry) {
GEOSWKTWriter* writer = GEOSWKTWriter_create_r(context);
char* text = GEOSWKTWriter_write_r(context, writer, geometry);
GEOSWKTWriter_destroy_r(context, writer);
if (!text) fail();
const std::string wkt = text;
GEOSFree_r(context, text);
return wkt;
}
// Takes ownership of a result and writes it normalised.
std::string result(GEOSGeometry* geometry) {
const Geometry owned = own(geometry);
if (GEOSNormalize_r(context, owned.get()) != 0) fail();
return write(owned.get());
}
[[noreturn]] void fail() const { throw std::runtime_error(error.empty() ? "GEOS operation failed" : error); }
static void remember(const char* message, void* error) { *static_cast<std::string*>(error) = message; }
};
};
main.js
import { initNative, Validity } from './native/validity.h';
import { Measure } from './native/measure.h';
await initNative();
const bowtie = 'POLYGON ((0 0, 10 10, 10 0, 0 10, 0 0))';
console.log(await Validity.isValid(bowtie), await Validity.reason(bowtie));
const repaired = await Validity.makeValid(bowtie, 'linework');
console.log(repaired, await Validity.isValid(repaired), await Measure.area(repaired));
const leaky = 'POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (5 5, 15 5, 15 15, 5 15, 5 5))';
console.log(await Validity.reason(leaky));
for (const method of ['linework', 'structure']) {
console.log(method, await Measure.area(await Validity.makeValid(leaky, method)));
}
PRINTSfirst run downloads 1.7 MB
false Self-intersection[5 5] MULTIPOLYGON (((5 5, 10 10, 10 0, 5 5)), ((0 0, 0 10, 5 5, 0 0))) true 50 Self-intersection[5 10] linework 150 structure 75
GEOSMakeValidParams_setMethod_r takes an enum GEOSMakeValidMethods, so pass the member itself: a plain number crosses as 0, GEOS_MAKE_VALID_LINEWORK, and the call still returns 1. GEOSisValid_r returns a C char (1, 0, or 2 when GEOS failed), and the reason is a char * to read with readCString and return to GEOSFree_r.
main.js
import {
initNative, GEOS_init_r, GEOS_finish_r, GEOSWKTReader_create_r, GEOSWKTReader_read_r,
GEOSWKTReader_destroy_r, GEOSWKTWriter_create_r, GEOSWKTWriter_write_r, GEOSWKTWriter_destroy_r,
GEOSisValid_r, GEOSisValidReason_r, GEOSMakeValidParams_create_r,
GEOSMakeValidParams_setMethod_r, GEOSMakeValidParams_destroy_r, GEOSMakeValidWithParams_r,
GEOSMakeValidMethods, GEOSNormalize_r, GEOSArea_r, GEOSGeom_destroy_r, GEOSFree_r, allocBuffer,
readNumberAt, readCString,
} from '@crossbind/port-geos/geos_c.h';
await initNative();
const ctx = await GEOS_init_r();
const reader = await GEOSWKTReader_create_r(ctx);
const writer = await GEOSWKTWriter_create_r(ctx);
const bowtie = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((0 0, 10 10, 10 0, 0 10, 0 0))');
const leaky = await GEOSWKTReader_read_r(ctx, reader, 'POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (5 5, 15 5, 15 15, 5 15, 5 5))');
if (!bowtie || !leaky) throw new Error('not a WKT geometry');
const out = await allocBuffer(8); // GEOSArea_r writes the area here, as a double
const area = async (geometry) => {
if (!(await GEOSArea_r(ctx, geometry, out))) throw new Error('GEOS could not measure the geometry');
return readNumberAt(out, 0, 'float64');
};
const isValid = async (geometry) => {
const valid = await GEOSisValid_r(ctx, geometry);
if (valid === 2) throw new Error('GEOS could not check the geometry');
return valid === 1;
};
const reason = async (geometry) => {
const text = await GEOSisValidReason_r(ctx, geometry); // a char * GEOS allocated
const copy = await readCString(text);
await GEOSFree_r(ctx, text);
return copy;
};
const makeValid = async (geometry, method) => {
const params = await GEOSMakeValidParams_create_r(ctx);
await GEOSMakeValidParams_setMethod_r(ctx, params, method);
const repaired = await GEOSMakeValidWithParams_r(ctx, geometry, params);
await GEOSMakeValidParams_destroy_r(ctx, params);
await GEOSNormalize_r(ctx, repaired); // the same shape always prints the same WKT
return repaired;
};
const linework = await GEOSMakeValidMethods.GEOS_MAKE_VALID_LINEWORK;
const structure = await GEOSMakeValidMethods.GEOS_MAKE_VALID_STRUCTURE;
console.log(await isValid(bowtie), await reason(bowtie));
const repaired = await makeValid(bowtie, linework);
const wkt = await GEOSWKTWriter_write_r(ctx, writer, repaired);
console.log(await readCString(wkt), await isValid(repaired), await area(repaired));
await GEOSFree_r(ctx, wkt);
console.log(await reason(leaky));
for (const [name, method] of [['linework', linework], ['structure', structure]]) {
const fixed = await makeValid(leaky, method);
console.log(name, await area(fixed));
await GEOSGeom_destroy_r(ctx, fixed);
}
for (const geometry of [bowtie, leaky, repaired]) await GEOSGeom_destroy_r(ctx, geometry);
await GEOSWKTReader_destroy_r(ctx, reader);
await GEOSWKTWriter_destroy_r(ctx, writer);
await GEOS_finish_r(ctx);
PRINTSfirst run downloads 2.5 MB
false Self-intersection[5 5] MULTIPOLYGON (((5 5, 10 10, 10 0, 5 5)), ((0 0, 0 10, 5 5, 0 0))) true 50 Self-intersection[5 10] linework 150 structure 75
What is different on WebAssembly
- In a browser the module runs in a Worker by default (
useWorker), so every call returns a promise:awaitcalls and constructors alike. - The module has its own filesystem:
m.FSwrites files,m.getFileBytesreads them back andm.autoMountFilesmountsFileobjects from an<input type=file>./memfslives in memory;/opfspersists across reloads and needs the Worker. See Filesystem. - In Node.js,
m.FSis the real disk, so use real paths there. - Multi-threaded builds (
runtime: 'mt') need COOP and COEP headers in production. See Threading.
Other platforms
- GEOS overview: the apps, every platform's setup and the packages.
- GEOS for Android: React Native apps on Android.
- GEOS for iOS: React Native apps on iOS.
- GEOS for WASI: command-line programs under wasmtime.
Facts on this page come from the port manifests in the repository and from what npm served on beta when the site was built. See the Libraries guide for the full consumer flow.
MORE LIBRARIES