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(array: Array<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| array | Array<number> | Yes | A number array whose length is 16 (4 x 4). For details, see **array** parameters.<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 | 4 x 4 matrix object created based on the input parameter.| 37 38**array** parameters 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 | 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 | 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 private matrix2 = this.matrix1.copy().scale({ x: 2 }) 154 155 build() { 156 Column() { 157 Image($r("app.media.bg1")) 158 .width("40%") 159 .height(100) 160 .transform(this.matrix1) 161 Image($r("app.media.bg2")) 162 .width("40%") 163 .height(100) 164 .margin({ top: 50 }) 165 .transform(this.matrix2) 166 } 167 } 168} 169``` 170 171 172 173 174## Matrix4 175 176 177### combine 178 179combine(matrix: Matrix4): Matrix4Transit 180 181 182Combines the effects of two matrices to generate a new matrix object. 183 184**System capability**: SystemCapability.ArkUI.ArkUI.Full 185 186**Parameters** 187 188| Name| Type | Mandatory| Description | 189| ------ | ------- | ---- | ------------------ | 190| matrix | Matrix4 | Yes | Matrix object to be combined.| 191 192**Return value** 193 194| Type | Description | 195| -------------- | ------------------ | 196| 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 }).copy() 208 private matrix2 = matrix4.identity().scale({ x: 2 }).copy() 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.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. 236 237**System capability**: SystemCapability.ArkUI.ArkUI.Full 238 239**Return value** 240 241| Type | Description | 242| -------------- | ---------------------- | 243| 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.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({x?: number, y?: number, z?: number}): Matrix4Transit 277 278Translates this matrix object along the x, y, and z axes. 279 280**System capability**: SystemCapability.ArkUI.ArkUI.Full 281 282**Parameters** 283 284| Name| Type | Mandatory| Description | 285| ------ | ------ | ---- | ----------------------------------------------------------- | 286| x | number | No | Translation distance along the x-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 287| y | number | No | Translation distance along the y-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 288| z | number | No | Translation distance along the z-axis, in px.<br>Default value: **0**<br>Value range: (-∞, +∞)| 289 290**Return value** 291 292| Type | Description | 293| -------------- | ---------------------------- | 294| Matrix4Transit | Matrix object after the translation effect is added.| 295 296**Example** 297 298```ts 299// xxx.ets 300import matrix4 from '@ohos.matrix4' 301 302@Entry 303@Component 304struct Test { 305 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }) 306 307 build() { 308 Column() { 309 Image($r("app.media.bg1")).transform(this.matrix1) 310 .width("40%") 311 .height(100) 312 } 313 } 314} 315``` 316 317 318 319 320### scale 321 322scale({x?: number, y?: number, z?: number, centerX?: number, centerY?: number}): Matrix4Transit 323 324 325Scales this matrix object along the x, y, and z axes. 326 327**System capability**: SystemCapability.ArkUI.ArkUI.Full 328 329**Parameters** 330 331| Name | Type | Mandatory| Description | 332| ------- | ------ | ---- | ------------------------------------------------------------ | 333| x | number | No | Scaling multiple along the x-axis. If the value is greater than 1, the image is scaled up along the x-axis. If the value is less than 1, the image is scaled down along the x-axis.<br>Default value: **1**<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the default value.| 334| y | number | No | Scaling multiple along the y-axis. If the value is greater than 1, the image is scaled up along the y-axis. If the value is less than 1, the image is scaled down along the y-axis.<br>Default value: **1**<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the default value.| 335| z | number | No | Scaling multiple along the z-axis. If the value is greater than 1, the image is scaled up along the z-axis. If the value is less than 1, the image is scaled down along the z-axis.<br>Default value: **1**<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the default value.| 336| centerX | number | No | X coordinate of the center point.<br>Default value: **0**<br>Value range: (-∞, +∞) | 337| centerY | number | No | Y coordinate of the center point.<br>Default value: **0**<br>Value range: (-∞, +∞) | 338 339**Return value** 340 341| Type | Description | 342| -------------- | ---------------------------- | 343| Matrix4Transit | Matrix object after the scaling effect is added.| 344 345**Example** 346 347```ts 348// xxx.ets 349import matrix4 from '@ohos.matrix4' 350@Entry 351@Component 352struct Test { 353 private matrix1 = matrix4.identity().scale({ x:2, y:3, z:4, centerX:50, centerY:50 }) 354 355 build() { 356 Column() { 357 Image($r("app.media.bg1")).transform(this.matrix1) 358 .width("40%") 359 .height(100) 360 } 361 } 362} 363``` 364 365 366 367 368### rotate 369 370rotate({x?: number, y?: number, z?: number, angle?: number, centerX?: Length, centerY?: Length}): Matrix4Transit 371 372 373Rotates this matrix object along the x, y, and z axes. 374 375**System capability**: SystemCapability.ArkUI.ArkUI.Full 376 377**Parameters** 378 379| Name | Type | Mandatory| Description | 380| ------- | ------ | ---- | ------------------------------------------------------- | 381| x | number | No | X coordinate of the rotation axis vector.<br>Default value: **1**<br>Value range: (-∞, +∞)| 382| y | number | No | Y coordinate of the rotation axis vector.<br>Default value: **1**<br>Value range: (-∞, +∞)| 383| z | number | No | Z coordinate of the rotation axis vector.<br>Default value: **1**<br>Value range: (-∞, +∞)| 384| angle | number | No | Rotation angle.<br>Default value: **0** | 385| centerX | number | No | X coordinate of the center point.<br>Default value: **0** | 386| centerY | number | No | Y coordinate of the center point.<br>Default value: **0** | 387 388**Return value** 389 390| Type | Description | 391| -------------- | ---------------------------- | 392| Matrix4Transit | Matrix object after the rotation effect is added.| 393 394**Example** 395 396```ts 397// xxx.ets 398import matrix4 from '@ohos.matrix4' 399 400@Entry 401@Component 402struct Test { 403 private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 }) 404 405 build() { 406 Column() { 407 Image($r("app.media.bg1")).transform(this.matrix1) 408 .width("40%") 409 .height(100) 410 }.width("100%").margin({ top: 50 }) 411 } 412} 413``` 414 415 416 417 418### transformPoint 419 420transformPoint(point: Point): Point 421 422 423Applies the current transformation effect to a coordinate point. 424 425**System capability**: SystemCapability.ArkUI.ArkUI.Full 426 427**Parameters** 428 429| Name| Type | Mandatory| Description | 430| ------ | ----- | ---- | ------------------ | 431| point | Point | Yes | Point to be transformed.| 432 433**Return value** 434 435| Type | Description | 436| ----- | ---------------- | 437| Point | Point object after matrix transformation| 438 439**Example** 440 441```ts 442// xxx.ets 443import matrix4 from '@ohos.matrix4' 444 445@Entry 446@Component 447struct Test { 448 private originPoint: [number, number] = [50, 50] 449 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }) 450 private transformPoint = this.matrix_1.transformPoint(this.originPoint) 451 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }) 452 453 build() { 454 Column() { 455 Text(`Coordinates before matrix transformation: [${this.originPoint}]`) 456 .fontSize(16) 457 Image($r("app.media.image")) 458 .width('600px') 459 .height('300px') 460 .margin({ top: 50 }) 461 Text(`Coordinates after matrix transformation: [${this.transformPoint}]`) 462 .fontSize(16) 463 .margin({ top: 100 }) 464 Image($r("app.media.image")) 465 .width('600px') 466 .height('300px') 467 .margin({ top: 50 }) 468 .transform(this.matrix_2) 469 }.width("100%").padding(50) 470 } 471} 472``` 473 474 475
