SVG Transforms 1.0, Part 2: Language

This working draft defines features of the Scalable Vector Graphics (SVG) Language that are specifically for display environments.

This document defines the markup used by SVG Transforms. SVG Transforms allows two-dimensional objects to be transformed using three-dimensional transformations.

Although originally designed for use in SVG, some aspects of this specification are defined in XML and are accessed via presentation properties, and therefore could be used in other environments, such as HTML styled with CSS and XSL:FO.

Status of This Document

This will be the last published Working Draft of this specification. Work will continue with a combined CSS and SVG Transforms specification operating under the FX Taskforce. The latest Editors' Draft of the new specification is available.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document is the first public working draft of this specification. There will be an accompanying Transforms Primer that lists the ways SVG Transforms may be used.

We explicitly invite comments on this specification. Please send them to www-svg@w3.org (archives), the public email list for issues related to vector graphics on the Web. Acceptance of the archiving policy is requested automatically upon first post to either list. To subscribe to this list, please send an email to www-svg-request@w3.org with the word subscribe in the subject line.

The latest information regarding patent disclosures related to this document is available on the Web. As of this publication, the SVG Working Group are not aware of any royalty-bearing patents they believe to be essential to SVG.

How to read this document and give feedback

This working draft of SVG Transforms introduces new Transforms syntax and markup for the SVG language. One of the goals is that this specification can be re-used more easily by other specifications that want to have advanced Transforms features. This specification introduces syntax that may not be backwards compatible with older SVG User Agents, and the use of this syntax should be accompanied by a fallback using the 'switch' element.

The main purpose of this document is to encourage public feedback. The best way to give feedback is by sending an email to www-svg@w3.org. Please include some kind of keyword that identifies the area of the specification the comment is referring to in the subject line of your message (e.g "Section X.Y - Foo attribute values" or "Transforms Functionality"). If you have comments on multiple areas of this document, then it is probably best to split those comments into multiple messages.

The public are welcome to comment on any aspect in this document, but there are a few areas in which the SVG Working Group are explicitly requesting feedback. These areas are noted in place within this documentlike this. There is also a specific area related to the specification that is listed here:

1. Introduction

This document is normative and lists features that may be used in the context of display. The various scenarios are listed in the SVG Transforms Requirements document.

Note that even though this specification references parts of SVG Tiny 1.2 it does not require a complete or SVG Tiny 1.2 implementation.

This document contains explicit conformance criteria that overlap with some RNG definitions in requirements. If there is any conflict between the two, the explicit conformance criteria are the definitive reference.

The SVG Transforms module extends the two-dimensional transformation pipeline in SVG to allow graphical elements to be transformed in three-dimensions. For elements to be transformed using three-dimensonal transformations a Z axis is introduced by this module. The elements in SVG can be positioned along the Z axis and transformed in 3D space, however the elements themselves still remain two-dimensional. A perspective projection can be applied to elements to give the illusion of depth. The projection plane for a perspective projection is the X-Y plane (where Z = 0). All are still rendered to this plane. Unless stated otherwise, all elements are rendered in document order as per the existing SVG specifications.

1.1. Projection Matrix

The projection matrix provides a means for depth information of an element to be specified. Depth information can be represented as a 4x4 matrix of the following form:

The projection transformation matrix is also expressed as a vector [x y d]. The 'perspective' property is used to set the perspective projection matrix of an object.

1.2. 3D Transformation Matrix

The 3D transformation matrices provide a means to transform a point in 3D space before it is projected to a 2D plane. Mathematically, all 3D transforms can be represted as a 4x4 transformation matrices.

The 3D transforms matrices are of the following form:

a b c d
e f g h
i j k m
0 0 0 1

The 3D transformation matrix is also expressed as a vector [a b c d e f g h i j k m]. The transforms in the TransformsList Extensions can be used to set the transformation of an object.

The CSS 3D Transforms specification uses 16 values.

1.2.1. 3D Translation Matrix

A 3D Translation is equivalent to the matrix:

1.2.2. 3D Scaling Matrix

A 3D Scaling is equivalent to the matrix:

1.2.3. 3D Rotation

A 3D Rotation is equivalent to the matrix:

t.nx.nx + c     t.nx.ny - s.nz  t.nx.nz + s.ny  0
t.nx.ny + s.nz  t.ny.ny + c     t.ny.nz - s.nx  0
t.nx.nz - s.ny  t.ny.nz + s.nx  t.nz.nz + c     0
       0              0               0         1

where:

c = cos(a)
s = sin(a)
t = 1 - cos(a)

1.2.4. 3D Rotation about X

A 3D Rotation about the X axis is equivalent to the matrix:

1   0       0    0
0 cos(a) -sin(a) 0
0 sin(a) cos(a)  0
0   0       0    1

1.2.5. 3D Rotation about Y

A 3D Rotation about the Y axis is equivalent to the matrix:

 cos(a) 0 sin(a)  0
   0    1    0    0
-sin(a) 0 cos(a)  0
   0    0    0    1

1.2.6. 3D Rotation about Z

A 3D Rotation about the Z axis is equivalent to the matrix:

cos(a) -sin(a) 0  0
sin(a)  cos(a) 0  0
  0      0     1  0
  0      0     0  1

2. Perspective Definitions

The SVG Working Group is currently discussing how to give the author the ability to change the Z order of objects. One possible solution is to use the CSS 'transform-style' property on a group. When set to "preserve-3d", it allows child elements in the group to be re-ordered based on their Z position (rather than document order). A similar option is to introduce a container element 'layeredG' or 'g3d' where the order of rendering the child elements is based on its Z position. Note that in either case I different tree traversal order may only be needed. This would help restrict the complexity when rendering 3D Transforms in SVG. The SVG Working Group believes this is the most optimal solution without causing too many complexities to SVG Implementations. The SVG Working Group welcomes any comments or suggestions regarding this feature.

2.1. The 'transform-origin' property

The 'transform-origin' property establishes the transformation origin of an element in the element's CTM .

'transform-origin'

Value:	<list-of-lengths> \| none
Initial:	0 0 0
Applies to:	Renderable elements. For SVG container elements and graphics elements.
Inherited:	no
Percentages:	no
Media:	visual
Animatable:	yes

none

No new transformation origin is established. This is the lacuna value.

<list-of-lengths>

A list of three <lengths>s (<ox>, <oy> and <oz>), separated by white space and or a comma, which specify the origin to transform the element about. The coordinate definitions are as follows:

<ox> specifies the x <coordinate> of the new origin of the element using one of the values: left | center | right | <percentage>. This coordinate is established using the bounding box of the element to which the transform is applied (see Object bounding box units).

The value left means the left most edge of the object's bounding box.

The value center means the horizontal center of the object's bounding box.

The value right means the right most edge of the object's bounding box.
<oy> specifies the y <coordinate> of the new origin of the element using one of the values: top | center | bottom | <percentage>. This coordinate is established using the bounding box of the element to which the transform is applied (see Object bounding box units).

The value top means the top most edge of the object's bounding box.

The value center means the vertical center of the object's bounding box.

The value bottom means the right most edge of the object's bounding box.
<oz> specifies the z <coordinate> of the new origin of the element. The value is in the current user coordinate system .

The 'transform-origin' is the equivalent of the following specification: translate(<ox>, <oy>, <oz>) <transform> translate(-<ox>, -<oy>, -<oz>) . If a <transform> already specifies a transformation origin the 'transform-origin' is still applied as per the equivalent specification specified above.

This property is similar to property in the CSS 3D Transforms specification.

2.2. The 'perspective' Property

The 'perspective' property specifies a projeciton matrix to apply to child elements contained within the current element. It effectively sets the viewpoint to project an element on the X-Y viewing plane (where z=0).

'perspective'

Value:	<list-of-lengths> \| none
Initial:	none
Applies to:	Renderable elements. For SVG container elements and graphics elements.
Inherited:	no
Percentages:	N/A
Media:	visual
Animatable:	yes

none

No perspective transformation is applied to the element. This is the lacuna value.

<list-of-lengths>

A list of three <lengths>s (<px>, <py> and <pd>), separated by white space and or a comma, which specify the position and depth of the perspective projection matrix for an element. The coordinate definitions are as follows:

<px> specifies the x <coordinate> of the perspective viewpoint on the X-Y viewing plane. The value is in the current user coordinate system .
<py> specifies the y <coordinate> of the perspective viewpoint on the X-Y viewing plane. The value is in the current user coordinate system .
<pd> specifies the <coordinate> representing the viewpoint distance from the X, Y viewing plane. The value is in the current user coordinate system .

This property is similar to property in the CSS 3D Transforms specification.

Consider adding "near" and "far" planes to the 'perspective' property. Could have a value like: perspective(<px> <py> <pd> [<n> <f>]). <n> and <f> define the Near and Far clipping planes for the perspective view.

3. TransformList Extensions

SVG Transforms extends the transform types availble in the SVG TransformList.

matrix(a b c d e f g h i j k m), which specifies a transformation in the form of a 3D transformation matrix of 12 values. matrix(a,b,c,d,e,f,g,h,i,j,k,m) is equivalent to applying the transformation matrix [a b c d e f g h i j k m].
translate(<tx> [<ty> [<tz>]]), which specifies a 3D translation by tx, ty and tz. If <ty> and <tz> are not provided, it is assumed to be zero.
scale(<sx> [<sy> [<sz>]]), which specifies a 3D scale operation by sx, sy and sz. If <sy> and <sz> are not provided, it is assumed to be equal to <sx>.
rotate(<rotate-angle> <nx> <ny> <nz> [<cx> <cy> <cz>]), which specifies a 3D rotation by <rotate-angle> degrees in the direction defined by the vector <nx> <ny> <nz> about a given point.

If optional parameters <cx>, <cy> and <cz> are not supplied, the rotation is about the origin of the current user coordinate system.

If optional parameters <cx>, <cy> and <cz> are supplied, the rotation is about the point (cx, cy and cz). The operation represents the equivalent of the following specification: translate(<cx>, <cy>, <cz>) rotate(<rotate-angle> <nx> <ny> <nz>) translate(-<cx>, -<cy>, -<cz>).
rotateX(<rotate-angle> [<cy> <cz>]), which specifies a rotation by <rotate-angle> degrees about the X axis.

If optional parameters <cy> and <cz> are supplied, the rotation is about the point (cy, cz). The operation represents the equivalent of the following specification: translate(0, <cy>, <cz>) rotateX(<rotate-angle>) translate(0, -<cy>, -<cz>).
rotateY(<rotate-angle> [<cx> <cz>]), which specifies a rotation by <rotate-angle> degrees about the Y axis.

If optional parameters <cx> and <cz> are supplied, the rotation is about the point (cx, cz). The operation represents the equivalent of the following specification: translate(<cx>, 0, <cz>) rotateX(<rotate-angle>) translate(-<cx>, 0, -<cz>).
rotateZ(<rotate-angle> [<cx> <cy>]), which specifies a rotation by <rotate-angle> degrees about the Z axis.

If optional parameters <cx> and <cy> are supplied, the rotation is about the point (cx, cy). The operation represents the equivalent of the following specification: translate(<cx>, <cy>, 0) rotateX(<rotate-angle>) translate(-<cx>, -<cy>, 0).

4. 'animateTransform' Extensions

SVG Transforms extends the 'animateTransform' element 'type' to include the TransformList extensions.

Attribute definition:

Indicates the type of transformation which is to have its values change over time. If 'type' has an unsupported value (e.g. type="foo" or type="ref(svg)") the 'animateTransform' element is ignored.

Animatable: no.

The 'from', 'by' and 'to' attributes take a value expressed using the same syntax that is available for the given transformation type:

For a type="translate", each individual value is expressed as <tx> [,<ty> [,<tz>]].
For a type="scale", each individual value is expressed as <sx> [,<sy>[,<sz>]].
For a type="rotate", each individual value is expressed as rotate(<rotate-angle> <nx> <ny> <nz> [<cx> <cy> <cz>]) .
For a type="rotateX", each individual value is expressed as rotateX(<rotate-angle> [<cy> <cz>]) .
For a type="rotateY", each individual value is expressed as rotateY(<rotate-angle> [<cx> <cz>]) .
For a type="rotateZ", each individual value is expressed as rotateZ(<rotate-angle> [<cx> <cy>]) .
For a type="skewX" and type="skewY", each individual value is expressed as <skew-angle>.

5. Converting a 4x4 to a 3x3 matrix

A rectangle ABCD is given on plane X-Y. When a 3D affine transform and perspective projection are applied, a quadrangle A'B'C'D' will appear on the X-Y plane. Note the X-Y plane is the projection plane. Generally, this mapping is expressed as a 4x4 matrix.

An affine 3D Transform Matrix T is given as

    | a11 a12 a13 a14 |
M = | a21 a22 a23 a24 |
    | a31 a32 a33 a34 |
    |  0   0   0   1  |

A Perspective Projection Matrix P is given as

    | 1 0  0   0 |
P = | 0 1  0   0 |
    | 0 0  0   0 |
    | 0 0 1/d  1 |

The combined matrix Mcan be expressed as

M = P.T

    | 1 0  0   0 | | a11 a12 a13 a14 |
  = | 0 1  0   0 |.| a21 a22 a23 a24 |
    | 0 0  0   0 | | a31 a32 a33 a34 |
    | 0 0 1/d  1 | |  0   0   0   1  |

    |  a11   a12   a13     a14    |
  = |  a21   a22   a23     a24    |
    |   0     0     0       0     |
    | a31/d a32/d a33/d (a34/d)+1 |

  = Expression 1

An arbitary point K can be expressed as (kx, ky, 0). If the point K is transformed to point K'(k'x,k'y,0), the eqation is derived

| k'x |     | kx |
| k'y | = M.| ky |
|  0  |     | 0  |
| k'w |     | 1  |

          |  a11   a12   a13     a14    | | kx |
        = |  a21   a22   a23     a24    |.| ky |
          |   0     0     0       0     | | 0  |
          | a31/d a32/d a33/d (a34/d)+1 | | 1  |

          | a11.kx + a12.ky + a14               |
        = | a21.kx + a22.ky + a24               |
          | 0                                   |
          | (a31/d).kx + (a32/d).ky + (a34/d)+1 |

        = Expression 2

A non-affine 3x3 matrix (F) can be expressed as a 4x4 where the components that make up the Z axis are set to 0 as shown below

    | b11 b12  0  b14 |
F = | b21 b22  0  b24 |
    |  0   0   0   0  |
    | b41 b42  0   1  |

If matrix F can be used to map point K to point K' as shown below

| k'x |     | kx |
| k'y | = F.| ky |
|  0  |     | 0  |
| k'w |     | 1  |

          | b11 b12  0  b14 | | kx |
        = | b21 b22  0  b24 |.| ky |
          |  0   0   0   0  | | 0  |
          | b41 b42  0   1  | | 1  |

          | b11.kx + b12.ky + b14 |
        = | b21.kx + b22.ky + b24 |
          | 0                     |
          | b41.kx + b42.ky + 1   |

        = Expression 3

Expression 2 can be shown to be related to Expression 3 for any arbitary point kx, ky by a constant m

| a11.kx + a12.ky + a14               |   | m.(b11.kx + b12.ky + b14) |
| a21.kx + a22.ky + a24               | = | m.(b21.kx + b22.ky + b24) |
| 0                                   |   |    0                      |
| (a31/d).kx + (a32/d).ky + (a34/d)+1 |   | m.(b41.kx + b42.ky + 1)   |

Thus it can be said from the above relationship

        a11 = m.b11
        a12 = m.b12
        a14 = m.b14
        a21 = m.b21
        a22 = m.b22
        a24 = m.b24
      a31/d = m.b41
      a32/d = m.b42
(a34/d) + 1 = m

Therefore, the combination of An affine 3D Transform Matrix and a Perspective Projection Matrix can be expressed by using a 3x3 matirx as follows

| a11     a12        a14    |
| a21     a22        a24    |
| a31/d  a32/d  (a34/d) + 1 |

6. RelaxNG Schema for SVG Transforms 1.0

The schema for SVG Transforms 1.0 is written in RelaxNG [RelaxNG], a namespace-aware schema language that uses the datatypes from XML Schema Part 2 [Schema2]. This allows namespaces and modularity to be much more naturally expressed than using DTD syntax. The RelaxNG schema for SVG Transforms 1.0 may be imported by other RelaxNG schemas, or combined with other schemas in other languages into a multi-namespace, multi-grammar schema using Namespace-based Validation Dispatching Language [NVDL].

Unlike a DTD, the schema used for validation is not hardcoded into the document instance. There is no equivalent to the DOCTYPE declaration. Simply point your editor or other validation tool to the IRI of the schema (or your local cached copy, as you prefer).

The RNG is under construction, and only the individual RNG snippets are available at this time. They have not yet been integrated into a functional schema. The individual RNG files will be available soon.

7. DOM interfaces

The interfaces below will be made available in a IDL file for an upcoming draft.

7.1. Interface SVGMatrix

The SVGMatrix interface corresponds to setting the equivalent matrix values of a component from the transform attribute specification.

IDL Definition

interface SVGMatrix
{
  float getComponent(in unsigned long index)
      raises(DOMException);
  SVGMatrix multiply(in SVGMatrix secondMatrix);
  SVGMatrix inverse()
      raises(SVGException);
  SVGMatrix translate(in float x, in float y, in float z);
  SVGMatrix scale(in float scaleFactor-x, in float scaleFactor-y, in scaleFactor-y);
  SVGMatrix rotate(in float angle);
  SVGMatrix rotateX(in float angle);
  SVGMatrix rotateY(in float angle);
  SVGMatrix rotateZ(in float angle);
};

Methods

getComponent3D
multiply3D
inverse
translate
scale
rotateX
rotateY
rotateZ

7.2. Interface SVGPerspective

The SVGPerspective interface corresponds to the 'perspective' attribute.

IDL Definition

Interface SVGPerspective
{
  attribute float ex;
  attribute float ey;
  attribute float ez;
};

Attributes

float ex
float ey
float ez

7.3. Interface SVGTransformOrigin

The SVGTransformOrigin interface corresponds to the 'transform-origin' attribute.

IDL Definition

Interface SVGTransformOrigin
{
  attribute float ox;
  attribute float oy;
  attribute float oz;
};

Attributes

float ox
float oy
float oz

7.4. Interface SVGSVGElement

The SVGMatrix interface corresponds to creating a 3D Transformation Matrix.

IDL Definition

interface SVGSVGElement : SVGLocatableElement, SVGTimedElement
{
  SVGMatrix createSVGMatrixComponents
  (
    in float m1, in float m2, in float m3, in float m4,
    in float m5, in float m6, in float m7, in float m8,
    in float m9, in float m10, in float m11, in float m12
  );
  SVGPerspective createSVGerspective
  (
    in float p1, in float p2, in float p3
  );
};

Methods

createSVGMatrixComponents
createSVGerspective

Interface SVGLocatable

IDL Definition

interface SVGLocatable
{
  SVGMatrix getScreenCTM();
  SVGPerspective getScreenPerspective();
};

Methods

getScreenCTM
getScreenPerspective

7.5. Interface TraitAccess

IDL Definition

interface TraitAccess
{
  SVGMatrix getMatrixTrait(in DOMString name)
      raises(DOMException);
  SVGMatrix getMatrixPresentationTrait(in DOMString name)
      raises(DOMException);
  void setMatrixTrait(in DOMString name, in SVGMatrix matrix)
      raises(DOMException);
};

Methods

getMatrixTrait
getMatrixPresentationTrait
setMatrixTrait

8. References

8.1. Normative References

[NVDL]: Document Schema Definition Languages (DSDL) — Part 4: Namespace-based Validation Dispatching Language — NVDL. ISO/IEC FCD 19757-4, See http://www.asahi-net.or.jp/~eb2m-mrt/dsdl/
[RelaxNG]: Document Schema Definition Languages (DSDL) — Part 2: Regular grammar- based validation — RELAX NG. ISO/IEC FDIS 19757-2:2002(E), J. Clark, 村田真 (Murata M.), eds., 12 December 2002. See http://www.y12.doe.gov/sgml/sc34/document/0362_files/relaxng-is.pdf
[Schema2]: XML Schema Part 2: Datatypes Second Edition, P. Biron, A. Malhotra, eds. W3C, 28 October 2004 (Recommendation). Latest version available at http://www.w3.org/TR/xmlschema-2/. See also Processing XML 1.1 documents with XML Schema 1.0 processors.
[SVGT12]: Scalable Vector Graphics (SVG) Tiny 1.2 Specification, O. Andersson, R. Berjon, E. Dahlström, A. Emmons, J. Ferraiolo, A. Grasso, V. Hardy, S. Hayman, D. Jackson, C. Lilley, C. McCormack, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear, editors. W3C, 22 December 2008 (Recommendation). See http://www.w3.org/TR/2008/REC-SVGTiny12-20081222/

8.2. Informative References

[SVGTransformsReqs]: SVG Transforms Requirements, Jun Fujisawa, Anthony Grasso, Canon Inc., (Working Draft). See http://dev.w3.org/SVG/modules/transforms/SVGTransformsReqs.html
[OpenVG11]: OpenVG 1.1 Specification, Daniel Rice, Google Inc. See http://www.khronos.org/registry/vg/specs/openvg_1_0_1.pdf

SVG Transforms 1.0, Part 2: Language

W3C Editor's Draft 11 March 2009

Abstract

Status of This Document

How to read this document and give feedback

Contents

1. Introduction

1.1. Projection Matrix

1.2. 3D Transformation Matrix

1.2.1. 3D Translation Matrix

1.2.2. 3D Scaling Matrix

1.2.3. 3D Rotation

1.2.4. 3D Rotation about X

1.2.5. 3D Rotation about Y

1.2.6. 3D Rotation about Z

2. Perspective Definitions

2.1. The 'transform-origin' property

2.2. The 'perspective' Property

3. TransformList Extensions

4. 'animateTransform' Extensions

5. Converting a 4x4 to a 3x3 matrix

6. RelaxNG Schema for SVG Transforms 1.0

7. DOM interfaces

7.1. Interface SVGMatrix

7.2. Interface SVGPerspective

7.3. Interface SVGTransformOrigin

7.4. Interface SVGSVGElement

Interface SVGLocatable

7.5. Interface TraitAccess

8. References

8.1. Normative References

8.2. Informative References

9. Acknowledgements