Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
https://github.com/Fil/d3-geo-voronoi

Voronoi / Delaunay tessellations on the sphere
https://github.com/Fil/d3-geo-voronoi
convex-hull d3 d3js delaunay-triangulation geospatial voronoi
Last synced: about 2 months ago
JSON representation
Voronoi / Delaunay tessellations on the sphere
Host: GitHub
URL: https://github.com/Fil/d3-geo-voronoi
Owner: Fil
License: isc
Created: 2016-09-07T20:39:43.000Z (almost 8 years ago)
Default Branch: main
Last Pushed: 2024-04-01T13:48:51.000Z (3 months ago)
Last Synced: 2024-04-18T13:23:24.812Z (2 months ago)
Topics: convex-hull, d3, d3js, delaunay-triangulation, geospatial, voronoi
Language: JavaScript
Homepage:
Size: 1.6 MB
Stars: 224
Watchers: 12
Forks: 24
Open Issues: 9
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists

awesome-d3 - d3-geo-voronoi - Voronoi diagrams and Delaunay triangulation for the sphere (Maps)
awesome-d3 - d3-geo-voronoi - Voronoi diagrams and Delaunay triangulation for the sphere (Maps)
awesome-d3 - d3-geo-voronoi - Voronoi diagrams and Delaunay triangulation for the sphere (Maps)
awesome-frontend-gis - d3-geo-voronoi - Voronoi diagrams and Delaunay triangulation for the sphere. (👨‍💻 JavaScript Libraries / Mapping)
README

        # d3-geo-voronoi

This module adapts [d3-delaunay](https://github.com/d3/d3-delaunay) for spherical data. Given a set of objects in spherical coordinates, it computes their Delaunay triangulation and its dual, the Voronoi diagram.

In addition, it offers convenience methods to extract the convex hull, the Urquhart graph, the circumcenters of the Delaunay triangles, and to find the cell that contains any given point on the sphere.

The module offers two APIs.

The GeoJSON API is the most convenient for drawing the results on a map. It follows as closely as possible the API of the [d3-voronoi](https://github.com/d3/d3-voronoi/) module. It is available with *d3.geoVoronoi()*.

A lighter API is available with *d3.geoDelaunay()*. It offers the same contents, but with a different presentation, where every vertex, edge, polygon… is referenced by an id rather than by its coordinates. This allows a more compact representation in memory and eases topology computations.

## Installing

If you use npm, `npm install d3-geo-voronoi`. You can also download the [latest release on GitHub](https://github.com/d3/d3-geo-voronoi/releases/latest). For vanilla HTML in modern browsers, import d3-geo-voronoi from Skypack:

```html

import {geoDelaunay} from "https://cdn.skypack.dev/d3-geo-voronoi@2";

```

For legacy environments, you can load d3-geo-voronoi’s UMD bundle from an npm-based CDN such as jsDelivr; a `d3` global is exported:

```html

d3.geoContour();

```

## API Reference

* [Delaunay](#delaunay)

* [Voronoi](#voronoi)

* [Contours](#contours)

### Delaunay

This API is a similar to [d3-delaunay](https://github.com/d3/d3-delaunay)’s API. It provides information on the Delaunay triangulation (edges, triangles, neighbors, Voronoi cells, etc) as indices in two arrays — the array of points, and the array of circumcenters. It facilitates topological computations. To draw the actual triangles, Voronoi cells etc, the [Voronoi](#Voronoi) API described in the next section will often be easier to use.

# d3.geoDelaunay([data])

 · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/delaunay.js)

Creates a new *spherical* Delaunay layout. _data_ must be passed as an array of [lon, lat] coordinates.

# delaunay.find(*lon*, *lat*[, *node*])

Returns the closest point to [lon, lat]; optionally starting the search at *node* to boost the performance.

# delaunay.urquhart([*distances*])

Given a vector of distances (in the same order as the edges list), returns a vector of boolean values: true if the edge belongs to the Urquhart graph, false otherwise.

[](https://observablehq.com/@fil/world-cities-urquhart)

# delaunay.hull()

Returns an array of indices of points on the hull. The array is empty if the points cover more than a hemisphere.

# delaunay.edges

An array of edges as indices of points [from, to].

[](https://observablehq.com/@manzt/world-airports-voronoi-in-vega-lite)

# delaunay.triangles

An array of the triangles, as indices of points [a, b, c]. The triangles are orientated in a clockwise manner, triangles that span more than the hemisphere are removed.

# delaunay.centers

The array of centers in spherical coordinates; the first *t* centers are the *t* triangles’s circumcenters. More centers might be listed in order to build the Voronoi diagram for smaller number of points (n≤3).

# delaunay.neighbors

The array of neighbors indices for each vertex.

[](https://observablehq.com/@mbostock/spherical-voronoi-coloring)

# delaunay.polygons

Array of Voronoi cells for each vertex. Each cell is an array of centers ordered in a clockwise manner.

# delaunay.mesh

An array containing all the edges of the Voronoi polygons.

### Voronoi

This API is a wrapper around the Delaunay API, with inputs and outputs in GeoJSON, ready to draw on a map.

# d3.geoVoronoi([data])

 · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/74295d9ffe097ae4e3c93d7d00377d45)

Creates a new *spherical* Voronoi layout. _data_ can be passed as an array of [lon, lat] coordinates, an array of GeoJSON features, or a GeoJSON FeatureCollection.

The following methods are similar to [d3-voronoi](https://github.com/d3/d3-voronoi/)'s methods:

# voronoi.delaunay

The geoDelaunay object used to compute this diagram. 

# voronoi.x([x])

Sets or returns the _x_ accessor. The default _x_ and _y_ accessors are smart enough to recognize GeoJSON objects and return the geoCentroid of each feature.

# voronoi.y([y])

Sets or returns the _y_ accessor.

[![](img/geoVoronoiXY.png)](https://bl.ocks.org/Fil/74295d9ffe097ae4e3c93d7d00377d45)

# voronoi.polygons([data]) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/a9ba8d0d023752aa580bd95480b7de60)

Returns the Voronoi tessellation of the data as a GeoJSON collection of polygons. (If there is only one data point, returns the Sphere). Each polygon exposes its datum in its properties.

[![](img/geoVoronoiPolygons.png)](https://bl.ocks.org/Fil/a9ba8d0d023752aa580bd95480b7de60)

# voronoi.cellMesh([data]) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js)

Returns the Voronoi tessellation as a GeoJSON mesh (MultiLineString).

# voronoi.triangles([data]) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/b1ef96e4bc991eb274f8d3a0a08932f9)

Returns the Voronoi tessellation of the data as a GeoJSON collection of polygons. Each triangle exposes in its properties the three sites, its spherical area (in steradians), and its circumcenter.

[![](img/geoVoronoiTriangles.png)](https://bl.ocks.org/Fil/b1ef96e4bc991eb274f8d3a0a08932f9)

[![](img/geoVoronoiRadome.png)](https://bl.ocks.org/Fil/955da86d6a935b26d3599ca5e344fb38)

# voronoi.mesh([data]) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/fbaf391e1ae252461741ccf401af5a10)

Returns the Delaunay edges [as a GeoJSON mesh](https://bl.ocks.org/Fil/fbaf391e1ae252461741ccf401af5a10) (MultiLineString).

# voronoi.links([data]) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/1a78acf8b9b40fe8ecbae7b5035acf2b)

Returns the Delaunay links of the data as a GeoJSON collection of lines. Each line exposes its source and target in its properties, but also its length (in radians), and a boolean flag for links that belong to the [Urquhart graph](https://en.wikipedia.org/wiki/Urquhart_graph).

[![](img/geoVoronoiUrquhart.png)](https://bl.ocks.org/Fil/1a78acf8b9b40fe8ecbae7b5035acf2b)

[![](img/geoVoronoiCircumcircles.png)](https://bl.ocks.org/Fil/79b9f17979c4070dee3cbba1c5283502)

[![](img/geoVoronoiMars.png)](https://bl.ocks.org/Fil/1c2f954201523af16280db018ddd90cc)

voronoi.extent([extent]) and voronoi.size([size]) are not implemented.

Indeed, defining the “paper extent” of the geoVoronoi polygons can be quite tricky, [as this block demonstrates](https://bl.ocks.org/Fil/6128aae082c04eef06422f953d0f593f).

# voronoi.find(x,y,[angle]) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/e94fc45f5ed4dbcc989be1e52b797fdd)

Finds the closest site to point *x,y*, i.e. the Voronoi polygon that contains it. Optionally, return null if the distance between the point and the site is larger than *angle* degrees.

[![](img/geoVoronoiFind.png)](https://bl.ocks.org/Fil/e94fc45f5ed4dbcc989be1e52b797fdd)

# voronoi.hull(data) · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/voronoi.js), [Examples](https://bl.ocks.org/Fil/6a1ed09f6e5648a5451cb130f2b13d20)

Returns the spherical convex hull of the *data* array, as a GeoJSON polygon. Returns null if the dataset spans more than a hemisphere. Equivalent to:

```js

voronoi(data).hull();

```

[![](img/geoVoronoiHull.png)](https://bl.ocks.org/Fil/6a1ed09f6e5648a5451cb130f2b13d20)

### Contours

Create *spherical* contours for non-gridded data.

The API of geoContour is similar to that of [d3-contour](https://github.com/d3/d3-contour) and [d3-tricontour](https://github.com/Fil/d3-tricontour):

# d3.geoContour()

 · [Source](https://github.com/Fil/d3-geo-voronoi/blob/main/src/contour.js), [Examples](https://observablehq.com/collection/@fil/tricontours)

Constructs a new geocontour generator with the default settings.

[](https://observablehq.com/@fil/spherical-contours)

# _geocontour_(_data_) · [Examples](https://observablehq.com/@fil/tricontours)

Returns an array of contours, one for each threshold. The contours are MultiPolygons in GeoJSON format, that contain all the points with a value larger than the threshold. The value is indicated as _geometry_.value.

The _data_ is passed as an array of points, by default with the format [lon, lat, value].

# _geocontour_.contour(_data_[, _threshold_])

Returns a contour, as a MultiPolygon in GeoJSON format, containing all points with a value larger or equal to _threshold_. The threshold is indicated as _geometry_.value 

# _geocontour_.contours(_data_)

Returns an iterable over the contours.

[](https://observablehq.com/@fil/spherical-contours-iterator)

# _geocontour_.isobands(_data_)

Returns an iterable over the isobands: contours between pairs of consecutive threshold values _v0_ (inclusive) and _v1_ (exclusive). _geometry_.value is equal to _v0_, _geometry_.valueMax to _v1_.

[](https://observablehq.com/@fil/spherical-isobands)

# _geocontour_.x([_x_])

Sets the *x* (longitude) accessor. Defaults to \`d => d[0]\`. If _x_ is not given, returns the current x accessor.

# _geocontour_.y([_y_])

Sets the *y* (latitude) accessor. Defaults to \`d => d[1]\`. If _y_ is not given, returns the current y accessor.

# _geocontour_.value([_value_])

Sets the *value* accessor. Defaults to \`d => d[2]\`. Values must be defined and finite. If _value_ is not given, returns the current value accessor.

[](https://observablehq.com/@fil/blurry-contours)

[](https://observablehq.com/@fil/h3-hexagons-geocontours)

#  _geocontour_.thresholds([_thresholds_])

Sets the thresholds, either explicitly as an array of values, or as a count that will be passed to d3.ticks. If empty, returns the current thresholds.

_Note:_ d3.geoContour uses the experimental API of d3-tricontour: [triangulate](https://github.com/Fil/d3-tricontour/blob/main/README.md#triangulate), [pointInterpolate](https://github.com/Fil/d3-tricontour/blob/main/README.md#pointInterpolate) and [ringsort](https://github.com/Fil/d3-tricontour/blob/main/README.md#ringsort).

### Other tools & projections

There is no reason to limit the display of Voronoi cells to the orthographic projection. The example below displays the Urquhart graph of top container ports on a Winkel tripel map.

[![](img/geoVoronoiPorts.png)](https://bl.ocks.org/Fil/24d5ee71f09ba72893323d803242c38a)

[Geo_triangulate](https://jessihamel.github.io/geo_triangulate/) converts GeoJSON to triangles for 3d rendering.

### Comparison with planar Voronoi Diagrams

- the Delaunay/Voronoi topology is quite different on the sphere and on the plane. This module deals with these differences by first projecting the points with a stereographic projection, then stitching the geometries that are near the singularity of the projection (the “infinite horizon” on the plane is one point on the sphere).

- geoVoronoi returns GeoJSON objects, which are often `FeatureCollections`. By consequence, you will have to change `.data(voronoi.polygons())` to `.data(geovoronoi.polygons().features)`, and so on.

- geoVoronoi is built on [d3-delaunay](https://github.com/d3/d3-delaunay), which is also exposed as d3.geoDelaunay in this library. If you want to have the fastest results, you should try to use d3.geoDelaunay directly (see the examples).

- geoVoronoi and geoDelaunay offer methods to compute the spherical [convex hull](#geo_voronoi_hull) and the [Urquhart graph](#geo_voronoi_links) of the data set. These can be achieved with the planar Voronoi ([hull](https://bl.ocks.org/mbostock/6f14f7b7f267a85f7cdc), [Urquhart](https://bl.ocks.org/Fil/df20827f817abd161c768fa18dcafcf5)), but are not part of d3-voronoi or d3-delaunay.