# TopoJSON Simplify

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

For an introduction to line simplification:

## 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:

```
<script src="https://unpkg.com/topojson-client@3"></script>
<script src="https://unpkg.com/topojson-simplify@3"></script>
<script>
topology = topojson.presimplify(topology);
</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.