dodolooking / geotoolbox

geojson toolbox

]

geotoolbox is a javascript tool for geographers. It allows one to manage geojson properties (attribute data) and provides several useful GIS operations for thematic cartography.

1. Installation

1.1. In browser

Latest version

<script src="https://cdn.jsdelivr.net/npm/geotoolbox" charset="utf-8"></script>

Pinned version

<script
  src="https://cdn.jsdelivr.net/npm/geotoolbox@1.9.2"
  charset="utf-8"
></script>

1.2. In Observable

Latest version

geo = require("geotoolbox");

Pinned version

geo = require("geotoolbox@1.9.2");

2. Demo

Find a demo of all functions here.

3. Documentation

3.1. Handle properties

_Here we are talking about some basic functions which are useful for handling attribute data. Example.

add allows adding a new field in the attribute table. This function returns a new object and does not modify the initial object.

geo.add({
    x: world, // a geojson object
    field: "gdppc", // new colname (string) 
    expression: "gdp/pop*1000" // a string containing an expression
})

head allows getting the n top values from a given field. This function returns a new object and does not modify the initial object.

geo.head({
    x: world, // a geojson object
    field: "gdp", // a colname (string)
    nb: 5 // default:10. Number of features to get. Here, the 5 richest countries.
})

keep allows selecting one or several columns to keep in the attribute table. All other columns are deleted. This function returns a new object and does not modify the initial object.

geo.keep({
    x: world, // a geojson object
    field: ["ISO3", "pop2020"] // colname(s) (string or array of strings) 
})

remove allows removing one or several columns in the attribute table. This function returns a new object and does not modify the initial object.

geo.remove({
    x: world, // a geojson object
    field: ["tmp", "FID"] // colname(s) (string or array of strings) 
})

select allows filtering a geojson object by its attribute table. This function returns a new object and does not modify the initial object.

geo.select({
    x: world, // a geojson object
    expression: "pop2022 >= 100000" // an expression (string) 
})

subset allows creating a subset from an array of values. This function returns a new object and does not modify the initial object.

geo.subset({
    x: world, // a geojson object
    field: "ISO3", // colname (string)
    selection: ["USA", "CAN", "MEX"], // values to be kept. Here, North American countries
    inverse: false // default: false. If true, all countries except USA, CAN and MEX are kept 
})

table allows getting a geojson attribute table.

geo.table(world // a geojson object

tail allows getting the n bottom values from a given field. This function returns a new object and does not modify the initial object.

geo.tail({
    x: world, // a geojson object
    field: "gdp", // a colname (string)
    nb: 5 // default:10. Number of features to get. Here, the 5 least wealthy countries
})

3.2 Handle geometries

Here we are talking about some basic functions which are useful for thematic maps, based on topojson, d3geo and jsts.

aggregate allows merging geometries based on their topology. To merge polygon geometries, see union. Example

geo.aggregate(world) // a geojson object

With options, you can compute an aggregate by id.

continents = geo.aggregate(
    world, // a geojson object
    { 
        id: "continent" // ids
    })

bbox allows returning a geographic bounding box as geojson from a geojson or a n array defining a bounding box [[left, bottom], [right, top]]. This function is based on Jacob Rus code. Example

geo.bbox(world) // a geojson object

border allows extracting boundaries from a geojson object (polygons). With options, you can get ids and calculate discontinuities. Example

geo.border(world) // a geojson object

With options:

geo.border(
    world, // a geojson object
    { 
        id: "ISO3", // ids
        values: "pop", // values
        type: "abs", // type of discontinuities calculated: rel (relative), abs(absolute) (default:"rel")
        share: 0.8 // share of kept borders (default: null for all)
    })

buffer allows building a buffer from points, lines or polygones. The distance is in kilometers.

geo.buffer(geojson, { dist: 1000 }) // 1000 km 

The distance value can also be contained in a geojson field (in the properties). In this case, you just have to indicate the name of this field.

geo.buffer(geojson, { dist: "a field" }) // a field in properties

The merge option allows merging all the output buffers.

geo.buffer(geojson, { dist: 1000, merge:true }) 

The clip option prevents the buffers from sticking out of the world outline. Not having coordinates that exceed [-90, 90] in latitude and [-180, 180] in longitude is necessary for the d3.js projection functions to work properly.

geo.buffer(geojson, { dist: 1000, clip:true }) 

The step option allows defining the precision of the buffer (default:8)

geo.buffer(geojson, { dist: 1000, step:1 }) 

You can use wgs84=false if your geojson is not in wgs84. In this case, the distance will be given in the map coordinates.

geo.buffer(geojson, { dist: 1000, wgs84:false }) 

clip allows clipping geometries. Example

geo.clip(geojson1, {clip:geojson2}) 

With the option reverse:true, you can do a difference operation.

geo.clip(geojson1, {clip:geojson2, reverse: true}) 

You can also define a buffer in km around the clip.

geo.clip(geojson1, {clip:geojson2, buffer: 100}) 

centroid allows computing centroids from polygons. Example

geo.centroid(world) // a geojson (polygons) object

By default, the centroid is placed in the largest polygon. But you can avoid it.

geo.centroid(
    world, // a geojson object
    {
        largest: false // largest polygon. true/false (default: true)
    })

It may happen that the coordinates of your base map are not in latitudes and longitudes, but already projected. In this case you can use the option planar = true.

geo.centroid(
    world, // a geojson object
    {
        largest: false, // largest polygon. true/false (default: true)
        planar: true // if geometries are already projected
    })

coords2geo allows building a geojson object from a table with lat,lng coordinates. Example

geo.coords2geo(
    data, // a json object
    {
        lat: "lat" // the field containing latitude coordinates (you can use also `latitude`) 
        lng: "lon" // the field containing longitude coordinates (you can use also `longitude`) 
    })

This function works also if coordinates are stored in a single field.

geo.coords2geo(
    data, // a json object
    {
        coords: "Coordinates" // the field containing coordinates (you can use also `coordinates`) 
    })

For an even simpler automatic use, you don't have to specify the name of the variables containing the coordinates. If your data table contains the following fields (lat, latitude, lon,lng, longitude, coords, coordinates, coordinate), they are automatically selected. It is convenient, but for a better control and a faster calculation, it is still better to define where the coordinates are.

geo.coords2geo(data) // a json object

Sometimes the coordinates can be inverted. In this case you can set the reverse option to true.

geo.coords2geo(
    data, // a json object
    {
        reverse: true // to reverse latitudes and longitude coordinates
    })

dissolve allows disolving geometries (multipart to single parts). Example

geo.dissolve(world) // a geojson object

union allows merging polygon geometries. Example

geo.union(world) // a geojson object

With options, you can compute an union by id.

continents = geo.union(
    world, // a geojson object
    { 
        id: "continent" // ids
    })

simplify allows simplifying geometries while preserving topology (topojson.simplify algorithm). Example

geo.simplify(
    world, // a geojson object
    { 
        k, // factor of simplification (default: 0.5)
        merge: false // true to merge geometries(default: false)
    })

tissot tissot allows getting the Tissot's indicatrix. Example

geo.tissot(20) // step (default; 10)

geolines allows getting the natural geographic lines such as equator, tropics & polar circles. Example

geo.geolines() 

3.3 Utils

filter allows to create and returns a new geojson containing all the elements of the original geojson that meet a condition determined by the callback function applied on properties (or geometries). the function returns a new geojson and does not modify the initial geojson. Find examples here.

newworld = geo.filter(world, (d) => d.CNTR_ID == "BR")

You can also do the same thing on geometries by specifying a third argument as "geometry". For example:

newworld = geo.filter(world, (d) => d3.geoArea(d) > area, "geometry")

map allows to create a new geojson with the results of a function call provided on each element of geojson properties (or geometries). the function returns a new geojson and does not modify the initial geojson. Find examples here.

renameproperties = geo.map(world, (d, i) => ({
  index: i,
  id: d.CNTR_ID,
  name: d.CNTR_NAME
}))

You can also do the same thing on geometries by specifying a third argument as "geometry". For example:

dot = geo.map(
  world,
  (d) => ({ type: "Point", coordinates: d3.geoCentroid(d) }),
  "geometry"
)

featurecollection allows converting an array of features or an array of geometries to a well formated geosjon. Example

geo.featurecollection(features) 

type allows get the geometry type of a geojson ("point", "line", "polygon")

geo.type(geojson)