Repository files navigation

This library computes contour polygons by applyingmarching squares to a rectangular array of numeric values. For example, here is Maungawhau’s topology (the classicvolcano dataset andterrain.colors from R):

For eachthreshold value, thecontour generator constructs a GeoJSON MultiPolygon geometry object representing the area where the input values are greater than or equal to the threshold value. The geometry is in planar coordinates, where ⟨i + 0.5,j + 0.5⟩ corresponds to elementi +jn in the input values array. Here is an example that loads a GeoTIFF of surface temperatures, and another that blurs a noisy monochrome PNG to produce smooth contours of cloud fraction:

Since the contour polygons are GeoJSON, you can transform and display them using standard tools; seed3.geoPath,d3.geoProject andd3.geoStitch, for example. Here the above contours of surface temperature are displayed in the Natural Earth projection:

Contour plots can also visualize continuous functions by sampling. Here is the Goldstein–Price function (a test function for global optimization) and a trippy animation ofsin(x +y)sin(x -y):

Contours can also show theestimated density of point clouds, which is especially useful to avoid overplotting in large datasets. This library implements fast two-dimensional kernel density estimation; seed3.contourDensity. Here is a scatterplot showing the relationship between the idle duration and eruption duration for Old Faithful:

And here is a density contour plot showing the relationship between the weight and price of 53,940 diamonds:

If you use NPM,npm install d3-contour. Otherwise, download thelatest release. You can also load directly fromd3js.org, either as astandalone library or as part ofD3 4.0. AMD, CommonJS, and vanilla environments are supported. In vanilla, ad3 global is exported:

<scriptsrc="https://d3js.org/d3-contour.v1.min.js"></script><script>// Populate a grid of n×m values where -2 ≤ x ≤ 2 and -2 ≤ y ≤ 1.varn=256,m=256,values=newArray(n*m);for(varj=0.5,k=0;j<m;++j){for(vari=0.5;i<n;++i,++k){values[k]=goldsteinPrice(i/n*4-2,1-j/m*3);}}// Compute the contour polygons at log-spaced intervals; returns an array of MultiPolygon.varcontours=d3.contours().size([n,m]).thresholds(d3.range(2,21).map(p=>Math.pow(2,p)))(values);// See https://en.wikipedia.org/wiki/Test_functions_for_optimizationfunctiongoldsteinPrice(x,y){return(1+Math.pow(x+y+1,2)*(19-14*x+3*x*x-14*y+6*x*x+3*y*y))*(30+Math.pow(2*x-3*y,2)*(18-32*x+12*x*x+48*y-36*x*y+27*y*y));}</script>

# d3.contours()<>

Constructs a new contour generator with the default settings.

#contours(values)<>

Computes the contours for the given array ofvalues, returning an array ofGeoJSONMultiPolygongeometry objects. Each geometry object represents the area where the inputvalues are greater than or equal to the correspondingthreshold value; the threshold value for each geometry object is exposed asgeometry.value.

The inputvalues must be an array of lengthn×m where [n,m] is the contour generator’ssize; furthermore, eachvalues[i +jn] must represent the value at the position ⟨i,j⟩. For example, to construct a 256×256 grid for theGoldstein–Price function where -2 ≤x ≤ 2 and -2 ≤y ≤ 1:

varn=256,m=256,values=newArray(n*m);for(varj=0.5,k=0;j<m;++j){for(vari=0.5;i<n;++i,++k){values[k]=goldsteinPrice(i/n*4-2,1-j/m*3);}}functiongoldsteinPrice(x,y){return(1+Math.pow(x+y+1,2)*(19-14*x+3*x*x-14*y+6*x*x+3*y*y))*(30+Math.pow(2*x-3*y,2)*(18-32*x+12*x*x+48*y-36*x*y+27*y*y));}

The returned geometry objects are typically passed tod3.geoPath to display, using null ord3.geoIdentity as the associated projection.

#contours.contour(values,threshold)<>

Computes a single contour, returning aGeoJSONMultiPolygongeometry object representing the area where the inputvalues are greater than or equal to the giventhreshold value; the threshold value for each geometry object is exposed asgeometry.value.

The inputvalues must be an array of lengthn×m where [n,m] is the contour generator’ssize; furthermore, eachvalues[i +jn] must represent the value at the position ⟨i,j⟩. Seecontours for an example.

#contours.size([size])<>

Ifsize is specified, sets the expected size of the inputvalues grid to thecontour generator and returns the contour generator. Thesize is specified as an array [n,m] wheren is the number of columns in the grid andm is the number of rows;n andm must be positive integers. Ifsize is not specified, returns the current size which defaults to [1, 1].

#contours.smooth([smooth])<>

Ifsmooth is specified, sets whether or not the generated contour polygons are smoothed using linear interpolation. Ifsmooth is not specified, returns the current smoothing flag, which defaults to true.

#contours.thresholds([thresholds])<>

Ifthresholds is specified, sets the threshold generator to the specified function or array and returns this contour generator. Ifthresholds is not specified, returns the current threshold generator, which by default implementsSturges’ formula.

Thresholds are defined as an array of values [x0,x1, …]. The firstgenerated contour corresponds to the area where the input values are greater than or equal tox0; the second contour corresponds to the area where the input values are greater than or equal tox1, and so on. Thus, there is exactly one generated MultiPolygon geometry object for each specified threshold value; the threshold value is exposed asgeometry.value.

If acount is specified instead of an array ofthresholds, then the input values’extent will be uniformly divided into approximatelycount bins; seed3.ticks.

# d3.contourDensity()<>

Constructs a new density estimator with the default settings.

#density(data)<>

Estimates the density contours for the given array ofdata, returning an array ofGeoJSONMultiPolygongeometry objects. Each geometry object represents the area where the estimated number of points per square pixel is greater than or equal to the correspondingthreshold value; the threshold value for each geometry object is exposed asgeometry.value. The returned geometry objects are typically passed tod3.geoPath to display, using null ord3.geoIdentity as the associated projection. See alsod3.contours.

Thex- andy-coordinate for each data point are computed usingdensity.x anddensity.y. In addition,density.weight indicates the relative contribution of each data point (default 1). The generated contours are only accurate within the estimator’sdefined size.

#density.x([x])<>

Ifx is specified, sets thex-coordinate accessor. Ifx is not specified, returns the currentx-coordinate accessor, which defaults to:

functionx(d){returnd[0];}

#density.y([y])<>

Ify is specified, sets they-coordinate accessor. Ify is not specified, returns the currenty-coordinate accessor, which defaults to:

functiony(d){returnd[1];}

#density.weight([weight])<>

Ifweight is specified, sets the accessor for point weights. Ifweight is not specified, returns the current point weight accessor, which defaults to:

functionweight(){return1;}

#density.size([size])<>

Ifsize is specified, sets the size of the density estimator to the specified bounds and returns the estimator. Thesize is specified as an array [width,height], wherewidth is the maximumx-value andheight is the maximumy-value. Ifsize is not specified, returns the current size which defaults to [960, 500]. Theestimated density contours are only accurate within the defined size.

#density.cellSize([cellSize])<>

IfcellSize is specified, sets the size of individual cells in the underlying bin grid to the specified positive integer and returns the estimator. IfcellSize is not specified, returns the current cell size, which defaults to 4. The cell size is rounded down to the nearest power of two. Smaller cells produce more detailed contour polygons, but are more expensive to compute.

#density.thresholds([thresholds])<>

Ifthresholds is specified, sets the threshold generator to the specified function or array and returns this contour generator. Ifthresholds is not specified, returns the current threshold generator, which by default generates about twenty nicely-rounded density thresholds.

Thresholds are defined as an array of values [x0,x1, …]. The firstgenerated density contour corresponds to the area where the estimated density is greater than or equal tox0; the second contour corresponds to the area where the estimated density is greater than or equal tox1, and so on. Thus, there is exactly one generated MultiPolygon geometry object for each specified threshold value; the threshold value is exposed asgeometry.value. The first valuex0 should typically be greater than zero.

If acount is specified instead of an array ofthresholds, then approximatelycount uniformly-spaced nicely-rounded thresholds will be generated; seed3.ticks.

#density.bandwidth([bandwidth])<>

Ifbandwidth is specified, sets the bandwidth (the standard deviation) of the Gaussian kernel and returns the estimate. Ifbandwidth is not specified, returns the current bandwidth, which defaults to 20.4939…. The specifiedbandwidth is currently rounded to the nearest supported value by this implementation, and must be nonnegative.