Client for 'mapshaper' for 'Geospatial' Operations

Edit and simplify 'geojson', 'Spatial', and 'sf' objects. This is wrapper around the 'mapshaper' 'JavaScript' library by Matthew Bloch < https://github.com/mbloch/mapshaper/> to perform topologically-aware polygon simplification, as well as other operations such as clipping, erasing, dissolving, and converting 'multi-part' to 'single-part' geometries. It relies on the 'geojsonio' package for working with 'geojson' objects, the 'sf' package for working with 'sf' objects, and the 'sp' and 'rgdal' packages for working with 'Spatial' objects.


Travis-CI BuildStatus
AppVeyor BuildStatus codecov.io
CRAN_Status_Badge CRAN Downloads permonth CRAN totaldownloads

rmapshaper

An R package providing access to the awesome mapshaper tool by Matthew Bloch, which has both a Node.js command-line tool as well as an interactive web tool.

I started this package so that I could use mapshaper’s Visvalingam simplification method in R. There is, as far as I know, no other R package that performs topologically-aware multi-polygon simplification. (This means that shared boundaries between adjacent polygons are always kept intact, with no gaps or overlaps, even at high levels of simplification).

But mapshaper does much more than simplification, so I am working on wrapping most of the core functionality of mapshaper into R functions.

So far, rmapshaper provides the following functions:

  • ms_simplify - simplify polygons or lines
  • ms_clip - clip an area out of a layer using a polygon layer or a bounding box. Works on polygons, lines, and points
  • ms_erase - erase an area from a layer using a polygon layer or a bounding box. Works on polygons, lines, and points
  • ms_dissolve - aggregate polygon features, optionally specifying a field to aggregate on. If no field is specified, will merge all polygons into one.
  • ms_explode - convert multipart shapes to single part. Works with polygons, lines, and points in geojson format, but currently only with polygons and lines in the Spatial classes (not SpatialMultiPoints and SpatialMultiPointsDataFrame).
  • ms_lines - convert polygons to topological boundaries (lines)
  • ms_innerlines - convert polygons to shared inner boundaries (lines)
  • ms_points - create points from a polygon layer
  • ms_filter_fields - Remove fields from the attributes
  • ms_filter_islands - Remove small detached polygons

If you run into any bugs or have any feature requests, please file an issue

rmapshaper is on CRAN. Install the current version with:

install.packages("rmapshaper")

You can install the development version from github with devtools:

## install.packages("devtools")
library(devtools)
install_github("ropensci/geojsonio")
install_github("ateucher/rmapshaper")

Usage

rmapshaper works with geojson strings (character objects of class geo_json) and list geojson objects of class geo_list. These classes are defined in the geojsonio package. It also works with Spatial classes from the sp package, and with sf and scf objects from the sf package.

We will use the states dataset from the geojsonio package and first turn it into a geo_json object:

library(geojsonio)
#> 
#> Attaching package: 'geojsonio'
#> The following object is masked from 'package:base':
#> 
#>     pretty
library(rmapshaper)
library(sp)
library(sf)
#> Linking to GEOS 3.7.0, GDAL 2.3.1, PROJ 5.2.0
 
## First convert to json
states_json <- geojson_json(states, geometry = "polygon", group = "group")
#> Assuming 'long' and 'lat' are longitude and latitude, respectively
 
## For ease of illustration via plotting, we will convert to a `SpatialPolygonsDataFrame`:
states_sp <- geojson_sp(states_json)
 
## Plot the original
plot(states_sp)

 
## Now simplify using default parameters, then plot the simplified states
states_simp <- ms_simplify(states_sp)
plot(states_simp)

You can see that even at very high levels of simplification, the mapshaper simplification algorithm preserves the topology, including shared boundaries:

states_very_simp <- ms_simplify(states_sp, keep = 0.001)
plot(states_very_simp)

Compare this to the output using rgeos::gSimplify, where overlaps and gaps are evident:

library(rgeos)
#> rgeos version: 0.3-28, (SVN revision 572)
#>  GEOS runtime version: 3.6.1-CAPI-1.10.1 r0 
#>  Linking to sp version: 1.3-1 
#>  Polygon checking: TRUE
states_gsimp <- gSimplify(states_sp, tol = 1, topologyPreserve = TRUE)
plot(states_gsimp)

The package also works with sf objects. This time we’ll demonstrate the ms_innerlines function:

library(sf)
 
states_sf <- st_as_sf(states_sp)
states_sf_innerlines <- ms_innerlines(states_sf)
plot(states_sf_innerlines)

All of the functions are quite fast with geo_json character objects and geo_list list objects. They are slower with the Spatial classes due to internal conversion to/from json. Operating on sf objects is faster than with Spatial objects, but not as fast as with the geo_json or geo_list. If you are going to do multiple operations on large Spatial objects, it’s recommended to first convert to json using geojson_list or geojson_json from the geojsonio package. All of the functions have the input object as the first argument, and return the same class of object as the input. As such, they can be chained together. For a contrived example, using states_sp as created above:

library(geojsonio)
library(rmapshaper)
library(sp)
library(magrittr)
 
## First convert 'states' dataframe from geojsonio pkg to json
states_json <- geojson_json(states, lat = "lat", lon = "long", group = "group", 
                            geometry = "polygon")
 
states_json %>% 
  ms_erase(bbox = c(-107, 36, -101, 42)) %>% # Cut a big hole in the middle
  ms_dissolve() %>% # Dissolve state borders
  ms_simplify(keep_shapes = TRUE, explode = TRUE) %>% # Simplify polygon
  geojson_sp() %>% # Convert to SpatialPolygonsDataFrame
  plot(col = "blue") # plot

Using the system mapshaper

Sometimes if you are dealing with a very large spatial object in R, rmapshaper functions will take a very long time or not work at all. As of version 0.4.0, you can make use of the system mapshaper library if you have it installed. This will allow you to work with very large spatial objects.

First make sure you have mapshaper installed:

check_sys_mapshaper()
#> mapshaper version 0.4.98 is installed and on your PATH
#> [1] TRUE

If you get an error, you will need to install mapshaper. First install node (https://nodejs.org/en/) and then install mapshaper with:

npm install -g mapshaper

Then you can use the sys argmument in any rmapshaper function:

states_simp_internal <- ms_simplify(states_sf)
states_simp_sys <- ms_simplify(states_sf, sys = TRUE)
 
all.equal(states_simp_internal, states_simp_sys)
#> [1] TRUE

Thanks

This package uses the V8 package to provide an environment in which to run mapshaper’s javascript code in R. It relies heavily on all of the great spatial packages that already exist (especially sp and rgdal), the geojsonio package for converting between geo_list, geo_json, and sf and Spatial objects, and the jsonlite package for converting between json strings and R objects.

Thanks to timelyportfolio for helping me wrangle the javascript to the point where it works in V8. He also wrote the mapshaper htmlwidget, which provides access to the mapshaper web interface, right in your R session. We have plans to combine the two in the future.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

LICENSE

MIT

News

rmapshaper 0.4.1

  • Fixed a bug when using sys = TRUE would fail on Windows in some circumstances (#77)
  • Fixed an issue where running rmapshaper functions on sfc objects failed with sf v0.7

rmapshaper 0.4.0

New features

  • Added sys argument to allow the use of the system mapshaper if it's installed (#61)

Improvements and bug fixes

  • Upgraded to mapshaper v0.4.64 (#60)
  • sf::st_read() is now used throughout for reading from disk and from geojson strings, which allows for greater consistency and better performance.
  • Better handling of different column classes (#68, thanks @mdsumner)
  • Avoid stackoverflow caused by adding special geojson classes (#71, https://github.com/ropensci/geojsonio/issues/128)
  • The name of the sf column is now properly retained (#70)
  • Fixed issue where encoding/special characters were not preserved (#67)

rmapshaper 0.3.1

  • Fixed a bug where converting geojson objects to sf failed with sf >= 0.5-6 (#64)

rmapshaper 0.3.0

  • Methods for sf and sfc classes have been added (#46)
  • rmapshaperid column is only retained if it is the only column, otherwise it's dropped.
  • ms_innerlines returns only the geometry for sf and Spatial*DataFrame classes. (#57)
  • ms_dissolve gains a weight argument for generating weighted centroids of dissolved points. (#39)

rmapshaper 0.2.0

  • Added snap_interval to ms_simplify() (#43, @nikolai-b)
  • Bug-fix: Respect drop_null_geometries argument in ms_simplify.geo_list() (#45, @nikolai-b)
  • Add Kent Russell (@timelyportfolio) to authors list for his JavaScript expertise and advice
  • Add Matthew Bloch (@mbloch) to authors list as mapshaper copyright holder
  • Update mapshaper to version 0.3.41
  • A V8 session is now launched once per function call and destroyed when the function exits, rather than created on package load and retained for the entire session (#49)
  • Column classes are now restored after being sent through mapshaper functions (#46)
  • Fixed a bug where very small values of keep in ms_simplify() were converted to scientific notation (#48)
  • Added weighting argument to ms_simplify() (#27)
  • Added remove_slivers argument in ms_clip() and ms_erase()

rmapshaper 0.1.0

  • Initial release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("rmapshaper")

0.4.1 by Andy Teucher, 4 months ago


https://github.com/ateucher/rmapshaper


Report a bug at https://github.com/ateucher/rmapshaper/issues


Browse source code at https://github.com/cran/rmapshaper


Authors: Andy Teucher [aut, cre] , Kenton Russell [aut] (JavaScript support) , Matthew Bloch [cph] (mapshaper Javascript library)


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports geojsonio, geojsonlint, jsonlite, methods, readr, sf, sp, V8

Suggests knitr, magrittr, rgeos, rmarkdown, testthat


Imported by MazamaSpatialUtils, crawl.

Suggested by echarts4r, mregions, surveillance, tmap, tmaptools.


See at CRAN