spatialutils
The spatialutils class provides static utility functions for **performing geospatial
operations** such as measurement, geometry manipulation, and spatial analysis.
1. Measurement Functions 📐
Calculates the **distance** between two points (or feature centers) in the specified unit (e.g., 'kilometers', 'miles').
number (Distance)Usage Example: Calculating Distance
const pt2 = [-75.534, 39.123] ;
const distKm = gtswebsdkgl.spatialutils.distance(pt1, pt2, {unites:'kilometers'});
console.log(`Distance: ${distKm.toFixed(2)} km`);
Calculates the **area** of a Polygon or MultiPolygon geometry in square meters.
number (Area in square meters)Usage Example: Calculating Polygon Area
const areaSqMeters = gtswebsdkgl.spatialutils.area(poly);
console.log(`Area: ${areaSqMeters.toLocaleString()} sq meters`);
Takes a GeoJSON and measures its length in the specified units, (Multi)Point's distance are ignored.
number (Length)Usage Example: Calculating Line Length
const lineMiles = gtswebsdkgl.spatialutils.length(line, {unites:'kilometers'});
console.log(`Length: ${lineMiles.toFixed(2)} miles`);
Calculates the **bearing** (direction) from one Point to another in degrees, ranging from -180 to 180.
number (Bearing in degrees)Usage Example: Getting Bearing
const ptB = { type: 'Point', coordinates: [ -75, 45 ] };
const b = gtswebsdkgl.spatialutils.bearing(ptA, ptB);
console.log(`Bearing from A to B: ${b.toFixed(2)} degrees`);
2. Transformation & Derivation Functions 🔨
Calculates the **bounding box** (BBOX) of any GeoJSON object in the
format [minX, minY, maxX, maxY].
Array<number> (BBOX array)Usage Example: Getting the BBOX
const box = gtswebsdkgl.spatialutils.bbox(line);
console.log(`BBOX: [${box.join(', ')}]`); // Output: BBOX: [0, 0, 10, 10]
Takes a BBOX array and returns a GeoJSON **Polygon Feature** that represents that bounding box.
GeoJSON (Polygon Feature)Usage Example: Creating a Polygon from a BBOX
const bboxPoly = gtswebsdkgl.spatialutils.bboxPolygon(bboxArray);
console.log(bboxPoly.geometry.type); // Output: 'Polygon'
Calculates the **minimal bounding rectangle** (same as BBOX Polygon) for a given GeoJSON object.
GeoJSON (Polygon Feature)Usage Example: Creating a Bounding Envelope
const envelopePoly = gtswebsdkgl.spatialutils.envelope(points);
console.log(envelopePoly.properties); // Should be { bbox: [...] }
Calculates the **Convex Hull** (smallest convex polygon) of a Point, MultiPoint, or FeatureCollection of any type.
GeoJSON | null (Polygon Feature or null)Usage Example: Calculating Convex Hull
const hull = gtswebsdkgl.spatialutils.convex(points);
console.log(hull.geometry.type); // Output: 'Polygon'
Calculates the **Concave Hull** of a set of points. Requires a
maxEdge distance constraint.
GeoJSON | null (Polygon Feature or null)Usage Example: Calculating Concave Hull
// Max edge length of 10 kilometers
const concaveHull = gtswebsdkgl.spatialutils.concave(points, 10, 'kilometers');
console.log(concaveHull.geometry.type);
3. Center & Point Location Functions 🎯
Calculates the **centroid** (center of geometry) of a GeoJSON feature using the mathematical center of its coordinates.
GeoJSON (Point Feature)Usage Example: Getting the Centroid
const c = gtswebsdkgl.spatialutils.centroid(poly);
console.log('Centroid:', c.geometry.coordinates);
Calculates the **center** of a GeoJSON feature based on the midpoint of its bounding box (BBOX).
GeoJSON (Point Feature)Usage Example: Getting the BBOX Center
const center = gtswebsdkgl.spatialutils.center(features);
console.log('BBOX Center:', center.geometry.coordinates);
Calculates the **center of mass** (weighted center) for a GeoJSON feature. Typically more representative of the visual center for polygons than `centroid`.
GeoJSON (Point Feature)Usage Example: Finding the Center of Mass
const massCenter = gtswebsdkgl.spatialutils.centerOfMass(polygon);
console.log('Center of Mass:', massCenter.geometry.coordinates);
Returns a **Point** at a specified **distance** along a LineString.
GeoJSON (Point Feature)Usage Example: Point Along Line
const ptAlong = gtswebsdkgl.spatialutils.along(line, 5, 'miles');
console.log('Point 5 miles along:', ptAlong.geometry.coordinates);
Calculates the **midpoint** of the straight line segment between two given points.
GeoJSON (Point Feature)Usage Example: Finding the Midpoint
const end = { type: 'Point', coordinates: [ 10, 10 ] };
const mid = gtswebsdkgl.spatialutils.midpoint(start, end);
console.log('Midpoint:', mid.geometry.coordinates); // Output: [5, 5]
Returns a **Point** that is guaranteed to be **inside** a given Polygon or MultiPolygon Feature.
GeoJSON (Point Feature)Usage Example: Guaranteed Point Inside
const innerPoint = gtswebsdkgl.spatialutils.pointOnFeature(complexPoly);
// This point is guaranteed to be usable for labelling or positioning
4. Boolean & Spatial Analysis Functions 🧠
Checks if a **Point is inside a Polygon**. Returns true
if it is, false otherwise.
booleanUsage Example: Checking Point Inclusion
const poly = { /* GeoJSON Polygon covering [0,0] to [20,20] */ };
const isInside = gtswebsdkgl.spatialutils.booleanPointInPolygon(pt, poly);
console.log('Point is inside:', isInside);
Checks if **feature1 is completely within feature2** (e.g., Point in Polygon, LineString in Polygon).
booleanUsage Example: Feature Within
const cityBoundary = { /* City Polygon */ };
const isContained = gtswebsdkgl.spatialutils.booleanWithin(smallLine, cityBoundary);
console.log('Line is within boundary:', isContained);
Checks if **feature1 completely contains feature2**. (Inverse of `booleanWithin`).
booleanUsage Example: Feature Contains
const smallPoly = { /* Small Polygon B */ };
const contains = gtswebsdkgl.spatialutils.booleanContains(bigPoly, smallPoly);
console.log('A contains B:', contains);
Checks if the intersection of two geometries is not empty and is not equal to either of the features.
booleanUsage Example: Checking for Partial Overlap
const poly2 = { /* Polygon 2 */ };
const overlaps = gtswebsdkgl.spatialutils.booleanOverlap(poly1, poly2);
console.log('Polygons partially overlap:', overlaps);
Checks if two geometries **cross** (e.g., a LineString crosses a Polygon boundary, or two LineStrings intersect internally).
booleanUsage Example: Checking if Lines Cross
const lineB = { /* LineString B */ };
const crosses = gtswebsdkgl.spatialutils.booleanCrosses(lineA, lineB);
console.log('Lines cross:', crosses);
Checks if two geometries have **no points in common** (they do not intersect or touch).
boolean
Usage Example: Checking for No Intersection
const region2 = { /* Polygon far South */ };
const disjoint = gtswebsdkgl.spatialutils.booleanDisjoint(region1, region2);
console.log('Regions are separate:', disjoint); // Output: true
Takes a reference point and a collection of points, and returns the **nearest point** feature from the collection.
GeoJSON (Point Feature)Usage Example: Finding Nearest Point
const candidates = { /* FeatureCollection of points */ };
const nearest = gtswebsdkgl.spatialutils.nearestPoint(target, candidates);
console.log('Nearest candidate:', nearest.geometry.coordinates);
Returns the **closest Point on a LineString** to a given reference Point.
GeoJSON (Point Feature)Usage Example: Point Projection
const location = { /* Point off the road */ };
const projected = gtswebsdkgl.spatialutils.nearestPointOnLine(road, location);
console.log('Closest point on road:', projected.geometry.coordinates);
Takes a set of points and a set of polygons, and returns a **FeatureCollection** of all points that fall within the polygons.
GeoJSON (FeatureCollection)Usage Example: Points in Area of Interest
const aoi = { /* Polygon defining area of interest */ };
const filteredSites = gtswebsdkgl.spatialutils.pointsWithinPolygon(allSites, aoi);
console.log(`Found ${filteredSites.features.length} sites inside AOI.`);
5. Geometry Processing & Set Operations 🔄
Merges two or more Polygon or MultiPolygon features into a single feature. Uses a **spatial union** operation.
GeoJSON (Polygon Feature)Usage Example: Combining Polygons
const plotB = { /* Polygon B */ };
const mergedPlot = gtswebsdkgl.spatialutils.union(plotA, plotB);
console.log('Resulting geometry type:', mergedPlot.geometry.type);
Calculates the **geometric intersection** of two features (the area/line/point shared by both).
GeoJSON | null (The resulting geometry or null)Usage Example: Finding Overlapping Area
const polyB = { /* GeoJSON Polygon B */ };
const intersection = gtswebsdkgl.spatialutils.intersect(polyA, polyB);
if (intersection) {
console.log('Intersection area found:', gtswebsdkgl.spatialutils.area(intersection));
}
Calculates the **geometric difference** (the area of feature1 that does not overlap feature2).
GeoJSON | null (The resulting geometry or null)Usage Example: Cutting a Hole
const smallPoly = { /* Small inner Polygon to cut out */ };
const remainder = gtswebsdkgl.spatialutils.difference(bigPoly, smallPoly);
console.log('Remaining shape type:', remainder.geometry.type);
Simplifies a LineString or Polygon geometry using the **Douglas-Peucker algorithm**, reducing the number of vertices.
GeoJSON (Simplified Feature)Usage Example: Simplifying a Line
// Simplify with a tolerance of 0.01 degrees
const simpleLine = gtswebsdkgl.spatialutils.simplify(noisyLine, 0.01);
console.log('Original points vs simplified points');
Converts a Polygon or MultiPolygon feature into a **LineString** or **MultiLineString** feature that traces its exterior and interior rings.
GeoJSON (LineString Feature)Usage Example: Polygon to Line
const line = gtswebsdkgl.spatialutils.polygonToLine(poly);
console.log('New geometry type:', line.geometry.type); // Output: 'LineString'
Converts a LineString feature into a **Polygon** feature. Requires the LineString to be a closed loop (start/end points match).
GeoJSON (Polygon Feature)Usage Example: Line to Polygon
const poly = gtswebsdkgl.spatialutils.lineToPolygon(closedLine);
console.log('New geometry type:', poly.geometry.type); // Output: 'Polygon'
Aggregates properties from a Point FeatureCollection into a Polygon FeatureCollection based on spatial inclusion.
GeoJSON (Polygon FeatureCollection with aggregated
data)Usage Example: Aggregating Data
const sales = { /* Points with attribute 'revenue' */ };
const results = gtswebsdkgl.spatialutils.collect(zones, sales, 'revenue', 'total_revenue');
// Zones now contain a 'total_revenue' property
6. Line Manipulation & Grid Functions 📏
Returns a segment of a LineString sliced between the two nearest points to the given start and end coordinates.
GeoJSON (LineString Feature)Usage Example: Slicing a Line
const start = { /* Point near the start */ };
const end = { /* Point near the end */ };
const segment = gtswebsdkgl.spatialutils.lineSlice(start, end, route);
console.log('Segment length:', gtswebsdkgl.spatialutils.length(segment));
Returns a segment of a LineString sliced between two distances along the line.
GeoJSON (LineString Feature)Usage Example: Slicing by Distance
// Get segment between 10km and 20km along the route
const section = gtswebsdkgl.spatialutils.lineSliceAlong(route, 10, 20, {units:'kilometers'});
console.log('Section length:', gtswebsdkgl.spatialutils.length(section, {units:'kilometers'}));
Divides a LineString into **smaller segments** of a specified length, returning a MultiLineString or FeatureCollection.
GeoJSON (MultiLineString Feature)Usage Example: Splitting a Line
// Chunk the line into 5-mile segments
const segments = gtswebsdkgl.spatialutils.lineChunk(routeLine, 5, {units:'miles'});
console.log(`Split route into ${segments.features.length} features.`);
Returns a **Point** at a specified distance along a LineString, similar to `along`.
GeoJSON (Point Feature)Usage Example: Interpolate (same as along)
const pt = gtswebsdkgl.spatialutils.interpolate(line, 2.5, {units:'miles'});
console.log('Point 2.5 miles along:', pt.geometry.coordinates);
Creates a **FeatureCollection of Points** at regular intervals across a defined BBOX.
GeoJSON (Point FeatureCollection)Usage Example: Creating a Point Grid
// 10km cell size
const grid = gtswebsdkgl.spatialutils.pointGrid(bbox, 10, {units:'kilometers'});
console.log(`Generated ${grid.features.length} points.`);
Creates a **FeatureCollection of hexagonal Polygons** at a uniform size across a defined BBOX.
GeoJSON (Polygon FeatureCollection)Usage Example: Creating a Hex Grid
// 5-mile cell size
const hexes = gtswebsdkgl.spatialutils.hexGrid(bbox, 5, {units:'miles'});
console.log(`Generated ${hexes.features.length} hexagonal cells.`);
Creates a **FeatureCollection of triangular Polygons** at a uniform size across a defined BBOX.
GeoJSON (Polygon FeatureCollection)Usage Example: Creating a Triangle Grid
// 10km cell size
const triangles = gtswebsdkgl.spatialutils.triangleGrid(bbox, 10, {units:'kilometers'});
console.log(`Generated ${triangles.features.length} triangular cells.`);