Gathering detailed insights and metrics for d3-voronoi-map
Installations
npm install d3-voronoi-mapDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Node Version
14.15.5
NPM Version
6.14.11
Score
99.5
Supply Chain
100
Quality
75.8
Maintenance
100
Vulnerability
100
License
Releases
10
Contributors
3
Unable to fetch Contributors
Languages
1
JavaScript
JavaScript (100%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
Kcnarf
Download Statistics
Total Downloads
3,933,116
Last Day
14,452
Last Week
75,049
Last Month
330,843
Last Year
2,995,497
GitHub Statistics
BSD-3-Clause License
91 Stars
146 Commits
14 Forks
2 Watchers
2 Branches
3 Contributors
Updated on Nov 25, 2024
Bundle Size
38.28 kB
Minified
12.24 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
2.1.1
Package Id
d3-voronoi-map@2.1.1
Unpacked Size
689.22 kB
Size
586.91 kB
File Count
24
NPM Version
6.14.11
Node Version
14.15.5
Total Downloads
Cumulative downloads
Total Downloads
3,933,116
Last Day
8.3%
14,452
Compared to previous day
Last Week
5.6%
75,049
Compared to previous week
Last Month
43.4%
330,843
Compared to previous month
Last Year
231.4%
2,995,497
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
4
d3-voronoi-map
This D3 plugin produces a Voronoï map (i.e. one-level treemap). Given a convex polygon and weighted data, it tesselates/partitions the polygon in several inner cells, such that the area of a cell represents the weight of the underlying datum.
Because a picture is worth a thousand words:
Available for d3 v4, d3 v5 and d3 v6.
If you're interested on multi-level treemap, which handle nested/hierarchical data, take a look at the d3-voronoi-treemap plugin.
Context
D3 already provides a d3-treemap module which produces a rectangular treemap. Such treemaps could be distorted to fit shapes that are not rectangles (cf. Distorded Treemap - d3-shaped treemap).
This plugin allows to compute a map with a unique look-and-feel, where inner areas are not strictly aligned each others, and where the outer shape can be any hole-free convex polygons (square, rectangle, pentagon, hexagon, ... any regular convex polygon, and also any non regular hole-free convex polygon).
The computation of the Voronoï map is based on a iteration/looping process. Hence, obtaining the final partition requires some iterations/some times, depending on the number and type of data/weights, the desired representativeness of cell areas.
As the d3-force layout does, this module can be used in two ways :
- live Voronoï map: displays the evolution of the self-organizing Voronoï map; each iteration is displayed, with some delay between iterations so that the animation is appealing to human eyes;
- static Voronoï map: displays only the final most representative Voronoï map, which is faster than the live use case; intermediate iterations are silently computed, one after each other, without any delay.
The rest of this README gives some implementatiton details and example on these two use cases.
Examples
-
Real life use cases
- Democratic Primaries: Preferential Poll Results by Nadieh Bremer in Swayable, with animated Voronoï maps (more details at https://www.visualcinnamon.com/portfolio/swayable-preferential-polling)
- The Battleground States Biden and Trump Need to Win 270 by in The New York Times, with interactive and playful Voronoï maps
- Land of colors by Tristan Guillevin in Tableau, with small multiples Voronoï maps
-
Examples with available code
- The Individual Costs of Being Obese in the U.S. (2010), a remake of HowMuch.net's post
- a simple example explains how to switch from a live arrangement to a static arrangement
- a simple example and Global Population by Region by 1950 to 2100 - a remake explain how to update and animate an existing arrangement
Installing
If you use NPM, npm install d3-voronoi-map and import it with
1import { voronoiMapSimulation } from 'd3-voronoi-map';
Otherwise, load https://rawcdn.githack.com/Kcnarf/d3-voronoi-map/v2.1.1/build/d3-voronoi-map.js (or its d3-voronoi-map.min.js version) to make it available in AMD, CommonJS, or vanilla environments. In vanilla, you must load the d3-weighted-voronoi plugin prior to this one, and a d3 global is exported:
1<script src="https://d3js.org/d3.v6.min.js"></script> 2<script src="https://rawcdn.githack.com/Kcnarf/d3-weighted-voronoi/v1.1.3/build/d3-weighted-voronoi.js"></script> 3<script src="https://rawcdn.githack.com/Kcnarf/d3-voronoi-map/v2.1.1/d3-voronoi-map.js"></script> 4<script> 5 var simulation = d3.voronoiMapSimulation(data); 6</script>
If you're interested in the latest developments, you can use the master build, available throught:
1<script src="https://raw.githack.com/Kcnarf/d3-voronoi-map/master/build/d3-voronoi-map.js"></script>
TL;DR;
In your javascript, if you want to display a live Voronoï map (i.e. displays the evolution of the self-organizing Voronoï map) :
1var simulation = d3.voronoiMapSimulation(data) 2 .weight(function(d){ return weightScale(d); } // set the weight accessor 3 .clip([[0,0], [0,height], [width, height], [width,0]]) // set the clipping polygon 4 .on ("tick", ticked); // function 'ticked' is called after each iteration 5 6function ticked() { 7 var state = simulation.state(), // retrieve the simulation's state, i.e. {ended, polygons, iterationCount, convergenceRatio} 8 polygons = state.polygons, // retrieve polygons, i.e. cells of the current iteration 9 drawnCells; 10 11 drawnCells = d3.selectAll('path').data(polygons); // d3's join 12 drawnCells 13 .enter().append('path') // create cells at first render 14 .merge(drawnCells); // assigns appropriate shapes and colors 15 .attr('d', function(d) { 16 return cellLiner(d) + 'z'; 17 }) 18 .style('fill', function(d) { 19 return fillScale(d.site.originalObject); 20 }); 21}
Or, if you want to display only the static Voronoï map (i.e. display the final most representative arrangement):
1var simulation = d3.voronoiMapSimulation(data) 2 .weight(function(d){ return weightScale(d); } // set the weight accessor 3 .clip([[0,0], [0,height], [width, height], [width,0]]) // set the clipping polygon 4 .stop(); // immediately stops the simulation 5 6var state = simulation.state(); // retrieve the simulation's state, i.e. {ended, polygons, iterationCount, convergenceRatio} 7 8while (!state.ended) { // manually launch each iteration until the simulation ends 9 simulation.tick(); 10 state = simulation.state(); 11} 12 13var polygons = state.polygons; // retrieve polygons, i.e. cells of the final Voronoï map 14 15d3.selectAll('path').data(polygons); // d3's join 16 .enter() // create cells with appropriate shapes and colors 17 .append('path') 18 .attr('d', function(d) { 19 return cellLiner(d) + 'z'; 20 }) 21 .style('fill', function(d) { 22 return fillScale(d.site.originalObject); 23 });
Reference
- based on Computing Voronoï Treemaps - Faster, Simpler, and Resolution-independent
- https://github.com/ArlindNocaj/power-voronoi-diagram for a Java implementation
API
# d3.voronoiMapSimulation(data)
Creates a new simulation with the specified array of data, and the default accessors and configuration values (weight, clip, convergenceRatio, maxIterationCount, minWeightRatio, prng, initialPosition, and initialWeight).
The simulation starts automatically. For a live Voronoï map, use simulation.on to listen for tick events as the simulation runs, and end event when the simulation finishes. See also TL;DR; live Voronoï map.
For a static Voronoï map, call simulation.stop, and then call simulation.tick as desired. See also TL;DR; static Voronoï map.
# simulation.state()
Returns a hash of the current state of the simulation.
hash.polygons is a sparse array of polygons clipped to the clip-ping polygon, one for each cell (each unique input point) in the diagram. Each polygon is represented as an array of points [x, y] where x and y are the point coordinates, a site field that refers to its site (ie. with x, y and weight retrieved from the original data), and a site.originalObject field that refers to the corresponding element in data (specified in d3.voronoiMapSimulation(data)). Polygons are open: they do not contain a closing point that duplicates the first point; a triangle, for example, is an array of three points. Polygons are also counterclockwise (assuming the origin ⟨0,0⟩ is in the top-left corner).
Furthermore :
- the positive integer hash.iterationCount is the current iteration count;
- the floating number hash.convergenceRatio is the current convergence ratio (ie. cell area errors / area of the clip-ping polygon);
- the boolean hash.ended indicates if the current iteration is the final one, or if the simulation requires more iterations to complete.
# simulation.weight([weight])
If weight-accessor is specified, sets the weight accessor. If weight is not specified, returns the current weight accessor, which defaults to:
1function weight(d) { 2 return d.weight; 3}
# simulation.clip([clip])
If clip is specified, sets the clipping polygon, compute the adequate extent and size, and returns this layout. clip defines a hole-free convex polygon, and is specified as an array of 2D points [x, y], which must be (i) open (no duplication of the first D2 point) and (ii) counterclockwise (assuming the origin ⟨0,0⟩ is in the top-left corner). If clip is not specified, returns the current clipping polygon, which defaults to:
1[ 2 [0, 0], 3 [0, 1], 4 [1, 1], 5 [1, 0], 6];
# simulation.extent([extent])
If extent is specified, it is a convenient way to define the clipping polygon as a rectangle. It sets the extent, computes the adequate clipping polygon and size, and returns this layout. extent must be a two-element array of 2D points [x, y], which defines the clipping polygon as a rectangle with the top-left and bottom-right corners respectively set to the first and second points (assuming the origin ⟨0,0⟩ is in the top-left corner on the screen). If extent is not specified, returns the current extent, which is [[minX, minY], [maxX, maxY]] of current clipping polygon, and defaults to:
1[ 2 [0, 0], 3 [1, 1], 4];
# simulation.size([size])
If size is specified, it is a convenient way to define the clipping polygon as a rectangle. It sets the size, computes the adequate clipping polygon and extent, and returns this layout. size must be a two-element array of numbers [width, height], which defines the clipping polygon as a rectangle with the top-left corner set to [0, 0]and the bottom-right corner set to [width, height](assuming the origin ⟨0,0⟩ is in the top-left corner on the screen). If size is not specified, returns the current size, which is [maxX-minX, maxY-minY] of current clipping polygon, and defaults to:
1[1, 1];
# simulation.convergenceRatio([convergenceRatio])
If convergenceRatio is specified, sets the convergence ratio, which stops simulation when (cell area errors / (clip-ping polygon area) <= convergenceRatio. If convergenceRatio is not specified, returns the current convergenceRatio , which defaults to:
1var convergenceRation = 0.01; // stops computation when cell area error <= 1% clipping polygon's area
The smaller the convergenceRatio, the more representative is the final map, the longer the simulation takes time.
# simulation.maxIterationCount([maxIterationCount])
If maxIterationCount is specified, sets the maximum allowed number of iterations, which stops simulation when it is reached, even if the convergenceRatio is not reached. If maxIterationCount is not specified, returns the current maxIterationCount , which defaults to:
1var maxIterationCount = 50;
If you want to wait until simulation stops only when the convergenceRatio is reached, just set the maxIterationCount to a large amount. Be warned that simulation may take a huge amount of time, due to flickering behaviours in later iterations.
# simulation.minWeightRatio([minWeightRatio])
If minWeightRatio is specified, sets the minimum weight ratio, which allows to compute the minimum allowed weight (= maxWeight * minWeightRatio). If minWeightRatio is not specified, returns the current minWeightRatio , which defaults to:
1var minWeightRatio = 0.01; // 1% of maxWeight
minWeightRatio allows to mitigate flickerring behaviour (caused by too small weights), and enhances user interaction by not computing near-empty cells.
# simulation.prng([prng])
If prng is specified, sets the pseudorandom number generator which is used when randomness is required (e.g. in d3.voronoiMapInitialPositionRandom(), cf. initialPosition). The given pseudorandom number generator must implement the same interface as Math.random and must only return values in the range [0, 1[. If prng is not specified, returns the current prng , which defaults to Math.random.
prng allows to handle reproducibility. Considering the same set of data, severall Voronoï map computations lead to disctinct final arrangements, due to the non-seedable Math.random default number generator. If prng is set to a seedable pseudorandom number generator which produces repeatable outputs, then several computations will produce the exact same final arrangement. This is useful if you want the same arrangement for distinct page loads/reloads. For example, using seedrandom:
1<script src="//cdnjs.cloudflare.com/ajax/libs/seedrandom/2.4.3/seedrandom.min.js"></script> 2<script> 3 var myseededprng = new Math.seedrandom('my seed'); // (from seedrandom's doc) Use "new" to create a local pprng without altering Math.random 4 voronoiMap.prng(myseededprng); 5</script>
You can also take a look at d3-random for random number generator from other-than-uniform distributions.
# simulation.initialPosition([initialPosition])
If initialPosition is specified, sets the initial coordinate accessor. The accessor is a callback wich is passed the datum, its index, the array it comes from, and the current simulation. The accessor must provide an array of two numbers [x, y] inside the clipping polygon, otherwise a random initial position is used instead. If initialPosition is not specified, returns the current accessor, which defaults to a random position policy which insure to randomly pick a point inside the clipping polygon.
A custom accessor may look like:
1function precomputedInitialPosition(d, i, arr, simulation) {
2 return [d.precomputedX, d.precomputedY];
3}Furthermore, two predefined policies are available:
- the random policy, available through
d3.voronoiMapInitialPositionRandom(), which is the default intital position policy; it uses the specified prng, and may produce repeatable arrangement if a seeded random number generator is defined; - the pie-based policy, available through
d3.voronoiMapInitialPositionPie()which initializes positions of data along an inner circle of the clipping polygon, in an equaly distributed counterclockwise way (reverse your data to have a clockwise counterpart); the first datum is positioned at 0 radian (i.e. at right), but this can be customized through thed3.voronoiMapInitialPositionPie().startAngle(<yourFavoriteAngleInRad>)API; the name of this policy comes from the very first iteration which looks like a pie;
You can take a look at these policies to define your own complex initial position policies/accessors.
# voronoiMap.initialWeight([initialWeight])
If initialWeight is specified, sets the initial weight accessor. The accessor is a callback wich is passed the datum, its index, the array it comes from, and the current simulation. The accessor must provide a positive amount. If initialWeight is not specified, returns the current accessor, which defaults to initialize all sites with the same amount (which depends on the clipping polygon and the number of data):
A custom accessor may look like:
1function precomputedInitialWeight(d, i, arr, simulation) {
2 return d.precomputedWeight;
3}Furthermore, the default half average area policy is available through d3.voronoiMapInitialWeightHalfAverageArea().
Considering a unique clipping polygon where you want animate the same set of data but with evolving weights (e.g., animate according to passing time), this API combined with the initialPosition API allows you to maintain areas from one set to another:
- first, compute the Voronoï map of a first set of data
- then, compute the Voronoï map of another set of data, by initializing sites to the final values (positions and weights) of first Voronoï map
See Update and Animate a Voronooï map or Global Population by Region from 1950 to 2100 - a remake for live examples.
# simulation.stop()
Stops the simulation’s internal timer, if it is running, and returns the simulation. If the timer is already stopped, this method does nothing. This method is useful to display only a static Voronoï map. In such a case, you have to stop the simulation, and run it manually till its end with simulation.tick (see also TL;DR; static Voronoï map).
# simulation.tick()
If the simulation is not ended, computes a more representative Voronoï map by adapting the one of the previous iteration, and increments the current iteration count. If the simulation is ended, it does nothing.
This method does not dispatch events; events are only dispatched by the internal timer when the simulation is started automatically upon creation or by calling simulation.restart.
This method can be used in conjunction with simulation.stop to compute a static Voronoï map (see also TL;DR; static Voronoï map). For large graphs, static layouts should be computed in a web worker to avoid freezing the user interface.
# simulation.restart()
Restarts the simulation’s internal timer and returns the simulation. This method can be used to resume the simulation after temporarily pausing it with simulation.stop.
# simulation.on(typenames, [listener])
If listener is specified, sets the event listener for the specified typenames and returns this simulation. If an event listener was already registered for the same type and name, the existing listener is removed before the new listener is added. If listener is null, removes the current event listeners for the specified typenames, if any. If listener is not specified, returns the first currently-assigned listener matching the specified typenames, if any. When a specified event is dispatched, each listener will be invoked with the this context as the simulation.
The typenames is a string containing one or more typename separated by whitespace. Each typename is a type, optionally followed by a period (.) and a name, such as tick.foo and tick.bar; the name allows multiple listeners to be registered for the same type. The type must be one of the following:
- tick - after each tick of the simulation’s internal timer.
- end - after the simulation’s timer stops when alpha < alphaMin.
Note that tick events are not dispatched when simulation.tick is called manually when only displaying a [static] Voronoï map; events are only dispatched by the internal timer, and are intended for the live Voronoï map.
See dispatch.on for details.
Migrations
From v1.x.x to v2.x.x
In v1.x.x, the plugin only allows to compute a static Voronoï map. In order to maintain this behaviour with v2.x.x, your should update your code as it is described in TL;DR; static Voronoï map.
Regarding the API:
- all the APIs of v1.x.x are available in v2.x.x
- v2.x.x adds APIs related to the simulation (i.e. simulation.stop, simulation.tick, simulation.restart, simulation.on and simulation.state)
simulation.state().polygonsis the new way to retrieve cells.
Dependencies
- d3-dispatch.dispatch
- d3-polygon.{polygonArea, polygonCentroid, polygonContains}
- d3-timer.timer
- d3-weighted-voronoi.weightedVoronoi
Semantic Versioning
d3-voronoi-map attempts to follow semantic versioning and bump major version only when backwards incompatible changes are released.
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
no dangerous workflow patterns detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: BSD 3-Clause "New" or "Revised" License: LICENSE:0
Reason
2 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
Reason
Found 1/23 approved changesets -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/main.yml:1
- Info: no jobLevel write permissions found
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/Kcnarf/d3-voronoi-map/main.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/Kcnarf/d3-voronoi-map/main.yml/master?enable=pin
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
Project has not signed or included provenance with any releases.
Details
- Warn: release artifact v2.1.1 not signed: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/74280201
- Warn: release artifact v2.1.0 not signed: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/33546924
- Warn: release artifact v2.0.1 not signed: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/23033906
- Warn: release artifact v2.0.0 not signed: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/13217617
- Warn: release artifact v1.2.0 not signed: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/12395573
- Warn: release artifact v2.1.1 does not have provenance: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/74280201
- Warn: release artifact v2.1.0 does not have provenance: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/33546924
- Warn: release artifact v2.0.1 does not have provenance: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/23033906
- Warn: release artifact v2.0.0 does not have provenance: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/13217617
- Warn: release artifact v1.2.0 does not have provenance: https://api.github.com/repos/Kcnarf/d3-voronoi-map/releases/12395573
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 9 are checked with a SAST tool
Score
3
/10
Last Scanned on 2025-02-10
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More