TopoJSON Simplify

Topology-preserving simplification and filtering for TopoJSON. Smaller files, faster rendering!

For an introduction to line simplification:

• https://bost.ocks.org/mike/simplify/
• https://www.jasondavies.com/simplify/

Installing

If you use NPM, npm install topojson-simplify. Otherwise, download the latest release. You can also load directly from unpkg. AMD, CommonJS, and vanilla environments are supported. In vanilla, a topojson global is exported:

1<script src="https://unpkg.com/topojson-client@3"></script>
2<script src="https://unpkg.com/topojson-simplify@3"></script>
3<script>
4
5topology = topojson.presimplify(topology);
6
7</script>

Try topojson-simplify in your browser.

API Reference

# topojson.presimplify(topology[, weight]) <>

Returns a shallow copy of the specified topology where each coordinate of each arc is assigned a z-value according to the specified weight function. If weight is not specified, it defaults to planarTriangleArea. If the input topology is delta-encoded (that is, if a topology.transform is present), this transform is removed in the returned output topology.

The returned presimplified topology can be passed to simplify to remove coordinates below a desired weight threshold.

# topojson.simplify(topology[, minWeight]) <>

Returns a shallow copy of the specified topology where every arc coordinate whose z-value is lower than minWeight is removed. Only the x and y dimensions of the coordinates are preserved in the returned topology. If minWeight is not specified, it defaults to Number.MIN_VALUE. This method has no effect on Point and MultiPoint geometries.

See presimplify to assign z-value for each coordinate. See also toposimplify.

# topojson.quantile(topology, p) <>

Returns the p-quantile of the weighted points in the given presimplified topology, where p is a number in the range [0, 1]. The quantile value is then typically passed as the minWeight to simplify. For example, the median weight can be computed using p = 0.5, the first quartile at p = 0.25, and the third quartile at p = 0.75. This implementation uses the R-7 method, which is the default for the R programming language and Excel.

Filtering

# topojson.filter(topology[, filter]) <>

Returns a shallow copy of the specified topology, removing any rings that fail the specified filter function. See filterAttached and filterWeight for built-in filter implementations.

If a resulting Polygon geometry object has no rings, it is replaced with a null geometry; likewise, empty polygons are removed from MultiPolygon geometry objects, and if the resulting MultiPolygon geometry object has no polygons, it is replaced with a null geometry; likewise, any null geometry objects are removed from GeometryCollection objects, and if the resulting GeometryCollection is empty, it is replaced with a null geometry.

After any geometry objects are removed from the topology, the resulting topology is pruned, removing any unused arcs. As a result, this operation typically changes the arc indexes of the topology.

# topojson.filterAttached(topology) <>

Returns a ring filter function that returns true if the specified ring shares an arc with any other object in the topology.

# topojson.filterAttachedWeight(topology[, minWeight[, weight]]) <>

Returns a ring filter function that returns true if the weight of the specified ring is greater than or equal to the specified minWeight threshold or the specified ring shares an arc with any other object in the topology.

# topojson.filterWeight(topology[, minWeight[, weight]]) <>

Returns a ring filter function that returns true if the weight of the specified ring is greater than or equal to the specified minWeight threshold. If minWeight is not specified, it defaults to Number.MIN_VALUE. If weight is not specified, it defaults to planarRingArea.

# filter(ring, interior)

To filter a topology, you supply a ring filter function to filter. The filter function is invoked for each ring in the input topology, being passed two arguments: the ring, specified as an array of points where each point is a two-element array of numbers, and the interior flag. If interior is false, the given ring is the exterior ring of a polygon; if interior is true, the given ring is an interior ring (a hole). The filter function must then return true if the ring should be preserved, or false if the ring should be removed.

Geometry

# topojson.planarRingArea(ring) <>

Returns the planar area of the specified ring, which is an array of points [[x₀, y₀], [x₁, y₁], …]. The first point must be equal to the last point. This implementation is agnostic to winding order; the returned value is always non-negative.

# topojson.planarTriangleArea(triangle) <>

Returns the planar area of the specified triangle, which is an array of three points [[x₀, y₀], [x₁, y₁], [x₂, y₂]]. This implementation is agnostic to winding order; the returned value is always non-negative.

# topojson.sphericalRingArea(ring, interior) <>

Returns the spherical area of the specified ring, which is an array of points [[x₀, y₀], [x₁, y₁], …] where x and y represent longitude and latitude in degrees, respectively. The first point must be equal to the last point.

This implementation uses d3-geo’s winding order convention to determine which side of the polygon is the inside: polygons smaller than a hemisphere must be clockwise, while polygons larger than a hemisphere must be anticlockwise. If interior is true, the opposite winding order is used. This winding order convention is also used by ESRI shapefiles; however, it is the opposite convention of GeoJSON’s RFC 7946.

# topojson.sphericalTriangleArea(triangle) <>

Returns the spherical excess of the specified triangle, which is an array of three points [[x₀, y₀], [x₁, y₁], [x₂, y₂]] where x and y represent longitude and latitude in degrees, respectively. This implementation uses the same winding order convention as sphericalRingArea.

Command Line Reference

toposimplify

# toposimplify [options…] [file] <>

Given an input topology, assigns a z-value to every arc coordinate according to a configurable weight function, and then generates an output topology where every arc coordinate whose z-value is lower than a configurable minimum weight is removed. Only the x and y dimensions of the coordinates are preserved in the returned topology. See also presimplify, simplify and filter.

# toposimplify -h
# toposimplify --help

Output usage information.

# toposimplify -V
# toposimplify --version

Output the version number.

# toposimplify -o file
# toposimplify --out file

Specify the output TopoJSON file name. Defaults to “-” for stdout.

# toposimplify -p value
# toposimplify --planar-area value

Specify simplification threshold value as the minimum planar triangle area, typically in square pixels.

# toposimplify -P value
# toposimplify --planar-quantile value

Specify simplification threshold value as the minimum quantile of planar triangle areas. The value should be in the range [0, 1].

# toposimplify -s value
# toposimplify --spherical-area value

Specify simplification threshold value as the minimum spherical triangle area (spherical excess), in steradians.

# toposimplify -S value
# toposimplify --spherical-quantile value

Specify simplification threshold value as the minimum quantile of spherical triangle areas (spherical excess). The value should be in the range [0, 1].

# toposimplify -f
# toposimplify --filter-detached

Remove detached rings that are smaller than the simplification threshold after simplifying. See filterAttached.

# toposimplify -F
# toposimplify --filter-all

Remove any rings that are smaller than the simplification threshold after simplifying. See filterWeight.