Skip to content

Latest commit

 

History

History
340 lines (293 loc) · 14 KB

readme.md

File metadata and controls

340 lines (293 loc) · 14 KB
Raw

geojson-geometries-lookup

Latest version on npm Downloads on npm Project license
Lint status Test macOS status Test Ubuntu status Test Windows status
Codecov Coverage report Known Vulnerabilities Dependency Status
XO Code Style used AVA Test Runner used Istanbul Test Coverage used NI Scaffolding System used NP Release System used

⚡️ Fast geometry in geometry lookup for large GeoJSONs.
Coded with ❤️ by Simone Primarosa.

Synopsis

With this package you can perform the following operations (and more) on a given GeoJSON.

  • Given a Point get all the Points in the GeoJSON that intersects it.
  • Given a Point get all the Lines in the GeoJSON that intersects it.
  • Given a Point get all the Polygons in the GeoJSON that contains it.
  • Given a Line get all the Lines in the GeoJSON that contains it.
  • Given a Line get all the Polygons in the GeoJSON that contains it.
  • Given a Polygon get all the Polygons in the GeoJSON that contains it.

Install

$ npm install --save geojson-geometries-lookup

Showcase

Do you use geojson-geometries-lookup in your application? Please open a Pull Request to include it here.
We would love to have it in our list:

  • country-iso: 🗺 Get ISO 3166-1 alpha-3 country code for geographic coordinates.
  • is-sea: 🌊 Check whether a geographic coordinate is in the sea or not on the earth.

Usage

const GeoJsonGeometriesLookup = require('geojson-geometries-lookup');

const geojson = {type: 'FeatureCollection',
  features: [{
    type: 'Feature',
    geometry: {
      type: 'Point',
      coordinates: [102.0, 0.5]
    },
    properties: {prop0: 'value0'}
  }, {
    type: 'Feature',
    geometry: {
      type: 'LineString',
      coordinates: [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0]]
    },
    properties: {prop1: 'value1'}
  }, {
    type: 'Feature',
    geometry: {
      type: 'Polygon',
      coordinates: [
        [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]
      ]
    },
    properties: {prop2: 'value2'}
  }]
};

const glookup = new GeoJsonGeometriesLookup(geojson);

const point1 = {type: "Point", coordinates: [102.0, 0.5]};
glookup.getContainers(point1);
// => {
//   type: 'FeatureCollection',
//   features: [{
//     type: 'Feature',
//     geometry: {
//       type: 'Point',
//       coordinates: [102.0, 0.5]
//     },
//     properties: {prop0: 'value0'}
//   }]
// }
glookup.countContainers(point1);
// => 1

glookup.getContainers(point1, {ignorePoints: true});
// => {
//   type: 'FeatureCollection',
//   features: []
// }
glookup.countContainers(point1, {ignorePoints: true});
// => 0

const point2 = {type: "Point", coordinates: [101.0, 0.0]};
glookup.getContainers(point2);
// => {
//   type: 'FeatureCollection',
//   features: [{
//     type: 'Feature',
//     geometry: {
//       type: 'LineString',
//       coordinates: [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0]]
//     },
//     properties: {prop1: 'value1'}
//   }, {
//     type: 'Feature',
//     geometry: {
//       type: 'Polygon',
//       coordinates: [
//         [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]
//       ]
//     },
//     properties: {prop2: 'value2'}
//   }]
// }
glookup.getContainers(point2, {ignorePolygons: true});
// => {
//   type: 'FeatureCollection',
//   features: [{
//     type: 'Feature',
//     geometry: {
//       type: 'LineString',
//       coordinates: [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0]]
//     },
//     properties: {prop1: 'value1'}
//   }]
// }
glookup.hasContainers(point1, {ignorePoints: true, ignoreLines: true});
// => true

const poly1 = {
  type: 'Polygon',
  coordinates: [
    [[100.0+0.25, 0.0+0.25], [101.0-0.25, 0.0+0.25], [101.0-0.25, 1.0-0.25], [100.0+0.25, 1.0-0.25], [100.0+0.25, 0.0+0.25]]
  ]
}
glookup.getContainers(poly1, {ignorePoints: true, ignoreLines: true});
// => {
//   type: 'FeatureCollection',
//   features: [{
//     type: 'Feature',
//     geometry: {
//       type: 'Polygon',
//       coordinates: [
//         [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]
//       ]
//     },
//     properties: {prop2: 'value2'}
//   }]
// }

API

new GeoJsonGeometriesLookup(geoJson, [options])

Create an instance of the GeoJSON lookup class.

Param Type Description
geoJson Object The GeoJSON for which create the lookup data.
[options] Object Optional options.
options.ignorePoints boolean If true the extractor will ignore geometries of type Point.
options.ignoreLines boolean If true the extractor will ignore geometries of type LineString.
options.ignorePolygon boolean If true the extractor will ignore geometries of type Polygon.

geoJsonGeometriesLookup.forEachContainer(geometry, [options]) ⇒ number

Iterate on each geometry that completely contains the geometry provided.

Kind: instance method of GeoJsonGeometriesLookup
Returns: number - The number of geometries that completely contains the geometry provided iterated. The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a).

Param Type Description
geometry Object The geometry of type Point, LineString or Polygon for which to check if a container exists.
[options] Object Optional options.
options.limit number If greater than 0 it will limit the number of results on which iterate.
options.ignorePoints boolean If true will ignore geometries of type Point.
options.ignoreLines boolean If true will ignore geometries of type LineString.
options.ignorePolygon boolean If true will ignore geometries of type Polygon.

geoJsonGeometriesLookup.getContainers(geometry, [options]) ⇒ Object

Gets the geometries that completely contains the geometry provided.

Kind: instance method of GeoJsonGeometriesLookup
Returns: Object - A FatureCollection of geometries that completely contains the geometry provided. The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a).

Param Type Description
geometry Object The geometry of type Point, LineString or Polygon for which to count containers.
[options] Object Optional options.
options.limit number If greater than 0 it will limit the number of results returned.
options.ignorePoints boolean If true will ignore geometries of type Point.
options.ignoreLines boolean If true will ignore geometries of type LineString.
options.ignorePolygon boolean If true will ignore geometries of type Polygon.

geoJsonGeometriesLookup.hasContainers(geometry, [options]) ⇒ boolean

Checks if there is at least one geometry that completely contains the geometry provided.

Kind: instance method of GeoJsonGeometriesLookup
Returns: boolean - True if there is at least one geometry that completely contains the geometry provided. The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a).

Param Type Description
geometry Object The geometry of type Point, LineString or Polygon for which to check if a container exists.
[options] Object Optional options.
options.ignorePoints boolean If true will ignore geometries of type Point.
options.ignoreLines boolean If true will ignore geometries of type LineString.
options.ignorePolygon boolean If true will ignore geometries of type Polygon.

geoJsonGeometriesLookup.countContainers(geometry, [options]) ⇒ number

Counts the number of geometries that completely contains the geometry provided.

Kind: instance method of GeoJsonGeometriesLookup
Returns: number - The number of geometries that completely contains the geometry provided. The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b) must not intersect the exterior of the primary (geometry a).

Param Type Description
geometry Object The geometry of type Point, LineString or Polygon for which to count containers.
[options] Object Optional options.
options.limit number If greater than 0 it will stop counting when this number of containers has been found.
options.ignorePoints boolean If true will ignore geometries of type Point.
options.ignoreLines boolean If true will ignore geometries of type LineString.
options.ignorePolygon boolean If true will ignore geometries of type Polygon.

Contributing

Contributions are REALLY welcome and if you find a security flaw in this code, PLEASE report it.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the license file for details.