8 Coordinate Systems, Transformations and Units


8.1 Introduction

Each SVG drawing has a parent (real or implicit) into which the SVG drawing is placed. The parent provides a rectangular viewport into which the SVG drawing will be drawn. All SVG graphical objects are drawn onto the SVG canvas, which is mapped onto the viewport. The canvas always has a current coordinate system which determines how coordinates and attributes are mapped onto the canvas. (See drawing below.)

The current coordinate system can be modified at any place in the SVG drawing by specifying transformations in the form of transformation matrices or simple transformation operations such as rotation, skewing, scaling and translation.

All coordinates and lengths in SVG can be specified in any of a number of units, which correspond closely to the set of units available in CSS.

(Insert drawing here.)

8.2 Viewport space

Each SVG drawing has an explicit or an implicit parent which provides a rectangular viewport into which the SVG drawing should be placed. The coordinate system of the parent at the time when the rectangular viewport is defined is called viewport space.

Viewport space is conceptually equivalent to the term device space from the PostScript and PDF languages. The term viewport space is used because SVG is often drawn into a viewport provided by an HTML or XML document rather than directly drawn onto a device such as a printer.

One important example of a parent is an HTML or XML document which includes (either inline or via a URL reference) an SVG drawing. Typically, the HTML or XML document will define a rectangular viewport using the positioning and sizing features from CSS [???]. For example:

<?xml version="1.0"?>
<parent xmlns="http://...">
   ...
   <g xmlns="http://www.w3.org/...svg1.0"
      style="position: absolute;
             left: 2cm; top: 2cm;
             width: 10cm; height: 6cm">
      <!-- SVG graphics would go here -->
   </g>
   ...
</parent>

In the above example, an SVG drawing (the <g> element) is placed inline within a XML document. The viewport for the SVG drawing is established using CSS positioning (i.e., style="position: absolute; left: 2cm; top: 2cm; width: 10cm; height: 6cm"). In this example, the viewport space is the untransformed CSS coordinate system. The viewport for the SVG drawing, expressed in viewport space, has a top/left of (2cm,2cm) and a bottom right of (12cm,8cm).

In other situations, the parent document might have an entirely different coordinate system. For example, suppose one SVG drawing (SVG drawing A) embeds another SVG drawing (SVG drawing B) as follows:

<?xml version="1.0"?>
<!-- This is SVG drawing A. -->
<g xmlns="http://www.w3.org/...svg1.0"
   style="position: absolute;
          left: 2cm; top: 2cm; width: 10cm; height: 6cm">

   <!-- ...The coordinate system gets modified here... -->

   <!-- The following statement establishing a new viewport
        and renders SVG drawing B into that viewport -->
   <g style="left: 25%; top: 25%; width: 50%; height: 50%"
      href="B.svg"/>
</g>

In this example, the viewport spaces for A and B are different. The viewport space for drawing A is the untransformed CSS coordinate space and the viewport for drawing A (in viewport space units) has its left/top at (2cm, 2cm) and right/bottom at (12cm,8cm). The viewport space for drawing B, however, is the current user space (see User space below) that is in place at the point where the element <g style="left: 25%; top: 25%; width: 50%; height: 50%" href="B.svg"/> is processed.

(Insert a drawing here.)

8.3 User space

In SVG, all graphical elements are drawn onto a canvas which is mapped onto a viewport. The coordinate system used to position and size graphical objects onto the canvas is user space. All user space coordinates and lengths are resolution independent.

There is an implicit initial user space in place at the start of every SVG drawing. This initial user space defines how the canvas is mapped onto the viewport. The initial user space has the following characteristics:

To illustrate with a simple example:

<?xml version="1.0"?>
<g xmlns="http://www.w3.org/...svg1.0"
      style="position: absolute;
             left: 100pt; top: 100pt;
             width: 300pt; height: 200pt">

   <!-- ...The contents of the SVG drawing go here... -->

</g>

In the example above:

 Viewport's (left,top) cornerViewport's (bottom,right) corner
In viewport space(100pt,100pt)(400pt,300pt)
In initial user space(0,0)(300,200)

(Replace the above table with a drawing.)

8.4 Establishing a New Viewport: CSS positioning

At any point in an SVG drawing, you can establish a new viewport into which all contained graphics should be drawn. By establishing a new viewport, you implicitly also establish a new viewport space and thus a new initial user space. (Also, you might implicitly establish a new clipping path, although the details of this haven't been worked out yet. ??? add link to clipping path section.)

To establish a new viewport, you use the positioning properties from CSS such as left:, top:, right:, bottom:, width:, height:, margin properties and padding properties. Here is an example:

<?xml version="1.0"?>
<!-- This is SVG drawing A. -->
<g xmlns="http://www.w3.org/...svg1.0"
   style="position: absolute;
          left: 100pt; top: 100pt; width: 400pt; height: 200pt">

   <!-- ...The coordinate system gets modified here... -->

   <!-- The following statement establishing a new viewport
        and renders SVG drawing B into that viewport -->
   <g style="left: 25%; top: 25%; width: 50%; height: 50%"
      href="B.svg"/>
</g>

8.5 Establishing A New User Space: Transformations

To change the current user space coordinate system, you define a transformation which defines how to transform coordinates from the new user space coordinate system into the previous coordinate system. Mathematically, the transformation is represented by a transformation matrix which maps coordinates in the new user space coordinate system into the previous coordinate system. To illustrate:

(Insert an image which shows this concept.)

Transformation matrices define the mathematical mapping from one coordinate space into another. Of particular interest is the current transformation matrix (CTM) which defines the mapping from user space into viewport space.

(Insert an image showing the CTM mapping user space into device space.)

Transformation matrices are specified as 3x3 matrices of the following form:

(Insert an image showing [a b 0 c d 0 e f 1], but as a rectangular matrix.)

Because SVG's transformation matrices only have six entries that can be changed, these matrices will be called 2x3 transformation matrices, which for convenience are often written as an array of six numbers: [a b c d e f].

All coordinates in user space are expressed as (x,y) values. To calculate the transformation from the current user space coordinate system into viewport space, you multiply the vector (x,y,1) by the current transformation matrix (CTM) to yield (x',y',1):

(Insert an image showing [x',y',1]=[x,y,1][a b 0 c d 0 e f 1])

Whenever a new transformation is provided, a new CTM is calculated by the following formula. Note that the new transformation is pre-multiplied to the CTM:

(Insert an image which shows newCTM[a b c d e f]=[transformmatrix]*oldCTM[a b c d e f].)

It is important to understand the following key points regarding transformations in SVG:

Mathematically, all transformations can be expressed as matrices. To illustrate:

(Insert an image illustrates the above concept.)

8.6 Properties to Establish a New Viewport

(Extract sections from chapter 8 of the CSS spec. Make modifications as necessary.).

8.7 The 'transform' property: Establishing a New User Coordinate System

All transformations are specified with the transform CSS property:

'transform'
Value:   matrix(<a> <b> <c> <d> <e> <f>) |
translate(<tx> [<ty>]) |
scale(<sx> [<sy> [<center-x> [<center-y>]]]) |
rotate(<rotate-angle> [<center-x> [<center-y>]]) |
fit(<bbox-left> <bbox-top> <bbox-right> <bbox-bottom>
    [ preserve-aspect-ratio [ left | center | right ] [ top | middle | bottom ]]) |
inherit
Initial:   see discussion below
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

The 'transform' property defines a new coordinate system transformation and thus implicitly new user space and a new CTM. A transform property has exactly one of matrix, scale, rotate, translate, fit and inherit.

The parameters to matrix have the following meanings (see the explanation of simple transformations.):

<a> <b> <c> <d> <e> <f>
Specifies the transformation matrix which should be premultiplied to the old CTM to yield a new CTM. All values are real numbers.

The parameters to translate have the following meanings (see the explanation of simple transformations.): Translations are represented as [1 0 0 1 tx ty], where tx and ty are the distances to translate the origin of the coordinate system in x and y, respectively.

<tx> and <ty>
The distances to translate the origin of the coordinate system in x and y, respectively. If <ty> is not provided, it is assumed to be zero.

The parameters to scale have the following meanings (see the explanation of simple transformations.):

<sx> and <sy>
The factor used to scale the x and y coordinates so that one unit in the x and y directions of the new coordinate system is the same as <sx> and <sy> units in the previous coordinate system, respectively. If <sy> is not provided, it is assumed to be the same as <sx>.
<center-x> and <center-x>
The center point for the scaling operation, in the previous coordinate system. If a center point is provided, the resulting operation is as if the coordinate system were translated by [0 0 0 0 -<center-x> -<center-y>], then scaled, then translated again back to the center point. If either <center-x> or <center-y> is not provided, they default to zero.

The parameters to rotate have the following meanings (see the explanation of simple transformations.):

<rotate-angle>
The angle in degrees by which the coordinate system axes should be rotated (counterclockwise).
<center-x> and <center-x>
The center point for the rotation operation, in the previous coordinate system. If a center point is provided, the resulting operation is as if the coordinate system were translated by [0 0 0 0 -<center-x> -<center-y>], then rotated, then translated again back to the original center point. If either <center-x> or <center-y> is not provided, they default to zero.

(The working group is investigating providing convenience mechanisms for other simple transformations such as skew and reflect.)

fit provides a mechanism for having the SVG processor automatically compute a transformation matrix such that the coordinates <bbox-left> <bbox-top> <bbox-right> <bbox-bottom> (all <number>s) will align exactly with the corresponding corners of the viewport. You can specify preserve-aspect-ratio to ensure that the aspect ratio of the graphic is preserved (i.e., uniform scaling onto the viewport) and what kind of horizontal and vertical alignment within the viewport is desired.

<bbox-left> <bbox-top> <bbox-right> <bbox-bottom>
The bounding box of the graphic in the coordinate system of the current object. Typically (although this doesn't have to be the case), this is a rectangle which is defined to be just large enough to surround all drawn graphics for the current object and its children.
preserve-aspect-ratio
If present, then the transformations that are computed ensure that the aspect ratio of the graphic will be preserved (i.e., uniform scaling will be used to map the bbox onto the viewport).
left, center, right
If preserve-aspect-ratio is specified and the aspect ratio of the bbox does not match the aspect ratio of the viewport, and furthermore if the bbox's height/width is greater than the viewport's height/width, then either left, center or right justify the box inside the viewport, respectively.
top, middle, bottom
If preserve-aspect-ratio is specified and the aspect ratio of the bbox does not match the aspect ratio of the viewport, and furthermore if the bbox's height/width is less than the viewport's height/width, then either top, middle or bottom justify the box inside the viewport, respectively.

(Insert a drawing here.)

8.8 Units

All coordinates and lengths in SVG can be specified in one of the following ways:

8.9 Examples

(Include an example which shows multiple viewports, multiple user spaces and multiple use of different units.)