7 Coordinate Systems, Transformations and Units


Contents


 

7.1 Introduction

For all media, the SVG document canvas describes "the space where the SVG document is rendered." The canvas is infinite for each dimension of the space, but rendering occurs relative to a finite rectangular region of the canvas. This finite rectangular region is called the SVG document viewport. For visual media, the SVG document viewport is the viewing area where the user sees the SVG document.

The size of the SVG document viewport (i.e., its width and height) is determined by a negotiation process (see Establishing the size of the initial viewport) between the SVG document and its parent (real or implicit). Once that negotiation process is completed, the SVG user agent is provided the following information:

Using the above information, the SVG user agent determines the viewport, an initial viewport coordinate system and an initial user coordinate system such that the two coordinates systems are identical. Both coordinates systems are established such that the origin matches the origin of the viewport, and one unit in the initial coordinate system equals one "pixel" in the viewport. (The viewport coordinate system is also called viewport space and and the user coordinate system is also called user space.)

Lengths in SVG can be specified as:

The supported CSS length unit specifiers are: em, ex, px, pt, pc, cm, mm, in, and percentages.

A new user space (i.e., a new current coordinate system) can be established at any place in the SVG document by specifying transformations in the form of transformation matrices or simple transformation operations such as rotation, skewing, scaling and translation. Establishing new user spaces via transformation operations are fundamental operations to 2D graphics and represent the typical way of controlling the size, position, rotation and skew of graphic objects.

New viewports also can be established, but are for more specialized uses. By establishing a new viewport, you can redefine the meaning of some of the various CSS unit specifiers (px, pt, pc, cm, mm, in, and percentages) and provide a new reference rectangle for "fitting" a graphic into a particular rectangular area. ("Fit" means that a given graphic is transformed in such a way that its bounding box in user space aligns exactly with the edges of a given viewport.)

7.2 Establishing the initial viewport

The SVG user agent negotiates with its parent user agent using any CSS positioning parameters on the <svg> element and the width= and height= XML attributes that are required on the <svg> element to determine the viewport ito which the SVG user agent can render the document. The size (i.e., width and height) of the viewport is determined as follows. If the outermost <svg> element contains CSS positioning properties which establish the width for the viewport, then the width of the viewport should be set to that size. If the CSS positioning properties on the outermost <svg> element do not provide sufficient information to determine the width of the viewport, then the XML attributes width= determines the width of the viewport. Similarly, if the outermost <svg> element contains CSS positioning properties which establish the height for the viewport, then the height of the viewport should be set to that size. If the CSS positioning properties on the <svg> element do not provide sufficient information to determine the height of the viewport, then the XML attributes height= determines the height of the viewport.

In the following example, an SVG graphic is embedded within a parent XML document which is formatted using CSS layout rules. The width="100px" and height="200px" attributes are used to determine the initial viewport:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://some.url">
   
   <!-- SVG graphic -->
   <svg xmlns='http://www.w3.org/Graphics/SVG/svg-19990730.dtd'
      width="100px" height="200px">
      <path d="M100,100 Q200,400,300,100"/>
      <!-- rest of SVG graphic would go here -->
   </svg>   
   
</parent>

Download this example

The initial clipping path for an SVG document is determined by the actual values of the 'clip' and 'overflow' properties that apply to the outermost <svg> element. (These concepts and properties are defined in the Cascading Style Sheets, level 2 CSS2 Specification.)

7.3 Establishing A New User Coordinate System: Transformations

To change the current user space coordinate system, you define a transformation which defines how to transform coordinates from the new user coordinate system into the previous user coordinate system. Mathematically, the transformation is represented by a transformation matrix which maps coordinates in the new user coordinate system into the previous user 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:


A: Original

Untransformed image

B: transform="translate(10,5)"

Translated image

C: transform="scale(1.25)"

Scaled image

D: transform="rotate(20)"

Rotated image

E: transform="skewX(30)"

Skewed in X image

F: transform="skewY(30)"

Skewed in Y image

7.4 Establishing an Initial User Coordinate System: the fitBoxToViewport attribute

Various SVG elements have the effect of establishing a new viewport:

It is very common to have the requirement that a given SVG document, <symbol>, <marker> or <pattern> should be scaled automatically to fit within a target rectangle. The fitBoxToViewport="<min-x> <min-y> <width> <height>" attribute on the <svg> and <symbol> elements indicates that an initial coordinate system should be established such that the given rectangle in user space (specified by the four numbers <min-x> <min-y> <width> <height>) maps exactly to the bounds of the viewport. For example:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990730.dtd">
<svg width="4in" height="3in" fitBoxToViewport"0 0 40 30">
  <desc>This SVG drawing uses the fitBoxToViewport 
   attribute to automatically create an initial user coordinate
   system which causes the graphic to scale to fit into the
   viewport no matter what size the viewport is.
  </desc>
  <!-- This rectangle goes from (0,0) to (40,30) in user space.
       Because of the fitBoxToViewport attribute above,
       the rectangle will end up filling the entire area
       reserved for the SVG document. -->
  <rect x="0" y="0" width="40" height="30" style="fill: blue" />
</svg>

Download this example

In some cases, it is necessary that the aspect ratio of the graphic be retained when utilizing fitBoxToViewport. A supplemental attribute preserveAspectRatio="<align> [<meetOrSlice>]" indicates whether or not to preserve the aspect ratio of the original graphic. The <align> parameter indicates whether to preserve aspect ratio and what alignment method should be used if aspect ratio is preserved. The <align> parameter must be one of the following strings:

The <meetOrSlice> parameter is optional and must be one of the following strings:

7.5 Modifying the User Coordinate System: the transform attribute

All modifications to the user coordinate system are specified with the transform attribute: The transform attribute defines a new coordinate system transformation and thus implicitly a new user space and a new CTM. A transform attribute takes a list of transformations, which are applied in the order provided. The available transformations include:

All values are real numbers.

If a list of transforms is provided, then the net effect is as if each transform had been applied separately in the order provided. For example, transform="translate(-10,-20) scale(2) rotate(45) translate(5,10)" indicates that:

The result is equivalent to pre-multiplying all of the matrices together: [1 0 0 1 5 10] * [cos(45) sin(45) -sin(45) cos(45)] * [2 0 0 2 0 0] * [1 0 0 1 -10 -20], which would be roughly equivalent to the following transform definition: matrix(1.414 1.414 -1.414 1.414 -17.07 1.213).

The transform attribute is applied to an element before processing any other coordinate or length values supplied for that element. Thus, in the element <rect x="10" y="10" width="20" height="20" transform="scale(2)" />, the x, y, width and height values are processed after the current coordinate system has been scaled uniformly by a factor of 2 by the transform attribute. Thus, x, y, width and height (and any other attributes or properties) are treated as values in the new user coordinate system, not the previous user coordinate system.

7.6 Establishing a New Viewport: the <svg> element within an SVG document

At any point in an SVG drawing, you can establish a new viewport into which all contained graphics should be drawn by including an <svg> element inside an SVG document. By establishing a new viewport, you also implicitly establish a new initial user space, new meanings for many of the CSS unit specifiers and, potentially, a new clipping path.

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" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990730.dtd">
<svg width="4in" height="3in">
  <desc>This SVG drawing embeds another one,
    thus establishing a new viewport
  </desc>
  <!-- The following statement establishing a new viewport
       and renders SVG drawing B into that viewport -->
  <svg style="left: 25%; top: 25%" width="50%" height="50%">
     <!-- drawing B goes here -->
  </svg>
</svg>

Download this example

You can also specify values for the 'clip' and 'overflow' properties for <svg> elements within an SVG document. If specified on an <svg> element, these properties will change the current clipping path. (Note that these properties will be ignored if used on any other type of element.)

7.7 Units

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

If possible, the SVG user agent should be passed the actual size of a px unit in inches or millimeters by its parent user agent. (See Conformance Requirements and Recommendations.) If such information is not available from the parent user agent, then the SVG user agent should assume a px is defined to be exactly .28mm.

7.8 Redefining the meaning of CSS unit specifiers

The process of establishing a new viewport via an <svg> element inside of an SVG document changes the meaning of the following CSS unit specifiers: px, pt, cm, mm, in, and % (percentages). A "pixel" (the px unit) becomes equivalent to a single unit in the user coordinate system for the given <svg> element. The meaning of the other absolute unit specifiers (pt, cm, mm, in) are determined as an appropriate multiple of a px unit using the actual size of px unit (as passed from the parent user agent to the SVG user agent). Any percentage values that are relative to the current viewport will also represent new values.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990730.dtd">
<svg width="300px" height="3oopx">
  <desc>Transformation with establishment of a new viewport
  </desc>
  <!-- The following two text elements will both draw with a 
        font height of 12 pixels -->
   <text style="font-size: 12">This prints 12 pixels high.</text>
   <text style="font-size: 12px">This prints 12 pixels high.</text>

   <!-- Now scale the coordinate system by 2. -->
   <g transform="scale(2)">

      <!-- The following text will actually draw 24 pixels high
           because each unit in the new coordinate system equals
           2 units in the previous coordinate system. -->
      <text style="font-size: 12">This prints 24 pixels high.</text>

      <!-- The following text will actually still draw 12 pixels high
           because the CSS unit specifier has been provided. -->
      <text style="font-size: 12px">This prints 12 pixels high.</text>
   </g>

   <!-- This time, scale the coordinate system by 3. -->
   <g transform="scale(3)">

      <!-- Establish a new viewport and thus change the meaning of
           some CSS unit specifiers. -->
      <svg style="left:0; top:0; right:100; bottom:100" 
           width="100%" height="100%">

         <!-- The following two text elements will both draw with a 
              font height of 36 screen pixels. The first text element
              defines its height in user coordinates, which have been
              scaled by 3. The second text element defines its height
              in CSS px units, which have been redefined to be three times
              as big as screen pixels due the <svg> element establishing
              a new viewport. -->
         <text style="font-size: 12">This prints 36 pixels high.</text>
         <text style="font-size: 12px">This prints 36 pixels high.</text>

      </svg>
   </g>
</svg>

Download this example

7.9 Processing rules for CSS units and percentages

Any values expressed in CSS units or percentages of the current viewport should be implemented such that these values map to corresponding values in user space as follows:

7.10 Further Examples

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