master/paths.html

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional+edit//EN" "xhtml1-transitional+edit.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:edit="http://xmlns.grorg.org/SVGT12NG/">
<head>
  <title>Paths</title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <meta name="viewport"           content="width=device-width, initial-scale=1, shrink-to-fit=no"/>
  <link rel="stylesheet"           title="Default"               type="text/css" media="screen" href="style/default_svg.css"/>
  <link rel="alternate stylesheet" title="No issues/annotations" type="text/css" media="screen" href="style/default_no_issues.css"/>
  <!--
  <link rel="alternate stylesheet" title="CSS3 Unmodified"       type="text/css" media="screen" href="style/default.css"/>
  <link rel="alternate stylesheet" title="SVG 1.1"               type="text/css" media="screen" href="style/svg-style.css"/>
  -->
  <!-- W3C style sheet will be added here during processing. -->
</head>
<body>

<h1>Paths</h1>

<edit:with element='path'>

<h2 id="Introduction">Introduction</h2>

<p>
  A path represents the outline of a shape which can be filled or
  stroked. A path can also be used as a clipping path, to describe
  animation, or position text. A path can be used for more than one of
  these functions at the same time. (See
  <a href="painting.html">Filling, Stroking and Paint Servers</a>,
  <a href="render.html#ClippingAndMasking">Clipping and Masking</a>,
  Animation (<a href="https://svgwg.org/specs/animations/#AnimateMotionElement">'animateMotion'</a>),
  and <a href="text.html#TextLayoutPath">Text on a Path</a>.)
</p>

<p>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.</p>

<p>Paths represent the geometry of the outline of an object,
defined in terms of <em>moveto</em> (set a new current point),
<em>lineto</em> (draw a straight line), <em>curveto</em> (draw
a curve using a cubic Bézier), <em>arc</em> (elliptical
or circular arc) and <em>closepath</em> (close the current
shape by connecting to the last <em>moveto</em>) commands.
Compound paths (i.e., a path with multiple subpaths) are
possible to allow effects such as "donut holes" in objects.</p>

<p>This chapter describes the syntax, behavior and DOM
interfaces for SVG paths. Various implementation notes for SVG
paths can be found in <a
href="paths.html#PathElementImplementationNotes"><span
class="element-name">'path'</span> element implementation
Notes</a> and <a
href="implnote.html#ArcImplementationNotes">Elliptical arc
implementation notes</a>.</p>

<p>A path is defined in SVG using the <a>'path'</a> element.</p>

<p>The <a>basic shapes</a> are all described in terms of what their
<dfn id="TermEquivalentPath">equivalent path</dfn> is, which is
what their shape is as a path.  (The equivalent path of a
<a>'path'</a> element is simply the path itself.)</p>

<h2 id="PathElement">The <span class="element-name">'path'</span> element</h2>

<edit:elementsummary name='path'/>

<p>The outline of a shape for a <a>'path'</a> element is specified using the <a>'d'</a>
property.  See <a href="#PathData">Path data</a> below.</p>

<h2 id="PathData">Path data</h2>

<h3 id="PathDataGeneralInformation">General information about path data</h3>

<p>A path is defined by including a <a>'path'</a>
element on which the <a>'d'</a> property specifies the
path data.  The path data contains the
<em>moveto</em>, <em>lineto</em>, <em>curveto</em> (both cubic and
quadratic Béziers), <em>arc</em> and <em>closepath</em>
instructions.</p>

<p><span class="example-ref">Example triangle01</span>
specifies a path in the shape of a triangle. (The
<strong>M</strong> indicates a <em>moveto</em>, the
<strong>L</strong>s indicate <em>lineto</em>s, and the
<strong>z</strong> indicates a <em>closepath</em>).</p>

<edit:example href='images/paths/triangle01.svg' link='yes' image='yes' name='triangle01' description="simple example of a 'path'"/>

<p>Path data can contain newline characters and thus can be
broken up into multiple lines to improve readability.
Newlines inside attributes in markup will be normalized to space
characters while parsing.</p>

<p>The syntax of path data is concise 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:</p>

<ul>
  <li>All instructions are expressed as one character (e.g., a
  <em>moveto</em> is expressed as an <strong>M</strong>).</li>

  <li>
    <div>Superfluous white space and separators (such as commas) may
    be eliminated; for instance, the following contains unnecessary
    spaces:</div>
    <div style="margin-left: 2em"><code>M 100 100 L 200 200</code></div>
    <div>It may be expressed more compactly as:</div>
    <div style="margin-left: 2em"><code>M100 100L200 200</code></div>
  </li>

  <li>
    <div>A command letter may be eliminated if an identical command
    letter would otherwise precede it; for instance, the following
    contains an unnecessary second "L" command:</div>
    <div style="margin-left: 2em"><code>M 100 200 L 200 100 L -100 -200</code></div>
    <div>It may be expressed more compactly as:</div>
    <div style="margin-left: 2em"><code>M 100 200 L 200 100 -100 -200</code></div>
  </li>

  <li>For most commands there are absolute and relative
  versions available (uppercase means absolute coordinates,
  lowercase means relative coordinates).</li>

  <li>Alternate forms of <em>lineto</em> are available to
  optimize the special cases of horizontal and vertical lines
  (absolute and relative).</li>

  <li>Alternate forms of <em>curve</em> 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.</li>
</ul>

<p>The path data syntax is a prefix notation (i.e., commands
followed by parameters). The only allowable decimal point is a
Unicode
U+0046 FULL STOP (".") character (also referred to in Unicode as
PERIOD, dot and decimal point) and no other delimiter
characters are allowed [<a href='refs.html#ref-unicode'>UNICODE</a>].
(For example, the following is an
invalid numeric value in a path data stream: "13,000.56".
Instead, say: "13000.56".)</p>

<p>For the relative versions of the commands, all coordinate
values are relative to the current point at the start of the
command.</p>

<p>In the tables below, the following notation is used to
describe the syntax of a given path command:</p>

<ul>
  <li>(): grouping of parameters</li>
  <li>+: 1 or more of the given parameter(s) is required</li>
</ul>

<div class="ready-for-wider-review">

<p>In the description of the path commands, <var>cpx</var> and
<var>cpy</var> represent the coordinates of the current point.</p>

</div>

<div class='ready-for-wider-review'>

<h3 id="TheDProperty">Specifying path data: the <span class='property'>'d'</span> property</h3>

<table class="propdef def">
  <tr>
    <th>Name:</th>
    <td><dfn id="DProperty">d</dfn></td>
  </tr>
  <tr>
    <th>Value:</th>
    <td>none | <a>&lt;string&gt;</a></td>
  </tr>
  <tr>
    <th>Initial:</th>
    <td>none</td>
  </tr>
  <tr>
    <th>Applies to:</th>
    <td><a>'path'</a></td>
  </tr>
  <tr>
    <th>Inherited:</th>
    <td>no</td>
  </tr>
  <tr>
    <th>Percentages:</th>
    <td>N/A</td>
  </tr>
  <tr>
    <th>Media:</th>
    <td>visual</td>
  </tr>
  <tr>
    <th>Computed&#160;value:</th>
    <td>as specified</td>
  </tr>
  <tr>
    <th><a>Animatable</a>:</th>
    <td>yes</td>
  </tr>
</table>

<p>The <a>'d'</a> property is used to specify the shape of a <a>'path'</a> element.</p>

<p>The value <span class='prop-value'>none</span> indicates that there is no
path data for the element.  For <a>'path'</a> elements, this means that the
element does not render or contribute to the <a>bounding box</a> of ancestor
<a>container elements</a>.</p>

<p>A path is made up of multiple segments, and every command, either explicit
or implicit, other than moveto or closepath,
defines one <dfn id="TermPathSegment">path segment</dfn>.</p>

<p>All coordinates and lengths specified within path data must be treated as
being in <a>user units</a> in the current user coordinate system.</p>

<p>The <span class='prop-value'><a>&lt;string&gt;</a></span> value
specifies a shape using a path data string.  The contents of the
<a>&lt;string&gt;</a> value must match the <a href="#PathDataBNF">svg-path</a>
<a href="types.html#syntax">EBNF grammar</a> defined below, and errors within the string are handled according to
the rules in the <a href="paths.html#PathDataErrorHandling">Path Data Error Handling</a> section.
If the path data string contains no valid commands, then the behavior
is the same as the <span class='prop-value'>none</span> value.</p>

<p>
  For animation, two <a>'d'</a> property values can only be
  interpolated smoothly when the path data strings contain have the
  same structure, (i.e. exactly the same number and types of path data
  commands which are in the same order). If an animation is specified
  and the lists of path data commands do not have the same structure,
  then the values must be
  <a href="https://drafts.csswg.org/web-animations/#animation-interpolation">interpolated</a>
  using the
  <a href="https://drafts.csswg.org/web-animations/#discrete-animation-type-section">discrete</a>
  animation type.
</p>
<p>
  If the list of path data commands have the same structure, then each
  parameter to each path data command must be
  <a href="https://drafts.csswg.org/web-animations/#animation-interpolation">interpolated</a>
  separately <a href="https://drafts.csswg.org/web-animations/#real-number-animation-type">as
  real numbers</a>.  Flags and booleans must be interpolated as
  fractions between zero and one, with any non-zero value considered
  to be a value of one/true.
</p>

<p class="annotation">
  Resolved that "d will become a presentation attribute (no name
  change) with path data string as value" at
  <a href="https://www.w3.org/2016/04/21-svg-minutes.html">London
  Editor's Meeting</a>.
</p>

</div>

<p>The following sections list the commands that canbe used
in path data strings.  Those that
draw straight line segments include the <a href="paths.html#PathDataLinetoCommands">lineto commands</a>
(<strong>L</strong>, <strong>l</strong>,
<strong>H</strong>, <strong>h</strong>, <strong>V</strong> and <strong>v</strong>)
and the <a href="paths.html#PathDataClosePathCommand">close path commands</a>
(<strong>Z</strong> and <strong>z</strong>).  These three groups of commands draw curves:</p>

<ul>
  <li><a href="paths.html#PathDataCubicBezierCommands">Cubic
  Bézier commands</a> (<strong>C</strong>,
  <strong>c</strong>, <strong>S</strong> and
  <strong>s</strong>). A cubic Bézier segment is defined
  by a start point, an end point, and two control points.</li>

  <li><a
  href="paths.html#PathDataQuadraticBezierCommands">Quadratic
  Bézier commands</a> (<strong>Q</strong>,
  <strong>q</strong>, <strong>T</strong> and
  <strong>t</strong>). A quadratic Bézier segment is
  defined by a start point, an end point, and one control
  point.</li>

  <li><a
  href="paths.html#PathDataEllipticalArcCommands">Elliptical
  arc commands</a> (<strong>A</strong> and <strong>a</strong>).
  An elliptical arc segment draws a segment of an ellipse.</li>
</ul>

<h3 id="PathDataMovetoCommands">The <strong>"moveto"</strong> commands</h3>

<p>The "moveto" commands (<strong>M</strong> or
<strong>m</strong>) must establish a new <dfn id="TermInitialPoint">initial point</dfn>
and a new current point. The effect is as if the "pen" were lifted and moved to
a new location. A path data segment (if there is one) must begin with a "moveto"
command. Subsequent "moveto" commands (i.e., when the "moveto"
is not the first command) represent the start of a new
<em>subpath</em>:</p>

<table class="PathDataTable">
  <tr>
    <th>Command</th>
    <th>Name</th>
    <th>Parameters</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><strong>M</strong> (absolute)<br />
     <strong>m</strong> (relative)</td>
    <td>moveto</td>
    <td>(x y)+</td>
    <td>
      Start a new sub-path at the given (x,y) coordinates.
      <strong>M</strong> (uppercase) indicates that absolute
      coordinates will follow; <strong>m</strong> (lowercase)
      indicates that relative coordinates will follow. If a moveto is
      followed by multiple pairs of coordinates, the subsequent pairs
      are treated as implicit lineto commands. Hence, implicit lineto
      commands will be relative if the moveto is relative, and
      absolute if the moveto is absolute. If a relative moveto
      (<strong>m</strong>) appears as the first element of the path,
      then it is treated as a pair of absolute coordinates. In this
      case, subsequent pairs of coordinates are treated as relative
      even though the initial moveto is interpreted as an absolute moveto.
    </td>
  </tr>
</table>

<div class="ready-for-wider-review">

<p>When a relative <strong>m</strong> command is used, the
position moved to is (<var>cpx</var> + <var>x</var>,
<var>cpy</var> + <var>y</var>).</p>

</div>

<h3 id="PathDataClosePathCommand">The <strong>"closepath"</strong> command</h3>

<p>The "closepath" (<strong>Z</strong> or <strong>z</strong>)
  ends the current subpath by connecting it back to its <a>initial point</a>.
  An automatic
  straight line is drawn from the current point to the <a>initial point</a>
  of the current subpath. This <a>path segment</a> may be of zero
  length.
</p>

<table class="PathDataTable">
  <tr>
    <th>Command</th>
    <th>Name</th>
    <th>Parameters</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><strong>Z</strong> or<br />
     <strong>z</strong></td>
    <td>closepath</td>
    <td>(none)</td>
    <td>Close the current subpath by connecting it back to the current
    subpath's <a>initial point</a> (see prose above). Since the
    <strong>Z</strong> and <strong>z</strong>
    commands take no parameters, they have an identical effect.</td>
  </tr>
</table>

<p>A <dfn id="TermClosedSubpath">closed subpath</dfn> must be closed with a
"closepath" command, this "joins" the first and last <a>path segments</a>.
Any other path is an <dfn id="TermOpenSubpath">open subpath</dfn>.</p>

<p class="note ready-for-wider-review">A <a>closed subpath</a> differs in behavior
from an <a>open subpath</a> whose final coordinate is the <a>initial point</a>
of the subpath.
The first and last <a>path segments</a> of an <a>open subpath</a> will not be
joined, even when the final coordinate of the last <a>path segment</a> is the
<a>initial point</a> of the subpath. This will result in the first and last
<a>path segments</a> being capped using the current value of <a>'stroke-linecap'</a>
rather than joined using the current value of <a>'stroke-linejoin'</a>.</p>

<p>If a "closepath" is followed immediately by a
"moveto", then the "moveto" identifies the start point of the
next subpath. If a "closepath" is followed immediately by any
other command, then the next subpath must start at the same <a>initial point</a>
as the current subpath.</p>

<h3 id="PathDataLinetoCommands">The <strong>"lineto"</strong> commands</h3>

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

<table  class="PathDataTable">
  <tr>
    <th>Command</th>
    <th>Name</th>
    <th>Parameters</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><strong>L</strong> (absolute)<br />
     <strong>l</strong> (relative)</td>
    <td>lineto</td>
    <td>(x y)+</td>
    <td>Draw a line from the current point to the given (x,y)
    coordinate which becomes the new current point.
    <strong>L</strong> (uppercase) indicates that absolute
    coordinates will follow; <strong>l</strong> (lowercase)
    indicates that relative coordinates will follow. A number
    of coordinates pairs may be specified to draw a polyline.
    At the end of the command, the new current point is set to
    the final set of coordinates provided.</td>
  </tr>
  <tr>
    <td><strong>H</strong> (absolute)<br />
     <strong>h</strong> (relative)</td>
    <td>horizontal lineto</td>
    <td>x+</td>
    <td>Draws a horizontal line from the current point.
    <strong>H</strong> (uppercase) indicates
    that absolute coordinates will follow; <strong>h</strong>
    (lowercase) indicates that relative coordinates will
    follow. Multiple x values can be provided (although usually
    this doesn't make sense). An <strong>H</strong> or <strong>h</strong>
    command is equivalent to an <strong>L</strong> or <strong>l</strong>
    command with 0 specified for the y coordinate.
    At the end of the command, the new current point is
    taken from the final coordinate value.</td>
  </tr>
  <tr>
    <td><strong>V</strong> (absolute)<br />
     <strong>v</strong> (relative)</td>
    <td>vertical lineto</td>
    <td>y+</td>
    <td>Draws a vertical line from the current point.
    <strong>V</strong> (uppercase) indicates that
    absolute coordinates will follow; <strong>v</strong>
    (lowercase) indicates that relative coordinates will
    follow. Multiple y values can be provided (although usually
    this doesn't make sense).  A <strong>V</strong> or <strong>v</strong>
    command is equivalent to an <strong>L</strong> or <strong>l</strong>
    command with 0 specified for the x coordinate.
    At the end of the command, the new current point is
    taken from the final coordinate value.</td>
  </tr>
</table>

<div class="ready-for-wider-review">

<p>When a relative <strong>l</strong> command is used, the
end point of the line is (<var>cpx</var> + <var>x</var>,
<var>cpy</var> + <var>y</var>).</p>

<p>When a relative <strong>h</strong> command is used,
the end point of the line is (<var>cpx</var> + <var>x</var>,
<var>cpy</var>).  This means
that an <strong>h</strong> command with a positive <var>x</var>
value draws a horizontal line in the direction of the positive x-axis.</p>

<p>When a relative <strong>v</strong> command is used,
the end point of the line is (<var>cpx</var>,
<var>cpy</var> + <var>y</var>).</p>

</div>

<h3 id="PathDataCubicBezierCommands">The cubic Bézier curve commands</h3>

<p>The cubic Bézier commands are as follows:</p>

<table class="PathDataTable">
  <tr>
    <th>Command</th>
    <th>Name</th>
    <th>Parameters</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><strong>C</strong> (absolute)<br />
     <strong>c</strong> (relative)</td>
    <td>curveto</td>
    <td>(x1 y1 x2 y2 x y)+</td>
    <td>Draws a cubic Bézier curve from the current
    point to (x,y) using (x1,y1) as the control point at the
    beginning of the curve and (x2,y2) as the control point at
    the end of the curve. <strong>C</strong> (uppercase)
    indicates that absolute coordinates will follow;
    <strong>c</strong> (lowercase) indicates that relative
    coordinates will follow. Multiple sets of coordinates may
    be specified to draw a polybézier. At the end of the
    command, the new current point becomes the final (x,y)
    coordinate pair used in the polybézier.</td>
  </tr>
  <tr>
    <td><strong>S</strong> (absolute)<br />
     <strong>s</strong> (relative)</td>
    <td>shorthand/smooth curveto</td>
    <td>(x2 y2 x y)+</td>
    <td>Draws a cubic Bézier curve from the current
    point to (x,y). The first control point is assumed to be
    the reflection of the second control point on the previous
    command relative to the current point. (If there is no
    previous command or if the previous command was not an C,
    c, S or s, assume the first control point is coincident
    with the current point.) (x2,y2) is the second control
    point (i.e., the control point at the end of the curve).
    <strong>S</strong> (uppercase) indicates that absolute
    coordinates will follow; <strong>s</strong> (lowercase)
    indicates that relative coordinates will follow. Multiple
    sets of coordinates may be specified to draw a
    polybézier. At the end of the command, the new
    current point becomes the final (x,y) coordinate pair used
    in the polybézier.</td>
  </tr>
</table>

<div class="ready-for-wider-review">

<p>When a relative <strong>c</strong> or <strong>s</strong>
command is used, each of the relative coordinate pairs
is computed as for those in an <strong>m</strong> command.
For example, the final control point of the curve of
both commands is (<var>cpx</var> + <var>x</var>,
<var>cpy</var> + <var>y</var>).</p>

</div>

<p><span class="example-ref">Example cubic01</span> shows some
simple uses of cubic Bézier commands within a path. The
example uses an internal CSS style sheet to assign styling
properties. Note that the control point for the "S" command is
computed automatically as the reflection of the control point
for the previous "C" command relative to the start point of the
"S" command.</p>

<edit:example href='images/paths/cubic01.svg' name='cubic01' description='cubic Bézier comamnds in path data' image='yes' link='yes'/>

<p>The following picture shows some how cubic Bézier
curves change their shape depending on the position of the
control points. The first five examples illustrate a single
cubic Bézier <a>path segment</a>. The example at the lower
right shows a "C" command followed by an "S" command.</p>
<p><img
alt="Example cubic02 - cubic Bézier commands in path data"
 src="images/paths/cubic02.png" width="355" height="355" /></p>
<p class="view-as-svg"><a href="images/paths/cubic02.svg">View
this example as SVG (SVG-enabled browsers only)</a><br />
 &nbsp;</p>

<h3 id="PathDataQuadraticBezierCommands">The quadratic Bézier curve commands</h3>

<p>The quadratic Bézier commands are as follows:</p>

<table class="PathDataTable">
  <tr>
    <th>Command</th>
    <th>Name</th>
    <th>Parameters</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><strong>Q</strong> (absolute)<br />
     <strong>q</strong> (relative)</td>
    <td>quadratic Bézier curveto</td>
    <td>(x1 y1 x y)+</td>
    <td>Draws a quadratic Bézier curve from the current
    point to (x,y) using (x1,y1) as the control point.
    <strong>Q</strong> (uppercase) indicates that absolute
    coordinates will follow; <strong>q</strong> (lowercase)
    indicates that relative coordinates will follow. Multiple
    sets of coordinates may be specified to draw a
    polybézier. At the end of the command, the new
    current point becomes the final (x,y) coordinate pair used
    in the polybézier.</td>
  </tr>
  <tr>
    <td><strong>T</strong> (absolute)<br />
     <strong>t</strong> (relative)</td>
    <td>Shorthand/smooth quadratic Bézier curveto</td>
    <td>(x y)+</td>
    <td>Draws a quadratic Bézier curve from the current
    point to (x,y). The control point is assumed to be the
    reflection of the control point on the previous command
    relative to the current point. (If there is no previous
    command or if the previous command was not a Q, q, T or t,
    assume the control point is coincident with the current
    point.) <strong>T</strong> (uppercase) indicates that
    absolute coordinates will follow; <strong>t</strong>
    (lowercase) indicates that relative coordinates will
    follow. At the end of the command, the new current point
    becomes the final (x,y) coordinate pair used in the
    polybézier.</td>
  </tr>
</table>

<div class="ready-for-wider-review">

<p>When a relative <strong>q</strong> or <strong>t</strong>
command is used, each of the relative coordinate pairs
is computed as for those in an <strong>m</strong> command.
For example, the final control point of the curve of
both commands is (<var>cpx</var> + <var>x</var>,
<var>cpy</var> + <var>y</var>).</p>

</div>

<p><span class="example-ref">Example quad01</span> shows some
simple uses of quadratic Bézier commands within a path.
Note that the control point for the "T" command is computed
automatically as the reflection of the control point for the
previous "Q" command relative to the start point of the "T"
command.</p>

<edit:example href='images/paths/quad01.svg' name='quad01' description='quadratic Bézier commands in path data' image='yes' link='yes'/>

<h3 id="PathDataEllipticalArcCommands">The elliptical arc curve commands</h3>

<div class="annotation svg2-requirement">
  <table>
    <tr>
      <th>SVG 2 Requirement:</th>
      <td>Make it simpler to draw arcs in SVG path syntax.</td>
    </tr>
    <tr>
      <th>Resolution:</th>
      <td><a href="http://www.w3.org/2011/11/04-svg-minutes.html#item08">Make arcs in paths easier.</a></td>
    </tr>
    <tr>
      <th>Purpose:</th>
      <td>To make it easier for authors to write path data with arcs by hand.</td>
    </tr>
    <tr>
      <th>Owner:</th>
      <td>Cameron (<a href="http://www.w3.org/Graphics/SVG/WG/track/actions/3151">ACTION-3151</a>)</td>
    </tr>
  </table>
</div>

<p>The elliptical arc commands are as follows:</p>

<table  class="PathDataTable">
  <tr>
    <th>Command</th>
    <th>Name</th>
    <th>Parameters</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><strong>A</strong> (absolute)<br />
     <strong>a</strong> (relative)</td>
    <td>elliptical arc</td>
    <td>(rx ry x-axis-rotation large-arc-flag sweep-flag x
    y)+</td>
    <td>Draws an elliptical arc from the current point to
    (<strong>x</strong>, <strong>y</strong>). The size and
    orientation of the ellipse are defined by two radii
    (<strong>rx</strong>, <strong>ry</strong>) and an
    <strong>x-axis-rotation</strong>, which indicates how the
    ellipse as a whole is rotated, in degrees, relative to the current
    coordinate system. The center (<strong>cx</strong>,
    <strong>cy</strong>) of the ellipse is calculated
    automatically to satisfy the constraints imposed by the
    other parameters. <strong>large-arc-flag</strong> and
    <strong>sweep-flag</strong> contribute to the automatic
    calculations and help determine how the arc is drawn.</td>
  </tr>
</table>

<div class="ready-for-wider-review">

<p>When a relative <strong>a</strong> command is used, the end point
of the arc is (<var>cpx</var> + <var>x</var>,
<var>cpy</var> + <var>y</var>).</p>

</div>

<p><span class="example-ref">Example arcs01</span> shows some
simple uses of arc commands within a path.</p>

<edit:example href='images/paths/arcs01.svg' name='arcs01' description='arc commands in path data' image='yes' link='yes'/>

<p>The elliptical arc command draws a section of an ellipse
which must meet the following constraints:</p>

<ul>
  <li>the arc starts at the current point</li>
  <li>the arc ends at point (<strong>x</strong>,
  <strong>y</strong>)</li>
  <li>the ellipse has the two radii (<strong>rx</strong>,
  <strong>ry</strong>)</li>
  <li>the x-axis of the ellipse is rotated by
  <strong>x-axis-rotation</strong> degrees relative to the x-axis of
  the current coordinate system.</li>
</ul>

<p>For most situations, there are actually four different arcs
(two different ellipses, each with two different arc sweeps)
that satisfy these constraints. <strong>large-arc-flag</strong>
and <strong>sweep-flag</strong> indicate which one of the four
arcs are drawn, as follows:</p>

<ul>
  <li>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
  <strong>large-arc-flag</strong> is '1', then one of the two
  larger arc sweeps will be chosen; otherwise, if
  <strong>large-arc-flag</strong> is '0', one of the smaller
  arc sweeps will be chosen,</li>

  <li>If <strong>sweep-flag</strong> is '1', then the arc will
  be drawn in a "positive-angle" direction (i.e., the ellipse
  formula x=<strong>cx</strong>+<strong>rx</strong>*cos(theta)
  and y=<strong>cy</strong>+<strong>ry</strong>*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)).</li>
</ul>

<p>The following illustrates the four combinations of
<strong>large-arc-flag</strong> and <strong>sweep-flag</strong>
and the four different arcs that will be drawn based on the
values of these flags. For each case, the following path data
command was used:</p>

<pre>
&lt;path d="M 125,75 a100,50 0 ?,? 100,50"
      style="fill:none; stroke:red; stroke-width:6"/&gt;
</pre>

<p>where "?,?" is replaced by "0,0" "0,1" "1,0" and "1,1" to
generate the four possible cases.</p>

<p><img alt="Illustration of flags in arc commands"
src="images/paths/arcs02.png" width="426" height="187" /></p>
<p class="view-as-svg"><a href="images/paths/arcs02.svg">View
this example as SVG (SVG-enabled browsers only)</a></p>

<p>Refer to <a
href="implnote.html#ArcImplementationNotes">Elliptical arc
implementation notes</a> for detailed implementation notes for
the path data elliptical arc commands.</p>


<h3 id="PathDataBNF">The grammar for path data</h3>

<p>SVG path data matches the following EBNF grammar.</p>
<pre class='grammar ready-for-wider-review'>
svg_path::= wsp* moveto? (moveto drawto_command*)?

drawto_command::=
    moveto
    | closepath
    | lineto
    | horizontal_lineto
    | vertical_lineto
    | curveto
    | smooth_curveto
    | quadratic_bezier_curveto
    | smooth_quadratic_bezier_curveto
    | elliptical_arc

moveto::=
    ( "M" | "m" ) wsp* coordinate_pair_sequence

closepath::=
    ("Z" | "z")

lineto::=
    ("L"|"l") wsp* coordinate_pair_sequence

horizontal_lineto::=
    ("H"|"h") wsp* coordinate_sequence

vertical_lineto::=
    ("V"|"v") wsp* coordinate_sequence

curveto::=
    ("C"|"c") wsp* curveto_coordinate_sequence

curveto_coordinate_sequence::=
    coordinate_pair_triplet
    | (coordinate_pair_triplet comma_wsp? curveto_coordinate_sequence)

smooth_curveto::=
    ("S"|"s") wsp* smooth_curveto_coordinate_sequence

smooth_curveto_coordinate_sequence::=
    coordinate_pair_double
    | (coordinate_pair_double comma_wsp? smooth_curveto_coordinate_sequence)

quadratic_bezier_curveto::=
    ("Q"|"q") wsp* quadratic_bezier_curveto_coordinate_sequence

quadratic_bezier_curveto_coordinate_sequence::=
    coordinate_pair_double
    | (coordinate_pair_double comma_wsp? quadratic_bezier_curveto_coordinate_sequence)

smooth_quadratic_bezier_curveto::=
    ("T"|"t") wsp* coordinate_pair_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::=
    number comma_wsp? number comma_wsp? number comma_wsp
    flag comma_wsp? flag comma_wsp? coordinate_pair

coordinate_pair_double::=
    coordinate_pair comma_wsp? coordinate_pair

coordinate_pair_triplet::=
    coordinate_pair comma_wsp? coordinate_pair comma_wsp? coordinate_pair

coordinate_pair_sequence::=
    coordinate_pair | (coordinate_pair comma_wsp? coordinate_pair_sequence)

coordinate_sequence::=
    coordinate | (coordinate comma_wsp? coordinate_sequence)

coordinate_pair::= coordinate comma_wsp? coordinate

coordinate::= sign? number

sign::= "+"|"-"
number ::= ([0-9])+
flag::=("0"|"1")
comma_wsp::=(wsp+ ","? wsp*) | ("," wsp*)
wsp ::= (#x9 | #x20 | #xA | #xC | #xD)
</pre>

<p>The processing of the EBNF must consume as much of a given
EBNF 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".</p>

<p>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".</p>

<p>Note that the EBNF allows the path data string in the
<a>'d'</a> property to be empty. This is not
an error, instead it disables rendering of the path.
Rendering is also disabled when the <a>'d'</a> property
has the value <span class='prop-value'>none</span>.</p>

<p class="ready-for-wider-review">
If path data not matching the grammar is encountered, then the path data is in error
(see <a href="paths.html#PathDataErrorHandling">Error Handling</a>).
</p>

<div class="ready-for-wider-review">
<h2 id="PathDirectionality">Path directionality</h2>

<p>Some features, such as the <a href="painting.html#OrientAttribute">orientation</a>
of <a>markers</a> and the <a href="painting.html#TermCapShape">shapes</a> of
<a href="painting.html#LineCaps">line caps</a>, are defined in terms of
the direction of the path at a given distance along the path or at the
start or end of an individual segment.</p>

<p>The <dfn id="TermPathDirection">direction of a path</dfn> at a specified
distance along the path is defined as follows:</p>

<ul>
  <li>If the given distance is zero, then the direction of the path is
  the <a href="#TermPathSegmentStartDirection">direction at the start of
  the path's first segment</a>.</li>

  <li>Otherwise, if the given distance is the length of the path, then
  the direction of the path is the
  <a href="#TermPathSegmentEndDirection">direction at the end of the path's
  last segment</a>.</li>

  <li>Otherwise, if the given distance along the path occurs at a path
  segment boundary, then the direction of the path is the
  <a href="#TermPathSegmentStartDirection">direction at the start of
  the segment at the given distance</a>, considering each segment to
  be endpoint exclusive.

  <div class="note">This will "move past"
  zero length segments, and choose the later segment if the distance
  is at the boundary between two non-zero length segments.</div>
  <div class="note">The default direction at segment boundaries is overriden
  when calculating a <a>cap shape</a> and when <a href="painting.html#RenderingMarkers">rendering markers</a>.
  </div></li>

  <li>Otherwise, the given distance along the path occurs in the middle
  of a non-zero length <a>path segment</a>.  The direction is simply the direction
  of the curve at that point.  If the point lies at a discontinuity, such as
  a cusp in a Bézier segment, then the direction is undefined; in this case,
  a direction between the incoming and outgoing direction around the discontinuity
  should be used.</li>
</ul>

<p>The <dfn id="TermPathSegmentStartDirection">direction at the start
of a <a>path segment</a></dfn> is defined as follows:</p>

<ul>
  <li>If length of the entire path the segment belongs to is zero, then the
  direction at the start of the segment points in the same direction as the
  positive x-axis.</li>

  <li>Otherwise, if the <a>path segment</a> is zero length and the segment does not
  have any preceding non-zero length segments, then the direction at the
  start of the segment is the same as the
  <a href="#TermPathSegmentEndDirection">direction at the end of the segment</a>.</li>

  <li>Otherwise, if the <a>path segment</a> is zero length and there is some non-zero
  length segment preceding this segment, then the direction at the start of
  this segment is the same as the
  <a href="#TermPathSegmentEndDirection">direction at the end of the closest
  preceding non-zero length segment</a>.</li>

  <li>Otherwise, the <a>path segment</a> is non-zero length.  The direction at the
  start of the segment is simply the direction coming out of the segment's start
  point.</li>
</ul>

<p>The <dfn id="TermPathSegmentEndDirection">direction at the end of a path
segment</dfn> is defined as follows:</p>

<ul>
  <li>If length of the entire path the segment belongs to is zero, then the
  direction at the end of the segment points in the same direction as the
  positive x-axis.</li>

  <li>Otherwise, if the <a>path segment</a> is zero length and the segment does not
  have any following non-zero length segments, then the direction at the
  end of the segment is the same as the
  <a href="#TermPathSegmentStartDirection">direction at the start of the segment</a>.</li>

  <li>Otherwise, if the <a>path segment</a> is zero length and there is some non-zero
  length segment following this segment, then the direction at the end of
  this segment is the same as the
  <a href="#TermPathSegmentStartDirection">direction at the start of the closest
  following non-zero length segment</a>.</li>

  <li>Otherwise, the <a>path segment</a> is non-zero length.  The direction at the
  end of the segment is simply the direction coming in to the segment's end
  point.</li>
</ul>
</div>


<h2 id="PathElementImplementationNotes">Implementation notes</h2>

<h3 id="PathDataErrorHandling">Error handling in path data</h3>

<p>A conforming SVG user agent must implement path rendering as follows:</p>

<ul>
  <li>
    Error handling:
    <ul>
      <li>The general rule for error handling in path data is
      that the SVG user agent shall render a <a>'path'</a> element up
      to (but not including) the path command containing the
      first error in the path data specification. This will
      provide a visual clue to the user or developer about
      where the error might be in the path data specification.
      This rule will greatly discourage generation of invalid
      SVG path data.</li>

      <li>If a path data command contains an incorrect set of
      parameters, then the given path data command is rendered
      up to and including the last correctly defined <a>path segment</a>,
      even if that <a>path segment</a> is a sub-component of
      a compound path data command, such as a "lineto" with
      several pairs of coordinates. For example, for the path
      data string <span class='attr-value'>'M 10,10 L 20,20,30'</span>,
      there is an odd number of parameters for the "L" command, which requires an even
      number of parameters. The user agent is required to draw
      the line from (10,10) to (20,20) and then perform error
      reporting since <span class='attr-value'>'L 20 20'</span>
      is the last correctly defined segment of the path data specification.</li>

      <li>Wherever possible, all SVG user agents shall report
      all errors to the user.</li>
    </ul>
  </li>
  <li>
    Markers and zero-length <a>path segments</a>:
    <ul>
      <li>If markers are specified, then a marker is drawn on
      every applicable vertex, even if the given vertex is the
      end point of a zero-length <a>path segment</a> and even if
      "moveto" commands follow each other.</li>

      <li>As mentioned in <a href="painting.html#StrokeProperties">Stroke Properties</a>,
      linecaps must be painted for zero length subpaths when
      <a>'stroke-linecap'</a> has a value of
      <span class='prop-value'>round</span> or
      <span class='prop-value'>square</span>.</li>
    </ul>
  </li>
  <li>
    The S/s commands indicate that the first control point of
    the given cubic Bézier segment is calculated by
    reflecting the previous <a>path segments</a> second control point
    relative to the current point. The exact math is as
    follows. If the current point is (<var>curx</var>, <var>cury</var>) and the
    second control point of the previous <a>path segment</a> is
    (<var>oldx2</var>, <var>oldy2</var>), then the reflected point (i.e., (<var>newx1</var>,
    <var>newy1</var>), the first control point of the current <a>path
    segment</a>) is:
<pre>
(newx1, newy1) = (curx - (oldx2 - curx), cury - (oldy2 - cury))
               = (2*curx - oldx2, 2*cury - oldy2)
</pre>
  </li>

  <li>A non-positive radius value is an error.</li>

  <li>Unrecognized contents within a path data stream (i.e.,
  contents that are not part of the path data grammar) is an
  error.</li>
</ul>

<h2 id="DistanceAlongAPath">Distance along a path</h2>

<p>Various operations, including <a
href="text.html#TextLayoutPath">text on a path</a> and <a
href="https://svgwg.org/specs/animations/#AnimateMotionElement">motion animation</a>
and various <a href="painting.html#StrokeProperties">stroke
operations</a>, require that the user agent compute the
distance along the geometry of a graphics element, such as a <a>'path'</a>.</p>

<p>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 <a>'pathLength'</a> 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 <a>'pathLength'</a> to the user agent's own
computed value for total path length.</p>

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

<h3 id="PathLengthAttribute">The <span class="attr-name">'pathLength'</span> attribute</h3>

<dl class="attrdef-list">
  <dt>
    <table class="attrdef def">
      <tr>
        <th>Name</th>
        <th>Value</th>
        <th>Initial value</th>
        <th>Animatable</th>
      </tr>
      <tr>
        <td><dfn data-dfn-type="element-attr">pathLength</dfn></td>
        <td><a>&lt;number&gt;</a></td>
        <td>(none)</td>
        <td>yes</td>
      </tr>
    </table>
  </dt>
  <dd>
    <p>The author's computation of the total length of the
    path, in user units. This value is used to calibrate the
    user agent's own <a href="paths.html#DistanceAlongAPath">distance-along-a-path</a>
    calculations with that of the author. The user agent will
    scale all distance-along-a-path computations by the ratio
    of <a>'pathLength'</a> to the user
    agent's own computed value for total path length. <a>'pathLength'</a> potentially affects
    calculations for <a href="text.html#TextLayoutPath">text on a path</a>,
    <a href="https://svgwg.org/specs/animations/#AnimateMotionElement">motion animation</a> and
    various <a href="painting.html#StrokeProperties">stroke operations</a>.</p>
    <p class="ready-for-wider-review">
    A value of zero is valid and must be treated as a scaling factor of infinity.
    A value of zero scaled infinitely must remain zero, while any value greater
    than zero must become +Infinity.
    </p>
    <p>A negative value is an error (see <a href="paths.html#PathDataErrorHandling">Error handling</a>).</p>
  </dd>
</dl>


</edit:with>

<div class='ready-for-wider-review'>
<h2 id="DOMInterfaces">DOM interfaces</h2>

<h3 id="InterfaceSVGPathElement">Interface SVGPathElement</h3>

<edit:with element="path">
<p>An <a>SVGPathElement</a> object represents a <a>'path'</a> in the DOM.</p>

<pre class="idl">[Exposed=Window]
interface <b>SVGPathElement</b> : <a>SVGGeometryElement</a> {
};</pre>

</edit:with>
</div>

</body>
</html>