1# @ohos.matrix4 (Matrix Transformation) 2 3The **matrix4** module provides APIs for matrix transformation. You can use these APIs to translate, rotate, and scale images. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```ts 13import matrix4 from '@ohos.matrix4' 14``` 15 16 17## matrix4.init 18 19init(options: [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number]): Matrix4Transit 20 21 22Matrix constructor, which is used to create a 4 x 4 matrix with the input parameters. Column-major order is used. 23 24**System capability**: SystemCapability.ArkUI.ArkUI.Full 25 26**Parameters** 27 28| Name| Type | Mandatory| Description | 29| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 30| option | [number,number,number,number,<br>number,number,number,number,<br>number,number,number,number,<br>number,number,number,number] | Yes | A number array whose length is 16 (4 x 4). For details, see **4 x 4 matrix description**.<br>Default value:<br>[1, 0, 0, 0,<br>0, 1, 0, 0,<br>0, 0, 1, 0,<br>0, 0, 0, 1] | 31 32**Return value** 33 34| Type | Description | 35| --------------------------------- | ---------------------------- | 36| [Matrix4Transit](#matrix4transit) | 4 x 4 matrix object created based on the input parameters.| 37 38**4 x 4 matrix description** 39 40| Name | Type | Mandatory | Description | 41| ---- | ------ | ---- | -------------------- | 42| m00 | number | Yes | Scaling value of the x-axis. The default value is **1** for the identity matrix. | 43| m01 | number | Yes | The second value, which is affected by the rotation of the x, y, and z axes. | 44| m02 | number | Yes | The third value, which is affected by the rotation of the x, y, and z axes. | 45| m03 | number | Yes | The fourth value, which is meaningless. | 46| m10 | number | Yes | The fifth value, which is affected by the rotation of the x, y, and z axes. | 47| m11 | number | Yes | Scaling value of the y-axis. The default value is **1** for the identity matrix. | 48| m12 | number | Yes | The seventh value, which is affected by the rotation of the x, y, and z axes. | 49| m13 | number | Yes | The eighth value, which is meaningless. | 50| m20 | number | Yes | The ninth value, which is affected by the rotation of the x, y, and z axes. | 51| m21 | number | Yes | The tenth value, which is affected by the rotation of the x, y, and z axes. | 52| m22 | number | Yes | Scaling value of the z-axis. The default value is **1** for the identity matrix. | 53| m23 | number | Yes | Meaningless value. | 54| m30 | number | Yes | Translation value of the x-axis, in px. The default value is **0** for the identity matrix.| 55| m31 | number | Yes | Translation value of the y-axis, in px. The default value is **0** for the identity matrix.| 56| m32 | number | Yes | Translation value of the z-axis, in px. The default value is **0** for the identity matrix.| 57| m33 | number | Yes | Valid in homogeneous coordinates, presenting the perspective projection effect. | 58 59**Example** 60 61```ts 62import matrix4 from '@ohos.matrix4' 63// Create a 4 x 4 matrix. 64let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0, 65 0.0, 1.0, 0.0, 0.0, 66 0.0, 0.0, 1.0, 0.0, 67 0.0, 0.0, 0.0, 1.0]) 68@Entry 69@Component 70struct Tests { 71 build() { 72 Column() { 73 Image($r("app.media.zh")) 74 .width("40%") 75 .height(100) 76 .transform(matrix) 77 } 78 } 79} 80``` 81 82 83## matrix4.identity 84 85identity(): Matrix4Transit 86 87 88Constructs an identity matrix. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92**Return value** 93 94| Type | Description | 95| --------------------------------- | -------------- | 96| [Matrix4Transit](#matrix4transit) | Identity matrix object.| 97 98**Example** 99 100```ts 101// The effect of matrix 1 is the same as that of matrix 2. 102import matrix4 from '@ohos.matrix4' 103let matrix1 = matrix4.init([1.0, 0.0, 0.0, 0.0, 104 0.0, 1.0, 0.0, 0.0, 105 0.0, 0.0, 1.0, 0.0, 106 0.0, 0.0, 0.0, 1.0]) 107let matrix2 = matrix4.identity() 108@Entry 109@Component 110struct Tests { 111 build() { 112 Column() { 113 Image($r("app.media.zh")) 114 .width("40%") 115 .height(100) 116 .transform(matrix1) 117 Image($r("app.media.zh")) 118 .width("40%") 119 .height(100) 120 .margin({ top: 150 }) 121 .transform(matrix2) 122 } 123 } 124} 125``` 126 127## Matrix4Transit 128 129### copy 130 131copy(): Matrix4Transit 132 133 134Copies this matrix object. 135 136**System capability**: SystemCapability.ArkUI.ArkUI.Full 137 138**Return value** 139 140| Type | Description | 141| --------------------------------- | -------------------- | 142| [Matrix4Transit](#matrix4transit) | Copy object of the current matrix.| 143 144 145**Example** 146 147```ts 148// xxx.ets 149import matrix4 from '@ohos.matrix4' 150 151@Entry 152@Component 153struct Test { 154 private matrix1 = matrix4.identity().translate({ x: 200 }) 155 // Perform the scale operation on the copy matrix of matrix1, which does not affect matrix1. 156 private matrix2 = this.matrix1.copy().scale({ x: 1.5 }) 157 158 build() { 159 Column() { 160 Image($r("app.media.test")) 161 .width("40%") 162 .height(100) 163 .transform(this.matrix1) 164 Image($r("app.media.test")) 165 .width("40%") 166 .height(100) 167 .margin({ top: 50 }) 168 .transform(this.matrix2) 169 }.alignItems(HorizontalAlign.Center) 170 .height('100%') 171 .justifyContent(FlexAlign.Center) 172 } 173} 174``` 175 176 177### combine 178 179combine(options: Matrix4Transit): Matrix4Transit 180 181 182Combines the effects of two matrices to generate a new matrix object. The original matrix that calls this API will be changed. 183 184**System capability**: SystemCapability.ArkUI.ArkUI.Full 185 186**Parameters** 187 188| Name| Type | Mandatory| Description | 189| ------ | --------------------------------- | ---- | ------------------ | 190| option | [Matrix4Transit](#matrix4transit) | Yes | Matrix object to be combined.| 191 192**Return value** 193 194| Type | Description | 195| --------------------------------- | ------------------ | 196| [Matrix4Transit](#matrix4transit) | Object after matrix combination.| 197 198**Example** 199 200```ts 201// xxx.ets 202import matrix4 from '@ohos.matrix4' 203 204@Entry 205@Component 206struct Test { 207 private matrix1 = matrix4.identity().translate({ x: 200 }) 208 private matrix2 = matrix4.identity().scale({ x: 2 }) 209 210 build() { 211 Column() { 212 // Before matrix transformation 213 Image($r("app.media.icon")) 214 .width("40%") 215 .height(100) 216 .margin({ top: 50 }) 217 // Translate the x-axis by 200px, and then scale it twice to obtain the resultant matrix. 218 Image($r("app.media.icon")) 219 .transform(this.matrix1.copy().combine(this.matrix2)) 220 .width("40%") 221 .height(100) 222 .margin({ top: 50 }) 223 } 224 } 225} 226``` 227 228 229 230 231### invert 232 233invert(): Matrix4Transit 234 235Inverts this matrix object. The original matrix that calls this API will be changed. 236 237**System capability**: SystemCapability.ArkUI.ArkUI.Full 238 239**Return value** 240 241| Type | Description | 242| --------------------------------- | ---------------------- | 243| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 244 245**Example** 246 247```ts 248import matrix4 from '@ohos.matrix4' 249// The effect of matrix 1 (width scaled up by 2x) is opposite to that of matrix 2 (width scaled down by 2x). 250let matrix1 = matrix4.identity().scale({ x: 2 }) 251let matrix2 = matrix1.copy().invert() 252 253@Entry 254@Component 255struct Tests { 256 build() { 257 Column() { 258 Image($r("app.media.zh")) 259 .width(200) 260 .height(100) 261 .transform(matrix1) 262 .margin({ top: 100 }) 263 Image($r("app.media.zh")) 264 .width(200) 265 .height(100) 266 .margin({ top: 150 }) 267 .transform(matrix2) 268 } 269 } 270} 271``` 272 273 274### translate 275 276translate(options: TranslateOption): Matrix4Transit 277 278Translates this matrix object along the x, y, and z axes. The original matrix that calls this API will be changed. 279 280**System capability**: SystemCapability.ArkUI.ArkUI.Full 281 282**Parameters** 283 284| Name| Type | Mandatory| Description | 285| ------ | ----------------------------------- | ---- | -------------- | 286| option | [TranslateOption](#translateoption) | Yes | Translation configuration.| 287 288**Return value** 289 290| Type | Description | 291| --------------------------------- | ---------------------------- | 292| [Matrix4Transit](#matrix4transit) | Matrix object after the translation.| 293 294**Example** 295 296```ts 297// xxx.ets 298import matrix4 from '@ohos.matrix4' 299 300@Entry 301@Component 302struct Test { 303 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }) 304 305 build() { 306 Column() { 307 Image($r("app.media.bg1")).transform(this.matrix1) 308 .width("40%") 309 .height(100) 310 } 311 } 312} 313``` 314 315 316 317 318### scale 319 320scale(options: ScaleOption): Matrix4Transit 321 322 323Scales this matrix object along the x, y, and z axes. The matrix that calls this API will be changed. 324 325**System capability**: SystemCapability.ArkUI.ArkUI.Full 326 327**Parameters** 328 329| Name| Type | Mandatory| Description | 330| ------ | --------------------------- | ---- | -------------- | 331| option | [ScaleOption](#scaleoption) | Yes | Scaling configuration.| 332 333**Return value** 334 335| Type | Description | 336| --------------------------------- | ---------------------------- | 337| [Matrix4Transit](#matrix4transit) | Matrix object after the scaling.| 338 339**Example** 340 341```ts 342// xxx.ets 343import matrix4 from '@ohos.matrix4' 344@Entry 345@Component 346struct Test { 347 private matrix1 = matrix4.identity().scale({ x:2, y:3, z:4, centerX:50, centerY:50 }) 348 349 build() { 350 Column() { 351 Image($r("app.media.bg1")).transform(this.matrix1) 352 .width("40%") 353 .height(100) 354 } 355 } 356} 357``` 358 359 360 361 362### rotate 363 364rotate(options: RotateOption): Matrix4Transit 365 366 367Rotates this matrix object along the x, y, and z axes. The matrix that calls this API will be changed. 368 369**System capability**: SystemCapability.ArkUI.ArkUI.Full 370 371**Parameters** 372 373| Name| Type | Mandatory| Description | 374| ------ | ----------------------------- | ---- | -------------- | 375| option | [RotateOption](#rotateoption) | Yes | Rotation configuration.| 376 377**Return value** 378 379| Type | Description | 380| --------------------------------- | ---------------------------- | 381| [Matrix4Transit](#matrix4transit) | Matrix object after the rotation.| 382 383**Example** 384 385```ts 386// xxx.ets 387import matrix4 from '@ohos.matrix4' 388 389@Entry 390@Component 391struct Test { 392 private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 }) 393 394 build() { 395 Column() { 396 Image($r("app.media.bg1")).transform(this.matrix1) 397 .width("40%") 398 .height(100) 399 }.width("100%").margin({ top: 50 }) 400 } 401} 402``` 403 404 405 406 407### transformPoint 408 409transformPoint(options: [number, number]): [number, number] 410 411 412Applies the current transformation effect to a coordinate point. 413 414**System capability**: SystemCapability.ArkUI.ArkUI.Full 415 416**Parameters** 417 418| Name| Type | Mandatory| Description | 419| ------ | ---------------- | ---- | ------------------ | 420| option | [number, number] | Yes | Point to be transformed.| 421 422**Return value** 423 424| Type | Description | 425| ---------------- | --------------------------- | 426| [number, number] | Point object after matrix transformation| 427 428**Example** 429 430```ts 431// xxx.ets 432import matrix4 from '@ohos.matrix4' 433 434@Entry 435@Component 436struct Test { 437 private originPoint: number[] = [50, 50] 438 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }) 439 private transformPoint = this.matrix_1.transformPoint([this.originPoint[0], this.originPoint[1]]) 440 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }) 441 442 build() { 443 Column() { 444 Text(`Coordinates before matrix transformation: [${this.originPoint}]`) 445 .fontSize(16) 446 Image($r("app.media.image")) 447 .width('600px') 448 .height('300px') 449 .margin({ top: 50 }) 450 Text(`Coordinates after matrix transformation: [${this.transformPoint}]`) 451 .fontSize(16) 452 .margin({ top: 100 }) 453 Image($r("app.media.image")) 454 .width('600px') 455 .height('300px') 456 .margin({ top: 50 }) 457 .transform(this.matrix_2) 458 }.width("100%").padding(50) 459 } 460} 461``` 462 463 464 465## TranslateOption 466 467**System capability**: SystemCapability.ArkUI.ArkUI.Full 468 469| Name| Type | Mandatory| Description | 470| ---- | ------ | ---- | ----------------------------------------------------------- | 471| x | number | No | Translation distance along the x-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 472| y | number | No | Translation distance along the y-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 473| z | number | No | Translation distance along the z-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 474 475## ScaleOption 476 477**System capability**: SystemCapability.ArkUI.ArkUI.Full 478 479| Name | Type | Mandatory| Description | 480| ------- | ------ | ---- | ------------------------------------------------------------ | 481| x | number | No | Scaling multiple along the x-axis. x > 1: The image is scaled up along the x-axis.<br>0 < x < 1: The image is scaled down along the x-axis.<br>x < 0: The image is scaled in the reverse direction of the x-axis.<br>Default value: **1**<br>Value range: (-∞, +∞)| 482| y | number | No | Scaling multiple along the y-axis. y > 1: The image is scaled up along the y-axis.<br>0 < y < 1: The image is scaled down along the y-axis.<br>y < 0: The image is scaled in the reverse direction of the y-axis.<br>Default value: **1**<br>Value range: (-∞, +∞)| 483| z | number | No | Scaling multiple along the z-axis. z > 1: The image is scaled up along the z-axis.<br>0 < z < 1: The image is scaled down along the z-axis.<br>z < 0: The image is scaled in the reverse direction of the z-axis.<br>Default value: **1**<br>Value range: (-∞, +∞)| 484| centerX | number | No | X coordinate of the center point.<br>Default value: **0**<br>Value range: (-∞, +∞) | 485| centerY | number | No | Y coordinate of the center point.<br>Default value: **0**<br>Value range: (-∞, +∞) | 486 487## RotateOption 488 489**System capability**: SystemCapability.ArkUI.ArkUI.Full 490 491| Name | Type | Mandatory| Description | 492| ------- | ------ | ---- | ------------------------------------------------------- | 493| x | number | No | X coordinate of the rotation axis vector.<br>Default value: **0**<br>Value range: (-∞, +∞)| 494| y | number | No | Y coordinate of the rotation axis vector.<br>Default value: **0**<br>Value range: (-∞, +∞)| 495| z | number | No | Z coordinate of the rotation axis vector.<br>Default value: **0**<br>Value range: (-∞, +∞)<br>**NOTE**<br>The rotation axis vector is valid only when at least one of **x**, **y**, and **z** is not 0.| 496| angle | number | No | Rotation angle.<br>Default value: **0** | 497| centerX | number | No | X coordinate of the center point.<br>Default value: **0** | 498| centerY | number | No | Y coordinate of the center point.<br>Default value: **0** | 499 500 501 502 503## matrix4.copy<sup>(deprecated)</sup> 504 505copy(): Matrix4Transit 506 507 508Copies this matrix object. 509 510> **NOTE** 511> 512> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.copy](#copy) instead. 513 514 515**System capability**: SystemCapability.ArkUI.ArkUI.Full 516 517**Return value** 518 519| Type | Description | 520| --------------------------------- | -------------------- | 521| [Matrix4Transit](#matrix4transit) | Copy object of the current matrix.| 522 523**Example** 524 525```ts 526// xxx.ets 527import matrix4 from '@ohos.matrix4' 528 529@Entry 530@Component 531struct Test { 532 private matrix1 = matrix4.identity().translate({ x: 100 }) 533 // Perform the scale operation on the copy matrix of matrix1, which does not affect matrix1. 534 private matrix2 = this.matrix1.copy().scale({ x: 2 }) 535 536 build() { 537 Column() { 538 Image($r("app.media.bg1")) 539 .width("40%") 540 .height(100) 541 .transform(this.matrix1) 542 Image($r("app.media.bg2")) 543 .width("40%") 544 .height(100) 545 .margin({ top: 50 }) 546 .transform(this.matrix2) 547 } 548 } 549} 550``` 551 552 553 554## matrix4.invert<sup>(deprecated)</sup> 555 556invert(): Matrix4Transit 557 558Inverts this matrix object. 559 560> **NOTE** 561> 562> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.invert](#invert) instead. 563 564**System capability**: SystemCapability.ArkUI.ArkUI.Full 565 566**Return value** 567 568| Type | Description | 569| --------------------------------- | ---------------------- | 570| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 571 572## matrix4.combine<sup>(deprecated)</sup> 573 574combine(options: Matrix4Transit): Matrix4Transit 575 576Combines the effects of two matrices to generate a new matrix object. 577 578> **NOTE** 579> 580> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.combine](#combine) instead. 581 582**System capability**: SystemCapability.ArkUI.ArkUI.Full 583 584**Parameters** 585 586| Name| Type | Mandatory| Description | 587| ------ | --------------------------------- | ---- | ------------------ | 588| option | [Matrix4Transit](#matrix4transit) | Yes | Matrix object to be combined.| 589 590**Return value** 591 592| Type | Description | 593| --------------------------------- | ---------------------- | 594| [Matrix4Transit](#matrix4transit) | Matrix object after combination.| 595 596## matrix4.translate<sup>(deprecated)</sup> 597 598translate(options: TranslateOption): Matrix4Transit 599 600Translates this matrix object along the x, y, and z axes. 601 602> **NOTE** 603> 604> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.translate](#translate) instead. 605 606**System capability**: SystemCapability.ArkUI.ArkUI.Full 607 608**Parameters** 609 610| Name| Type | Mandatory| Description | 611| ------ | ----------------------------------- | ---- | -------------- | 612| option | [TranslateOption](#translateoption) | Yes | Translation configuration.| 613 614**Return value** 615 616| Type | Description | 617| --------------------------------- | ---------------------- | 618| [Matrix4Transit](#matrix4transit) | Matrix object after translation.| 619 620## matrix4.scale<sup>(deprecated)</sup> 621 622scale(options: ScaleOption): Matrix4Transit 623 624Scales this matrix object along the x, y, and z axes. 625 626> **NOTE** 627> 628> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.scale](#scale) instead. 629 630**System capability**: SystemCapability.ArkUI.ArkUI.Full 631 632**Parameters** 633 634| Name| Type | Mandatory| Description | 635| ------ | --------------------------- | ---- | -------------- | 636| option | [ScaleOption](#scaleoption) | Yes | Scaling configuration.| 637 638**Return value** 639 640| Type | Description | 641| --------------------------------- | ---------------------- | 642| [Matrix4Transit](#matrix4transit) | Matrix object after scaling.| 643 644## matrix4.rotate<sup>(deprecated)</sup> 645 646rotate(options: RotateOption): Matrix4Transit 647 648Rotates this matrix object along the x, y, and z axes. 649 650> **NOTE** 651> 652> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.rotate](#rotate) instead. 653 654**System capability**: SystemCapability.ArkUI.ArkUI.Full 655 656**Parameters** 657 658| Name| Type | Mandatory| Description | 659| ------ | ----------------------------- | ---- | -------------- | 660| option | [RotateOption](#rotateoption) | Yes | Rotation configuration.| 661 662**Return value** 663 664| Type | Description | 665| --------------------------------- | ---------------------- | 666| [Matrix4Transit](#matrix4transit) | Matrix object after rotation.| 667 668## matrix4.transformPoint<sup>(deprecated)</sup> 669 670transformPoint(options: [number, number]): [number, number] 671 672Applies the current transformation effect to a coordinate point. 673 674> **NOTE** 675> 676> This API is deprecated since API version 10. You are advised to use [Matrix4Transit.transformPoint](#transformpoint) instead. 677 678**System capability**: SystemCapability.ArkUI.ArkUI.Full 679 680**Parameters** 681 682| Name| Type | Mandatory| Description | 683| ------ | ---------------- | ---- | ------------------ | 684| option | [number, number] | Yes | Point to be transformed.| 685 686**Return value** 687 688| Type | Description | 689| ---------------- | --------------------------- | 690| [number, number] | Point object after matrix transformation| 691
