Matrix

Matrices in SVG.js have their own class SVG.Matrix, wrapping the native SVGMatrix. They add a lot of functionality like extracting transform values, matrix morphing and improvements on the native methods.

SVG.Matrix

In SVG.js matrices accept various values on initialization.

Without a value:

var matrix = new SVG.Matrix
matrix.toString() //-> returns matrix(1,0,0,1,0,0)

Six arguments:

var matrix = new SVG.Matrix(1, 0, 0, 1, 100, 150)
matrix.toString() //-> returns matrix(1,0,0,1,100,150)

A string value:

var matrix = new SVG.Matrix('1,0,0,1,100,150')
matrix.toString() //-> returns matrix(1,0,0,1,100,150)

An object value:

var matrix = new SVG.Matrix({ a: 1, b: 0, c: 0, d: 1, e: 100, f: 150 })
matrix.toString() //-> returns matrix(1,0,0,1,100,150)

A native SVGMatrix:

var svgMatrix = svgElement.getCTM()
var matrix = new SVG.Matrix(svgMatrix)
matrix.toString() //-> returns matrix(1,0,0,1,0,0)

Even an instance of SVG.Element:

var rect = draw.rect(50, 25)
var matrix = new SVG.Matrix(rect)
matrix.toString() //-> returns matrix(1,0,0,1,0,0)

around()

returns SVG.Matrix

Performs a given matrix transformation around a given center point:

// cx, cy, matrix
matrix.around(100, 150, new SVG.Matrix().skew(0, 45))

The matrix passed as the third argument will be used to multiply.

at()

returns SVG.Matrix

This method will morph the matrix to a given position between 0 and 1:

matrix.at(0.27)

This will only work when a destination matirx is defined using the morph() method.

clone()

returns SVG.Matrix

Returns an exact copy of the matrix:

matrix.clone()

extract()

returns object

Gets the calculated values of the matrix as an object:

matrix.extract()

The returned object contains the following values:

  • x (translation on the x-axis)
  • y (translation on the y-axis)
  • skewX (calculated skew on x-axis)
  • skewY (calculated skew on y-axis)
  • scaleX (calculated scale on x-axis)
  • scaleY (calculated scale on y-axis)
  • rotation (calculated rotation)

flip()

returns SVG.Matrix

Flips matrix over a given axis:

matrix.flip('x')

or

matrix.flip('y')

By default elements are flipped over their center point. The flip axis position can be defined with the second argument:

matrix.flip('x', 150)

or

matrix.flip('y', 100)

inverse()

returns SVG.Matrix

Creates an inverted matix:

matrix.inverse()

morph()

returns itself

In order to animate matrices the morph() method lets you pass a destination matrix. This can be any value a SVG.Matrix would accept on initialization:

matrix.morph('matrix(2,0,0,2,100,150)')

multiply()

returns SVG.Matrix

Multiplies by another given matrix:

matrix.matrix(matrix2)

native()

returns SVGMatrix

Returns a native SVGMatrix extracted from the SVG.Matrix instance:

matrix.native()

rotate()

returns SVG.Matrix

Rotates matrix by degrees with one value given:

// degrees
matrix.rotate(45)

Rotates a matrix by degrees around a given point with three values:

// degrees, cx, cy
matrix.rotate(45, 100, 150)

scale()

returns SVG.Matrix

Scales matrix uniformal with one value:

// scale
matrix.scale(2)

Scales matrix non-uniformal with two values:

// scaleX, scaleY
matrix.scale(2, 3)

Scales matrix uniformal on a given center point with three values:

// scale, cx, cy
matrix.scale(2, 100, 150)

Scales matrix non-uniformal on a given center point with four values:

// scaleX, scaleY, cx, cy
matrix.scale(2, 3, 100, 150)

skew()

returns SVG.Matrix

Skews matrix a given degrees over x and or y axis with two values:

// degreesX, degreesY
matrix.skew(0, 45)

Skews matrix a given degrees over x and or y axis on a given point with four values:

// degreesX, degreesY, cx, cy
matrix.skew(0, 45, 150, 100)

toString()

returns string

Converts the matrix to a transform string:

matrix.toString()
// -> matrix(1,0,0,1,0,0)

translate()

returns SVG.Matrix

Translates matrix by a given x and y value:

matrix.translate(10, 20)
Fork me on GitHub