DOMMatrix: 2D / 3D 変形（アフィン変換）の行列を扱う DOM API

Tweet

はじめに

null です。 図面（PDF や画像）を共有して注釈でコミュニケーションする Web アプリ を開発しております。

DOM 要素をアフィン変換（移動・拡縮・回転・剪断）するには CSS の transform プロパティ や SVG の transform 属性 を使うと思います。 translate, scale, rotate をそれぞれ 個別の CSS プロパティとする提案 もあり、すでに Firefox と Safari でサポートされています。

図形を扱う Web アプリを作っていると、 CSS transform で実現できる DOM 要素の変形だけでなく、スクリプトでも座標変換したいケースが出てきます。たとえば次のアニメーションのように、回転させた図形をリサイズしたい場合。リサイズを CSS transform や SVG transform の拡縮で実現すると線の太さが変わってしまうので、リサイズは座標計算で実現したいところです。回転行列とポインターの移動量から新たな座標とサイズを算出するにあたり、行列演算がほしくなります。

行列による座標変換の計算には、ブラウザーに組み込まれている DOMMatrix が使えます。ごく一般的な行列演算であればサードパーティライブラリは不要です。

DOMMatrix

コード例を見るのが早いと思います。

// 次の順に座標変換を適用するのと同等の行列を生成します。
//  1. 左へ 20px、上へ 30px、手前へ 50px 移動
//  2. 時計回りに 90° 回転
//  3. 上下左右へ 2 倍に拡大
// （一般に行列 X と Y による座標変換をこの順で適用するのと同等の行列は積 YX で求められます、順序に注意してください。）
const matrix = new DOMMatrix()
  .scaleSelf(2)
  .rotateSelf(0, 0, 90)
  .translateSelf(-20, -30, 50)

// 座標 (100, 150, 200) に座標変換を適用します。
const transformed = matrix.transformPoint({ x: 100, y: 150, z: 200 })

console.log(transformed)
// -> DOMPoint {x: -240, y: 160.00000000000003, z: 250, w: 1}

DOMMatrixReadOnly と DOMMatrix は 4×4 行列を表します。 m11 プロパティで (1, 1) 成分、 m12 プロパティで (1, 2) 成分、…、 m44 プロパティで (4, 4) 成分にアクセスできます。 DOMMatrixReadOnly は名前のとおり読み取り専用で、各プロパティ値を設定できず、自身を変更するメソッドを持ちません。 DOMMatrix は DOMMatrixReadOnly を継承し、各プロパティの setter や scaleSelf() などの自身を変更するメソッドを持ちます。
https://triple-underscore.github.io/geometry-ja.html#DOMMatrix

2D 変形では m11, m12, m21, m22, m41, m42 だけを扱います。この 6 つの成分は特別に a, b, c, d, e, f プロパティでアクセスできます。この 6 つ以外の成分が単位行列に一致するときは is2D プロパティが true になります。

DOMMatrixReadOnly と DOMMatrix でできる操作を見ていきましょう。

DOMMatrixReadOnly／DOMMatrix 初期化

コード例は DOMMatrix で記述しますが、 DOMMatrixReadOnly でも同じように使えます。

// 単位行列
new DOMMatrix()

// 2D 変形用の 2×3 行列: 6 要素の配列 [a, b, c, d, e, f]
new DOMMatrix([1, 2, 3, 4, 5, 6])

// 3D 変形用の 4×4 行列: 16 要素の配列 [m11, m12, ..., m44]
new DOMMatrix([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16])

// CSS transform で有効な文字列
new DOMMatrix('matrix(1,2,3,4,5,6)')
new DOMMatrix('matrix3d(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16)')
new DOMMatrix('translate(10px,20px)')
new DOMMatrix('translate3d(10px,20px,30px)')
new DOMMatrix('scale(2)')
new DOMMatrix('rotate(45deg)')
new DOMMatrix('rotateX(45deg)')
new DOMMatrix('skewX(30deg)')

// 座標 (10, 20) を中心に時計回りに 45° 回転
new DOMMatrix('translate(10px,20px) rotate(45deg) translate(-10px,-20px)')

// プロパティ（の一部）直接指定
DOMMatrix.fromMatrix({ a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 })
DOMMatrix.fromMatrix({ m44: 16 })

// 型付き配列（6 要素 または 16 要素）
DOMMatrix.fromFloat32Array(Float32Array.of(1, 2, 3, 4, 5, 6))
DOMMatrix.fromFloat64Array(Float64Array.of(1, 2, 3, 4, 5, 6))

DOMMatrixReadOnly インスタンスメソッド（DOMMatrix でも利用可）

ここで紹介するメソッドのすべての引数は省略可能です。特筆しない限りデフォルト引数は行列なら単位行列、座標・移動量・回転角なら 0、拡大率なら 1 です。

transformPoint() は新しい DOMPoint インスタンス（後述）を返します。 transformPoint() 以外のメソッドは新しい DOMMatrix インスタンスを返します（DOMMatrixReadOnly ではありません）。

const m = new DOMMatrixReadOnly()

// 逆行列
m.inverse()

// 積
m.multiply(anotherMatrix)

// 平行移動
m.translate(tx, ty, tz)


// 拡大縮小、 デフォルト引数は scaleX: 1, scaleY: scaleX, scaleZ: 1, 他は 0
// （引数 2 つ以上なら軸ごとに異なる倍率で拡縮、引数 1 つなら xy 方向に同じ倍率で拡縮）
m.scale(scaleX, scaleY, scaleZ, originX, originY, originZ)

// m.scale(scale, scale, scale, originX, originY, originZ) と同じ
m.scale3d(scale, originX, originY, originZ)

// 非推奨、 m.scale(scaleX === undefined ? 1 : scaleX, scaleY === undefined ? 1 : scaleY) と同じ
m.scaleNonUniform(scaleX, scaleY)


// xyz 軸まわりの回転: x, y, z 軸まわりに、この順で、それぞれ rotX, rotY, rotZ （単位は度）だけ時計回りに回転
m.rotate(rotX, rotY, rotZ)

// 任意の軸まわりの回転: (x, y, z) 方向を回転軸として angle （単位は度）だけ時計回りに回転
m.rotateAxisAngle(x, y, z, angle)

// (1, 0) 方向から (x, y) 方向への回転角だけ x 軸まわりに回転
// m.rotate(Math.atan2(y, x) * 180 / Math.PI) と同じ
// たとえば (1, 1) なら 45° で m.rotate(45) と同じ
m.rotateFromVector(x, y)


// 水平剪断
// https://developer.mozilla.org/docs/Web/CSS/transform-function/skewX()
m.skewX(sx)

// 鉛直剪断
// https://developer.mozilla.org/docs/Web/CSS/transform-function/skewY()
m.skewY(sy)


// 点の座標変換、デフォルト引数は x: 0, y: 0, z: 0, w: 1
m.transformPoint({ x, y, z, w })

DOMMatrix インスタンスメソッド

いずれも this 自身を変更して this 自身を返します。

const m = new DOMMatrix()

// DOMMatrixReadOnly の `Self` が付かない各メソッドと同等の演算により自身を変更
m.multiplySelf(anotherMatrix)
m.translateSelf(tx, ty, tz)
m.scaleSelf(scaleX, scaleY, scaleZ, originX, originY, originZ)
m.scale3dSelf(scale, originX, originY, originZ)
m.rotateSelf(rotX, rotY, rotZ)
m.rotateAxisAngleSelf(x, y, z, angle)
m.rotateFromVectorSelf(x, y)
m.skewXSelf(sx)
m.skewYSelf(sy)

// 逆行列
m.invertSelf()

// 左からの積
m.preMultiplySelf(anotherMatrix)

// CSS transform で有効な文字列のパース
m.setMatrixValue('matrix(1,2,3,4,5,6)')
m.setMatrixValue('translate(10px,20px) rotate(45deg) translate(-10px,-20px)')

DOMPoint

DOMPointReadOnly と DOMPoint は x y z 軸の各座標と視座 w で点を表します。 DOMPointReadOnly は名前のとおり読み取り専用で、各プロパティ値を設定できません。 DOMPoint は DOMPointReadOnly を継承し、各プロパティの setter を持ちます。
https://triple-underscore.github.io/geometry-ja.html#DOMPoint

行列による座標変換 API として DOMMatrixReadOnly.prototype.transformPoint({ x, y, z, w }) を紹介しましたが、 DOMPointReadOnly.prototype.matrixTransform(matrix) でも同じことができます。違いは this と引数の型の縛りです。 transformPoint は this として DOMMatrixReadOnly を継承したオブジェクトが必要で、引数は座標ライクなオブジェクト（x, y, z, w プロパティが影響）（省略可）です。 matrixTransform() は this として DOMPointReadOnly を継承したオブジェクトが必要で、引数は行列ライクなオブジェクト（a, …, f, m11, …, m44 プロパティが影響）（省略可）です。私は基本的に transformPoint({ x, y, z }) を使えば良いと思っています： どうせ DOMMatrix は作るので DOMPoint を作らずに済む方がラクですし、行列を構築するメソッドチェインから流れるように座標変換できて読みやすいからです。

WebKitCSSMatrix と MSCSSMatrix

もしあの IE で行列が使いたくなったらどうしましょう？ IE 10+ には MSCSSMatrix があります。

DOMMatrix が標準化されるより前、 Safari と Chrome には WebKitCSSMatrix という名前で現在の DOMMatrixReadOnly の機能の一部が実装されていました。下記リンクから当時のインターフェイスを参照できます。現在では Safari も Chrome も WebKitCSSMatrix が DOMMatrix のエイリアスになっています。今後わざわざ WebKitCSSMatrix を使う機会はないでしょう。

• WebKitCSSMatrix | Apple Developer Documentation
  https://developer.apple.com/documentation/webkitjs/webkitcssmatrix
• third_party/WebKit/Source/core/css/WebKitCSSMatrix.idl – chromium/src – Git at Google
  https://chromium.googlesource.com/chromium/src/+/0b2fd946c81a4c7a26dcb6ed1c3957edb9acedcd/third_party/WebKit/Source/core/css/WebKitCSSMatrix.idl

IE 10+ に組み込まれている MSCSSMatrix は WebKitCSSMatrix と同様のインターフェイスを持ちます。 transformPoint() がないので、点を座標変換するには行列同士の積 multiply() を使います。

const Matrix = window.DOMMatrix || window.MSCSSMatrix

const matrix = new Matrix()
  .scale(2)
  .rotate(0, 0, 90)
  .translate(-20, -30, 50)

const point = new Matrix()
point.e = 100   // x
point.f = 150   // y
point.m43 = 200 // z

const transformed = matrix.multiply(point)
console.log(transformed.e, transformed.f, transformed.m43)
// -> -240 160.00000000000003 250

Can I use で DOMMatrix の歴史が垣間見られます。
https://caniuse.com/dommatrix

SVGMatrix

SVGMatrix は 2D 変形用の 2×3 行列です。 IE 9+ で使えます。 a, b, c, d, e, f プロパティはありますが m11, m12, …, m44 プロパティはありません。 DOMMatrixReadOnly が持つメソッドの一部が同じ名前で使えます（次のリンク先参照）。
https://triple-underscore.github.io/SVG11/coords.html#InterfaceSVGMatrix

SVGMatrix は MDN に Deprecated と明記されています。 SVG 1.1 では SVGMatrix を使う仕様だったインターフェイスが SVG 2 では DOMMatrix や DOMMatrixReadOnly を使うよう変更されています（SVGGraphicsElement.prototype.getScreenCTM や SVGTransform.prototype.matrix など）。が、現在の主要ブラウザー（Chrome 91, Firefox 88, Safari 14.1, IE 11）はいずれも DOMMatrix ではなく SVGMatrix を利用する実装になっています。（もしかしたら後方互換性のためにずっとこのままかもしれませんね。）

SVGMatrix は下記例のとおり DOMMatrix に比べると扱いづらいです。 DOMMatrix が使える場面では DOMMatrix を使いましょう。必要なら DOMMatrix.fromMatrix() で SVGMatrix から DOMMatrix を生成できます。

const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')

// SVGMatrix インスタンスは new SVGMatrix() では生成できず SVGSVGElement インスタンスが必要、
// しかも生成時に初期化できない（createSVGMatrix() は引数を取らない）
const svgMatrix = svg
  .createSVGMatrix()
  .scale(2)
  .rotate(0, 0, 90)
  .translate(-20, -30)

// SVGPoint インスタンスは new SVGPoint() では生成できず SVGSVGElement インスタンスが必要、
// しかも生成時に初期化できない（createSVGPoint() は引数を取らない）
const svgPoint = svg.createSVGPoint()
svgPoint.x = 100
svgPoint.y = 150

// transformPoint() がないので matrixTransform() を使う
const transformed = svgPoint.matrixTransform(svgMatrix)

// DOMMatrix に変換した方が扱いやすいかもしれない
DOMMatrix.fromMatrix(svgMatrix).transformPoint({ x: 100, y: 150 })

// DOMPointReadOnly.prototype.matrixTransform() の引数は SVGMatrix でも OK
new DOMPoint(100, 150).matrixTransform(svgMatrix)

TypeScript 使用上の注意：
SVGMatrix の IDL 属性は DOMMatrix より少ないのですが、 TypeScript 4.2.4 現在、 lib.dom.d.ts の SVGMatrix 型定義 は type SVGMatrix = DOMMatrix と記述されており、実際の SVGMatrix にないメンバーを使ってもコンパイルが通ってしまいます（補完候補としても出てきてしまいます）。

まとめ

座標変換のための行列を扱う DOMMatrix とその周辺の API を紹介しました。