.. role:: ts-api-decorator

######
Matrix
######

.. container:: ts-api-section

   .. js:class:: Matrix

      Object representing the 4x4 Matrix. More information can be found [here](https://docs.techsoft3d.com/communicator/latest/prog_guide/viewing/model_attributes/matrices.html).



.. container:: api-index-section

   .. rubric:: Constructors

   .. rst-class:: api-index-list-item api-kind-constructor api-parent-kind-class

   * :js:meth:`~Matrix.constructor`



.. container:: api-index-section

   .. rubric:: Properties

   .. rst-class:: api-index-list-item api-kind-property api-parent-kind-class

   * :js:attr:`~Matrix.m`



.. container:: api-index-section

   .. rubric:: Methods

   .. rst-class:: api-index-list-item api-kind-method api-parent-kind-class

   * :js:meth:`~Matrix.assign`
   * :js:meth:`~Matrix.copy`
   * :js:meth:`~Matrix.equals`
   * :js:meth:`~Matrix.equalsWithTolerance`
   * :js:meth:`~Matrix.inverseAndDeterminant`
   * :js:meth:`~Matrix.isIdentity`
   * :js:meth:`~Matrix.loadIdentity`
   * :js:meth:`~Matrix.multiplyByScalar`
   * :js:meth:`~Matrix.normalMatrix`
   * :js:meth:`~Matrix.setScaleComponent`
   * :js:meth:`~Matrix.setTranslationComponent`
   * :js:meth:`~Matrix.toJson`
   * :js:meth:`~Matrix.transform`
   * :js:meth:`~Matrix.transform4`
   * :js:meth:`~Matrix.transformArray`
   * :js:meth:`~Matrix.transformBox`
   * :js:meth:`~Matrix.transpose`
   * :js:meth:`~Matrix.upperLeft3x3Determinant`
   * :js:meth:`~Matrix.createFromArray`
   * :js:meth:`~Matrix.createFromBasis`
   * :js:meth:`~Matrix.createFromOffAxisRotation`
   * :js:meth:`~Matrix.fromJson`
   * :js:meth:`~Matrix.inverse`
   * :js:meth:`~Matrix.multiply`
   * :js:meth:`~Matrix.xAxisRotation`
   * :js:meth:`~Matrix.yAxisRotation`
   * :js:meth:`~Matrix.zAxisRotation`





------------

Constructors
============

.. container:: ts-api-section

   .. js:function:: Matrix.constructor()



      Creates a new matrix set to the identity matrix.


      :rtype: Matrix



Properties
==========

.. container:: ts-api-section

   .. js:attribute:: Matrix.m

      :type: Matrix16





Methods
=======

.. rst-class:: ts-api-section

assign
------

.. js:method:: Matrix.assign( matrix)

   :param matrix: the matrix whose values will be set.
   :type matrix: Matrix


   Sets the value of this matrix to another.

   :returns: This matrix object.


   :rtype: this

.. rst-class:: ts-api-section

copy
----

.. js:method:: Matrix.copy()



   Creates a copy of this matrix.

   :returns: Copy of this matrix.


   :rtype: Matrix

.. rst-class:: ts-api-section

equals
------

.. js:method:: Matrix.equals( other)

   :param other: Matrix to compare with.
   :type other: Matrix


   Strictly compares this matrix with another.

   :returns: True if the values of this matrix equal those of the other.


   :rtype: boolean

.. rst-class:: ts-api-section

equalsWithTolerance
-------------------

.. js:method:: Matrix.equalsWithTolerance( other, tolerance)

   :param other: Matrix to compare with.
   :type other: Matrix
   :param tolerance: Tolerance to be used in the comparison.
   :type tolerance: number


   Compares this matrix with another using a tolerance.

   :returns: True if the values of this matrix equal those of the other.


   :rtype: boolean

.. rst-class:: ts-api-section

inverseAndDeterminant
---------------------

.. js:method:: Matrix.inverseAndDeterminant()



   Computes the determinant and inverse of a matrix, if possible.

   :returns: An array containing the inverse (or null if not invertible) followed by the determinant


   :rtype: (null | Matrix, number)

.. rst-class:: ts-api-section

isIdentity
----------

.. js:method:: Matrix.isIdentity()



   :rtype: boolean

.. rst-class:: ts-api-section

loadIdentity
------------

.. js:method:: Matrix.loadIdentity()



   Sets the matrix to the identity matrix.

   :returns: This matrix object.


   :rtype: this

.. rst-class:: ts-api-section

multiplyByScalar
----------------

.. js:method:: Matrix.multiplyByScalar( scalar)

   :param scalar: Scalar to multiply the matrix with.
   :type scalar: number


   Multiply the matrix by given scalar.

   :returns: This matrix object.


   :rtype: this

.. rst-class:: ts-api-section

normalMatrix
------------

.. js:method:: Matrix.normalMatrix()





   :returns: the version of this matrix suitable for applying to normals, i.e. the inverse transpose of the upper-left 3x3 submatrix.


   :rtype: null | Matrix

.. rst-class:: ts-api-section

setScaleComponent
-----------------

.. js:method:: Matrix.setScaleComponent( x, y, z)

   :param x: X scale value.
   :type x: number
   :param y: Y scale value.
   :type y: number
   :param z: Z scale value.
   :type z: number


   Sets the scale components of this matrix.

   :returns: This matrix object.


   :rtype: this

.. rst-class:: ts-api-section

setTranslationComponent
-----------------------

.. js:method:: Matrix.setTranslationComponent( x, y, z)

   :param x: X translation value.
   :type x: number
   :param y: Y translation value.
   :type y: number
   :param z: Z translation value.
   :type z: number


   Sets the translation components of this matrix.

   :returns: This matrix object.


   :rtype: this

.. rst-class:: ts-api-section

toJson
------

.. js:method:: Matrix.toJson()



   Creates an object ready for JSON serialization.

   :returns: The prepared object.


   :rtype: [number]

.. rst-class:: ts-api-section

transform
---------

.. js:method:: Matrix.transform( point[, result])

   :param point: The point to be transformed.
   :type point: Point3
   :param result: :ts-api-decorator:`optional` A Point3 which can hold the result of the transformation.
   :type result: Point3


   Transforms a point according to this matrix. The source and destination points are allowed to be the same object.

   :returns: A new point if result is undefined, result otherwise.


   :rtype: Point3

.. rst-class:: ts-api-section

transform4
----------

.. js:method:: Matrix.transform4( point[, result])

   :param point: The point to be transformed.
   :type point: Point4
   :param result: :ts-api-decorator:`optional` A Point3 which can hold the result of the transformation.
   :type result: Point4


   Transforms a point according to this matrix. The source and destination points are allowed to be the same object.

   :returns: A new point if result is undefined, result otherwise.


   :rtype: Point4

.. rst-class:: ts-api-section

transformArray
--------------

.. js:method:: Matrix.transformArray( inPoints, outPoints)

   :param inPoints: an array of points to be transformed.
   :type inPoints: [Point3]
   :param outPoints: an array that will be populated with transformed points. Note that the results will be pushed onto the end of the array.
   :type outPoints: [Point3]


   Transforms an array of points according to this matrix.


   :rtype: void

.. rst-class:: ts-api-section

transformBox
------------

.. js:method:: Matrix.transformBox( inBox)

   :param inBox: None
   :type inBox: Box


   :rtype: Box

.. rst-class:: ts-api-section

transpose
---------

.. js:method:: Matrix.transpose()



   Sets this matrix equal to its transpose.

   :returns: This matrix object.


   :rtype: this

.. rst-class:: ts-api-section

upperLeft3x3Determinant
-----------------------

.. js:method:: Matrix.upperLeft3x3Determinant()



   Computes the determinant of the upper-left 3x3 subsection of this matrix.


   :rtype: number

.. rst-class:: ts-api-section

:ts-api-decorator:`static` createFromArray
------------------------------------------

.. js:method:: Matrix.createFromArray( arr)

   :param arr: 16 element array of numbers.
   :type arr: [number]


   Creates a matrix from an array of numbers.

   :returns: New matrix with elements set to the values of the array parameter. Array elements will be in column-major order.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` createFromBasis
------------------------------------------

.. js:method:: Matrix.createFromBasis( xAxis, yAxis, zAxis)

   :param xAxis: The first column.
   :type xAxis: Point3
   :param yAxis: The second column.
   :type yAxis: Point3
   :param zAxis: The third column.
   :type zAxis: Point3


   Creates a matrix from three [[Point3]]s, which will be used as the
   columns of the matrix.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` createFromOffAxisRotation
----------------------------------------------------

.. js:method:: Matrix.createFromOffAxisRotation( axis, degrees)

   :param axis: Axis to rotate about.
   :type axis: Point3
   :param degrees: Amount of degrees to rotate about the provided axis.
   :type degrees: number


   Creates a rotation matrix from an arbitrary axis.

   :returns: Rotation matrix which represents the rotation about the supplied axis.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` fromJson
-----------------------------------

.. js:method:: Matrix.fromJson( obj)

   :param obj: None
   :type obj: unknown


   Creates a new [[Matrix]] from an object given by [[toJson]].

   :returns: The prepared object.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` inverse
----------------------------------

.. js:method:: Matrix.inverse( matrix)

   :param matrix: Matrix whose inverse will be computed.
   :type matrix: Matrix


   Computes the inverse of a matrix if possible.

   :returns: Matrix set to the inverse of the supplied matrix.


   :rtype: null | Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` multiply
-----------------------------------

.. js:method:: Matrix.multiply( m1, m2)

   :param m1: The first matrix.
   :type m1: Matrix
   :param m2: The second matrix.
   :type m2: Matrix


   Multiplies two matrices.

   (p' = ABp <=> p' = multiply(B, A).transform(p))

   :returns: Matrix which is the result of the multiplication.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` xAxisRotation
----------------------------------------

.. js:method:: Matrix.xAxisRotation( degrees)

   :param degrees: The degrees of the rotation.
   :type degrees: number


   Returns the matrix for a clockwise rotation around the X-axis.

   :returns: The rotation matrix.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` yAxisRotation
----------------------------------------

.. js:method:: Matrix.yAxisRotation( degrees)

   :param degrees: The degrees of the rotation.
   :type degrees: number


   Returns the matrix for a clockwise rotation around the Y-axis.

   :returns: The rotation matrix.


   :rtype: Matrix

.. rst-class:: ts-api-section

:ts-api-decorator:`static` zAxisRotation
----------------------------------------

.. js:method:: Matrix.zAxisRotation( degrees)

   :param degrees: The degrees of the rotation.
   :type degrees: number


   Returns the matrix for a clockwise rotation around the Z-axis.

   :returns: The rotation matrix.


   :rtype: Matrix

