SVG 2 – 25 May 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 9: Basic Shapes

9.1. Introduction and definitions

basic shape
shape
shape elements
A graphics element that is defined by some combination of straight lines and curves. Specifically: circle, ellipse, line, path, polygon, polyline and rect.

SVG contains the following set of basic shape elements:

Mathematically, these shape elements are equivalent to a path element that would construct the same shape. The basic shapes may be stroked, filled and used as clip paths. All of the properties available for path elements also apply to the basic shapes.

The equivalent path and algorithm to compute the stroke for each shape are defined in the shape sections below.

9.2. The ‘rect’ element

The rect element defines a rectangle which is axis-aligned with the current local coordinate system. Rounded rectangles can be achieved by setting appropriate values for attributes rx and ry.

rect
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
Geometry properties:
DOM Interfaces:

The x and y coordinates refer to the left and top edges of the rectangle, in the current user coordinate system.

The width and height of the rectangle. A negative value for either attribute is an error (see Error processing). A value of zero for either attribute disables rendering of the element.

For rounded rectangles, the x- and y-axis radii of the ellipse used to round off the corners of the rectangle. A negative value for either attribute is an error (see Error processing).

The values used for the x- and y-axis rounded corner radii are determined implicitly if the rx or ry attributes (or both) are not specified, or are specified but with invalid values. The values are also subject to clamping so that the lengths of the straight segments of the rectangle are never negative. The effective values for rx and ry are determined by following these steps in order:

  1. Let rx and ry be length values.
  2. If neither rx nor ry are properly specified, then set both rx and ry to 0. (This will result in square corners.)
  3. Otherwise, if a properly specified value is provided for rx, but not for ry, then set both rx and ry to the value of rx.
  4. Otherwise, if a properly specified value is provided for ry, but not for rx, then set both rx and ry to the value of ry.
  5. Otherwise, both rx and ry were specified properly. Set rx to the value of rx and ry to the value of ry.
  6. If rx is greater than half of width, then set rx to half of width.
  7. If ry is greater than half of height, then set ry to half of height.
  8. The effective values of rx and ry are rx and ry, respectively.

Mathematically, a rect element is mapped to an equivalent path element as follows: (Note: all coordinate and length values are first converted into local coordinate system coordinates according to Units.)

Path decomposition resolved during teleconference on June 3rd, 2013.

Example rect01 shows a rectangle with sharp corners. The rect element is filled with yellow and stroked with navy.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example rect01 - rectangle with sharp corners</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2"/>

  <rect x="400" y="100" width="400" height="200"
        fill="yellow" stroke="navy" stroke-width="10"  />
</svg>
Example rect01 — rectangle with sharp corners

Example rect01

View this example as SVG (SVG-enabled browsers only)

Example rect02 shows two rounded rectangles. The rx specifies how to round the corners of the rectangles. Note that since no value has been specified for the ry attribute, it will be assigned the same value as the rx attribute.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example rect02 - rounded rectangles</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2"/>

  <rect x="100" y="100" width="400" height="200" rx="50"
        fill="green" />

  <g transform="translate(700 210) rotate(-30)">
    <rect x="0" y="0" width="400" height="200" rx="50"
          fill="none" stroke="purple" stroke-width="30" />
  </g>
</svg>
Example rect02 — rounded rectangles expressed in user coordinates

Example rect02

View this example as SVG (SVG-enabled browsers only)

9.3. The ‘circle’ element

The circle element defines a circle based on a center point and a radius.

circle
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
Geometry properties:
DOM Interfaces:

The cx and cy attributes define the coordinates of the center of the circle.

The r attribute defines the radius of the circle. A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Mathematically, a circle element is mapped to an equivalent path element that consists of four elliptical arc segments, each covering a quarter of the circle. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformations).

Path decomposition resolved during teleconference on June 3rd, 2013.

Example circle01 consists of a circle element that is filled with red and stroked with blue.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example circle01 - circle filled with red and stroked with blue</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2"/>

  <circle cx="600" cy="200" r="100"
        fill="red" stroke="blue" stroke-width="10"  />
</svg>
Example circle01 — circle filled with red and stroked with blue

Example circle01

View this example as SVG (SVG-enabled browsers only)

9.4. The ‘ellipse’ element

The ellipse element defines an ellipse which is axis-aligned with the current local coordinate system based on a center point and two radii.

ellipse
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
Geometry properties:
DOM Interfaces:

The cx and cy coordinates define the center of the ellipse.

The cx and cy attributes define the x- and y-axis radii of the ellipse. A negative value for either attribute is an error (see Error processing). A value of zero disables rendering of the element.

Mathematically, an ellipse element is mapped to an equivalent path element that consists of four elliptical arc segments, each covering a quarter of the ellipse. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformation).

Path decomposition resolved during teleconference on June 3rd, 2013.

Example ellipse01 below specifies the coordinates of the two ellipses in the user coordinate system established by the viewBox attribute on the svg element and the transform property on the g and ellipse elements. Both ellipses use the default values of zero for the cx and cy attributes (the center of the ellipse). The second ellipse is rotated.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example ellipse01 - examples of ellipses</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <g transform="translate(300 200)">
    <ellipse rx="250" ry="100"
          fill="red"  />
  </g>

  <ellipse transform="translate(900 200) rotate(-30)" 
        rx="250" ry="100"
        fill="none" stroke="blue" stroke-width="20"  />

</svg>
Example ellipse01 — ellipses expressed in user coordinates

Example ellipse01

View this example as SVG (SVG-enabled browsers only)

9.5. The ‘line’ element

The line element defines a line segment that starts at one point and ends at another.

line
Categories:
Graphics element, markable element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
x1, y1 <length> | <percentage> | <number> 0 yes
The x- and y-axis coordinates of the start of the line.
Name Value Initial value Animatable
x2, y2 <length> | <percentage> | <number> 0 yes
The x- and y-axis coordinates of the end of the line.

Mathematically, a line element can be mapped to an equivalent path element as follows: (Note: all coordinate and length values are first converted into local coordinate system coordinates according to Units.)

Because line elements are single lines and thus are geometrically one-dimensional, they have no interior; thus, line elements are never filled (see the fill property).

Example line01 below specifies the coordinates of the five lines in the user coordinate system established by the viewBox attribute on the svg element. The lines have different thicknesses.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example line01 - lines expressed in user coordinates</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <g stroke="green" >
    <line x1="100" y1="300" x2="300" y2="100"
            stroke-width="5"  />
    <line x1="300" y1="300" x2="500" y2="100"
            stroke-width="10"  />
    <line x1="500" y1="300" x2="700" y2="100"
            stroke-width="15"  />
    <line x1="700" y1="300" x2="900" y2="100"
            stroke-width="20"  />
    <line x1="900" y1="300" x2="1100" y2="100"
            stroke-width="25"  />
  </g>
</svg>
Example line01 — lines expressed in user coordinates

Example line01

View this example as SVG (SVG-enabled browsers only)

9.6. The ‘polyline’ element

The polyline element defines a set of connected straight line segments. Typically, polyline elements define open shapes.

polyline
Categories:
Graphics element, markable element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
points <points> (none) yes

where:

<points> =
[<number> ,? <number> ,?]+

The points that make up the polyline. All coordinate values are in the user coordinate system.

If an odd number of coordinates is provided, then the element is in error, with the same user agent behavior as occurs with an incorrectly specified path element. In such error cases the user agent will drop the last, odd coordinate and otherwise render the shape.

The initial value, (none), indicates that the polyline element is valid but does not render.

Mathematically, a polyline element can be mapped to an equivalent path element as follows:

Example polyline01 below specifies a polyline in the user coordinate system established by the viewBox attribute on the svg element.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example polyline01 - increasingly larger bars</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <polyline fill="none" stroke="blue" stroke-width="10" 
            points="50,375
                    150,375 150,325 250,325 250,375
                    350,375 350,250 450,250 450,375
                    550,375 550,175 650,175 650,375
                    750,375 750,100 850,100 850,375
                    950,375 950,25 1050,25 1050,375
                    1150,375" />
</svg>
Example polyline01 — increasingly larger bars

Example polyline01

View this example as SVG (SVG-enabled browsers only)

9.7. The ‘polygon’ element

The polygon element defines a closed shape consisting of a set of connected straight line segments.

polygon
Categories:
Graphics element, markable element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
points <points> (none) yes

The points that make up the polygon. All coordinate values are in the user coordinate system.

If an odd number of coordinates is provided, then the element is in error, with the same user agent behavior as occurs with an incorrectly specified path element.

The initial value, (none), indicates that the polygon element is valid, but does not render.

Mathematically, a polygon element can be mapped to an equivalent path element as follows:

Example polygon01 below specifies two polygons (a star and a hexagon) in the user coordinate system established by the viewBox attribute on the svg element.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example polygon01 - star and hexagon</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <polygon fill="red" stroke="blue" stroke-width="10" 
            points="350,75  379,161 469,161 397,215
                    423,301 350,250 277,301 303,215
                    231,161 321,161" />
  <polygon fill="lime" stroke="blue" stroke-width="10" 
            points="850,75  958,137.5 958,262.5
                    850,325 742,262.6 742,137.5" />
</svg>
Example polygon01 — star and hexagon

Example polygon01

View this example as SVG (SVG-enabled browsers only)

9.8. DOM interfaces

9.8.1. Interface SVGRectElement

An SVGRectElement object represents a rect element in the DOM.

interface SVGRectElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGAnimatedLength rx;
  [SameObject] readonly attribute SVGAnimatedLength ry;
};

The x, y, width, height, rx and ry IDL attributes reflect the computed values of the x, y, width, height, rx and ry properties and their corresponding presentation attributes, respectively.

9.8.2. Interface SVGCircleElement

An SVGCircleElement object represents a circle element in the DOM.

interface SVGCircleElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength cx;
  [SameObject] readonly attribute SVGAnimatedLength cy;
  [SameObject] readonly attribute SVGAnimatedLength r;
};

The cx, cy and r IDL attributes reflect the computed values of the cx, cy and y properties and their corresponding presentation attributes, respectively.

9.8.3. Interface SVGEllipseElement

An SVGEllipseElement object represents a ellipse element in the DOM.

interface SVGEllipseElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength cx;
  [SameObject] readonly attribute SVGAnimatedLength cy;
  [SameObject] readonly attribute SVGAnimatedLength rx;
  [SameObject] readonly attribute SVGAnimatedLength ry;
};

The cx, cy, rx and ry IDL attributes reflect the computed values of the cx, cy, rx and ry properties and their corresponding presentation attributes, respectively.

9.8.4. Interface SVGLineElement

The SVGLineElement interface corresponds to the line element.
interface SVGLineElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength x1;
  [SameObject] readonly attribute SVGAnimatedLength y1;
  [SameObject] readonly attribute SVGAnimatedLength x2;
  [SameObject] readonly attribute SVGAnimatedLength y2;
};

The x1, y1, x2 and y2 IDL attributes reflect the x1, y1, x2 and y2 content attributes, respectively

9.8.5. Interface SVGAnimatedPoints

The SVGAnimatedPoints interface is used to reflect a points attribute on a polygon or polyline element. It is mixed in to the SVGPolygonElement and SVGPolylineElement interfaces.

Note: In SVG 1.1 SE, the animatedPoints attribute represented the current animated value. In this version of SVG, it is simply an alias for points.

[NoInterfaceObject]
interface SVGAnimatedPoints {
  [SameObject] readonly attribute SVGPointList points;
  [SameObject] readonly attribute SVGPointList animatedPoints;
};

The points and animatedPoints IDL attributes represent the current non-animated value of the reflected attribute. On getting points or animatedPoints, an SVGPointList object is returned that reflects the base value of the reflected attribute.

9.8.6. Interface SVGPointList

The SVGPointList interface is a list interface whose elements are DOMPoint objects. An SVGPointList object represents a list of points.

interface SVGPointList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  DOMPoint initialize(DOMPoint newItem);
  getter DOMPoint getItem(unsigned long index);
  DOMPoint insertItemBefore(DOMPoint newItem, unsigned long index);
  DOMPoint replaceItem(DOMPoint newItem, unsigned long index);
  DOMPoint removeItem(unsigned long index);
  DOMPoint appendItem(DOMPoint newItem);
  setter void (unsigned long index, DOMPoint newItem);
};

The behavior of all of the interface members of SVGPointList are defined in List interfaces.

This specification imposes additional requirements on the behaviour of DOMPoint objects beyond those described in the the Geometry Interfaces specification, so that they can be used to reflect points attributes.

Every DOMPoint object operates in one of three modes. It can:

  1. reflect an element of the base value of a reflected animatable attribute (being exposed through the methods on the points member of an SVGAnimatedPoints),
  2. represent the current translation of a given svg element (being exposed through the currentTranslate member on SVGSVGElement), or
  3. be detached, which is the case for DOMPoint objects created using their constructor or with createSVGPoint.

A DOMPoint object can be associated with a particular element. The associated element is used to determine which element's content attribute to update if the object reflects an attribute. Unless otherwise described, a DOMPoint object is not associated with any element.

A DOMPoint object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. When assigning to a read only DOMPoint's x, y, w or z IDL attribute, a NoModificationAllowedError must be thrown instead of updating the internal coordinate value.

Note that this applies only to the read-write DOMPoint interface; the DOMPointReadOnly interface, which is not used for reflecting the points attribute, will already throw an exception if an attempt is made to modify it.

When assigning to a writable DOMPoint's x, y, w or z IDL attribute, the following steps are run after updating the internal coordinate value:

  1. If the DOMPoint reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute using the SVGPointList that reflects the attribute's base value.
  2. Otherwise, if the DOMPoint represents the current translation of an svg element and that element is the outermost svg element, then:
    1. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
    2. Let x and y be the x and y coordinates of the DOMPoint object, respectively.
    3. Set the document's magnification and panning transform to [a 0 0 d x y].

9.8.7. Interface SVGPolylineElement

An SVGPolylineElement object represents a polyline element in the DOM.

interface SVGPolylineElement : SVGGeometryElement {
};

SVGPolylineElement implements SVGAnimatedPoints;

9.8.8. Interface SVGPolygonElement

An SVGPolygonElement object represents a polygon element in the DOM.

interface SVGPolygonElement : SVGGeometryElement {
};

SVGPolygonElement implements SVGAnimatedPoints;
SVG 2 – 25 May 2016 TopContentsPreviousNextElementsAttributesProperties