@ideditor/location-conflation

location-conflation

🧩 Define complex geographic regions by including and excluding country codes and GeoJSON shapes.

What is it?

Location-conflation is a tool for generating GeoJSON features by including and excluding other locations and shapes.

⚡️ Try it now!: https://ideditor.github.io/location-conflation/

You can define a location set as an Object with include and exclude properties:

let locationSet = {
  include: [ Array of locations ],
  exclude: [ Array of locations ]
};

The "locations" can be any of the following:

• Strings recognized by the country-coder library. These should be ISO 3166-1 2 or 3 letter country codes or UN M.49 numeric codes.
  Example: "de"
• Filenames for .geojson features. If you want to use your own features, pass them to the LocationConflation constructor in a FeatureCollection - each Feature must have an id that ends in .geojson.
  Example: "de-hamburg.geojson"
• Points as [longitude, latitude] coordinate pairs. A 25km radius circle will be computed around the point.
  Example: [8.67039, 49.41882]

Usage

To install location-conflation as a dependency in your project:

$  npm install --save @ideditor/location-conflation

location-conflation is distributed in both UMD and ES6 module formats for maxmimum compatibility. (Read more about Javascript module formats)

• index.mjs - ES6 module
• dist/index.js - UMD module, ES6 syntax
• dist/index.es5.js - UMD module, ES5 syntax

Whether you require or import it, it should just work.

const LocationConflation = require('@ideditor/location-conflation');    // UMD import all
// or
import * as LocationConflation from '@ideditor/location-conflation';    // ES6 import all

You can also use location-conflation directly in a web browser. A good way to do this is to fetch the file from the jsDelivr CDN, which can even deliver minified versions.

The latest versions of many web browsers now support ES6 modules in script tags like this:

<script type="module" src="https://cdn.jsdelivr.net/npm/@ideditor/location-conflation@0/index.min.mjs"></script>

Older versions of modern ES6-capable browsers can still load the UMD build:

<script src="https://cdn.jsdelivr.net/npm/@ideditor/location-conflation@0/dist/index.min.js"></script>

Or if you need to support even older browsers like Internet Explorer, fetch the ES5 version:

<script src="https://cdn.jsdelivr.net/npm/@ideditor/location-conflation@0/dist/index.es5.min.js"></script>

 

Examples

const LocationConflation = require('@ideditor/location-conflation');
const myFeatures = require('./path/to/FeatureCollection.json');   // optional
const loco = new LocationConflation(myFeatures);

Southern Europe:

let result = loco.resolveLocationSet({ include: ['039'] });   // 039 = Southern Europe

Southern Europe and Northern Africa:

let result = loco.resolveLocationSet({ include: ['039','015'] });   // 015 = Northern Africa

Southern Europe and Northern Africa, excluding Egypt and Sudan:

let result = loco.resolveLocationSet({ include: ['039','015'], exclude: ['eg','sd'] });

The Alps, excluding Liechtenstein and regions around Bern and Zürich

let result = loco.resolveLocationSet({ include: ['alps.geojson'], exclude: ['li', [8.55,47.36], [7.45,46.95]] });

Other Fun facts

• This library is a wrapper around
  • country-coder for world boundaries, and
  • polygon-clipping for union/difference functions
• Results contain an area property containing the approximate size of the feature in km²
  (This is helpful for sorting features)
• Results contain a stable id in the form +[included]-[excluded]
  (e.g. "+[015,039]-[eg,sd]")
• Results are cached, so if you ask for the same thing multiple times we don't repeat the expensive clipping operations.

Prerequisites

• Node.js version 10 or newer
• git for your platform

Installing

• Clone this project, for example: git clone [e-mail]:ideditor/location-conflation.git
• cd into the project folder,
• Run npm install to install libraries

Building

• npm run build

License

This project is available under the ISC License. See the LICENSE.md file for more details.

Changelog

0.4.0

2020-Aug-20

• Replace turf with mfogel/polygon-clipping ([#1], [#2], [#20])
• Include stringify convenience method
• Update country-coder and other dependencies