geojson-geometries-lookup

⚡️ 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

• Simone Primarosa - Github (@simonepri) • Twitter (@simoneprimarosa)

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.