@konfirm/geojson

GeoJSON validation, iteration, intersection and distance calculation.

API

Types

All GeoJSON types are available as export

| type | descriptions | note | | ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Position | A GeoJSON Position | [Longitude, Latitude, Altitude?] | | Point | A GeoJSON Point | The coordinates property is a Position | | MultiPoint | A GeoJSON MultiPoint | The coordinates property is an array of Position | | LineString | A GeoJSON LineString | The coordinates property is an array of two or more Position | | MultiLineString | A GeoJSON MultiLineString | The coordinates property is an array ofLineString coordinates | | Polygon | A GeoJSON Polygon | The coordinates property is an array of "LinearRings" (closed LineString coordinates, where the first and last Position are identical) | | MultiPolygon | A GeoJSON MultiPolygon | The coordinates property is an array of Polygon coordinate arrays | | GeometryCollection | A GeoJSON GeometryCollection | geometries is an array of Geometries (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon) | | Feature | A GeoJSON Feature | A spatially bounded 'Thing', consisting of a geometry property (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection) with additional properties | | FeatureCollection | A GeoJSON Collection | The features property is an array of Feature objects |

Type Guards

Most of the exported functionality is based on validation of GeoJSON objects, validating required and optional (if provided) properties. The isStrict* variants of the type guards also validate the following:

• Longitude is a number in the range (inclusive) -180..180
• Latitude is a number in the range (inclusive) -90..90
• Altitude is a number in the range (inclusive) -6371008.7714..20180000 (Earth center(-ish) up to the GPS satelite distance)
• Polygon "LinearRing" are closed (first and last Position are identical)
• Polygon "LinearRing" have the correct winding (counterclockwise for exterior rings (outline), clockwise for interior rings (holes))

| type | guard | strict guard | description | | ------------------ | ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Position | isPosition | isStrictPosition | validate whether the input is valid GeoJSON Position | | Point | isPoint | isStrictPoint | validate whether the input is valid GeoJSON Point | | MultiPoint | isMultiPoint | isStrictMultiPoint | validate whether the input is valid GeoJSON MultiPoint | | LineString | isLineString | isStrictLineString | validate whether the input is valid GeoJSON LineString | | MultiLineString | isMultiLineString | isStrictMultiLineString | validate whether the input is valid GeoJSON MultiLineString | | Polygon | isPolygon | isStrictPolygon | validate whether the input is valid GeoJSON Polygon | | MultiPolygon | isMultiPolygon | isStrictMultiPolygon | validate whether the input is valid GeoJSON MultiPolygon | | GeometryCollection | isGeometryCollection | isStrictGeometryCollection | validate whether the input is valid GeoJSON GeometryCollection | | Geometry | isGeometry | isStrictGeometry | validate whether the input is valid GeoJSON Geometry (Point, LineString, Polygon or their Multi* variants) | | Feature | isFeature | isStrictFeature | validate whether the input is valid GeoJSON Feature | | FeatureCollection | isFeatureCollection | isStrictFeatureCollection | validate whether the input is valid GeoJSON FeatureCollection | | GeoJSON | isGeoJSON | isStrictGeoJSON | validate the input to be valid GeoJSON |

import { isPoint, isStrictPoint } from '@konfirm/geojson';

const point: Point = {
    type: 'Point',
    coordinates: [181, 91],
};

console.log('the point is a GeoJSON Point', isPoint(point)); // true, as the structure is up to specification
console.log('the point is a strict GeoJSON Point', isStrictPoint(point)); // false, as the coordinates are not within the specified ranges

intersect

Verify whether the provided GeoJSON objects intersect.

Usage: intersect(<Geometry(Collection)|Feature(Collection)>, <Geometry(Collection)|Feature(Collection)>): boolean

import { intersect, Point, Feature } from '@konfirm/geojson';

const point: Point = {
    type: 'Point',
    coordinates: [1, 1],
};
const feature: Feature = {
    type: 'Feature',
    properties: {
        name: 'triangle'
    },
    geometry: {
        type: 'Polygon',
        coordinates: [[[0, 0], [0, 2], [2, 1], [0, 0]]],
    },
}

console.log('point intersects feature', intersect(point, feature)); // true
console.log('feature intersects point', intersect(feature, point)); // true

distance

Obtain the (shortest) distance in meters between two GeoJSON objects. There are three formulas which can be used:

• cartesian (default), calculates the distance between coordinates using the Pythagorean equation, this is the fastest formula at the cost of (huge amount of) accuracy
• haversine, calculates the distance between coordinates using the haversine formula, improves the accuracy to a level which is probably suitable for most needs with a decent performance
• vincenty, calculates the distance between coordinates using the Vincenty's formula, the most accurate but the least performant algorithm.

Usage: distance(<Geometry(Collection)|Feature(Collection)>, <Geometry(Collection)|Feature(Collection)> [, <'cartesian'|'haversine'|'vincenty'>]): number

import { distance, Feature } from '@konfirm/geojson';

    const a: Feature = {
        type: 'Feature',
        properties: {
            name: 'Schiphol Airpoirt, Amsterdam',
        },
        geometry: {
            type: 'Point',
            coordinates: [4.763889, 52.308333],
        },
    };
    const b: Feature = {
        type: 'Feature',
        properties: {
            name: 'John F. Kennedy International Airport, New York',
        },
        geometry: {
            type: 'Point',
            coordinates: [-73.778889, 40.639722],
        },
    };

    console.log(distance(a, b));             // 8829424.604594177
    console.log(distance(a, b, 'direct');    // 8829424.604594177 ('direct' is the default)
    console.log(distance(a, b, 'haversine'); // 5847546.425707642
    console.log(distance(a, b, 'vincenty');  // 5863355.371234315

SimpleGeometryIterator

The SimpleGeometryIterator class is a convenience helper utility which yeilds all simple Geometric shapes (Point, LineString, Polygon) from any GeoJSON object. Using a SimpleGeometryIterator allows you to focus on just implementing logic for the simple Geometric shapes whilst supporting any compbination of GeoJSON objects as input.

| input type | yields type(s) | description | | -------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- | | Point | Point | yields the Point geometry as is | | MultiPoint | Point | yields every Point of the MultiPoint | | LineString | LineString | yields the LineString geometry as is | | MultiLineString | LineString | yields every LineString of the MultiLineString | | Polygon | Polygon | yields the Polygon geometry as is | | MultiPolygon | Polygon | yields every Polygon of the MultiPolygon | | GeometryCollection | Point, LineString or Polygon | yields every geometry contained within the collection (see the corresponing types above) | | Feature | Point, LineString or Polygon | yields the geometry of a feature (see the corresponding types above) | | FeatureCollection | Point, LineString or Polygon | yields every Feature (see Feature) |

import type { Point, MultiPoint, LineString, MultiLineString, GeometryCollection, Feature, FeatureCollection } from '@konfirm/geojson';
import { SimpleGeometryIterator } from '@konfirm/geojson';

const point: Point = {
    type: 'Point',
    coordinates: [5.903949737548828, 51.991936460056515],
};
const multipoint: MultiPoint = {
    type: 'MultiPoint',
    coordinates: [
        [5.896482467651367, 52.00039200820837],
        [5.888843536376953, 51.99912377779024],
    ],
};
const linestring: LineString = {
    type: 'LineString',
    coordinates: [
        [5.9077370166778564, 51.9944435645134],
        [5.90764045715332, 51.994209045542206],
        [5.907415151596069, 51.99408683094357],
    ],
};
const multilinestring: MultiLineString = {
    type: 'MultiLineString',
    coordinates: [
        [
            [5.905205011367797, 51.99430813821511],
            [5.905086994171143, 51.994261894995034],
            [5.905033349990845, 51.99414958983319],
            [5.9051138162612915, 51.994116558849626]
        ],
        [
            [5.904818773269653, 51.993825885143515],
            [5.905521512031555, 51.993551725259614],
            [5.905789732933044, 51.99358805979856],
        ],
    ],
};
const geometrycollection: GeometryCollection = {
    type: 'GeometryCollection',
    geometries: [point],
};
const featurecollection: FeatureCollection = {
    type: 'FeatureCollection',
    features: [
        {
            type: 'Feature',
            properties: {},
            geometry: linestring,
        },
        {
            type: 'Feature',
            properties: {},
            geometry: multilinestring,
        },
    ]
};

const simplified = [...new SimpleGeometryIterator(multipoint, geometrycollection, featurecollection)];
/*
    [
        {
            type: 'Point',
            coordinates: ...multipoint[0]
        },
        {
            type: 'Point',
            coordinates: ...multipoint[1]
        },
        {
            type: 'Point',
            coordinates: ...point
        },
        {
            type: 'LineString',
            coordinates: ...linestring
        },
        {
            type: 'LineString',
            coordinates: ...multilinestring[0]
        },
        {
            type: 'LineString',
            coordinates: ...multilinestring[1]
        },
    ]
*/

License

MIT License Copyright (c) 2021-2023 Rogier Spieker (Konfirm)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.