1# Matrix2D
2
3**Matrix2D** allows you to perform matrix transformation, such as scaling, rotating, and translating.
4
5>  **NOTE**
6>
7> The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9## APIs
10
11Matrix2D(unit?: LengthMetricsUnit)
12
13**Widget capability**: This API can be used in ArkTS widgets since API version 9.
14
15**Atomic service API**: This API can be used in atomic services since API version 11.
16
17**System capability**: SystemCapability.ArkUI.ArkUI.Full
18
19**Parameters**
20
21| Name | Type | Mandatory | Description                             |
22| ------ | -------- | ---- | ------------------------------------- |
23| unit<sup>12+</sup>  | [LengthMetricsUnit](../js-apis-arkui-graphics.md#lengthmetricsunit12) | No  | Unit mode of the **Matrix2D** object. The value cannot be dynamically changed once set. The configuration method is the same as that of [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md#lengthmetricsunit12).<br>Default value: **DEFAULT**|
24
25## Attributes
26
27**Widget capability**: This API can be used in ArkTS widgets since API version 9.
28
29**Atomic service API**: This API can be used in atomic services since API version 11.
30
31**System capability**: SystemCapability.ArkUI.ArkUI.Full
32
33| Name | Type | Read Only | Optional  | Description |
34| ----- | ----- | --------------- | ------ | ------------------------ |
35| [scaleX](#scalex)         | number | No | Yes | Horizontal scale factor.          |
36| [scaleY](#scaley)         | number | No | Yes | Vertical scale factor.          |
37| [rotateX](#rotatex)       | number | No | Yes | Horizontal tilt coefficient.          |
38| [rotateY](#rotatey)       | number | No | Yes | Vertical tilt coefficient.          |
39| [translateX](#translatex) | number | No | Yes | Distance to translate on the x-axis.<br>Default unit: vp |
40| [translateY](#translatey) | number | No | Yes | Distance to translate on the y-axis.<br>Default unit: vp |
41
42>  **NOTE**
43>
44>  You can use the [px2vp](ts-pixel-units.md#pixel-unit-conversion) API to convert the unit.
45
46### scaleX
47
48```ts
49// xxx.ets
50@Entry
51@Component
52struct Matrix2DScaleX {
53  @State message: string = 'Matrix2D ScaleX'
54
55  printMatrix(title: string, matrix: Matrix2D) {
56    console.log(title)
57    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
58                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
59                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
60  }
61  build() {
62    Row() {
63      Column() {
64        Text(this.message)
65          .fontSize(20)
66          .fontWeight(FontWeight.Bold)
67        Button("Set scaleX")
68          .onClick(() => {
69            let matrix : Matrix2D = new Matrix2D()
70            matrix.scaleX = 1
71            this.printMatrix(this.message, matrix)
72          })
73      }
74      .width('100%')
75    }
76    .height('100%')
77  }
78}
79```
80
81### scaleY
82
83```ts
84// xxx.ets
85@Entry
86@Component
87struct Matrix2DScaleY {
88  @State message: string = 'Matrix2D ScaleY'
89
90  printMatrix(title: string, matrix: Matrix2D) {
91    console.log(title)
92    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
93                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
94                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
95  }
96  build() {
97    Row() {
98      Column() {
99        Text(this.message)
100          .fontSize(20)
101          .fontWeight(FontWeight.Bold)
102        Button("Set scaleY")
103          .onClick(() => {
104            let matrix : Matrix2D = new Matrix2D()
105            matrix.scaleY = 1
106            this.printMatrix(this.message, matrix)
107          })
108      }
109      .width('100%')
110    }
111    .height('100%')
112  }
113}
114```
115
116### rotateX
117
118```ts
119// xxx.ets
120@Entry
121@Component
122struct Matrix2DRotateX {
123  @State message: string = 'Matrix2D RotateX'
124
125  printMatrix(title: string, matrix: Matrix2D) {
126    console.log(title)
127    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
128                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
129                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
130  }
131  build() {
132    Row() {
133      Column() {
134        Text(this.message)
135          .fontSize(20)
136          .fontWeight(FontWeight.Bold)
137        Button("Set rotateX")
138          .onClick(() => {
139            let matrix : Matrix2D = new Matrix2D()
140            matrix.rotateX = Math.sin(45 / Math.PI)
141            this.printMatrix(this.message, matrix)
142          })
143      }
144      .width('100%')
145    }
146    .height('100%')
147  }
148}
149```
150
151### rotateY
152
153```ts
154// xxx.ets
155@Entry
156@Component
157struct Matrix2DRotateY {
158  @State message: string = 'Matrix2D RotateY'
159
160  printMatrix(title: string, matrix: Matrix2D) {
161    console.log(title)
162    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
163                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
164                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
165  }
166  build() {
167    Row() {
168      Column() {
169        Text(this.message)
170          .fontSize(20)
171          .fontWeight(FontWeight.Bold)
172        Button("Set rotateY")
173          .onClick(() => {
174            let matrix : Matrix2D = new Matrix2D()
175            matrix.rotateY = Math.cos(45 / Math.PI)
176            this.printMatrix(this.message, matrix)
177          })
178      }
179      .width('100%')
180    }
181    .height('100%')
182  }
183}
184```
185
186### translateX
187
188```ts
189// xxx.ets
190@Entry
191@Component
192struct Matrix2DTranslateX {
193  @State message: string = 'Matrix2D TranslateX'
194
195  printMatrix(title: string, matrix: Matrix2D) {
196    console.log(title)
197    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
198                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
199                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
200  }
201  build() {
202    Row() {
203      Column() {
204        Text(this.message)
205          .fontSize(20)
206          .fontWeight(FontWeight.Bold)
207        Button("Set translateX")
208          .onClick(() => {
209            let matrix : Matrix2D = new Matrix2D()
210            matrix.translateX = 10
211            this.printMatrix(this.message, matrix)
212          })
213      }
214      .width('100%')
215    }
216    .height('100%')
217  }
218}
219```
220
221### translateY
222
223```ts
224// xxx.ets
225@Entry
226@Component
227struct Matrix2DTranslateY {
228  @State message: string = 'Matrix2D TranslateY'
229
230  printMatrix(title: string, matrix: Matrix2D) {
231    console.log(title)
232    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
233                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
234                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
235  }
236  build() {
237    Row() {
238      Column() {
239        Text(this.message)
240          .fontSize(20)
241          .fontWeight(FontWeight.Bold)
242        Button("Set translateY")
243          .onClick(() => {
244            let matrix : Matrix2D = new Matrix2D()
245            matrix.translateY = 10
246            this.printMatrix(this.message, matrix)
247          })
248      }
249      .width('100%')
250    }
251    .height('100%')
252  }
253}
254```
255
256## Methods
257
258### identity
259
260identity(): Matrix2D
261
262Creates an identity matrix.
263
264**Widget capability**: This API can be used in ArkTS widgets since API version 9.
265
266**Atomic service API**: This API can be used in atomic services since API version 11.
267
268**System capability**: SystemCapability.ArkUI.ArkUI.Full
269
270**Return value**
271
272| Type                 | Description      |
273| --------------------- | ---------- |
274| [Matrix2D](#matrix2d) | Identity matrix. |
275
276**Example**
277
278```ts
279// xxx.ets
280@Entry
281@Component
282struct Matrix2DIdentity {
283  @State message: string = 'Matrix2D Identity'
284
285  printMatrix(title: string, matrix: Matrix2D) {
286    console.log(title)
287    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
288                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
289                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
290  }
291  build() {
292    Row() {
293      Column() {
294        Text(this.message)
295          .fontSize(20)
296          .fontWeight(FontWeight.Bold)
297        Button("matrix identity")
298          .onClick(() => {
299            let matrix : Matrix2D = new Matrix2D()
300            matrix = matrix.identity()
301            this.printMatrix(this.message, matrix)
302          })
303      }
304      .width('100%')
305    }
306    .height('100%')
307  }
308}
309```
310
311### invert
312
313invert(): Matrix2D
314
315Obtains an inverse of this matrix.
316
317**Widget capability**: This API can be used in ArkTS widgets since API version 9.
318
319**Atomic service API**: This API can be used in atomic services since API version 11.
320
321**System capability**: SystemCapability.ArkUI.ArkUI.Full
322
323**Return value**
324
325| Type                 | Description        |
326| --------------------- | ------------ |
327| [Matrix2D](#matrix2d) | Inverse of the current matrix. |
328
329**Example**
330
331```ts
332// xxx.ets
333@Entry
334@Component
335struct Matrix2DInvert {
336  @State message: string = 'Matrix2D Invert'
337
338  printMatrix(title: string, matrix: Matrix2D) {
339    console.log(title)
340    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
341                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
342                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
343  }
344  build() {
345    Row() {
346      Column() {
347        Text(this.message)
348          .fontSize(20)
349          .fontWeight(FontWeight.Bold)
350        Button("matrix invert")
351          .onClick(() => {
352            let matrix : Matrix2D = new Matrix2D()
353            matrix.scaleX = 2
354            matrix.scaleY = 1
355            matrix.rotateX = 0
356            matrix.rotateY = 0
357            matrix.translateX = 10
358            matrix.translateY = 20
359            matrix.invert()
360            this.printMatrix(this.message, matrix)
361          })
362      }
363      .width('100%')
364    }
365    .height('100%')
366  }
367}
368```
369
370### multiply<sup>(deprecated) </sup>
371
372multiply(other?: Matrix2D): Matrix2D
373
374Multiplies this matrix by the target matrix.
375
376**Widget capability**: This API can be used in ArkTS widgets since API version 9. This API is an empty API.
377
378This API is deprecated since API version 10.
379
380**Parameters**
381
382| Name | Type    | Mandatory |  Description  |
383| ----- | -------- | ---- | ---------- |
384| other | Matrix2D | No | Target matrix.<br>Default value: **null** |
385
386**Return value**
387
388| Type                 | Description          |
389| --------------------- | -------------- |
390| [Matrix2D](#matrix2d) | Matrix of the multiplication result. |
391
392**Example**
393
394```ts
395// xxx.ets
396@Entry
397@Component
398struct Matrix2DMultiply {
399  @State message: string = 'Matrix2D Multiply'
400
401  printMatrix(title: string, matrix: Matrix2D) {
402    console.log(title)
403    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
404                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
405                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
406  }
407  build() {
408    Row() {
409      Column() {
410        Text(this.message)
411          .fontSize(20)
412          .fontWeight(FontWeight.Bold)
413        Button("matrix multiply")
414          .onClick(() => {
415            let matrix : Matrix2D = new Matrix2D()
416            matrix.scaleX = 1
417            matrix.scaleY = 1
418            matrix.rotateX = 0
419            matrix.rotateY = 0
420            matrix.translateX = 0
421            matrix.translateY = 0
422            let other: Matrix2D = new Matrix2D()
423            other.scaleX = 2
424            other.scaleY = 2
425            other.rotateX = 0
426            other.rotateY = 0
427            other.translateX = 10
428            other.translateY = 10
429            other.multiply(other)
430            this.printMatrix(this.message, matrix)
431          })
432      }
433      .width('100%')
434    }
435    .height('100%')
436  }
437}
438```
439
440### rotate<sup>(deprecated) </sup>
441
442rotate(rx?: number, ry?: number): Matrix2D
443
444Performs a rotation operation on this matrix.
445
446**Widget capability**: This API can be used in ArkTS widgets since API version 9. This API is an empty API.
447
448This API is deprecated since API version 10. You are advised to use [rotate](#rotate10) instead.
449
450**Parameters**
451
452| Name | Type  | Mandatory | Description                         |
453| ---- | ------ | ---- | -------------------------------- |
454| rx   | number | No  | Horizontal coordinate of the rotation point.<br>Default unit: vp<br>Default value: **0** |
455| ry   | number | No  | Vertical coordinate of the rotation point.<br>Default unit: vp<br>Default value: **0** |
456
457**Return value**
458
459| Type                 | Description                |
460| --------------------- | -------------------- |
461| [Matrix2D](#matrix2d) | Matrix of the rotation result. |
462
463**Example**
464
465```ts
466// xxx.ets
467@Entry
468@Component
469struct Matrix2DRotate {
470  @State message: string = 'Matrix2D Rotate'
471
472  printMatrix(title: string, matrix: Matrix2D) {
473    console.log(title)
474    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
475                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
476                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
477  }
478  build() {
479    Row() {
480      Column() {
481        Text(this.message)
482          .fontSize(20)
483          .fontWeight(FontWeight.Bold)
484        Button("matrix rotate")
485          .onClick(() => {
486            let matrix : Matrix2D = new Matrix2D()
487            matrix.scaleX = 1
488            matrix.scaleY = 1
489            matrix.rotateX = 0
490            matrix.rotateY = 0
491            matrix.translateX = 0
492            matrix.translateY = 0
493            matrix.rotate(10, 10)
494            this.printMatrix(this.message, matrix)
495          })
496      }
497      .width('100%')
498    }
499    .height('100%')
500  }
501}
502```
503
504### rotate<sup>10+</sup>
505
506rotate(degree: number, rx?: number, ry?: number): Matrix2D
507
508Performs a right multiplication rotation operation on this matrix, with the specified rotation point as the transform origin.
509
510**Widget capability**: This API can be used in ArkTS widgets since API version 10.
511
512**Atomic service API**: This API can be used in atomic services since API version 11.
513
514**System capability**: SystemCapability.ArkUI.ArkUI.Full
515
516**Parameters**
517
518| Name  | Type  | Mandatory | Description                                                        |
519| ------ | ------ | ---- | ------------------------------------------------------------ |
520| degree | number | Yes | Rotation angle, in radians. A positive angle denotes a clockwise rotation. You can use **Math.PI& / 180** to convert the angle to a radian value.<br>Default value: **0**|
521| rx     | number | No | Horizontal coordinate of the rotation point.<br>Default unit: vp<br>Default value: **0**   |
522| ry     | number | No | Vertical coordinate of the rotation point.<br>Default unit: vp<br>Default value: **0**   |
523
524**Return value**
525
526| Type                 | Description                |
527| --------------------- | -------------------- |
528| [Matrix2D](#matrix2d) | Matrix of the rotation result. |
529
530**Example**
531
532```ts
533// xxx.ets
534@Entry
535@Component
536struct Matrix2DRotate {
537  @State message: string = 'Matrix2D Rotate'
538
539  printMatrix(title: string, matrix: Matrix2D) {
540    console.log(title)
541    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
542                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
543                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
544  }
545  build() {
546    Row() {
547      Column() {
548        Text(this.message)
549          .fontSize(20)
550          .fontWeight(FontWeight.Bold)
551        Button("matrix rotate")
552          .onClick(() => {
553            let matrix : Matrix2D = new Matrix2D()
554            matrix.scaleX = 1
555            matrix.scaleY = 1
556            matrix.rotateX = 0
557            matrix.rotateY = 0
558            matrix.translateX = 0
559            matrix.translateY = 0
560            matrix.rotate(90 / Math.PI, 10, 10)
561            this.printMatrix(this.message, matrix)
562          })
563      }
564      .width('100%')
565    }
566    .height('100%')
567  }
568}
569```
570
571### translate
572
573translate(tx?: number, ty?: number): Matrix2D
574
575Performs a left multiplication translation operation on this matrix.
576
577**Widget capability**: This API can be used in ArkTS widgets since API version 9.
578
579**Atomic service API**: This API can be used in atomic services since API version 11.
580
581**System capability**: SystemCapability.ArkUI.ArkUI.Full
582
583**Parameters**
584
585| Name | Type  | Mandatory | Description                 |
586| ---- | ------ | ---- | ---------------------------- |
587| tx   | number | No  | Distance to translate on the x-axis.<br>Default unit: vp<br>Default value: **0** |
588| ty   | number | No  | Distance to translate on the y-axis.<br>Default unit: vp<br>Default value: **0** |
589
590**Return value**
591
592| Type                 | Description                |
593| --------------------- | -------------------- |
594| [Matrix2D](#matrix2d) | Matrix of the translation result. |
595
596**Example**
597
598```ts
599// xxx.ets
600@Entry
601@Component
602struct Matrix2DTranslate {
603  @State message: string = 'Matrix2D Translate'
604
605  printMatrix(title: string, matrix: Matrix2D) {
606    console.log(title)
607    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
608                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
609                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
610  }
611  build() {
612    Row() {
613      Column() {
614        Text(this.message)
615          .fontSize(20)
616          .fontWeight(FontWeight.Bold)
617        Button("matrix translate")
618          .onClick(() => {
619            let matrix : Matrix2D = new Matrix2D()
620            matrix.scaleX = 1
621            matrix.scaleY = 1
622            matrix.rotateX = 0
623            matrix.rotateY = 0
624            matrix.translateX = 0
625            matrix.translateY = 0
626            matrix.translate(100, 100)
627            this.printMatrix(this.message, matrix)
628          })
629      }
630      .width('100%')
631    }
632    .height('100%')
633  }
634}
635```
636
637### scale
638
639scale(sx?: number, sy?: number): Matrix2D
640
641Performs a right multiplication scaling operation on this matrix.
642
643**Widget capability**: This API can be used in ArkTS widgets since API version 9.
644
645**Atomic service API**: This API can be used in atomic services since API version 11.
646
647**System capability**: SystemCapability.ArkUI.ArkUI.Full
648
649**Parameters**
650
651| Name | Type  | Mandatory | Description              |
652| ---- | ------ | ---- | ------------------ |
653| sx   | number | No  | Horizontal scale factor.<br>Default value: **1** |
654| sy   | number | No  | Vertical scale factor.<br>Default value: **1** |
655
656**Return value**
657
658| Type                 | Description              |
659| --------------------- | ------------------ |
660| [Matrix2D](#matrix2d) | Matrix of the scale result. |
661
662**Example**
663
664```ts
665// xxx.ets
666@Entry
667@Component
668struct Matrix2DScale {
669  @State message: string = 'Matrix2D Scale'
670
671  printMatrix(title: string, matrix: Matrix2D) {
672    console.log(title)
673    console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY +
674                ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY +
675                ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]")
676  }
677  build() {
678    Row() {
679      Column() {
680        Text(this.message)
681          .fontSize(20)
682          .fontWeight(FontWeight.Bold)
683        Button("matrix scale")
684          .onClick(() => {
685            let matrix : Matrix2D = new Matrix2D()
686            matrix.scaleX = 1
687            matrix.scaleY = 1
688            matrix.rotateX = 0
689            matrix.rotateY = 0
690            matrix.translateX = 0
691            matrix.translateY = 0
692            matrix.scale(0.5, 0.5)
693            this.printMatrix(this.message, matrix)
694          })
695      }
696      .width('100%')
697    }
698    .height('100%')
699  }
700}
701```
702