d3-path

What is d3-path?

The d3-path npm package is a part of the D3.js library and provides a way to create and manipulate SVG path elements. It offers a simple API to generate complex path data for SVG elements, which can be used for drawing shapes, lines, and curves in web applications.

What are d3-path's main functionalities?

Move To

The moveTo method sets the starting point of a new sub-path to the specified (x, y) coordinates.

const d3 = require('d3-path');
const path = d3.path();
path.moveTo(100, 100);
console.log(path.toString());

Line To

The lineTo method adds a straight line from the current point to the specified (x, y) coordinates.

const d3 = require('d3-path');
const path = d3.path();
path.moveTo(100, 100);
path.lineTo(200, 200);
console.log(path.toString());

Arc

The arc method creates an arc centered at (x, y) with the specified radius and start and end angles.

const d3 = require('d3-path');
const path = d3.path();
path.arc(150, 150, 50, 0, Math.PI / 2);
console.log(path.toString());

Bezier Curve

The bezierCurveTo method creates a cubic Bézier curve from the current point to the specified (x, y) coordinates using the specified control points.

const d3 = require('d3-path');
const path = d3.path();
path.moveTo(100, 100);
path.bezierCurveTo(150, 50, 200, 150, 250, 100);
console.log(path.toString());

Close Path

The closePath method closes the current sub-path by drawing a straight line back to the starting point.

const d3 = require('d3-path');
const path = d3.path();
path.moveTo(100, 100);
path.lineTo(200, 200);
path.closePath();
console.log(path.toString());

Other packages similar to d3-path

svg-pathdata

The svg-pathdata package provides tools to parse, transform, and serialize SVG path data. It offers more granular control over path data manipulation compared to d3-path, but it may require more effort to achieve the same results.

two.js

Two.js is a lightweight 2D drawing library for modern web browsers. It provides a higher-level API for creating and manipulating shapes, including paths, but it is not as focused on SVG path data manipulation as d3-path.

paper

Paper.js is an open-source vector graphics scripting framework that runs on top of the HTML5 Canvas. It offers a comprehensive set of tools for working with vector graphics, including path manipulation, but it is more complex and feature-rich compared to d3-path.

README

d3-path

Say you have some code that draws to a 2D canvas:

function drawCircle(context, radius) {
  context.moveTo(radius, 0);
  context.arc(0, 0, radius, 0, 2 * Math.PI);
}

The d3-path module lets you take this exact code and additionally render to SVG. It works by serializing CanvasPathMethods calls to SVG path data. For example:

var context = d3.path();
drawCircle(context, 40);
pathElement.setAttribute("d", context.toString());

Now code you write once can be used with both Canvas (for performance) and SVG (for convenience). For a practical example, see d3-shape.

Installing

If you use NPM, npm install d3-path. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3-path.v1.min.js"></script>
<script>

var path = d3.path();
path.moveTo(1, 2);
path.lineTo(3, 4);
path.closePath();

</script>

Try d3-path in your browser.

API Reference

# d3.path() <>

Constructs a new path serializer that implements CanvasPathMethods.

# path.moveTo(x, y) <>

Move to the specified point ⟨x, y⟩. Equivalent to context.moveTo and SVG’s “moveto” command.

# path.closePath() <>

Ends the current subpath and causes an automatic straight line to be drawn from the current point to the initial point of the current subpath. Equivalent to context.closePath and SVG’s “closepath” command.

# path.lineTo(x, y) <>

Draws a straight line from the current point to the specified point ⟨x, y⟩. Equivalent to context.lineTo and SVG’s “lineto” command.

# path.quadraticCurveTo(cpx, cpy, x, y) <>

Draws a quadratic Bézier segment from the current point to the specified point ⟨x, y⟩, with the specified control point ⟨cpx, cpy⟩. Equivalent to context.quadraticCurveTo and SVG’s quadratic Bézier curve commands.

# path.bezierCurveTo(cpx1, cpy1, cpx2, cpy2, x, y) <>

Draws a cubic Bézier segment from the current point to the specified point ⟨x, y⟩, with the specified control points ⟨cpx1, cpy1⟩ and ⟨cpx2, cpy2⟩. Equivalent to context.bezierCurveTo and SVG’s cubic Bézier curve commands.

# path.arcTo(x1, y1, x2, y2, radius) <>

Draws a circular arc segment with the specified radius that starts tangent to the line between the current point and the specified point ⟨x1, y1⟩ and ends tangent to the line between the specified points ⟨x1, y1⟩ and ⟨x2, y2⟩. If the first tangent point is not equal to the current point, a straight line is drawn between the current point and the first tangent point. Equivalent to context.arcTo and uses SVG’s elliptical arc curve commands.

# path.arc(x, y, radius, startAngle, endAngle[, anticlockwise]) <>

Draws a circular arc segment with the specified center ⟨x, y⟩, radius, startAngle and endAngle. If anticlockwise is true, the arc is drawn in the anticlockwise direction; otherwise, it is drawn in the clockwise direction. If the current point is not equal to the starting point of the arc, a straight line is drawn from the current point to the start of the arc. Equivalent to context.arc and uses SVG’s elliptical arc curve commands.

# path.rect(x, y, w, h) <>

Creates a new subpath containing just the four points ⟨x, y⟩, ⟨x + w, y⟩, ⟨x + w, y + h⟩, ⟨x, y + h⟩, with those four points connected by straight lines, and then marks the subpath as closed. Equivalent to context.rect and uses SVG’s “lineto” commands.

# path.toString() <>

Returns the string representation of this path according to SVG’s path data specification.