Chapter 8: Coordinate Systems, Transformations and Units

8.1. Introduction

All SVG content is drawn inside SVG viewports. Every SVG viewport defines a drawing region characterized by a size (width, height), and an origin, measured in abstract user units.

Note that the term SVG viewport is distinct from the "viewport" term used in CSS.

The initial viewport is a top-level SVG viewport that establishes a mapping between the coordinate system used by the containing environment (for example, CSS pixels in web browsers) and user units. Establishing an initial viewport is described in more detail in The initial viewport.

SVG viewports are only established by elements. See Establishing a new SVG viewport for information on which elements generate viewports.

Each SVG viewport generates a viewport coordinate system and a user coordinate system, initially identical. Providing a ‘viewBox’ on a viewport's element transforms the user coordinate system relative to the viewport coordinate system as described in The ‘viewBox’ attribute. Child elements of a viewport can further modify the user coordinate system, for example by specifying the transform property.

SVG viewports can be nested. Percentage units are resolved with reference to the width and height of the nearest ancestral SVG viewport. Hence, nesting SVG viewports provides an opportunity to redefine the meaning of percentage units and provide a new reference rectangle for "fitting" a graphic relative to a particular rectangular area.

The width, height and origin of SVG viewports is established by a negotiation process between the SVG document fragment generating the SVG viewport, and the parent of that fragment (whether real or implicit). See Establishing a new SVG viewport for a description of this negotiation process.

By default, a nested SVG viewport's viewport coordinate system is equivalent to the local coordinate system of the parent element, translated by the origin of the SVG viewport's element. However, a transform property on an SVG viewport's element will modify the viewport coordinate system relative to the parent element's user coordinate system.

Abstractly, all SVG viewports are embedded in the canvas, a drawing region that is infinitely large in all relevant dimensions.

8.2. Computing the equivalent transform of an SVG viewport

This process converts the min-x, min-y, width and height values of a viewBox attribute, the position and size of the element on which the viewBox attribute is defined, and the value of the preserveAspectRatio attribute on that element into a translation and a scale that is applied to content contained by the element.

  1. Let vb-x, vb-y, vb-width, vb-height be the min-x, min-y, width and height values of the viewBox attribute respectively.
  2. Let e-x, e-y, e-width, e-height be the position and size of the element respectively.
  3. Let align be the align value of preserveAspectRatio, or 'xMidYMid' if preserveAspectRatio is not defined.
  4. Let meetOrSlice be the meetOrSlice value of preserveAspectRatio, or 'meet' if preserveAspectRatio is not defined or if meetOrSlice is missing from this value.
  5. Initialize scale-x to e-width/vb-width.
  6. Initialize scale-y to e-height/vb-height.
  7. If align is not 'none' and meetOrSlice is 'meet', set the larger of scale-x and scale-y to the smaller.
  8. Otherwise, if align is not 'none' and meetOrSlice is 'slice', set the smaller of scale-x and scale-y to the larger.
  9. Initialize translate-x to e-x - (vb-x * scale-x).
  10. Initialize translate-y to e-y - (vb-y * scale-y)
  11. If align contains 'xMid', add (e-width - vb-width * scale-x) / 2 to translate-x.
  12. If align contains 'xMax', add (e-width - vb-width * scale-x) to translate-x.
  13. If align contains 'yMid', add (e-height - vb-height * scale-y) / 2 to translate-y.
  14. If align contains 'yMax', add (e-height - vb-height * scale-y) to translate-y.

The transform applied to content contained by the element is given by translate(translate-x, translate-y) scale(scale-x, scale-y).

8.3. The initial viewport

The initial viewport's width, must be the value of the width presentation attribute on the outermost svg element, unless the following conditions are met:

Under these conditions, the viewport's width must be established via the positioning properties.

Similarly, if there are positioning properties specified on the referencing element or on the outermost svg element that are sufficient to establish the height of the viewport, then these positioning properties must establish the viewport's height; otherwise, the initial viewport's height must be the value of the height presentation attribute on the outermost svg element.

If the width or height presentation attributes on the outermost svg element are in user units (i.e., no unit identifier has been provided), then the value is assumed to be equivalent to the same number of "px" units (see Units).

In the following example, an SVG graphic is embedded inline within a parent XML document which is formatted using CSS layout rules. Since CSS positioning properties are not provided on the outermost svg element, the width="100px" and height="200px" attributes determine the size of the initial viewport:

8.4. The initial coordinate system

For the outermost svg element, the SVG user agent must determine an initial viewport coordinate system and an initial user coordinate system such that the two coordinates systems are identical. The origin of both coordinate systems must be at the origin of the SVG viewport, and one unit in the initial coordinate system must equal one CSS 2.1 px ([CSS2], section 4.3.2) in the SVG viewport. In stand-alone SVG documents and in SVG document fragments embedded (by reference or inline) within parent documents where the parent's layout is determined by CSS [CSS2], the initial viewport coordinate system (and therefore the initial user coordinate system) must have its origin at the top/left of the viewport, with the positive x-axis pointing towards the right, the positive y-axis pointing down, and text rendered with an "upright" orientation, which means glyphs are oriented such that Roman characters and full-size ideographic characters for Asian scripts have the top edge of the corresponding glyphs oriented upwards and the right edge of the corresponding glyphs oriented to the right.

If the SVG implementation is part of a user agent which supports styling documents using CSS 2.1 compatible px units, then the SVG user agent should set its initial value for the size of a px unit in real world units to match the value used for other styling operations; otherwise, if the user agent can determine the size of a px unit from its environment, it should use that value; otherwise, it should choose an appropriate size for one px unit. In all cases, the size of a px must be in conformance with the rules described in CSS 2.1 ([CSS2], section 4.3.2).

Example InitialCoords below shows that the initial coordinate system has the origin at the top/left with the x-axis pointing to the right and the y-axis pointing down. The initial user coordinate system has one user unit equal to the parent (implicit or explicit) user agent's "pixel".



  Example InitialCoords - SVG's initial coordinate system

  
    
    
  
  
    
    
    
  
  
    (0,0)
    (300,0)
    (0,100)
Example InitialCoords — SVG's initial coordinate system

Example InitialCoords

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

8.5. The ‘transform’ property

User agents must support the transform property and presentation attribute as defined in [css-transforms-1].

8.6. The ‘viewBox’ attribute

Name Value Initial value Animatable
viewBox [,? ,? ,? ] As if not specified. yes 
, , ,  =

Transform on the ‘svg’ element is a bit special due to the ‘viewBox’ attribute. The transform should be applied as if the ‘svg’ had a parent element with that transform set.

RESOLUTION: transform property applies conceptually to the outside of the 'svg' element and there is no difference between presentation attribute and style property (in terms of the visual result).

The ‘viewBox’ attribute, in conjunction with the ‘preserveAspectRatio’ attribute, provides the capability to stretch an SVG viewport to fit a particular container element.

The value of the ‘viewBox’ attribute is a list of four numbers , , and , separated by whitespace and/or a comma, that specify a rectangle in user space that should be mapped to the bounds of the SVG viewport established by the given element, taking into account the ‘preserveAspectRatio’ attribute. The presence of the ‘viewBox’ attribute results in a transformation being applied to the viewport coordinate system as described in Computing the equivalent transform of an SVG viewport.

A negative value for or is an error and invalidates the ‘viewBox’ attribute. A value of zero disables rendering of the element.

Example ViewBox illustrates the use of the ‘viewBox’ attribute on the outermost svg element to specify that the SVG content should stretch to fit bounds of the SVG viewport.



  Example ViewBox - uses the viewBox
   attribute to automatically create an initial user coordinate
   system which causes the graphic to scale to fit into the
   SVG viewport no matter what size the SVG viewport is.
  
  
  
  
  
  
    Stretch to fit
Example ViewBox
Rendered into
SVG viewport with
width=300px,
height=200px		       Rendered into
SVG viewport with
width=150px,
height=200px
Example ViewBox - stretch to fit 300 by 200       Example ViewBox - stretch to fit 150 by 200

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

The effect of the ‘viewBox’ attribute is that the user agent automatically supplies the appropriate transformation matrix to map the specified rectangle in user coordinate system to the bounds of a designated region (often, the SVG viewport). To achieve the effect of the example on the left, with SVG viewport dimensions of 300 by 200 pixels, the user agent needs to automatically insert a transformation which scales both X and Y by 0.2. The effect is equivalent to having an SVG viewport of size 300px by 200px and the following supplemental transformation in the document, as follows:

To achieve the effect of the example on the right, with SVG viewport dimensions of 150 by 200 pixels, the user agent needs to automatically insert a transformation which scales X by 0.1 and Y by 0.2. The effect is equivalent to having an SVG viewport of size 150px by 200px and the following supplemental transformation in the document, as follows:

Note that in some cases the user agent will need to supply a translate transformation in addition to a scale transformation. For example, on an outermost svg element, a translate transformation will be needed if the ‘viewBox’ attributes specifies values other than zero for or .

If both transform (or ‘patternTransform’) and ‘viewBox’ are applied to an element two new coordinate systems are established. transform establishes the first new coordinate system for the element. ‘viewBox’ establishes a second coordinate system for all descendants of the element. The first coordinate system is post-multiplied by the second coordinate system.

Unlike the transform property, the automatic transformation that is created due to a ‘viewBox’ does not affect the ‘x’, ‘y’, ‘width’ and ‘height’ attributes (or in the case of the ‘marker’ element, the ‘markerWidth’ and ‘markerHeight’ attributes) on the element with the ‘viewBox’ attribute. Thus, in the example above which shows an ‘svg’ element which has width and height presentation attributes and a ‘viewBox’ attribute, the width and height represent values in the coordinate system that exists before the ‘viewBox’ transformation is applied. On the other hand, like the transform property, it does establish a new coordinate system for all other attributes and for descendant elements.

8.7. The ‘preserveAspectRatio’ attribute

Name Value Initial value Animatable
preserveAspectRatio ? xMidYMid meet yes 
 =
    none
    | xMinYMin | xMidYMin | xMaxYMin
    | xMinYMid | xMidYMid | xMaxYMid
    | xMinYMax | xMidYMax | xMaxYMax
 = meet | slice

Indicates whether or not to force uniform scaling. Applies to all elements that establish a new SVG viewport (see elements that establish SVG viewports), plus the ‘image’, ‘marker’, ‘pattern’ and ‘view’ elements

In some cases, typically when using the ‘viewBox’ attribute, it is desirable that the graphics stretch to fit non-uniformly to take up the entire SVG viewport. In other cases, it is desirable that uniform scaling be used for the purposes of preserving the aspect ratio of the graphics.

For elements that establish a new SVG viewport (see elements that establish SVG viewports), plus the ‘marker’, ‘pattern’ and ‘view’ elements, ‘preserveAspectRatio’ only applies when a value has been provided for ‘viewBox’ on the same element. For these elements, if attribute ‘viewBox’ is not provided, then ‘preserveAspectRatio’ is ignored.

For ‘image’ elements, ‘preserveAspectRatio’ indicates how referenced images should be fitted with respect to the reference rectangle and whether the aspect ratio of the referenced image should be preserved with respect to the current user coordinate system.

The parameter indicates whether to force uniform scaling and, if so, the alignment method to use in case the aspect ratio of the ‘viewBox’ doesn't match the aspect ratio of the SVG viewport. The parameter must be one of the following strings:

The parameter is optional and, if provided, is separated from the value by one or more spaces and then must be one of the following strings:

Example PreserveAspectRatio illustrates the various options on ‘preserveAspectRatio’. The example creates several new SVG viewports by including ‘svg’ sub-elements embedded inside the outermost svg element (see Establishing a new SVG viewport).



  Example PreserveAspectRatio - illustrates preserveAspectRatio attribute

  

  
    
      
      
      
      
      
    
  

  

  SVG to fit
  

  Viewport 1
  

  Viewport 2
  

  
    --------------- meet ---------------
    
      xMin*
      
      
	
      
    
    
      xMid*
      
      
	
      
    
    
      xMax*
      
      
        
      
    
  

  
    ---------- meet ----------
    
      *YMin
      
      
	
      
    
    
      *YMid
      
      
	
      
    
    
      *YMax
      
      
	
      
    
  

  
    ---------- slice ----------
    
      xMin*
      
      
	
      
    
    
      xMid*
      
      
	
      
    
    
      xMax*
      
      
	
      
    
  

  
    --------------- slice ---------------
    
      *YMin
      
      
	
      
    
    
      *YMid
      
      
	
      
    
    
      *YMax
Example PreserveAspectRatio — demonstrate available options

Example PreserveAspectRatio

8.8. Establishing a new SVG viewport

Including an ‘svg’ element inside SVG content creates a new SVG viewport into which all contained graphics are drawn; this implicitly establishes both a new viewport coordinate system and a new user coordinate system. Additionally, there is a new meaning for percentage units therein, because a new SVG viewport has been established (see Units).

The bounds of the new SVG viewport are defined by the ‘x’, ‘y’, ‘width’ and ‘height’ attributes on the element establishing the new SVG viewport, such as an ‘svg’ element. Both the new viewport coordinate system and the new user coordinate system have their origins at (‘x’, ‘y’), where ‘x’ and ‘y’ represent the value of the corresponding attributes on the element establishing the SVG viewport. The orientation of the new viewport coordinate system and the new user coordinate system correspond to the orientation of the current user coordinate system for the element establishing the SVG viewport. A single unit in the new viewport coordinate system and the new user coordinate system are the same size as a single unit in the current user coordinate system for the element establishing the SVG viewport.

Here is an example:



  This SVG drawing embeds another one,
    thus establishing a new SVG viewport

For an extensive example of creating new SVG viewports, see Example PreserveAspectRatio.

The following elements establish new SVG viewports:

For historical reasons, the ‘pattern’ and ‘marker’ elements do not create a new viewport, despite accepting a ‘viewBox’ attribute. Neither do the ‘clipPath’ or ‘mask’ elements. Percentage lengths within the content of these elements are not proportional to the dimensions of the graphical effect region.

The ‘foreignObject’ element establishes a new CSS containing block for its child content. The same is true for a ‘video’, ‘audio’, or ‘canvas’ element when its fallback content is being rendered. This has some effects similar to a new viewport, resetting the scope of layout for child content. However, in order to render SVG elements that are descendents of ‘foreignObject’, a new ‘svg’ element must establish an SVG document fragment and SVG viewport.

An ‘image’ or ‘iframe’ element creates a new document viewport for the referenced document. If the referenced document is a SVG file, it will of course establish its own SVG viewport.

Whether a new SVG viewport also establishes a new additional clipping path is determined by the value of the overflow property on the element that establishes the new SVG viewport.

8.9. Units

SVG follows the description and definition of common values and units from the CSS Values and Units Module [css-values] for attributes, presentation attributes and CSS properties. Each attribute and property must specify the used component value type. Subsequent or extending specifications published by the CSS WG or SVG WG may extend basic data types or add new data types.

For values that are defined to be relative to the size of SVG viewport:

Example Units below illustrates some of the processing rules for different types of units.



  Example Units
  Illustrates various units options

  
  

  
    
    
      Abs. units:
      
      
      
        
      
    

    
    
      Rel. units:
      
      
      
        
      
    

    
    
      Percentages:
Example Units — demonstrate available options

Example Units

The three rectangles on the left demonstrate the use of one of the absolute unit identifiers, the "in" unit (inch). CSS defines 1 inch to be equal to 96 pixels. Therefore, the topmost rectangle, which is specified in inches, is exactly the same size as the middle rectangle, which is specified in user units such that there are 96 user units for each corresponding inch in the topmost rectangle. The bottom rectangle of the group illustrates what happens when values specified in inches are scaled.

The three rectangles in the middle demonstrate the use of one of the relative unit identifiers, the "em" unit. Because the font-size property has been set to 150 on the outermost ‘g’ element, each "em" unit is equal to 150 user units. The topmost rectangle, which is specified in "em" units, is exactly the same size as the middle rectangle, which is specified in user units such that there are 150 user units for each corresponding "em" unit in the topmost rectangle. The bottom rectangle of the group illustrates what happens when values specified in "em" units are scaled.

The three rectangles on the right demonstrate the use of percentages. Note that the width and height of the SVG viewport in the user coordinate system for the SVG viewport element (in this case, the outermost svg element) are 4000 and 2000, respectively, because processing the ‘viewBox’ attribute results in a transformed user coordinate system. The topmost rectangle, which is specified in percentage units, is exactly the same size as the middle rectangle, which is specified in equivalent user units. In particular, note that the stroke-width property in the middle rectangle is set to 1% of the sqrt((actual-width)**2 + (actual-height)**2) / sqrt(2), which in this case is .01*sqrt(4000*4000+2000*2000)/sqrt(2), or 31.62. The bottom rectangle of the group illustrates what happens when values specified in percentage units are scaled.

8.10. Bounding boxes

bounding box

The bounding box (or "bbox") of an element is the tightest fitting rectangle aligned with the axes of that element's user coordinate system that entirely encloses it and its descendants.

Three kinds of bounding boxes can be computed for an element:

  1. The object bounding box is the bounding box that contains only an element's geometric shape. For basic shapes, this is the area that is filled. Unless otherwise specified, this is what is meant by the unqualified term "bounding box".
  2. The stroke bounding box is the bounding box that contains an element's geometric shape and its stroke shape.
  3. The decorated bounding box is the bounding box that contains an element's geometric shape, its stroke shape and its markers.

Note that the values of the opacity, visibility, fill, fill-opacity, fill-rule, stroke-dasharray and stroke-dashoffset properties on an element have no effect on the bounding box of an element.

For curved shapes, the bounding box must enclose all portions of the shape along the edge, not just end points. Note that control points for a curve which are not defined as lying along the line of the resulting curve (e.g., the second coordinate pair of a Cubic Bézier command) must not contribute to the dimensions of the bounding box (though those points may fall within the area of the bounding box, if they lie within the shape itself, or along or close to the curve). For example, control points of a curve that are at a further distance than the curve edge, from the non-enclosing side of the curve edge, must be excluded from the bounding box.

Image showing the object bounding box of a quadratic Bézier curve.

The path 'M20,50 L35,100 H120 V50 Q70,10 20,50' is shown in light blue. On the left, a correct object bounding box of the path is shown. Note that it does not include the top-most control point of the curve, but it does include all of the blue shape, even the parts that lie outside of the convex hull of the control points.

Even if an element is not in the rendering tree – due to it being 'display: none', within a ‘defs’ element, not usually rendered like a ‘symbol’ element or not currently present in the document tree – it still has a bounding box. A call to getBBox on the element will return the same rectangle as if the element were rendered. However, an element that is not in the rendering tree does not contribute to the bounding box of any ancestor element.

The following example defines a number of elements. The expected object bounding box for each element with an ID is shown below.



  Bounding Box Calculation
  Examples of elements with different bounding box results based on context.
Element ID Bounding Box Result
"defs-1" {0, 0, 0, 0}
"rect-1" {20, 20, 40, 40}
"group-1" {30, 30, 40, 40}
"use-1" {30, 30, 40, 40}
"group-2" {10, 10, 100, 100}
"rect-2" {10, 10, 100, 100}

For text content elements, for the purposes of the bounding box calculation, each glyph must be treated as a separate graphics element. The calculations must assume that all glyphs occupy the full glyph cell. The full glyph cell must have width equal to the horizontal advance and height equal to the EM box for horizontal text. For vertical text that is typeset sideways, the full glyph cell must have width equal to the EM box and height equal to the horizontal advance. For other vertical text, the full glyph cell must have width equal to the EM box and height equal to the vertical advance, or height equal to the height of the EM box if no vertical advance is defined in the font. For example, for horizontal text, the calculations must assume that each glyph extends vertically to the full ascent and descent values for the font.

Because declarative or scripted animation can change the shape, size, and position of an element, the bounding box is mutable. Thus, the bounding box for an element shall reflect the current values for the element at the snapshot in time at which the bounding box is requested, whether through a script call or as part of a declarative or linking syntax.

An element which has zero width, zero height, or both (such as a vertical or horizontal line, or a ‘rect’ element with a zero width or height) still has a bounding box, with a positive value for the positive dimension, or with '0' for both the width and height if no positive dimension is specified. Similarly, subpaths segments of a ‘path’ element with zero width and height must be included in that element's geometry for the sake of the bounding box.

An element with no position specified (such as a ‘path’ element with a value of none for the d property) is positioned at the point (0,0) for the purposes of calculating a bounding box.

Note that elements whose DOM object does not derive from SVGGraphicsElement (such as gradient elements) do not have a bounding box, and thus have no interface to request a bounding box.

Elements in the rendering tree which reference unresolved resources shall still have a bounding box, defined by the position and dimensions specified in their attributes, or by the initial value for those attributes if no values are supplied. For example, the element would have a bounding box with an x and y of 10 and a width and height of 0.

The following algorithm defines how to compute a bounding box for a given element. The inputs to the algorithm are:

The algorithm to compute the bounding box is as follows, depending on the type of element:

a shape
a text content element
an ‘a’ element within a text content element
  1. Let box be a rectangle initialized to (0, 0, 0, 0).
  2. Let fill-shape be the equivalent path of element if it is a shape, or a shape that includes each of the glyph cells corresponding to the text within the elements otherwise.
  3. If fill is true, then set box to the tightest rectangle in the coordinate system space that contains fill-shape.

    The values of the fill, fill-opacity and fill-rule properties do not affect fill-shape.

  4. If stroke is true and the element's stroke is anything other than none, then set box to be the union of box and the tightest rectangle in coordinate system space that contains the stroke shape of the element, with the assumption that the element has no dash pattern.

    The values of the stroke-opacity, stroke-dasharray and stroke-dashoffset do not affect the calculation of the stroke shape.

  5. If markers is true, then for each marker marker rendered on the element:
    1. For each descendant graphics element child of the ‘marker’ element that defines marker's content:
      1. If child has an ancestor element within the ‘marker’ that is 'display: none', has a failing conditional processing attribute, or is not an ‘a’, ‘g’, ‘svg’ or ‘switch’ element, then continue to the next descendant graphics element.
      2. Otherwise, set box to be the union of box and the result of invoking the algorithm to compute a bounding box with child as the element, space as the target coordinate space, true for fill, stroke and markers, and clipped for clipped.
  6. If clipped is true and the value of clip-path on element is not none, then set box to be the tightest rectangle in coordinate system space that contains the intersection of box and the clipping path.
  7. Return box.
a container element
‘use’
  1. Let box be a rectangle initialized to (0, 0, 0, 0).
  2. Let parent be the container element if it is one, or the root of the ‘use’ element's shadow tree otherwise.
  3. For each descendant graphics element child of parent:
    1. If child is not rendered then continue to the next descendant graphics element.
    2. Otherwise, set box to be the union of box and the result of invoking the algorithm to compute a bounding box with child as the element and the same values for space, fill, stroke, markers and clipped as the corresponding algorithm input values.
  4. If clipped is true:
    • If the value of clip-path on element is not none, then set box to be the tightest rectangle in coordinate system space that contains the intersection of box and the clipping path.
    • If the overflow property applies to the element and does not have a value of visible, then set box to be the tightest rectangle in coordinate system space that contains the intersection of box and the element's overflow bounds.
    • If the clip property applies to the element and does not have a value of auto, then set box to be the tightest rectangle in coordinate system space that contains the intersection of box and the rectangle specified by clip.
  5. Return box.
‘canvas’
‘foreignObject’
‘iframe’
‘image’
‘video’
  1. Let box be the tightest rectangle in coordinate space space that contains the positioning rectangle defined by the ‘x’, ‘y’, ‘width’ and ‘height’ geometric properties of the element.

    The fill, stroke and markers input arguments to this algorithm do not affect the bounding box returned for these elements.

  2. If clipped is true and the value of clip-path on element is not none, then set box to be the tightest rectangle in coordinate system space that contains the intersection of box and the clipping path.
  3. Return box.

The union box with a value of (0, 0, 0, 0) and an empty shape is box.

The object bounding box, stroke bounding box or decorated bounding box of an element is the result of invoking the bounding box computation algorithm above with the following arguments: element is the element itself; space is the element's user coordinate system; fill is true; stroke is true if we are computing the stroke bounding box or decorated bounding box, and false othwerise; markers is true if we are computing the decorated bounding box, and false otherwise; and clipped is false.

8.11. Object bounding box units

The following elements offer the option of expressing coordinate values and lengths as fractions (and, in some cases, percentages) of the object bounding box, by setting a specified attribute to 'objectBoundingBox' on the given element:

Element Attribute Effect
‘linearGradient’ ‘gradientUnits’ Indicates that the attributes which specify the gradient vector (‘x1’, ‘y1’, ‘x2’, ‘y2’) represent fractions or percentages of the bounding box of the element to which the gradient is applied.
‘radialGradient’ ‘gradientUnits’ Indicates that the attributes which specify the center (‘cx’, ‘cy’), the radius (‘r’) and focus (‘fx’, ‘fy’) represent fractions or percentages of the bounding box of the element to which the gradient is applied.
‘pattern’ ‘patternUnits’ Indicates that the attributes which define how to tile the pattern (‘x’, ‘y’, ‘width’, ‘height’) are established using the bounding box of the element to which the pattern is applied.
‘pattern’ ‘patternContentUnits’ Indicates that the user coordinate system for the contents of the pattern is established using the bounding box of the element to which the pattern is applied.
‘clipPath’ ‘clipPathUnits’ Indicates that the user coordinate system for the contents of the ‘clipPath’ element is established using the bounding box of the element to which the clipping path is applied.
‘mask’ ‘maskUnits’ Indicates that the attributes which define the masking region (‘x’, ‘y’, ‘width’, ‘height’) is established using the bounding box of the element to which the mask is applied.
‘mask’ ‘maskContentUnits’ Indicates that the user coordinate system for the contents of the ‘mask’ element are established using the bounding box of the element to which the mask is applied.
‘filter’ ‘filterUnits’ Indicates that the attributes which define the filter effects region (‘x’, ‘y’, ‘width’, ‘height’) represent fractions or percentages of the bounding box of the element to which the filter is applied.
‘filter’ ‘primitiveUnits’ Indicates that the various length values within the filter primitives represent fractions or percentages of the bounding box of the element to which the filter is applied.

In the discussion that follows, the term applicable element is the element to which the given effect applies. For gradients and patterns, the applicable element is the graphics element which has its fill or stroke property referencing the given gradient or pattern. (For special rules concerning text elements, see the discussion of object bounding box units and text elements.) For clipping paths, masks and filters, the applicable element can be either a container element or a graphics element.

When keyword objectBoundingBox is used, then the effect is as if a supplemental transformation matrix were inserted into the list of nested transformation matrices to create a new user coordinate system.

First, the (minx,miny) and (maxx,maxy) coordinates are determined by the extends of the object bounding box of the applicable element.

Then, coordinate (0,0) in the new user coordinate system is mapped to the (minx,miny) corner of the tight bounding box within the user coordinate system of the applicable element and coordinate (1,1) in the new user coordinate system is mapped to the (maxx,maxy) corner of the tight bounding box of the applicable element. In most situations, the following transformation matrix produces the correct effect:

[ (maxx-minx) 0 0 (maxy-miny) minx miny ]

When percentages are used with attributes that define the gradient vector, the pattern tile, the filter region or the masking region, a percentage represents the same value as the corresponding decimal value (e.g., 50% means the same as 0.5). If percentages are used within the content of a ‘pattern’, ‘clipPath’, ‘mask’ or ‘filter’ element, these values are treated according to the processing rules for percentages as defined in Units.

Any numeric value can be specified for values expressed as a fraction or percentage of object bounding box units. In particular, fractions less are zero or greater than one and percentages less than 0% or greater than 100% can be specified.

Keyword objectBoundingBox should not be used when the geometry of the applicable element has no width or no height, such as the case of a horizontal or vertical line, even when the line has actual thickness when viewed due to having a non-zero stroke width since stroke width is ignored for bounding box calculations. When the geometry of the applicable element has no width or height and objectBoundingBox is specified, then the given effect (e.g., a gradient or a filter) will be ignored.

8.12. Intrinsic sizing properties of SVG content

To enable inclusion of SVG in host documents formatted with CSS, a concrete object size must be calculated. The concrete object size must be calculated using the Default Sizing Algorithm defined in CSS Images 3 [css-images-3], with the following inputs:

The specified size must be determined from the used values for the width and height sizing properties of the ‘svg’ element.

The intrinsic dimensions must also be determined from the width and height sizing properties. If either width or height are not specified, the used value is the initial value 'auto'. 'auto' and percentage lengths must not be used to determine an intrinsic width or intrinsic height.

With bitmap image formats, the intrinsic dimensions are fixed in the image file, and the specified size is defined in the host document as needed to scale the image. SVG, being inherently scalable, adapts the intrinsic width and intrinsic height to be the width and height of the specified size. Therefore, when specified as a length, the width and height sizing properties of the ‘svg’ element control the intrinsic dimensions of the SVG image and the specified size that is used when placing the SVG image in a host document.

The intrinsic aspect ratio must be calculated using the following algorithm. If the algorithm returns null, then there is no intrinsic aspect ratio.

  1. If the width and height sizing properties on the ‘svg’ element are both absolute values:
    1. return width / height
  2. If an SVG View is active:
    1. let viewbox be the viewbox defined by the active SVG View
    2. return viewbox.width / viewbox.height
  3. If the ‘viewBox’ on the ‘svg’ element is correctly specified:
    1. let viewbox be the viewbox defined by the ‘viewBox’ attribute on the ‘svg’ element
    2. return viewbox.width / viewbox.height
  4. return null

The behaviour defined in this section is specific to CSS, but may be adapted to other host contexts. In all host contexts, the intrinsic aspect ratio, where available, must be respected when sizing the SVG viewport.

Examples:

Example: Intrinsic Aspect Ratio 1 

  ...

In this example the intrinsic aspect ratio of the SVG viewport is 2:1. The intrinsic width is 10cm and the intrinsic height is 5cm.

Example: Intrinsic Aspect Ratio 2 

  ...

In this example the intrinsic aspect ratio of the outermost SVG viewport is 1:1. An aspect ratio calculation in this case allows embedding in an object within a containing block that is only constrained in one direction.

Example: Intrinsic Aspect Ratio 3 

  ...

In this case the intrinsic aspect ratio is 1:1.

Example: Intrinsic Aspect Ratio 4 

  ...

In this example, the intrinsic aspect ratio is 1:1.

Add more examples for the new auto value? E.g some of the examples provided by David Vest.

8.13. Vector effects

SVG 2 Requirement: SVG 2 will have constrained transformations based on SVG 1.2 Tiny.
Resolution: Add vector effects extension proposal to SVG 2 specification.
Purpose: To include non-scaling features (non-scaling part of the object, and non-scaling entire object
Owner: Satoru Takagi (ACTION-3619)

Sometimes it is of interest to let the outline of an object keep its original width or to let the position of an object fix no matter which transforms are applied to it. For example, in a map with a 2px wide line representing roads it is of interest to keep the roads 2px wide even when the user zooms into the map, or introductory notes on the graphic chart in which panning is possible.

To offer such effects regarding special coordinate transformations and graphic drawings, SVG Tiny 1.2 introduced the vector-effect property. Although SVG Tiny 1.2 introduced only non-scaling stroke behavior, this version introduces a number of additional effects. Furthermore, since these effects can be specified in combination, they show more various effects. And, future versions of the SVG language will allow for more powerful vector effects through this property.

Values of vector-effect other than non-scaling-stroke and none are at risk of being dropped from SVG 2 due to a lack of implementations. Feedback from implementers is requested, regarding the practicality of implementing them as currently specified, during the implementation period.

Name: vector-effect
Value: none | [ non-scaling-stroke | non-scaling-size | non-rotation | fixed-position ]+ [ viewport | screen ]?
Initial: none
Applies to: graphics elements and ‘use’
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes
none
Specifies that no vector effect shall be applied, i.e. the default rendering behaviour from SVG 1.1 is used which is to first fill the geometry of a shape with a specified paint, then stroke the outline with a specified paint.
non-scaling-stroke
Please refer to this description of vector effect on painting.
non-scaling-size
Specifies special user coordinate system toward this element and its descendant by constrained transformations with the following characteristics. The scale of the user coordinate system do not change in spite of change of CTMs from a host coordinate space. However, it does not specify the suppression of rotation and skew. Also, it does not specify the fixation of placement of user coordinate system. Since non-scaling-size suppresses scaling of user coordinate system, it also has the characteristic of non-scaling-stroke. The transformation formula and the example behavior are indicated to the following chapter.
non-rotation
Specifies special user coordinate system toward this element and its descendant by constrained transformations with the following characteristics. The rotation and skew of the user coordinate system is suppressd in spite of change of CTMs from a host coordinate space. However, it does not specify the suppression of scaling. Also, it does not specify the fixation of placement of user coordinate system. The transformation formula and the example behavior are indicated to the following chapter.
fixed-position
Specifies special user coordinate system toward this element and its descendant by constrained transformations with the following characteristics. The placement of user coordinate system is fixed in spite of change of CTMs from a host coordinate space. However, it does not specify the suppression of rotation, skew and scaling. When the element that has fixed-position effect and also has transform property, that property is consumed for this effect. The shift components e and f of matrix of transform property are used to transfer the origin of fixed user coordinate system. The transformation formula and the example behavior are indicated to the following chapter.

These values can be enumerated. Thereby, the effect which has these characteristics simultaneously can be specified.

The following two values assists the above-mentioned values. They show the host coordinate space of constrained transformations. Especially it has effective for the element belonging to nested viewport coordinate system such as nested contents or nested ‘svg’ elements. An initial value in case it is not specified is viewport.

viewport
Specifies immediate viewport coordinate system as the host coordinate space. When that element belongs to nested viewport coordinate system, vector effects are applied toward viewport coordinate system to which that element belongs directly. That is, that vector effect is not effective for change of CTM on ancestral viewport coordinate system.
screen
It specifies the coordinate system of content which under the immediate control of user agent. So to speak, it is "scrren" which user agent has. ("screen coordinate space" in SVGT1.2) Even if that element belongs to nested viewport coordinate system, that vector effect is always effective for change of CTM of the any hierarchy. If the SVG implementation is part of a user agent which supports CSS compatible px units, it is a coordinate system on CSS pixel of rootmost content. Generally, the pixel (or dot) of a device and pixel of CSS are not always equal by influences of the zoom function which user agent itself has, and variation of dpi. (see resolution [CSS Values and Units Module Level 3]) Accordingly, this value does not specify constrained transformations toward the such a device coordinate system.

Note: Future versions of SVG may allow ways to specify the device coordinate system.

8.13.1. Computing the vector effects

This section shows the list of transformation formulas regarding combinations of the values for clarification of the behavior of vector effects excluding non-scaling-stroke which has clear implications.

The vector-effect property has no effect on transformations performed in a 3d rendering context.

The normal coordinate transformation formula from user coordinate system to viewport coordinate system is as follows.

x viewport y viewport 1 = CTM ⋅ x userspace y userspace 1 CTM = a ctm c ctm e ctm b ctm d ctm f ctm 0 0 1

When the vector-effect is added to an element like the above, the transformation formula for user coordinate to the device coordinate changes as follows. Here, xf and yf are user coordinate of the corresponding element and its descendant. And, xo and yo are matrix element e and f of the transform attribute which the corresponding element has. In addition, |det(CTM)| is absolute value of the determinants of CTM. When this value becomes 0 and non-scaling-size is appointed, vector-effect becomes invalidity namely none.

det CTM = a ctm ⋅ d ctm - b ctm ⋅ c ctm
veValue Formula
non-scaling-size
x viewport y viewport 1 = CTM ⋅ 0 0 1 + CTM det CTM ⋅ 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1
non-rotation
x viewport y viewport 1 = CTM ⋅ 0 0 1 + det CTM ⋅ 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1
non-scaling-size non-rotation
x viewport y viewport 1 = CTM ⋅ 0 0 1 + 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1
fixed-position
x viewport y viewport 1 = x o y o 1 + CTM ⋅ 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1
fixed-position non-scaling-size
x viewport y viewport 1 = x o y o 1 + CTM det CTM ⋅ 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1
fixed-position non-rotation
x viewport y viewport 1 = x o y o 1 + det CTM ⋅ 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1
fixed-position non-scaling-size non-rotation
x viewport y viewport 1 = x o y o 1 + 1 0 0 0 1 0 0 0 0 ⋅ x f y f 1

8.13.2. Computing the vector effects for nested viewport coordinate systems

Below is normal coordinate transformation formula for nested viewport coordinate systems without vector effects. xviewport(UA) and yviewport(UA) are coordinates which under the immediate control of user agent. CTMthis is CTM for the transformation matrix from user coordinate system of an target graphic to viewport coordinate system to which it belongs. CTMparent is CTM for the transformation matrix from aforementioned viewport coordinate system to viewport coordinate system of the parent of that. And, CTMroot is CTM for rootmost viewport coordinate system (UA).

x viewport(UA) y viewport(UA) 1 = CTM root ⋅ ... ⋅ CTM parent ⋅ CTM this ⋅ x userspace y userspace 1

When applying seven formulas of the preceding section to nested viewport coordinate systems, the application way of those formulas changes as follows by whether viewport or screen is specified as the additional value of vector-effect.

When viewport value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.

x viewport ( UA ) y viewport ( UA ) 1 = CTM root ⋅ ... ⋅ CTM parent ⋅ x viewport y viewport 1 CTM = CTM this

When screen value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.

x viewport ( UA ) y viewport ( UA ) 1 = x viewport y viewport 1 CTM = CTM root ⋅ ... ⋅ CTM parent ⋅ CTM this

8.13.3. Examples of vector effects

Below is an example of the non-scaling-stroke vector-effect.




  Example non-scaling stroke

Below is an example of the none vector-effect (no vector effect).

Before changing CTMAfter changing CTM
Image showing none vector effect Image showing none vector effect

Source code

Below is an example of the non-scaling-size.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size vector effect

Below is an example of the non-rotation.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-rotation vector effect

Below is an example of the non-scaling-size non-rotation.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size non-rotation vector effect

Below is an example of the fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing fixed-position vector effect

Below is an example of the non-scaling-size fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size fixed-position vector effect

Below is an example of the non-rotation fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-rotation fixed-position vector effect

Below is an example of the non-scaling-size non-rotation fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size non-rotation fixed-position vector effect

8.14. DOM interfaces

8.14.1. Interface SVGTransform

The SVGTransform interface is used to represent values that appear in the transform property and its presentation attributes ‘transform’, ‘gradientTransform’ and ‘patternTransform’. An SVGTransform represents a single component in a transform list, such as a single scale(…) or matrix(…) value.

An SVGTransform object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.

An SVGTransform object can be associated with a particular element. The associated element is used to determine which element's ‘transform’ presentation attribute to update if the object reflects that attribute. Unless otherwise described, an SVGTransform object is not associated with any element.

Every SVGTransform object operates in one of two modes. It can:

  1. reflect an element of a presentation attribute value (being exposed through the methods on the baseVal member of an SVGAnimatedTransformList),
  2. be detached, which is the case for SVGTransform objects created with createSVGTransform and createSVGTransformFromMatrix.

An SVGTransform object maintains an internal value, which is called its value. It also maintains a DOMMatrix object, which is called its matrix object, which is the object returned from the matrix IDL attribute. An SVGTransform object's matrix object is always kept synchronized with its value.

[Exposed=Window]
interface SVGTransform {

  // Transform Types
  const unsigned short SVG_TRANSFORM_UNKNOWN = 0;
  const unsigned short SVG_TRANSFORM_MATRIX = 1;
  const unsigned short SVG_TRANSFORM_TRANSLATE = 2;
  const unsigned short SVG_TRANSFORM_SCALE = 3;
  const unsigned short SVG_TRANSFORM_ROTATE = 4;
  const unsigned short SVG_TRANSFORM_SKEWX = 5;
  const unsigned short SVG_TRANSFORM_SKEWY = 6;

  readonly attribute unsigned short type;
  [SameObject] readonly attribute DOMMatrix matrix;
  readonly attribute float angle;

  void setMatrix(DOMMatrixReadOnly matrix);
  void setTranslate(float tx, float ty);
  void setScale(float sx, float sy);
  void setRotate(float angle, float cx, float cy);
  void setSkewX(float angle);
  void setSkewY(float angle);
};

The numeric transform type constants defined on SVGTransform are used to represent the type of an SVGTransform's value. Their meanings are as follows:

ConstantMeaning
SVG_TRANSFORM_MATRIXA matrix(…) value.
SVG_TRANSFORM_TRANSLATEA translate(…) value.
SVG_TRANSFORM_SCALEA scale(…) value.
SVG_TRANSFORM_ROTATEA rotate(…) value.
SVG_TRANSFORM_SKEWXA skewX(…) value.
SVG_TRANSFORM_SKEWYA skewY(…) value.
SVG_TRANSFORM_UNKNOWNSome other type of value.

The use of numeric transform type constants is an anti-pattern and new constant values will not be introduced for any transform types supported by SVGTransform. If other types of transforms are supported and used, the SVGTransform uses the SVG_TRANSFORM_UNKNOWN type. See below for details on how the other properties of an SVGTransform operate with these types of transforms.

The type IDL attribute represents the type of transform item that the SVGTransform's value is. On getting type, the following steps are run:

  1. If the SVGTransform's value is a matrix(…), translate(…), scale(…), rotate(…), skewX(…) or skewY(…) function, then return the corresponding constant value from the transform type table above.
  2. Otherwise, return SVG_TRANSFORM_UNKNOWN.

    For example, for a scaleX(…) or translate3d(…) transform, SVG_TRANSFORM_UNKNOWN would be returned.

The matrix IDL attribute represents the transform as a 4x4 homogeneous matrix, and on getting returns the SVGTransform's matrix object. When the matrix object is first created, its values are set to match the SVGTransform's transform function value, and is set to reflects the SVGTransform.

See the CSS Transforms specification for a description of how the different transform function types correspond to particular matrix values.

The angle IDL attribute represents the angle parameter of a rotate(…), skewX(…) or skewY(…) transform function. On getting, the following steps are run:

  1. If the SVGTransform object's value is a rotate(…), skewX(…) or skewY(…) function, return its angle argument in degrees.
  2. Otherwise, return 0.

The setMatrix method is used to set the SVGTransform to a given matrix value. When setMatrix(matrix) is called, the following steps are run:

  1. If the SVGTransform object is read only, then throw a NoModificationAllowedError.
  2. If matrix would return true from its is2d method, then set the SVGTransform object's value to a matrix(…) value that represents the same matrix as matrix.
  3. Otherwise, set the SVGTransform object's value to a matrix3d(…) value that represents the same matrix as matrix.
  4. Copy the matrix component values from matrix into the SVGTransform object's matrix object.
  5. If the SVGTransform object reflects an element of a presentation attribute value, then reserialize the reflected attribute.

The setTranslate, setScale, setRotate, setSkewX and setSkewY methods are used to set the SVGTransform to a new transform function value. When one of these methods is called, the following steps are run:

  1. If the SVGTransform object is read only, then throw a NoModificationAllowedError.
  2. Set the SVGTransform object's value to a new transform function value, depending on which method was called:
    setTranslate(tx, ty)
    the new transform function value is translate(tx, ty)
    setScale(sx, sy)
    the new transform function value is scale(sx, sy)
    setRotate(angle, cx, cy)
    the new transform function value is rotate(angle, cx, cy)
    setSkewX(angle)
    the new transform function value is skewX(angle)
    setSkewY(angle)
    the new transform function value is skewY(angle)
  3. Set the components of the SVGTransform object's matrix object to match the new transform function value.
  4. If the SVGTransform object reflects an element of a presentation attribute value, then reserialize the reflected attribute.

This specification imposes additional requirements on the behavior of DOMMatrix objects beyond those described in the Geometry Interfaces specification, so that they can be used to reflect presentation attributes that take transform values.

Every DOMMatrix object operates in one of two modes. It can:

  1. reflect an SVGTransform (being exposed through the matrix IDL attribute on an SVGTransform), or
  2. be detached, which is the case for DOMMatrix objects created using their constructor or with createSVGMatrix.

A DOMMatrix can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. When assigning to any of a read only DOMMatrix's IDL attributes, or when invoking any of its mutable transform methods, a NoModificationAllowedError exception will be thrown instead of updating the internal value.

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

When assigning to any of a writable DOMMatrix's IDL attributes, or when invoking any of its mutable transform methods, the following steps are run after updating the internal matrix value:

  1. If the DOMMatrix reflects an SVGTransform, then:
    1. If the DOMMatrix would return true from its is2d method, then set the SVGTransform object's value to a matrix(…) value that represents the same matrix as the DOMMatrix.
    2. Otherwise, set the SVGTransform object's value to a matrix3d(…) value that represents the same matrix as the DOMMatrix.
    3. If the SVGTransform object reflects an element of a presentation attribute value, then reserialize the reflected attribute.

8.14.2. Interface SVGTransformList

The SVGTransformList interface is a list interface whose elements are SVGTransform objects. An SVGTransformList represents a value that the transform property can take, namely either a or the keyword none.

[Exposed=Window]
interface SVGTransformList {

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

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

  // Additional methods not common to other list interfaces.
  SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);
  SVGTransform? consolidate();
};

The createSVGTransformFromMatrix method is used to create a new SVGTransform object from a matrix object. When the createSVGTransformFromMatrix(matrix) method is called, the following steps are run:

  1. Let transform be a newly created SVGTransform object that is detached.
  2. Follow the steps that would be run if the setMatrix method on transform were called, passing matrix as its argument.
  3. Return transform.

The consolidate method is used to convert the transform list into an equivalent transformation using a single transform function. When the consolidate() method is called, the following steps are run:

  1. If the SVGTransformList object is read only, then throw a NoModificationAllowedError.
  2. If the list is empty, return null.
  3. Detach and then remove all elements in the list.
  4. Let transform be a newly created SVGTransform object.
  5. Let matrix be the matrix value obtained by beginning with an identity matrix, and then post-multiplying the value of the matrix object for each SVGTransform in the list, in order.
  6. Set the components of transform's matrix object to the component values in matrix.
  7. If transform's matrix object would return true from its is2d method, then set transform's value to a matrix(…) value that represents the same matrix as the matrix object.
  8. Otherwise, set transform's value to a matrix3d(…) value that represents the same matrix as the matrix object.
  9. Attach transform to this SVGTransformList.
  10. Append transform to this list.
  11. If the list reflects a presentation attribute, then reserialize the reflected attribute.
  12. Return transform.

The behavior of all other interface members of SVGLengthList are defined in List interfaces.

8.14.3. Interface SVGAnimatedTransformList

An SVGAnimatedTransformList object is used to reflect the transform property and its corresponding presentation attribute (which, depending on the element, is ‘transform’, ‘gradientTransform’ or ‘patternTransform’).

[Exposed=Window]
interface SVGAnimatedTransformList {
  [SameObject] readonly attribute SVGTransformList baseVal;
  [SameObject] readonly attribute SVGTransformList animVal;
};

The baseVal and animVal IDL attributes represent the value of the reflected presentation attribute. On getting baseVal or animVal, an SVGTransformList object is returned that reflects the given presentation attribute.

8.14.4. Interface SVGPreserveAspectRatio

The SVGPreserveAspectRatio interface is used to represent values for the ‘preserveAspectRatio’ attribute.

An SVGPreserveAspectRatio object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.

Every SVGPreserveAspectRatio object reflects the base value of a reflected ‘preserveAspectRatio’ attribute (being exposed through the methods on the baseVal or animVal member of an SVGAnimatedPreserveAspectRatio).

[Exposed=Window]
interface SVGPreserveAspectRatio {

  // Alignment Types
  const unsigned short SVG_PRESERVEASPECTRATIO_UNKNOWN = 0;
  const unsigned short SVG_PRESERVEASPECTRATIO_NONE = 1;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMIN = 2;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMIN = 3;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMIN = 4;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMID = 5;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMID = 6;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMID = 7;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMAX = 8;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMAX = 9;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMAX = 10;

  // Meet-or-slice Types
  const unsigned short SVG_MEETORSLICE_UNKNOWN = 0;
  const unsigned short SVG_MEETORSLICE_MEET = 1;
  const unsigned short SVG_MEETORSLICE_SLICE = 2;

  attribute unsigned short align;
  attribute unsigned short meetOrSlice;
};

The numeric alignment type constants defined on SVGPreserveAspectRatio are used to represent the alignment keyword values that ‘preserveAspectRatio’ can take. Their meanings are as follows:

ConstantMeaning
SVG_PRESERVEASPECTRATIO_NONEThe none keyword.
SVG_PRESERVEASPECTRATIO_XMINYMINThe xMinYMin keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMINThe xMidYMin keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMINThe xMaxYMin keyword.
SVG_PRESERVEASPECTRATIO_XMINYMIDThe xMinYMid keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMIDThe xMidYMid keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMIDThe xMaxYMid keyword.
SVG_PRESERVEASPECTRATIO_XMINYMAXThe xMinYMax keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMAXThe xMidYMax keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMAXThe xMaxYMax keyword.
SVG_PRESERVEASPECTRATIO_UNKNOWNSome other type of value.

Similarly, the numeric meet-or-slice type constants defined on SVGPreserveAspectRatio are used to represent the meet-or-slice keyword values that ‘preserveAspectRatio’ can take. Their meanings are as follows:

ConstantMeaning
SVG_MEETORSLICE_MEETThe meet keyword.
SVG_MEETORSLICE_SLICEThe slice keyword.
SVG_MEETORSLICE_UNKNOWNSome other type of value.

The align IDL attribute represents the alignment keyword part of the ‘preserveAspectRatio’ value. On getting, the following steps are run:

  1. Let value reflect the base value of a ‘preserveAspectRatio’ attribute. value is the current non-animated value of the attribute (using the attribute's initial value if it is not present or invalid).
  2. Return the constant value as specified in the alignment constant table above for the alignment keyword in value.

On setting align, the following steps are run:

  1. If the SVGPreserveAspectRatio is read only, then throw a NoModificationAllowedError.
  2. If value is SVG_PRESERVEASPECTRATIO_UNKNOWN or does not have a corresponding entry in the alignment keyword table above, then return.
  3. Let string be the corresponding keyword in the alignment keyword table above for value.
  4. Append a single U+0020 SPACE character to string.
  5. Let meet or slice be the value that would be returned from the meetOrSlice member on this SVGPreserveAspectRatio.
  6. Append to string the corresponding keyword in the meet-or-slice keyword table above for meet or slice.
  7. Set the reflected ‘preserveAspectRatio’ attribute to string.

The meetOrSlice IDL attribute represents the alignment keyword part of the ‘preserveAspectRatio’ value. On getting, the following steps are run:

  1. Let value be a ‘preserveAspectRatio’ value that reflects the base value of a ‘preserveAspectRatio’ attribute value is the current non-animated value of the attribute.
  2. If the meet-or-slice value is not present in value, then return SVG_MEETORSLICE_MEET.
  3. Otherwise, the meet-or-slice value is present. Return the constant value as specified in the meet-or-slice constant table above for the meet-or-slice keyword in value.

On setting meetOrSlice, the following steps are run:

  1. If the SVGPreserveAspectRatio is read only, then throw a NoModificationAllowedError.
  2. If value is SVG_MEETORSLICE_UNKNOWN or does not have a corresponding entry in the meet-or-slice keyword table above, then return.
  3. Let align be the value that would be returned from the align member on this SVGPreserveAspectRatio.
  4. Let string be the corresponding keyword in the alignment keyword table above for align.
  5. Append a single U+0020 SPACE character to string.
  6. Append to string the corresponding keyword in the meet-or-slice keyword table above for value.
  7. Set the reflected ‘preserveAspectRatio’ attribute to string.

8.14.5. Interface SVGAnimatedPreserveAspectRatio

An SVGAnimatedPreserveAspectRatio object is used to reflect the ‘preserveAspectRatio’ attribute.

[Exposed=Window]
interface SVGAnimatedPreserveAspectRatio {
  [SameObject] readonly attribute SVGPreserveAspectRatio baseVal;
  [SameObject] readonly attribute SVGPreserveAspectRatio animVal;
};

The baseVal and animVal IDL attributes represent the current non-animated value of the reflected ‘preserveAspectRatio’ attribute. On getting baseVal or animVal, an SVGPreserveAspectRatio object is returned that reflects the base value of the ‘preserveAspectRatio’ attribute on the SVG element that the object with the reflcting IDL attribute of type SVGAnimatedPreserveAspectRatio was obtained from.