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 by using the input parameter. 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 parameter.| 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 128## matrix4.copy 129 130copy(): Matrix4Transit 131 132 133Copies this matrix object. 134 135**System capability**: SystemCapability.ArkUI.ArkUI.Full 136 137**Return value** 138 139| Type | Description | 140| --------------------------------- | -------------------- | 141| [Matrix4Transit](#matrix4transit) | Copy object of the current matrix.| 142 143**Example** 144 145```ts 146// xxx.ets 147import matrix4 from '@ohos.matrix4' 148 149@Entry 150@Component 151struct Test { 152 private matrix1 = matrix4.identity().translate({ x: 100 }) 153 // Perform the scale operation on the copy matrix of matrix1, which does not affect matrix1. 154 private matrix2 = this.matrix1.copy().scale({ x: 2 }) 155 156 build() { 157 Column() { 158 Image($r("app.media.bg1")) 159 .width("40%") 160 .height(100) 161 .transform(this.matrix1) 162 Image($r("app.media.bg2")) 163 .width("40%") 164 .height(100) 165 .margin({ top: 50 }) 166 .transform(this.matrix2) 167 } 168 } 169} 170``` 171 172 173 174## matrix4.invert<sup>(deprecated)</sup> 175 176invert(): Matrix4Transit 177 178Inverts this matrix object. 179 180This API is deprecated since API version 10. 181 182**System capability**: SystemCapability.ArkUI.ArkUI.Full 183 184**Return value** 185 186| Type | Description | 187| --------------------------------- | ---------------------- | 188| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 189 190## matrix4.combine<sup>(deprecated)</sup> 191 192combine(options: Matrix4Transit): Matrix4Transit 193 194Combines the effects of two matrices to generate a new matrix object. 195 196This API is deprecated since API version 10. 197 198**System capability**: SystemCapability.ArkUI.ArkUI.Full 199 200**Parameters** 201 202| Name| Type | Mandatory| Description | 203| ------ | --------------------------------- | ---- | ------------------ | 204| option | [Matrix4Transit](#matrix4transit) | Yes | Matrix object to be combined.| 205 206**Return value** 207 208| Type | Description | 209| --------------------------------- | ---------------------- | 210| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 211 212## matrix4.translate<sup>(deprecated)</sup> 213 214translate(options: TranslateOption): Matrix4Transit 215 216Translates this matrix object along the x, y, and z axes. 217 218This API is deprecated since API version 10. 219 220**System capability**: SystemCapability.ArkUI.ArkUI.Full 221 222**Parameters** 223 224| Name| Type | Mandatory| Description | 225| ------ | ----------------------------------- | ---- | -------------- | 226| option | [TranslateOption](#translateoption) | Yes | Translation configuration.| 227 228**Return value** 229 230| Type | Description | 231| --------------------------------- | ---------------------- | 232| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 233 234## matrix4.scale<sup>(deprecated)</sup> 235 236scale(options: ScaleOption): Matrix4Transit 237 238Scales this matrix object along the x, y, and z axes. 239 240This API is deprecated since API version 10. 241 242**System capability**: SystemCapability.ArkUI.ArkUI.Full 243 244**Parameters** 245 246| Name| Type | Mandatory| Description | 247| ------ | --------------------------- | ---- | -------------- | 248| option | [ScaleOption](#scaleoption) | Yes | Scaling configuration.| 249 250**Return value** 251 252| Type | Description | 253| --------------------------------- | ---------------------- | 254| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 255 256## matrix4.rotate<sup>(deprecated)</sup> 257 258rotate(options: RotateOption): Matrix4Transit 259 260Rotates this matrix object along the x, y, and z axes. 261 262This API is deprecated since API version 10. 263 264**System capability**: SystemCapability.ArkUI.ArkUI.Full 265 266**Parameters** 267 268| Name| Type | Mandatory| Description | 269| ------ | ----------------------------- | ---- | -------------- | 270| option | [RotateOption](#rotateoption) | Yes | Rotation configuration.| 271 272**Return value** 273 274| Type | Description | 275| --------------------------------- | ---------------------- | 276| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 277 278## matrix4.transformPoint<sup>(deprecated)</sup> 279 280transformPoint(options: [number, number]): [number, number] 281 282Applies the current transformation effect to a coordinate point. 283 284This API is deprecated since API version 10. 285 286**System capability**: SystemCapability.ArkUI.ArkUI.Full 287 288**Parameters** 289 290| Name| Type | Mandatory| Description | 291| ------ | ---------------- | ---- | ------------------ | 292| option | [number, number] | Yes | Point to be transformed.| 293 294**Return value** 295 296| Type | Description | 297| ---------------- | --------------------------- | 298| [number, number] | Point object after matrix transformation| 299 300 301## Matrix4Transit 302 303 304### combine 305 306combine(options: Matrix4Transit): Matrix4Transit 307 308 309Combines the effects of two matrices to generate a new matrix object. The original matrix that calls this API will be changed. 310 311**System capability**: SystemCapability.ArkUI.ArkUI.Full 312 313**Parameters** 314 315| Name| Type | Mandatory| Description | 316| ------ | --------------------------------- | ---- | ------------------ | 317| option | [Matrix4Transit](#matrix4transit) | Yes | Matrix object to be combined.| 318 319**Return value** 320 321| Type | Description | 322| --------------------------------- | ------------------ | 323| [Matrix4Transit](#matrix4transit) | Object after matrix combination.| 324 325**Example** 326 327```ts 328// xxx.ets 329import matrix4 from '@ohos.matrix4' 330 331@Entry 332@Component 333struct Test { 334 private matrix1 = matrix4.identity().translate({ x: 200 }) 335 private matrix2 = matrix4.identity().scale({ x: 2 }) 336 337 build() { 338 Column() { 339 // Before matrix transformation 340 Image($r("app.media.icon")) 341 .width("40%") 342 .height(100) 343 .margin({ top: 50 }) 344 // Translate the x-axis by 200px, and then scale it twice to obtain the resultant matrix. 345 Image($r("app.media.icon")) 346 .transform(this.matrix1.copy().combine(this.matrix2)) 347 .width("40%") 348 .height(100) 349 .margin({ top: 50 }) 350 } 351 } 352} 353``` 354 355 356 357 358### invert 359 360invert(): Matrix4Transit 361 362Inverts this matrix object. The original matrix that calls this API will be changed. 363 364**System capability**: SystemCapability.ArkUI.ArkUI.Full 365 366**Return value** 367 368| Type | Description | 369| --------------------------------- | ---------------------- | 370| [Matrix4Transit](#matrix4transit) | Inverse matrix object of the current matrix.| 371 372**Example** 373 374```ts 375import matrix4 from '@ohos.matrix4' 376// The effect of matrix 1 (width scaled up by 2x) is opposite to that of matrix 2 (width scaled down by 2x). 377let matrix1 = matrix4.identity().scale({ x: 2 }) 378let matrix2 = matrix1.copy().invert() 379 380@Entry 381@Component 382struct Tests { 383 build() { 384 Column() { 385 Image($r("app.media.zh")) 386 .width(200) 387 .height(100) 388 .transform(matrix1) 389 .margin({ top: 100 }) 390 Image($r("app.media.zh")) 391 .width(200) 392 .height(100) 393 .margin({ top: 150 }) 394 .transform(matrix2) 395 } 396 } 397} 398``` 399 400 401### translate 402 403translate(options: TranslateOption): Matrix4Transit 404 405Translates this matrix object along the x, y, and z axes. The original matrix that calls this API will be changed. 406 407**System capability**: SystemCapability.ArkUI.ArkUI.Full 408 409**Parameters** 410 411| Name| Type | Mandatory| Description | 412| ------ | ----------------------------------- | ---- | -------------- | 413| option | [TranslateOption](#translateoption) | Yes | Translation configuration.| 414 415**Return value** 416 417| Type | Description | 418| --------------------------------- | ---------------------------- | 419| [Matrix4Transit](#matrix4transit) | Matrix object after the translation.| 420 421**Example** 422 423```ts 424// xxx.ets 425import matrix4 from '@ohos.matrix4' 426 427@Entry 428@Component 429struct Test { 430 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }) 431 432 build() { 433 Column() { 434 Image($r("app.media.bg1")).transform(this.matrix1) 435 .width("40%") 436 .height(100) 437 } 438 } 439} 440``` 441 442 443 444 445### scale 446 447scale(options: ScaleOption): Matrix4Transit 448 449 450Scales this matrix object along the x, y, and z axes. The original matrix that calls this API will be changed. 451 452**System capability**: SystemCapability.ArkUI.ArkUI.Full 453 454**Parameters** 455 456| Name| Type | Mandatory| Description | 457| ------ | --------------------------- | ---- | -------------- | 458| option | [ScaleOption](#scaleoption) | Yes | Scaling configuration.| 459 460**Return value** 461 462| Type | Description | 463| --------------------------------- | ---------------------------- | 464| [Matrix4Transit](#matrix4transit) | Matrix object after the scaling.| 465 466**Example** 467 468```ts 469// xxx.ets 470import matrix4 from '@ohos.matrix4' 471@Entry 472@Component 473struct Test { 474 private matrix1 = matrix4.identity().scale({ x:2, y:3, z:4, centerX:50, centerY:50 }) 475 476 build() { 477 Column() { 478 Image($r("app.media.bg1")).transform(this.matrix1) 479 .width("40%") 480 .height(100) 481 } 482 } 483} 484``` 485 486 487 488 489### rotate 490 491rotate(options: RotateOption): Matrix4Transit 492 493 494Rotates this matrix object along the x, y, and z axes. The original matrix that calls this API will be changed. 495 496**System capability**: SystemCapability.ArkUI.ArkUI.Full 497 498**Parameters** 499 500| Name| Type | Mandatory| Description | 501| ------ | ----------------------------- | ---- | -------------- | 502| option | [RotateOption](#rotateoption) | Yes | Rotation configuration.| 503 504**Return value** 505 506| Type | Description | 507| --------------------------------- | ---------------------------- | 508| [Matrix4Transit](#matrix4transit) | Matrix object after the rotation.| 509 510**Example** 511 512```ts 513// xxx.ets 514import matrix4 from '@ohos.matrix4' 515 516@Entry 517@Component 518struct Test { 519 private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 }) 520 521 build() { 522 Column() { 523 Image($r("app.media.bg1")).transform(this.matrix1) 524 .width("40%") 525 .height(100) 526 }.width("100%").margin({ top: 50 }) 527 } 528} 529``` 530 531 532 533 534### transformPoint 535 536transformPoint(options: [number, number]): [number, number] 537 538 539Applies the current transformation effect to a coordinate point. 540 541**System capability**: SystemCapability.ArkUI.ArkUI.Full 542 543**Parameters** 544 545| Name| Type | Mandatory| Description | 546| ------ | ---------------- | ---- | ------------------ | 547| option | [number, number] | Yes | Point to be transformed.| 548 549**Return value** 550 551| Type | Description | 552| ---------------- | --------------------------- | 553| [number, number] | Point object after matrix transformation| 554 555**Example** 556 557```ts 558// xxx.ets 559import matrix4 from '@ohos.matrix4' 560 561@Entry 562@Component 563struct Test { 564 private originPoint: number[] = [50, 50] 565 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }) 566 private transformPoint = this.matrix_1.transformPoint([this.originPoint[0], this.originPoint[1]]) 567 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }) 568 569 build() { 570 Column() { 571 Text(`Coordinates before matrix transformation: [${this.originPoint}]`) 572 .fontSize(16) 573 Image($r("app.media.image")) 574 .width('600px') 575 .height('300px') 576 .margin({ top: 50 }) 577 Text(`Coordinates after matrix transformation: [${this.transformPoint}]`) 578 .fontSize(16) 579 .margin({ top: 100 }) 580 Image($r("app.media.image")) 581 .width('600px') 582 .height('300px') 583 .margin({ top: 50 }) 584 .transform(this.matrix_2) 585 }.width("100%").padding(50) 586 } 587} 588``` 589 590 591 592## TranslateOption 593 594**System capability**: SystemCapability.ArkUI.ArkUI.Full 595 596| Name| Type | Mandatory| Description | 597| ---- | ------ | ---- | ----------------------------------------------------------- | 598| x | number | No | Translation distance along the x-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 599| y | number | No | Translation distance along the y-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 600| z | number | No | Translation distance along the z-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 601 602## ScaleOption 603 604**System capability**: SystemCapability.ArkUI.ArkUI.Full 605 606| Name | Type | Mandatory| Description | 607| ------- | ------ | ---- | ------------------------------------------------------------ | 608| 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: (-∞, +∞)| 609| 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: (-∞, +∞)| 610| 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: (-∞, +∞)| 611| centerX | number | No | X coordinate of the center point.<br>Default value: **0**<br>Value range: (-∞, +∞) | 612| centerY | number | No | Y coordinate of the center point.<br>Default value: **0**<br>Value range: (-∞, +∞) | 613 614## RotateOption 615 616**System capability**: SystemCapability.ArkUI.ArkUI.Full 617 618| Name | Type | Mandatory| Description | 619| ------- | ------ | ---- | ------------------------------------------------------- | 620| x | number | No | X coordinate of the rotation axis vector.<br>Default value: **0**<br>Value range: (-∞, +∞)| 621| y | number | No | Y coordinate of the rotation axis vector.<br>Default value: **0**<br>Value range: (-∞, +∞)| 622| 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.| 623| angle | number | No | Rotation angle.<br>Default value: **0** | 624| centerX | number | No | X coordinate of the center point.<br>Default value: **0** | 625| centerY | number | No | Y coordinate of the center point.<br>Default value: **0** | 626
