8 Paths

Contents

• 8.1 Introduction
• 8.2 The 'path' element
• 8.3 Path Data
  • 8.3.1 General information about path data
  • 8.3.2 The "moveto" commands
  • 8.3.3 The "closepath" command
  • 8.3.4 The "lineto" commands
  • 8.3.5 The curve commands
  • 8.3.6 The grammar for path data
• 8.4 Distance along a path
• 8.5 DOM interfaces
  • 8.5.1 Interface SVGPathElement
  • 8.5.2 Interface SVGPathSeg

8.1 Introduction

Paths represent the outline of a shape which can be filled, stroked, (see Filling, Stroking and Paint Servers) used as a clipping path (see Clipping, Masking and Compositing), or for any combination of the three.

A path is described using the concept of a current point. In an analogy with drawing on paper, the current point can be thought of as the location of the pen. The position of the pen can be changed, and the outline of a shape (open or closed) can be traced by dragging the pen in either straight lines or curves.

Paths represent an outline of an object which is defined in terms of moveto (set a new current point), lineto (draw a straight line), curveto (draw a curve using a cubic bezier), arc (elliptical or circular arc) and closepath (close the current shape by drawing a line to the last moveto) elements. Compound paths (i.e., a path with subpaths, each consisting of a single moveto followed by one or more line or curve operations) are possible to allow effects such as "donut holes" in objects.

A path is defined in SVG using the 'path' element.

8.2 The 'path' element

<!ENTITY % pathExt "" >
<!ELEMENT path (%descTitle;,(animate|set|animateMotion|animateColor|animateTransform
                %geExt;%pathExt;)*) >
<!ATTLIST path
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  transform CDATA #IMPLIED
  %graphicsElementEvents;
  system-required NMTOKEN #IMPLIED
  system-language CDATA #IMPLIED
  d CDATA #REQUIRED
  nominalLength CDATA #IMPLIED >

8.3 Path data

8.3.1 General information about path data

A path is defined by including a 'path' element which contains a d="(path data)" attribute, where the d attribute contains the moveto, line, curve (both cubic and quadratic beziers), arc and closepath instructions. The following example specifies a path in the shape of a triangle. (The M indicates a moveto, the L's indicate lineto's, and the z indicates a closepath:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
     xmlns = 'http://www.w3.org/Graphics/SVG/SVG-19991203.dtd'>
  <path d="M 100 100 L 140 100 L 120 140 z"/>
</svg>

Download this example

Path data values can contain newline characters and thus can be broken up into multiple lines to improve readability. Because of line length limitations with certain related tools, it is recommended that SVG generators split long path data strings across multiple lines, with each line not exceeding 255 characters. Also note that newline characters are only allowed at certain places within a path data value.

The syntax of path data is very abbreviated in order to allow for minimal file size and efficient downloads, since many SVG files will be dominated by their path data. Some of the ways that SVG attempts to minimize the size of path data are as follows:

• All instructions are expressed as one character (e.g., a moveto is expressed as an M)
• Superfluous white space and separators such as commas can be eliminated (e.g., "M 100 100 L 200 200" contains unnecessary spaces and could be expressed more compactly as "M100 100L200 200")
• The command letter can be eliminated on subsequent commands if the same command is used multiple times in a row (e.g., you can drop the second "L" in "M 100 200 L 200 100 L -100 -200" and use "M 100 200 L 200 100 -100 -200" instead)
• Relative versions of all commands are available (upper case means absolute coordinates, lower case means relative coordinates)
• Alternate forms of lineto are available to optimize the special cases of horizontal and vertical lines (absolute and relative)
• Alternate forms of curve are available to optimize the special cases where some of the control points on the current segment can be determined automatically from the control points on the previous segment

The path data syntax is a prefix notation (i.e., commands followed by parameters). The only allowable decimal point is a period (".") and no other delimiter characters are allowed. (For example, the following is an invalid numeric value in a path data stream: "13,000.56". Instead, say: "13000.56".)

In the tables below, the following notation is used:

• (): grouping of parameters
• +: 1 or more of the given parameter(s) is required

The following sections list the commands.

8.3.2 The "moveto" commands

The "moveto" commands (M or m) establish a new current point. The effect is as if the "pen" were lifted and moved to a new location. A path data segment must begin with either one of the "moveto" commands or one of the "arc" commands. Subsequent "moveto" commands (i.e., when the "moveto" is not the first command) represent the start of a new subpath:

8.3.3 The "closepath" command

The "closepath" (Z or z) causes an automatic straight line to be drawn from the current point to the initial point of the current subpath. "Closepath" differs in behavior from what happens when "manually" closing a subpath via a "lineto" command in how 'stroke-linejoin' and 'stroke-linecap' are implemented. With "closepath", the end of the final segment of the subpath is "joined" with the start of the initial segment of the subpath using the current value of 'stroke-linejoin' . If you instead "manually" close the subpath via a "lineto" command, the start of the first segment and the end of the last segment are not joined but instead are each capped using the current value of 'stroke-linecap':

8.3.4 The "lineto" commands

The various "lineto" commands draw straight lines from the current point to a new point:

8.3.5 The curve commands

These three groups of commands that draw curves:

• Cubic bezier commands (C, c, S and s). A cubic bezier segment is defined by a start point, an end point, and two control points.
• Quadratic bezier commands (Q, q, T and T). A quadratic bezier segment is defined by a start point, an end point, and one control point.
• Elliptical arc commands (A and a). An elliptical arc segment draws a segment of an ellipse.

The cubic bezier commands are as follows:

The quadratic bezier commands are as follows:

The elliptical arc commands are as follows:

The elliptical arc command draws a section of an ellipse which meets the following constraints:

• the arc starts at the current point
• the arc ends at point (x, y)
• the ellipse has the two radii (rx, ry)
• the X-axis of the ellipse is rotated by x-axis-rotation relative to the X-axis of the current coordinate system.

• Of the four candidate arc sweeps, two will represent an arc sweep of greater than or equal to 180 degrees (the "large-arc"), and two will represent an arc sweep of less than or equal to 180 degrees (the "small-arc"). If large-arc-flag is '1', then one of the two larger arc sweeps will be chosen; otherwise, if large-arc-flag is '0', one of the smaller arc sweeps will be chosen,
• If sweep-flag is '1', then the arc will be drawn in a "positive-angle" direction (i.e., the ellipse formula x=cx+rx*cos(theta) and y=cy+ry*sin(theta) is evaluated such that theta starts at an angle corresponding to the current point and increases positively until the arc reaches (x,y)). A value of 0 causes the arc to be drawn in a "negative-angle" direction (i.e., theta starts at an angle value corresponding to the current point and decreases until the arc reaches (x,y)).

(We need examples to illustrate all of this! Here is one for the moment. Suppose you have a circle with center (5,5) and radius 2 and you wish to draw an arc from 0 degrees to 90 degrees. Then one way to achieve this would be M 7,5 A 2,2 0 0 1 5,7. In this example, you move to the "0 degree" location on the circle, which is (7,5), since the center is at (5,5) and the circle has radius 2. Since we have circle, the two radii are the same, and in this example both are equal to 2. Since our sweep is 90 degrees, which is less than 180, we set large-arc-flag to 0. We want to draw the sweep in a positive angle direction, so we set sweep-flag to 1. Since we want to draw the arc to the point which is at the 90 degree location of the circle, we set (x,y) to (5,7).)

8.3.6 The grammar for path data

The following notation is used in the BNF description of the grammar for path data:

• *: 0 or more
• +: 1 or more
• ?: 0 or 1
• (): grouping
• |: separates alternatives
• double quotes surround literals

The following is the BNF for SVG paths.

svg-path:
    wsp* subpaths? wsp*

subpaths:
    subpath
    | subpath subpaths

subpath:
    moveto subpath-elements?

subpath-elements:
    subpath-element
    | subpath-element wsp* subpath-elements

subpath-element:
    closepath
    | lineto
    | horizontal-lineto
    | vertical-lineto
    | curveto
    | smooth-curveto
    | quadratic-bezier-curveto
    | smooth-quadratic-bezier-curveto
    | elliptical-arc

moveto:
    ( "M" | "m" ) wsp* moveto-argument-sequence

moveto-argument-sequence:
    coordinate-pair
    | coordinate-pair comma-wsp? lineto-argument-sequence

closepath:
    ("Z" | "z")

lineto:
    ( "L" | "l" ) wsp* lineto-argument-sequence

lineto-argument-sequence:
    coordinate-pair
    | coordinate-pair comma-wsp? lineto-argument-sequence

horizontal-lineto:
    ( "H" | "h" ) wsp* horizontal-lineto-argument-sequence

horizontal-lineto-argument-sequence:
    coordinate
    | coordinate comma-wsp? horizontal-lineto-argument-sequence

vertical-lineto:
    ( "V" | "v" ) wsp* vertical-lineto-argument-sequence

vertical-lineto-argument-sequence:
    coordinate
    | coordinate comma-wsp? vertical-lineto-argument-sequence

curveto:
    ( "C" | "c" ) wsp* curveto-argument-sequence

curveto-argument-sequence:
    curveto-argument
    | curveto-argument comma-wsp? curveto-argument-sequence

curveto-argument:
    coordinate-pair comma-wsp? coordinate-pair comma-wsp? coordinate-pair

smooth-curveto:
    ( "S" | "s" ) wsp* smooth-curveto-argument-sequence

smooth-curveto-argument-sequence:
    smooth-curveto-argument
    | smooth-curveto-argument comma-wsp? smooth-curveto-argument-sequence

smooth-curveto-argument:
    coordinate-pair comma-wsp? coordinate-pair

quadratic-bezier-curveto:
    ( "Q" | "q" ) wsp* quadratic-bezier-curveto-argument-sequence

quadratic-bezier-curveto-argument-sequence:
    quadratic-bezier-curveto-argument
    | quadratic-bezier-curveto-argument comma-wsp? 
        quadratic-bezier-curveto-argument-sequence

quadratic-bezier-curveto-argument:
    coordinate-pair comma-wsp? coordinate-pair

smooth-quadratic-bezier-curveto:
    ( "T" | "t" ) wsp* smooth-quadratic-bezier-curveto-argument-sequence

smooth-quadratic-bezier-curveto-argument-sequence:
    coordinate-pair
    | coordinate-pair comma-wsp? smooth-quadratic-bezier-curveto-argument-sequence

elliptical-arc:
    ( "A" | "a" ) wsp* elliptical-arc-argument-sequence

elliptical-arc-argument-sequence:
    elliptical-arc-argument
    | elliptical-arc-argument comma-wsp? elliptical-arc-argument-sequence

elliptical-arc-argument:
    nonnegative-number comma-wsp? nonnegative-number comma-wsp? 
        number comma-wsp? flag comma-wsp? flag comma-wsp? coordinate-pair

coordinate-pair:
    coordinate comma-wsp? coordinate

coordinate:
    number

nonnegative-number:
    integer-constant
    | floating-point-constant

number:
    sign? integer-constant
    | sign? floating-point-constant

flag:
    "0" | "1"

comma-wsp:
    (wsp+ comma? wsp*) | (comma wsp*)

comma:
    ","

integer-constant:
    digit-sequence

floating-point-constant:
    fractional-constant exponent?
    | digit-sequence exponent

fractional-constant:
    digit-sequence? "." digit-sequence
    | digit-sequence "."

exponent:
    ( "e" | "E" ) sign? digit-sequence

sign:
    "+" | "-"

digit-sequence:
    digit
    | digit digit-sequence

digit:
    "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

wsp:
    (#x20 | #x9 | #xD | #xA)

The processing of the BNF must consume as much of a given BNF production as possible, stopping at the point when a character is encountered which no longer satisfies the production. Thus, in the string "M 100-200", the first coordinate for the "moveto" consumes the characters "100" and stops upon encountering the minus sign because the minus sign cannot follow a digit in the production of a "coordinate". The result is that the first coordinate will be "100" and the second coordinate will be "-200".

Similarly, for the string "M 0.6.5", the first coordinate of the "moveto" consumes the characters "0.6" and stops upon encountering the second decimal point because the production of a "coordinate" only allows one decimal point. The result is that the first coordinate will be "0.6" and the second coordinate will be ".5".

8.4 Distance along a path

Various operations, including text on a path and motion animation and various stroke operations, require that the user agent compute the distance along the geometry of a graphics element, such as a 'path'.

Exact mathematics exist for computing distance along a path, but the formulas are highly complex and require substantial computation. It is recommended that authoring products and user agents employ algorithms that produce as precise results as possible; however, to accommodate implementation differences and to help distance calculations produce results that approximate author intent, the nomimalLength attribute can be used to provide the author's computation of the total length of the path so that the user agent can scale distance-along-a-path computations by the ratio of nomimalLength to the user agent's own computed value for total path length.

A "moveto" operation within a 'path' element is defined to have zero length. Only the various "lineto", "curveto" and "arcto" commands contribute to path length calculations.

8.5 DOM interfaces

8.5.1 Interface SVGPathElement

The SVGPathElement interface corresponds to the 'path' element.

interface SVGPathElement : SVGStyledAndTransformedElement {
  attribute SVGLength nominalLength;

  // Create an empty SVGPathSeg, specifying the type via a number.
  // All values initialized to zero.
  SVGPathSeg  createSVGPathSeg(in unsigned short pathsegType)
	                             raises(DOMException);

  // Create an empty SVGPathSeg, specifying the type via a single character.
  // All values initialized to zero.
  SVGPathSeg  createSVGPathSegFromLetter(in DOMString pathsegTypeAsLetter)
	                                       raises(DOMException);

  // Create an SVGPathSeg, specifying the path segment as a string.
  // For example, "M 100 200". All irrelevant values are set to zero.
  SVGPathSeg  createSVGPathSegFromString(in DOMString pathsegString)
	                                       raises(DOMException);

  // This set of methods allows retrieval and modification
  // to the path segments attached to this path object.
  // All 20 defined types of path segments are available
  // through these attributes and methods.

  readonly attribute unsigned long  number_of_pathsegs;
  SVGPathSeg      getSVGPathSeg(in unsigned long index);
  DOMString       getSVGPathSegAsString(in unsigned long index);

  // Replace all existing entries with a single entry.
  void            initialize(in SVGPathSeg newSVGPathSeg)
                                           raises(DOMException);
  void            clear(); // Clear all entries, giving an empty list
  SVGPathSeg      insertBefore(in SVGPathSeg newSVGPathSeg,
                                           in unsigned long index)
                                           raises(DOMException);
  SVGPathSeg      replace(in SVGPathSeg newSVGPathSeg,
                                      in unsigned long index)
                                      raises(DOMException);
  SVGPathSeg      remove(in unsigned long index)
                                     raises(DOMException);
  SVGPathSeg      append(in SVGPathSeg newSVGPathSeg)
                                     raises(DOMException);

  // This alternate set of methods also allows retrieval and modification
  // to the path segments attached to this path object.
  // These attributes and methods provide a "normalized" view of
  // the path segments where the path is expressed in terms of
  // the following subset of SVGPathSeg types:
  // kSVG_PATHSEG_MOVETO_ABS (M), kSVG_PATHSEG_LINETO_ABS (L),
  // kSVG_PATHSEG_CURVETO_CUBIC_ABS (C) and kSVG_PATHSEG_CLOSEPATH (z).
  // Note that number_of_pathsegs and number_of_normalized_pathsegs
  // are not always the same. In particular, elements such as arcs may
  // be expanded into multiple kSVG_PATHSEG_CURVETO_CUBIC_ABS (C)
  // pieces when retrieved in the "normalized" view of the path object.

  readonly attribute unsigned long  number_of_normalized_pathsegs;
  SVGPathSeg      getNormalizedSVGPathSeg(in unsigned long index);
  DOMString       getNormalizedSVGPathSegAsString(in unsigned long index);
  SVGPathSeg      insertNormalizedBefore(in SVGPathSeg newSVGPathSeg,
                                in unsigned long index)
                                raises(DOMException);
  SVGPathSeg      replaceNormalized(in SVGPathSeg newSVGPathSeg,
                                in unsigned long index)
                                raises(DOMException);
  SVGPathSeg      removeNormalized(in unsigned long index)
                                raises(DOMException);
  SVGPathSeg      appendNormalized(in SVGPathSeg newSVGPathSeg)
                                raises(DOMException);

  // This set of methods performs various distance-along-a-path calculations.

  float          getTotalLength();
  SVGPoint        getPointAtLength(in float distance);
  SVGPathSeg      getPathSegAtLength(in float distance);
};

8.5.2 Interface SVGPathSeg

The SVGPathSeg interface corresponds to a single command within a path data specification.

interface SVGPathSeg {
  // Path Segment Types
  const unsigned short kSVG_PATHSEG_UNKNOWN                      = 0;  // ?
  const unsigned short kSVG_PATHSEG_CLOSEPATH                    = 1;  // z
  const unsigned short kSVG_PATHSEG_MOVETO_ABS                   = 2;  // M
  const unsigned short kSVG_PATHSEG_MOVETO_REL                   = 3;  // m
  const unsigned short kSVG_PATHSEG_LINETO_ABS                   = 4;  // L
  const unsigned short kSVG_PATHSEG_LINETO_REL                   = 5;  // l
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_ABS            = 6;  // C
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_REL            = 7;  // c
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_ABS        = 8;  // Q
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_REL        = 9;  // q
  const unsigned short kSVG_PATHSEG_ARC_ABS                      = 10; // A
  const unsigned short kSVG_PATHSEG_ARC_REL                      = 11; // a
  const unsigned short kSVG_PATHSEG_LINETO_HORIZONTAL_ABS        = 12; // H
  const unsigned short kSVG_PATHSEG_LINETO_HORIZONTAL_REL        = 13; // h
  const unsigned short kSVG_PATHSEG_LINETO_VERTICAL_ABS          = 14; // V
  const unsigned short kSVG_PATHSEG_LINETO_VERTICAL_REL          = 15; // v
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_SMOOTH_ABS     = 16; // S
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_SMOOTH_REL     = 17; // s
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_SMOOTH_ABS = 18; // T
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_SMOOTH_REL = 19; // t

  readonly attribute  unsigned short pathsegType;
  readonly attribute  DOMString      pathsegTypeAsLetter;

  // Attribute values for a path segment.
  // Each pathseg has slots for any possible path seg type.
  attribute  float       x;   // end point for pathseg
  attribute  float       y;   // end point for pathseg
  attribute  float       x0,y0;         // for bezier control points
  attribute  float       x1,y1;         // for bezier control points
  attribute  float       r1,r2;         // radii for A/a
  attribute  float       angle;         // A/a
  attribute  boolean     largeArcFlag;  // for A/a
  attribute  boolean     sweepFlag;     // for A/a

  readonly attribute  Path parentPath;
  readonly attribute  SVGDocument ownerSVGDocument;
  readonly attribute  SVGPathSeg previousSibling;
  readonly attribute  SVGPathSeg nextSibling;
};