d4_shape library

Visualizations can be represented by discrete graphical marks such as symbols, arcs, lines, and areas. While the rectangles of a bar chart may sometimes be simple, other shapes are complex, such as rounded annular sectors and Catmull–Rom splines. The d4_shape package provides a variety of shape generators for your convenience.

As with other aspects of D4, these shapes are driven by data: each shape generator exposes accessors that control how the input data are mapped to a visual representation. For example, you might define a line generator for a time series by scaling fields of your data to fit the chart:

final line = Line(
  (d, i, data) => x(d["date"]),
  (d, i, data) => y(d["value"]),
);

This line generator can then be used to compute the d attribute of an SVG path element:

path.datum(data).attr("d", line);

Or you can use it to render to a Canvas 2D context:

line.context(context)(data);

Classes

Arc Arcs: The arc generator produces a circular or annular sector, as in a pie or donut chart.
Area<T> Areas: The area generator produces an area defined by a topline and a baseline as in an area chart.
AreaRadial<T> Radial areas: A radial area generator is like the Cartesian area generator except the Area.x and Area.y accessors are replaced with angle and radius accessors.
Curve Curves: Curves are typically not used directly, instead being passed to Line.curve and Area.curve. However, you can define your own curve implementation should none of the built-in curves satisfy your needs using the following interface; see the curveLinear source for an example implementation.
Line<T> Lines: The line generator produces a spline or polyline as in a line chart.
LineRadial<T> Radial lines: A radial line generator is like the Cartesian line generator except the Line.x and Line.y accessors are replaced with angle and radius accessors.
Link<T> Links: The link shape generates a smooth cubic Bézier curve from a source point to a target point.
LinkRadial<T> Radial links: A radial link generator is like the Cartesian link generator except the Link.x and Link.y accessors are replaced with angle and radius accessors.
Pie<T> Pies: The pie generator computes the necessary angles to represent a tabular dataset as a pie or donut chart; these angles can then be passed to an arc generator. (The pie generator does not produce a shape directly.)
Stack<K, T> Stacks: Stacking converts lengths into contiguous position intervals.
StackTidy<KL, KG, T> Stacks: Equivalent to Stack, except that it is designed to work with tidy data.
Symbol Symbols: Symbols provide a categorical shape encoding as in a scatterplot.
SymbolAsterisk Symbols: The asterisk symbol type; intended for stroking.
SymbolCircle Symbols: The circle symbol type; intended for either filling or stroking.
SymbolCross Symbols: The Greek cross symbol type, with arms of equal length; intended for filling.
SymbolDiamond Symbols: The rhombus symbol type; intended for filling.
SymbolDiamond2 Symbols: The rotated square symbol type; intended for stroking.
SymbolPlus Symbols: The plus symbol type; intended for stroking.
SymbolSquare Symbols: The square symbol type; intended for filling.
SymbolSquare2 Symbols: The square2 symbol type; intended for stroking.
SymbolStar Symbols: The pentagonal star (pentagram) symbol type; intended for filling.
SymbolTimes Symbols: The X-shape symbol type; intended for stroking.
SymbolTriangle Symbols: The up-pointing triangle symbol type; intended for filling.
SymbolTriangle2 Symbols: The up-pointing triangle symbol type; intended for stroking.
SymbolType Symbols: Symbol types are typically not used directly, instead being passed to Symbol.type. However, you can define your own symbol type implementation should none of the built-in types satisfy your needs using the following interface.
SymbolWye Symbols: The Y-shape symbol type; intended for filling.

Constants

symbols → const List<SymbolType> Symbols: Equivalent to symbolsFill.
symbolsFill → const List<SymbolType> Symbols: An list containing a set of symbol types designed for filling: SymbolCircle, SymbolCross, SymbolDiamond, SymbolSquare, SymbolStar, SymbolTriangle, and SymbolWye. Useful for a categorical shape encoding with an ordinal scale.
symbolsStroke → const List<SymbolType> Symbols: An list containing a set of symbol types designed for stroking: SymbolCircle, SymbolPlus, SymbolTimes, SymbolTriangle2, SymbolAsterisk, SymbolSquare2, and SymbolDiamond2. Useful for a categorical shape encoding with an ordinal scale.

Functions

curveBasis(Path context) → Curve Curves: Produces a cubic basis spline using the specified control points.
curveBasisClosed(Path context) → Curve Curves: Produces a closed cubic basis spline using the specified control points.
curveBasisOpen(Path context) → Curve Curves: Produces a cubic basis spline using the specified control points.
curveBumpX(Path context) → Curve Curves: Produces a Bézier curve between each pair of points, with horizontal tangents at each point.
curveBumpY(Path context) → Curve Curves: Produces a Bézier curve between each pair of points, with vertical tangents at each point.
curveBundle(Path context) → Curve Curves: Produces a straightened cubic basis spline using the specified control points, with the spline straightened according to the curve’s beta (see curveBundleBeta), which defaults to 0.85.
curveBundleBeta(num beta) → CurveFactory Curves: Returns a bundle curve with the specified beta in the range [0, 1], representing the bundle strength.
curveCardinal(Path context) → Curve Curves: Produces a cubic cardinal spline using the specified control points, with one-sided differences used for the first and last piece.
curveCardinalClosed(Path context) → Curve Curves: Produces a closed cubic cardinal spline using the specified control points. When a line segment ends, the first three control points are repeated, producing a closed loop.
curveCardinalClosedTension(num tension) → CurveFactory Curves: Equivalent to curveCardinalTension, but returns a curveCardinalClosed.
curveCardinalOpen(Path context) → Curve Curves: Produces a cubic cardinal spline using the specified control points.
curveCardinalOpenTension(num tension) → CurveFactory Curves: Equivalent to curveCardinalTension, but returns a curveCardinalOpen.
curveCardinalTension(num tension) → CurveCardinal Function(Path) Curves: Returns a cardinal curve with the specified tension in the range [0, 1].
curveCatmullRom(Path context) → Curve Curves: Produces a cubic Catmull–Rom spline using the specified control points and the parameter alpha (see curveCatmullRomAlpha), which defaults to 0.5, as proposed by Yuksel et al. in On the Parameterization of Catmull–Rom Curves, with one-sided differences used for the first and last piece.
curveCatmullRomAlpha(num alpha) → CurveFactory Curves: Returns a cubic Catmull–Rom curve with the specified alpha in the range [0, 1].
curveCatmullRomClosed(Path context) → Curve Curves: Produces a closed cubic Catmull–Rom spline using the specified control points and the parameter alpha (see curveCatmullRomClosedAlpha), which defaults to 0.5, as proposed by Yuksel et al.
curveCatmullRomClosedAlpha(num alpha) → CurveFactory Curves: Equivalent to curveCatmullRomAlpha, but returns a curveCatmullRomClosed.
curveCatmullRomOpen(Path context) → Curve Curves: Produces a cubic Catmull–Rom spline using the specified control points and the parameter alpha (see curveCatmullRomClosedAlpha), which defaults to 0.5, as proposed by Yuksel et al.
curveCatmullRomOpenAlpha(num alpha) → CurveFactory Curves: Equivalent to curveCatmullRomAlpha, but returns a curveCatmullRomOpen.
curveLinear(Path context) → Curve Curves: Produces a polyline through the specified points.
curveLinearClosed(Path context) → Curve Curves: Produces a closed polyline through the specified points by repeating the first point when the line segment ends.
curveMonotoneX(Path context) → Curve Curves: Produces a cubic spline that preserves monotonicity in y, assuming monotonicity in x, as proposed by Steffen in A simple method for monotonic interpolation in one dimension: “a smooth curve with continuous first-order derivatives that passes through any given set of data points without spurious oscillations.
curveMonotoneY(Path context) → Curve Curves: Produces a cubic spline that preserves monotonicity in x, assuming monotonicity in y, as proposed by Steffen in A simple method for monotonic interpolation in one dimension: “a smooth curve with continuous first-order derivatives that passes through any given set of data points without spurious oscillations.
curveNatural(Path context) → Curve Curves: Produces a natural cubic spline with the second derivative of the spline set to zero at the endpoints.
curveStep(Path context) → Curve Curves: Produces a piecewise constant function (a step function) consisting of alternating horizontal and vertical lines.
curveStepAfter(Path context) → Curve Curves: Produces a piecewise constant function (a step function) consisting of alternating horizontal and vertical lines.
curveStepBefore(Path context) → Curve Curves: Produces a piecewise constant function (a step function) consisting of alternating horizontal and vertical lines.
pointRadial(num angle, num radius) → List<num> Symbols: Returns the point [x, y] for the given angle in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise, and the given radius.
stackOffsetDiverging(List<List<List<num>>> series, List<int> order) → void Stack offsets Stacks: Positive values are stacked above zero, negative values are stacked below zero, and zero values are stacked at zero.
stackOffsetExpand(List<List<List<num>>> series, List<int> order) → void Stack offsets Stacks: Applies a zero baseline and normalizes the values for each point such that the topline is always one.
stackOffsetNone(List<List<List<num>>> series, List<int> order) → void Stack offsets Stacks: Applies a zero baseline.
stackOffsetSilhouette(List<List<List<num>>> series, List<int> order) → void Stack offsets Stacks: Shifts the baseline down such that the center of the streamgraph is always at zero.
stackOffsetWiggle(List<List<List<num>>> series, List<int> order) → void Stack offsets Stacks: Shifts the baseline so as to minimize the weighted wiggle of layers.
stackOrderAppearance(List<List<List<num>>> series) → List<int> Stack orders Stacks: Returns a series order such that the earliest series (according to the maximum value) is at the bottom.
stackOrderAscending(List<List<List<num>>> series) → List<int> Stack orders Stacks: Returns a series order such that the smallest series (according to the sum of values) is at the bottom.
stackOrderDescending(List<List<List<num>>> series) → List<int> Stack orders Stacks: Returns a series order such that the largest series (according to the sum of values) is at the bottom.
stackOrderInsideOut(List<List<List<num>>> series) → List<int> Stack orders Stacks: Returns a series order such that the earliest series (according to the maximum value) are on the inside and the later series are on the outside.
stackOrderNone(List<List<List<num>>> series) → List<int> Stack orders Stacks: Returns the given series order [0, 1, … n - 1] where n is the number of elements in series. Thus, the stack order is given by the key accessor (see Stack.keys).
stackOrderReverse(List<List<List<num>>> series) → List<int> Stack orders Stacks: Returns the reverse of the given series order [n - 1, n - 2, … 0] where n is the number of elements in series. Thus, the stack order is given by the reverse of the key accessor (see Stack.keys).

Typedefs

CurveFactory = Curve Function(Path context) Curves: The definition of a curve factory: given a context, returns a curve.
StackOffset = void Function(List<List<List<num>>>, List<int>) Stack offsets Stacks: The definition of a stack offset: given the generated series list and the order index list, it is then responsible for updating the lower and upper values in the series list.
StackOrder = Iterable<int> Function(List<List<List<num>>>) Stack orders Stacks: The definition of a stack order: given the generated series list, it must return an list of numeric indices representing the stack order.