Basic Shapes

Introduction

SVG contains the following set of basic shape elements:

rectangles (including optional rounded corners), created with the 'rect' element,
circles, created with the 'circle' element,
ellipses, created with the 'ellipse' element,
straight lines, created with the 'line' element,
polylines, created with the 'polyline' element, and
polygons, created with the 'polygon' element.

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.

We should define the equivalent path for each shape (and for text?). The algorithm that computes the stroke shape for an element refers to the equivalent path for the element, so that it is clear for example where dashing would start.

The 'rect' element

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

Attribute definitions:

Name Value Lacuna value Animatable x, y <length> 0 yes

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

Name Value Lacuna value Animatable width, height <length> 0 yes

Name	Value	Lacuna value	Animatable
x, y	<length>	0	yes

Name	Value	Lacuna value	Animatable
width, height	<length>	0	yes

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.

Name Value Lacuna value Animatable rx, ry <length> (see below) yes

Name	Value	Lacuna value	Animatable
rx, ry	<length>	(see below)	yes

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:

Let rx and ry be length values.
If neither 'rx' nor 'ry' are properly specified, then set both rx and ry to 0. (This will result in square corners.)
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'.
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'.
Otherwise, both 'rx' and 'ry' were specified properly. Set rx to the value of 'rx' and ry to the value of 'ry'.
If rx is greater than half of 'width', then set rx to half of 'width'.
If ry is greater than half of 'height', then set ry to half of 'height'.
The effective values of 'rx' and 'ry' are rx and ry, respectively.

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

perform an absolute moveto operation to location (x+rx,y), where x is the value of the 'rect' element's 'x' attribute converted to user space, rx is the effective value of the 'rx' attribute converted to user space and y is the value of the 'y' attribute converted to user space
perform an absolute horizontal lineto operation to location (x+width-rx,y), where width is the 'rect' element's 'width' attribute converted to user space
perform an absolute elliptical arc operation to coordinate (x+width,y+ry), where the effective values for the 'rx' and 'ry' attributes on the 'rect' element converted to user space are used as the rx and ry attributes on the elliptical arc command, respectively, the x-axis-rotation is set to zero, the large-arc-flag is set to zero, and the sweep-flag is set to one
perform a absolute vertical lineto to location (x+width,y+height-ry), where height is the 'rect' element's 'height' attribute converted to user space
perform an absolute elliptical arc operation to coordinate (x+width-rx,y+height)
perform an absolute horizontal lineto to location (x+rx,y+height)
perform an absolute elliptical arc operation to coordinate (x,y+height-ry)
perform an absolute absolute vertical lineto to location (x,y+ry)
perform an absolute elliptical arc operation to coordinate (x+rx,y)

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

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.

The 'circle' element

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

Attribute definitions:

Name Value Lacuna value Animatable cx, cy <length> 0 yes: The coordinates of the center of the circle.
Name Value Lacuna value Animatable r <length> 0 yes: The radius of the circle. A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Name	Value	Lacuna value	Animatable
cx, cy	<length>	0	yes

Name	Value	Lacuna value	Animatable
r	<length>	0	yes

The arc of a 'circle' element begins at the "3 o'clock" point on the radius and progresses towards the "9 o'clock" point. The starting point and direction of the arc are affected by the user space transform in the same manner as the geometry of the element.

Saying that it progresses towards the "9 o'clock point" is slightly unclear, since it doesn't say whether it goes clockwise or anti-clockwise. Maybe "progresses" implies clockwise, but it should say either way. (There is similar wording in the 'ellipse' section too.)

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

The 'ellipse' element

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

Attribute definitions:

Name Value Lacuna value Animatable cx, cy <length> 0 yes: The coordinates of the center of the ellipse.
Name Value Lacuna value Animatable rx, ry <length> 0 yes: 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.

Name	Value	Lacuna value	Animatable
cx, cy	<length>	0	yes

Name	Value	Lacuna value	Animatable
rx, ry	<length>	0	yes

The arc of an 'ellipse' element begins at the "3 o'clock" point on the radius and progresses towards the "9 o'clock" point. The starting point and direction of the arc are affected by the user space transform in the same manner as the geometry of the element.

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.

The 'line' element

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

Attribute definitions:

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

Name	Value	Lacuna value	Animatable
x1, y1	<length>	0	yes

Name	Value	Lacuna value	Animatable
x2, y2	<length>	0	yes

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

perform an absolute moveto operation to absolute location (x1,y1), where x1 and y1 are the values of the 'line' element's 'x1' and 'y1' attributes converted to user space, respectively
perform an absolute lineto operation to absolute location (x2,y2), where x2 and y2 are the values of the 'line' element's 'x2' and 'y2' attributes converted to user space, respectively

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.

The 'polyline' element

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

Attribute definitions:

Name Value Lacuna value Animatable points <list-of-points> (none) yes

Name	Value	Lacuna value	Animatable
points	<list-of-points>	(none)	yes

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.

The lacuna 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:

perform an absolute moveto operation to the first coordinate pair in the list of points
for each subsequent coordinate pair, perform an absolute lineto operation to that coordinate pair.

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

The 'polygon' element

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

Attribute definitions:

Name Value Lacuna value Animatable points <list-of-points> (none) yes

Name	Value	Lacuna value	Animatable
points	<list-of-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 lacuna 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:

perform an absolute moveto operation to the first coordinate pair in the list of points
for each subsequent coordinate pair, perform an absolute lineto operation to that coordinate pair
perform a closepath command

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.

The grammar for points specifications in 'polyline' and 'polygon' elements

The following is the Extended Backus-Naur Form (EBNF) for points specifications in 'polyline' and 'polygon' elements. The following notation is used:

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

list-of-points:
    wsp* coordinate-pairs? wsp*
coordinate-pairs:
    coordinate-pair
    | coordinate-pair comma-wsp coordinate-pairs
coordinate-pair:
    coordinate comma-wsp coordinate
    | coordinate negative-coordinate
coordinate:
    number
number:
    sign? integer-constant
    | sign? floating-point-constant
negative-coordinate:
    "-" integer-constant
    | "-" floating-point-constant
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"

If data not matching the grammar is encountered, then the points specification is in error (see Error Processing).

DOM interfaces

Interface SVGRectElement

The SVGRectElement interface corresponds to the 'rect' element.

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

Attributes:

x (readonly SVGAnimatedLength): Corresponds to attribute 'x' on the given 'rect' element.
y (readonly SVGAnimatedLength): Corresponds to attribute 'y' on the given 'rect' element.
width (readonly SVGAnimatedLength): Corresponds to attribute 'width' on the given 'rect' element.
height (readonly SVGAnimatedLength): Corresponds to attribute 'height' on the given 'rect' element.
rx (readonly SVGAnimatedLength): Corresponds to attribute 'rx' on the given 'rect' element.
ry (readonly SVGAnimatedLength): Corresponds to attribute 'ry' on the given 'rect' element.

Interface SVGCircleElement

The SVGCircleElement interface corresponds to the 'circle' element.

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

Attributes:

cx (readonly SVGAnimatedLength): Corresponds to attribute 'cx' on the given 'circle' element.
cy (readonly SVGAnimatedLength): Corresponds to attribute 'cy' on the given 'circle' element.
r (readonly SVGAnimatedLength): Corresponds to attribute 'r' on the given 'circle' element.

Interface SVGEllipseElement

The SVGEllipseElement interface corresponds to the 'ellipse' element.

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

Attributes:

cx (readonly SVGAnimatedLength): Corresponds to attribute 'cx' on the given 'ellipse' element.
cy (readonly SVGAnimatedLength): Corresponds to attribute 'cy' on the given 'ellipse' element.
rx (readonly SVGAnimatedLength): Corresponds to attribute 'rx' on the given 'ellipse' element.
ry (readonly SVGAnimatedLength): Corresponds to attribute 'ry' on the given 'ellipse' element.

Interface SVGLineElement

The SVGLineElement interface corresponds to the 'line' element.

interface SVGLineElement : SVGGeometryElement {
  readonly attribute SVGAnimatedLength x1;
  readonly attribute SVGAnimatedLength y1;
  readonly attribute SVGAnimatedLength x2;
  readonly attribute SVGAnimatedLength y2;
};

SVGLineElement implements SVGMarkableElement;

Attributes:

x1 (readonly SVGAnimatedLength): Corresponds to attribute 'x1' on the given 'line' element.
y1 (readonly SVGAnimatedLength): Corresponds to attribute 'y1' on the given 'line' element.
x2 (readonly SVGAnimatedLength): Corresponds to attribute 'x2' on the given 'line' element.
y2 (readonly SVGAnimatedLength): Corresponds to attribute 'y2' on the given 'line' element.

Interface SVGAnimatedPoints

The SVGAnimatedPoints interface supports elements which have a 'points' attribute which holds a list of coordinate values and which support the ability to animate that attribute.

Additionally, the 'points' attribute on the original element accessed via the XML DOM (e.g., using the getAttribute() method call) will reflect any changes made to points.

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

Attributes:

points (readonly SVGPointList): Provides access to the base (i.e., static) contents of the 'points' attribute.
animatedPoints (readonly SVGPointList): Provides access to the current animated contents of the 'points' attribute. If the given attribute or property is being animated, contains the current animated value of the attribute or property. If the given attribute or property is not currently being animated, contains the same value as points.

Interface SVGPolylineElement

The SVGPolylineElement interface corresponds to the 'polyline' element.

interface SVGPolylineElement : SVGGeometryElement {
};

SVGPolylineElement implements SVGAnimatedPoints;
SVGPolylineElement implements SVGMarkableElement;

Interface SVGPolygonElement

The SVGPolygonElement interface corresponds to the 'polygon' element.

interface SVGPolygonElement : SVGGeometryElement {
};

SVGPolygonElement implements SVGAnimatedPoints;
SVGPolygonElement implements SVGMarkableElement;