GeoJSON Diff
A Ruby library for diffing GeoJSON files
Overview
GeoJSON Diff takes two GeoJSON files representing the same geometry (or geometries) at two points in time, and generates three GeoJSON files representing the added
, removed
, and unchanged
geometries (including changed properties).
These three GeoJSON files can be used to generate a visual representation of the changes (proposed or realized), e.g., by coloring the added elements green and the removed elements red. GeoJSON Diff is what powers GeoJSON diffing on GitHub.
GeoJSON Diff in the wild
See GeoJSON diff in action! Here's a diff of Illinois's famed 4th congressional district after undergoing redistricting in 2011:
GeoJSON Diff will even diff properties within the geometry when they change:
Usage
diff = GeojsonDiff.new geojson_before, geojson_after
diff.added
# => {"type":"Feature"... (valid GeoJSON representing the added geometries)
diff.removed
# => {"type":"Feature"... (valid GeoJSON representing the removed geometries)
diff.unchanged
# => {"type":"Feature"... (valid GeoJSON representing the unchanged geometries)
For practical examples, take a look at the test/fixtures directory.
Displaying the resulting GeoJSON
Every geometry within the resulting GeoJSON files will be appended with standard GeoJSON properties in the _geojson_diff
namespace.
type
- this field contains eitheradded
,removed
, orunchanged
and describes the state of the geometry as it relates to the initial GeoJSON file.added
,removed
,changed
- these fields contain an array of property keys. If a given key is in theadded
array, that property existed in the resulting geometry, but not in the initial geometry. Likewise, if a key is inremoved
array it existed in the initial geometry, but not the resulting geometry, and if the key is in thechanged
array, it existed in both the initial and resulting geometry, but was changed.- For changed properties, the values of the
after
GeoJSON file will be marked up as a Diffy:html
diff and will represent the inline diff of the changed value.
Installation
Requirements
GeoJSON Diff is based on rgeo, rgeo-geojson, geos, ffi-geos, and diffy.
Installing GEOS
If you're on OS X and have Homebrew installed, you'll first want to run brew install geos
to install the GEOS geospatial library. On other systems, consult the GEOS installation instructions.
Installing the Gem
Add the following to your project's Gemfile and run bundle install
:
gem 'geojson-diff'
Pro-Tip
Because the library depends on GEOS, which can be finicky on some systems, the set-it-and-forget-it way to get everything set up is to:
- Add
gem 'geojson-diff'
to your project's Gemfile - Copy the contents of script/bootstrap
cd
to your project's root directory and paste/run the commands
This will install GEOS and configure the necessary environmental values.
Development
Bootstrapping a local development environment
script/bootstrap
Running tests
script/cibuild
Development console
script/console
Troubleshooting GEOS
On some environments, prior to running your application or running bundle install
, you'll need to run the following commands to properly configure your execution environment for Ruby to find the GEOS library:
export GEOS_LIBRARY_PATH=`geos-config --prefix`/lib
bundle config --local build.rgeo --with-geos-dir="$GEOS_LIBRARY_PATH"
License
Contributing
- Fork the project
- Create a descriptively named feature branch
- Make your changes
- Submit a pull request