Paths: the Pen Commands

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

path

A shape made by pen commands. Written as <path d="...">.

d attribute

The list of commands that describes the path, such as M 10 80 Q 95 10 180 80.

absolute / relative

A capital letter measures from the SVG's corner (absolute). A small letter measures from where the pen is now (relative).

control point

A point that pulls a curve towards it. The curve does not touch it.

flag

A setting that is only 0 or 1. Arcs have two: large-arc and sweep.

subpath

One continuous piece of a path. Every M starts a new one.

NaN

"Not a Number": what a failed calculation gives, such as "n/a" / 3992. Writing it into d is an error.

length (of a path)

How far the pen travels along the outline. getTotalLength() asks the browser for it, in user units.

1. 1

   Pull the curve harder

   In the path editor, drag the control point of the curve higher, or in the second example change the first path to M 10 120 Q 100 -60 190 120. The curve rises more but still does not reach the control point: it only gets about halfway there. Notice that the control point can sit outside the picture.

2. 2

   Close the open triangle

   In the first example, add Z to the end of the d of #open. The Console then says Closed with Z: 305.9 | open, no Z: 305.9, because both are the same shape now. The length of an open path grows by one side when you close it.

3. 3

   Lift the pen

   In the third example, change null back to 3742 in the gap line: the gap disappears and the Console says 1 piece(s). Then change Saturday's 3013 to null instead: the Console says 2 piece(s) (Monday to Friday, then Sunday). Put Thursday's null back as well and it says 3, because each separate gap starts a new piece.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: rectangles and circles cannot make a line chart with 365 points, a curve, or a custom icon. A polyline can follow many points but cannot bend or have gaps. A path can do all of these, in one element, with one d attribute. Every chart line, area and map outline in this course is a path.

2. 2

   **The d attribute is a list of commands.** Each command is a letter followed by numbers. M x y (move to) lifts the pen and puts it down at a point. L x y draws a straight line to a point. H x draws a horizontal line to that x, and V y a vertical line to that y. Z closes the shape with a straight line back to where it started. A path must begin with M: if it does not, the browser draws nothing and prints Error: <path> attribute d: Expected moveto path command ('M' or 'm'), "L 50 50 L 90 10".

3. 3

   Capital letters are absolute, small letters are relative. L 60 20 goes to the point (60, 20). l 60 20 goes 60 across and 20 down from wherever the pen is now. Relative commands let you describe a shape once and place it anywhere by changing only the first m. The first example draws the same triangle both ways, and both have the same box and the same length.

4. 4

   Curves bend towards control points. Q cx cy x y draws a curve to (x, y), pulled towards one control point (cx, cy). C c1x c1y c2x c2y x y uses two control points, one for each end. The curve never passes through its control points; it leans towards them, like a rubber band. A larger distance to the control point means a stronger pull. The path editor below lets you drag them.

5. 5

   Arcs take two flags. A rx ry rotation large-arc sweep x y draws a piece of an ellipse from the current point to (x, y). Between two points there are four such arcs. large-arc (0 or 1) picks the longer or the shorter one, and sweep (0 or 1) picks which side it bulges to (1 is clockwise). If the radii are too small to reach the end point, the browser scales them up until it can, so an arc never fails. Rotation is usually 0.

6. 6

   A line chart is a path. Turn each data point into x and y, write M for the first and L for each next point. D3 writes exactly this, with no spaces and numbers rounded to 3 decimals: M0,1L2.5,3. A missing value is a gap: lift the pen (a new M) instead of drawing across it. Topic 3.4 and Phase 7 build this for 365 points.

7. 7

   A bad number stops the path. If a calculation puts NaN into the string, the browser prints Error: <path> attribute d: Expected number, "…" and draws the path up to the last good command. The chart does not disappear; it ends early. This is why a line that stops partway is a hint to look for NaN. D3's line() writes the bad value into the string as it is (LNaN,3), so the error appears too. The quoted text is a window of about 32 characters around the bad spot, with … where the string was cut.

8. 8

   Other mistakes, other messages. The browser names the problem. A lone X gives Expected path command, "M 1 1 L 5 5 X 3". A string that stops in the middle of a command gives Unexpected end of attribute. Expected number, "M 0 0 L 10 20 Q". An arc flag other than 0 or 1 gives Expected arc flag ('0' or '1'), "M 0 0 A 5 5 0 2 1 10 10". The shape is drawn up to the last good command each time.

• ↔

  A path is more flexible than a polyline (curves, gaps, arcs) but its string is harder to read by hand. Use a polyline for a few straight segments, a path for everything that bends or breaks.

• ↔

  Absolute commands are easy to check against a grid. Relative commands make shapes easy to move and repeat. Hand-written icons often mix both.

• I can read a d string: M, L, H, V, Z, Q, C and A.

• I know what capital and small letters mean.

• I can turn a list of points into a path string, with a gap for a missing value.

• I recognise the NaN error and know the line is drawn only up to it.

• I know a path that does not start with M draws nothing and prints no error.