d3/docs/d3-shape/arc.md

Arcs

The arc generator produces a circular or annular sector, as in a pie or donut chart. Arcs are centered at the origin; use a transform to move the arc to a different position.

svg.append("path")
    .attr("transform", "translate(100,100)")
    .attr("d", d3.arc()({
      innerRadius: 100,
      outerRadius: 200,
      startAngle: -Math.PI / 2,
      endAngle: Math.PI / 2
    }));

If the absolute difference between the start and end angles (the angular span) is greater than 2π, the arc generator will produce a complete circle or annulus. If it is less than 2π, the arc’s angular length will be equal to the absolute difference between the two angles (going clockwise if the signed difference is positive and anticlockwise if it is negative). If the absolute difference is less than 2π, the arc may have rounded corners and angular padding.

See also the pie generator, which computes the necessary angles to represent an array of data as a pie or donut chart; these angles can then be passed to an arc generator.

arc()

Source · Constructs a new arc generator with the default settings. With default settings:

const arc = d3.arc();

Or, with the radii and angles configured as constants:

const arc = d3.arc()
    .innerRadius(0)
    .outerRadius(100)
    .startAngle(0)
    .endAngle(Math.PI / 2);

arc(...arguments)

Source · Generates an arc for the given arguments. The arguments are arbitrary; they are propagated to the arc generator’s accessor functions along with the this object. For example, with the default settings, an object with radii and angles is expected:

const arc = d3.arc();

arc({
  innerRadius: 0,
  outerRadius: 100,
  startAngle: 0,
  endAngle: Math.PI / 2
}); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

If the radii and angles are instead defined as constants, you can generate an arc without any arguments:

d3.arc()
    .innerRadius(0)
    .outerRadius(100)
    .startAngle(0)
    .endAngle(Math.PI / 2)
  (); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

If the arc generator has a context, then the arc is rendered to this context as a sequence of path method calls and this function returns void. Otherwise, a path data string is returned.

arc.centroid(...arguments)

Examples · Source · Computes the midpoint [x, y] of the center line of the arc that would be generated by the given arguments.

The arguments are arbitrary; they are propagated to the arc generator’s accessor functions along with the this object. To be consistent with the generated arc, the accessors must be deterministic, i.e., return the same value given the same arguments. The midpoint is defined as (startAngle + endAngle) / 2 and (innerRadius + outerRadius) / 2. For example:

Note that this is not the geometric center of the arc, which may be outside the arc; this method is merely a convenience for positioning labels.

arc.innerRadius(radius)

Source · If radius is specified, sets the inner radius to the specified function or number and returns this arc generator.

const arc = d3.arc().innerRadius(40);

If radius is not specified, returns the current inner radius accessor.

arc.innerRadius() // () => 40

The inner radius accessor defaults to:

function innerRadius(d) {
  return d.innerRadius;
}

Specifying the inner radius as a function is useful for constructing a stacked polar bar chart, often in conjunction with a sqrt scale. More commonly, a constant inner radius is used for a donut or pie chart. If the outer radius is smaller than the inner radius, the inner and outer radii are swapped. A negative value is treated as zero.

arc.outerRadius(radius)

Source · If radius is specified, sets the outer radius to the specified function or number and returns this arc generator.

const arc = d3.arc().outerRadius(240);

If radius is not specified, returns the current outer radius accessor.

arc.outerRadius() // () => 240

The outer radius accessor defaults to:

function outerRadius(d) {
  return d.outerRadius;
}

Specifying the outer radius as a function is useful for constructing a coxcomb or polar bar chart, often in conjunction with a sqrt scale. More commonly, a constant outer radius is used for a pie or donut chart. If the outer radius is smaller than the inner radius, the inner and outer radii are swapped. A negative value is treated as zero.

arc.cornerRadius(radius)

Corner radius: {{cornerRadius.toFixed(0)}}

Examples · Source · If radius is specified, sets the corner radius to the specified function or number and returns this arc generator.

const arc = d3.arc().cornerRadius({{cornerRadius}});

If radius is not specified, returns the current corner radius accessor.

arc.cornerRadius() // () => {{cornerRadius}}

The corner radius accessor defaults to:

function cornerRadius() {
  return 0;
}

If the corner radius is greater than zero, the corners of the arc are rounded using circles of the given radius. For a circular sector, the two outer corners are rounded; for an annular sector, all four corners are rounded.

The corner radius may not be larger than (outerRadius - innerRadius) / 2. In addition, for arcs whose angular span is less than π, the corner radius may be reduced as two adjacent rounded corners intersect. This is occurs more often with the inner corners. See the arc corners animation for illustration.

arc.startAngle(angle)

Source · If angle is specified, sets the start angle to the specified function or number in radius and returns this arc generator.

const arc = d3.arc().startAngle(Math.PI / 4);

If angle is not specified, returns the current start angle accessor.

arc.startAngle() // () => 0.7853981633974483

The start angle accessor defaults to:

function startAngle(d) {
  return d.startAngle;
}

The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise. If |endAngle - startAngle| ≥ 2π, a complete circle or annulus is generated rather than a sector.

arc.endAngle(angle)

Source · If angle is specified, sets the end angle to the specified function or number and returns this arc generator.

const arc = d3.arc().endAngle(Math.PI);

If angle is not specified, returns the current end angle accessor.

arc.endAngle() // () => 3.141592653589793

The end angle accessor defaults to:

function endAngle(d) {
  return d.endAngle;
}

The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise. If |endAngle - startAngle| ≥ 2π, a complete circle or annulus is generated rather than a sector.

arc.padAngle(angle)

Pad angle: {{padAngle.toFixed(3)}}

Examples · Source · If angle is specified, sets the pad angle to the specified function or number and returns this arc generator.

const arc = d3.arc().padAngle(0);

If angle is not specified, returns the current pad angle accessor.

arc.padAngle() // () => 0

The pad angle accessor defaults to:

function padAngle() {
  return d && d.padAngle;
}

The pad angle is converted to a fixed linear distance separating adjacent arcs, defined as padRadius × padAngle. This distance is subtracted equally from the start and end of the arc. If the arc forms a complete circle or annulus, as when |endAngle - startAngle| ≥ 2π, the pad angle is ignored.

If the inner radius or angular span is small relative to the pad angle, it may not be possible to maintain parallel edges between adjacent arcs. In this case, the inner edge of the arc may collapse to a point, similar to a circular sector. For this reason, padding is typically only applied to annular sectors (i.e., when innerRadius is positive), as shown in this diagram:

The recommended minimum inner radius when using padding is outerRadius * padAngle / sin(θ), where θ is the angular span of the smallest arc before padding. For example, if the outer radius is 200 pixels and the pad angle is 0.02 radians, a reasonable θ is 0.04 radians, and a reasonable inner radius is 100 pixels. See the arc padding animation for illustration.

Often, the pad angle is not set directly on the arc generator, but is instead computed by the pie generator so as to ensure that the area of padded arcs is proportional to their value; see pie.padAngle. See the pie padding animation for illustration. If you apply a constant pad angle to the arc generator directly, it tends to subtract disproportionately from smaller arcs, introducing distortion.

arc.padRadius(radius)

Pad radius: {{padRadius.toFixed()}}

Source · If radius is specified, sets the pad radius to the specified function or number and returns this arc generator. If radius is not specified, returns the current pad radius accessor, which defaults to null, indicating that the pad radius should be automatically computed as sqrt(innerRadius × innerRadius + outerRadius × outerRadius). The pad radius determines the fixed linear distance separating adjacent arcs, defined as padRadius × padAngle.

arc.context(context)

Source · If context is specified, sets the context and returns this arc generator.

const context = canvas.getContext("2d");
const arc = d3.arc().context(context);

If context is not specified, returns the current context, which defaults to null.

arc.context() // context

If the context is not null, then the generated arc is rendered to this context as a sequence of path method calls. Otherwise, a path data string representing the generated arc is returned.

arc.digits(digits)

Source · If digits is specified, sets the maximum number of digits after the decimal separator and returns this arc generator.

const arc = d3.arc().digits(3);

If digits is not specified, returns the current maximum fraction digits, which defaults to 3.

arc.digits() // 3

This option only applies when the associated context is null, as when this arc generator is used to produce path data.