Skip to main content

topojson - a powerful library to encode geographic data as topology in Python!🌍

Project description

TopoJSON

PyPI version License

[Work in Progress]

TopoJSON encodes geographic data structures into a shared topology. This repository describes the development of a Python implementation of this TopoJSON format. A TopoJSON topology represents one or more geometries that share sequences of positions called arcs.

Usage

The package can be used as follow:

import topojson

data = [
    {"type": "Polygon", "coordinates": [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]},
    {"type": "Polygon", "coordinates": [[[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]]]}
]

topojson.topology(data)
    {'type': 'Topology',
     'objects': {'data': {'geometries': [{'type': 'Polygon', 'arcs': [[0, -4, 1]]},
        {'type': 'Polygon', 'arcs': [[2, 3]]}],
       'type': 'GeometryCollection'}},
     'arcs': [[[0.0, 0.0], [1.0, 0.0]],
      [[1.0, 1.0], [0.0, 1.0], [0.0, 0.0]],
      [[1.0, 0.0], [2.0, 0.0], [2.0, 1.0], [1.0, 1.0]],
      [[1.0, 1.0], [1.0, 0.0]]]}

The result is TopoJSON.

The following geometry types are registered as correct geographical input data:

  • geojson.Feature
  • geojson.FeatureCollection
  • geopandas.GeoDataFrame
  • geopandas.GeoSeries
  • shapely.geometry.LineString
  • shapely.geometry.MultiLineString
  • shapely.geometry.Polygon
  • shapely.geometry.MultiPolygon
  • shapely.geometry.Point
  • shapely.geometry.MultiPoint
  • shapely.geometry.GeometryCollection
  • dict of objects that provide a valid __geo_interface__
  • list of objects that provide a valid __geo_interface__

Installation

The package is released on PyPi as version 1.0rc2. Installation can be done by:

python3 -m pip install topojson

The required dependencies are:

  • numpy
  • shapely
  • simplification

Download dependencies from https://www.lfd.uci.edu/~gohlke/pythonlibs/ for Windows where possible and use pip for Linux and Mac.

The packages geopandas and geojson are solely used in the tests and recognized as types with the extractor.

Examples and tutorial notebooks

Type: list

The list should contain items that supports the __geo_interface__

import topojson

list_geoms = [
    {"type": "Polygon", "coordinates": [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]},
    {"type": "Polygon", "coordinates": [[[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]]]}
]

topojson.topology(list_geoms)
    {'type': 'Topology',
     'objects': {'data': {'geometries': [{'type': 'Polygon', 'arcs': [[-3, 0]]},
        {'type': 'Polygon', 'arcs': [[1, 2]]}],
       'type': 'GeometryCollection'}},
     'arcs': [[[1.0, 1.0], [0.0, 1.0], [0.0, 0.0], [1.0, 0.0]],
      [[1.0, 0.0], [2.0, 0.0], [2.0, 1.0], [1.0, 1.0]],
      [[1.0, 1.0], [1.0, 0.0]]]}

Type: dict

The dictionary should be structured like {key1: obj1, key2: obj2}.

import topojson

dictionary = {
    "abc": {
        "type": "Polygon",
        "coordinates": [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]],
    },
    "def": {
        "type": "Polygon",
        "coordinates": [[[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]]],
    }
}

topojson.topology(dictionary)
    {'type': 'Topology',
     'objects': {'data': {'geometries': [{'type': 'Polygon', 'arcs': [[-3, 0]]},
        {'type': 'Polygon', 'arcs': [[1, 2]]}],
       'type': 'GeometryCollection'}},
     'arcs': [[[1.0, 1.0], [0.0, 1.0], [0.0, 0.0], [1.0, 0.0]],
      [[1.0, 0.0], [2.0, 0.0], [2.0, 1.0], [1.0, 1.0]],
      [[1.0, 1.0], [1.0, 0.0]]]}

Type: GeoDataFrame from package geopandas (if installed)

import geopandas
import topojson
from shapely import geometry
%matplotlib inline

gdf = geopandas.GeoDataFrame({
    "name": ["abc", "def"],
    "geometry": [
        geometry.Polygon([[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]),
        geometry.Polygon([[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]])
    ]
})
gdf.plot(column="name")
gdf.head()
name geometry
0 abc POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))
1 def POLYGON ((1 0, 2 0, 2 1, 1 1, 1 0))
Logo

topojson.topology(gdf)
    {'type': 'Topology',
     'objects': {'data': {'geometries': [{'id': '0',
         'type': 'Polygon',
         'properties': {'name': 'abc'},
         'bbox': (0.0, 0.0, 1.0, 1.0),
         'arcs': [[-3, 0]]},
        {'id': '1',
         'type': 'Polygon',
         'properties': {'name': 'def'},
         'bbox': (1.0, 0.0, 2.0, 1.0),
         'arcs': [[1, 2]]}],
       'type': 'GeometryCollection'}},
     'arcs': [[[1.0, 1.0], [0.0, 1.0], [0.0, 0.0], [1.0, 0.0]],
      [[1.0, 0.0], [2.0, 0.0], [2.0, 1.0], [1.0, 1.0]],
      [[1.0, 1.0], [1.0, 0.0]]]}

Type: FeatureCollection from package geojson (if installed)

from geojson import Feature, Polygon, FeatureCollection

feature_1 = Feature(
    geometry=Polygon([[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]),
    properties={"name":"abc"}
)
feature_2 = Feature(
    geometry=Polygon([[[1, 0], [2, 0], [2, 1], [1, 1], [1, 0]]]),
    properties={"name":"def"}
)
feature_collection = FeatureCollection([feature_1, feature_2])

topojson.topology(feature_collection)
    {'type': 'Topology',
     'objects': {'data': {'geometries': [{"arcs": [[-3, 0]], "properties": {"name": "abc"}, "type": "Polygon"},
        {"arcs": [[1, 2]], "properties": {"name": "def"}, "type": "Polygon"}],
       'type': 'GeometryCollection'}},
     'arcs': [[[1.0, 1.0], [0.0, 1.0], [0.0, 0.0], [1.0, 0.0]],
      [[1.0, 0.0], [2.0, 0.0], [2.0, 1.0], [1.0, 1.0]],
      [[1.0, 1.0], [1.0, 0.0]]]}

The notebooks folder of this GitHub repository also contains a Jupyter Notebook with a tutorial. The many tests as part of this package also can be used as example material.

Changelog

Version 1.0rc2:

  • apply linemerge on non-duplicate arcs
  • fix computing topology without shared boundaries (#1, #3)
  • use geopandas and geojson solely for tests, but recognize them as type (#2, #4)
  • use simplification as option to simplify linestrings
  • include option to snap vertices to grid
  • removed rdtree as dependency, use SRTtree from shapely instead

Version 1.0rc1:

  • initial release

Development Notes

Development of this packages started by reading:

The reason for development of this package was the willingness:

  • To adopt shapely (GEOS) and numpy for the core-functionalities in deriving the Topology.
  • To provide integration with other geographical packages within the Python ecosystem (eg. geopandas and altair).
  • Also the possibility of including the many tests available in the JavaScript implementation was hoped-for.

To create a certain synergy between the JavaScript and Python implementation the same naming conventions was adopted for the processing steps (extract, join, cut, dedup, hashmap). Even though the actual code differs significant.

Some subtile differences are existing between the JavaScript implementation and the current Python implementation for deriving the Topology. Some of these deviations are briefly mentioned here:

  1. The extraction class stores all the different geometrical objects as Shapely LineStrings in linestrings and keeps a record of these linestrings available under the key bookkeeping_geoms. In the JavaScript implementation there is a differentiation of the geometries between lines, rings and a seperate object containing all coordinates. Since the current approach adopts shapely for much of the heavy lifting this extraction is working against us (in the cut-process).

  2. In the join class only the geometries that have shared paths are considered to have junctions. This means that the intersection of two crossing lines at a single coordinate is not considered as a junction. This also means that the two ends of a LineString are not automatically considered as being a junction. So if a segment starts or finish on another segment, with that coordinate being the only coordinate in common, it is not considered as a junction.

  3. In the computation of a shared path, a junction can be created on an existing coordinate in one of the geometries. Where in the JavaScript implementation this only can be considered when both geometries contain the coordinate.

  4. In the process of cutting lines; the rings are rotated in the JavaScript implementation to make sure they start at a junction. This reduces the number of cuts. This rotation is done before cutting. In the current Python implementation this is done differently. First the linestrings are cut using the junction coordinates and afterwards there is tried to apply a linemerge on the non-duplicate arcs of a geometry containing at least one shared arc.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for topojson, version 1.0rc3
Filename, size File type Python version Upload date Hashes
Filename, size topojson-1.0rc3-py2.py3-none-any.whl (98.7 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size topojson-1.0rc3.tar.gz (4.2 MB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page