.. role:: clio-static
   :class: clio-flag clio-flag-static


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

.. js:class:: common.Matrix

   Object representing the 4x4 Matrix. More information can be found `here <https://docs.techsoft3d.com/hoops/visualize-web/latest/prog_guide/viewing/model_attributes/matrices.html>`__\ .
   
   
   Index
   =====
   
   .. rubric:: Constructors
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:func:`~common.Matrix.constructor`
   
   .. rubric:: Properties
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:data:`~common.Matrix.m`
   
   .. rubric:: Methods
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:meth:`~static common.Matrix.createFromArray`
   * :js:meth:`~static common.Matrix.createFromBasis`
   * :js:meth:`~static common.Matrix.createFromOffAxisRotation`
   * :js:meth:`~static common.Matrix.fromJson`
   * :js:meth:`~static common.Matrix.inverse`
   * :js:meth:`~static common.Matrix.multiply`
   * :js:meth:`~static common.Matrix.xAxisRotation`
   * :js:meth:`~static common.Matrix.yAxisRotation`
   * :js:meth:`~static common.Matrix.zAxisRotation`
   * :js:meth:`~common.Matrix.assign`
   * :js:meth:`~common.Matrix.copy`
   * :js:meth:`~common.Matrix.equals`
   * :js:meth:`~common.Matrix.equalsWithTolerance`
   * :js:meth:`~common.Matrix.inverseAndDeterminant`
   * :js:meth:`~common.Matrix.isIdentity`
   * :js:meth:`~common.Matrix.loadIdentity`
   * :js:meth:`~common.Matrix.multiplyByScalar`
   * :js:meth:`~common.Matrix.normalMatrix`
   * :js:meth:`~common.Matrix.setScaleComponent`
   * :js:meth:`~common.Matrix.setTranslationComponent`
   * :js:meth:`~common.Matrix.toJson`
   * :js:meth:`~common.Matrix.transform`
   * :js:meth:`~common.Matrix.transform4`
   * :js:meth:`~common.Matrix.transformArray`
   * :js:meth:`~common.Matrix.transformBox`
   * :js:meth:`~common.Matrix.transpose`
   * :js:meth:`~common.Matrix.upperLeft3x3Determinant`
   
   



.. rst-class:: kind-group kind-constructors

.. rubric:: Constructors
   :class: kind-group-title


.. js:method:: common.Matrix.constructor

      .. rst-class:: sig-pretty-signature
      
         | Matrix(): :js:class:`Matrix <common.Matrix>`
      
      Creates a new matrix set to the identity matrix.
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      



.. rst-class:: kind-group kind-properties

.. rubric:: Properties
   :class: kind-group-title


.. js:data:: common.Matrix.m

      .. rst-class:: sig-pretty-signature
      
         | m: :js:data:`Matrix16 <common.Matrix16>`
      



.. rst-class:: kind-group kind-methods

.. rubric:: Methods
   :class: kind-group-title


.. js:method:: static common.Matrix.createFromArray

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | createFromArray(**arr**\ : *number*\ []): :js:class:`Matrix <common.Matrix>`
      
      Creates a matrix from an array of numbers.
      
      **Parameters**
      
      
         **arr**\ : *number*\ []
      
      
            16 element array of numbers.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         New matrix with elements set to the values of the array parameter. Array elements will be in column-major order.
      
      



.. js:method:: static common.Matrix.createFromBasis

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | createFromBasis(**xAxis**\ : :js:class:`Point3 <common.Point3>`\ , **yAxis**\ : :js:class:`Point3 <common.Point3>`\ , **zAxis**\ : :js:class:`Point3 <common.Point3>`\ ): :js:class:`Matrix <common.Matrix>`
      
      Creates a matrix from three [[Point3]]s, which will be used as the columns of the matrix.
      
      **Parameters**
      
      
         **xAxis**\ : :js:class:`Point3 <common.Point3>`
      
      
            The first column.
      
      
         **yAxis**\ : :js:class:`Point3 <common.Point3>`
      
      
            The second column.
      
      
         **zAxis**\ : :js:class:`Point3 <common.Point3>`
      
      
            The third column.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      



.. js:method:: static common.Matrix.createFromOffAxisRotation

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | createFromOffAxisRotation(**axis**\ : :js:class:`Point3 <common.Point3>`\ , **degrees**\ : *number*\ ): :js:class:`Matrix <common.Matrix>`
      
      Creates a rotation matrix from an arbitrary axis.
      
      **Parameters**
      
      
         **axis**\ : :js:class:`Point3 <common.Point3>`
      
      
            Axis to rotate about.
      
      
         **degrees**\ : *number*
      
      
            Amount of degrees to rotate about the provided axis.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         Rotation matrix which represents the rotation about the supplied axis.
      
      



.. js:method:: static common.Matrix.fromJson

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | fromJson(**obj**\ : *unknown*\ ): :js:class:`Matrix <common.Matrix>`
      
      Creates a new [[Matrix]] from an object given by [[toJson]].
      
      **Parameters**
      
      
         **obj**\ : *unknown*
      
      
            An object given by [[toJson]].
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         The prepared object.
      
      



.. js:method:: static common.Matrix.inverse

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | inverse(**matrix**\ : :js:class:`Matrix <common.Matrix>`\ ): (*None* | :js:class:`Matrix <common.Matrix>`\ )
      
      Computes the inverse of a matrix if possible.
      
      **Parameters**
      
      
         **matrix**\ : :js:class:`Matrix <common.Matrix>`
      
      
            Matrix whose inverse will be computed.
      
      
      
      **Returns**\ : (*None* \| :js:class:`Matrix <common.Matrix>`\ )
      
      
         Matrix set to the inverse of the supplied matrix.
      
      



.. js:method:: static common.Matrix.multiply

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | multiply(**m1**\ : :js:class:`Matrix <common.Matrix>`\ , **m2**\ : :js:class:`Matrix <common.Matrix>`\ ): :js:class:`Matrix <common.Matrix>`
      
      Multiplies two matrices.
      
      (p' = ABp <=> p' = multiply(B, A).transform(p))
      
      **Parameters**
      
      
         **m1**\ : :js:class:`Matrix <common.Matrix>`
      
      
            The first matrix.
      
      
         **m2**\ : :js:class:`Matrix <common.Matrix>`
      
      
            The second matrix.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         Matrix which is the result of the multiplication.
      
      



.. js:method:: static common.Matrix.xAxisRotation

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | xAxisRotation(**degrees**\ : *number*\ ): :js:class:`Matrix <common.Matrix>`
      
      Returns the matrix for a clockwise rotation around the X-axis.
      
      **Parameters**
      
      
         **degrees**\ : *number*
      
      
            The degrees of the rotation.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         The rotation matrix.
      
      



.. js:method:: static common.Matrix.yAxisRotation

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | yAxisRotation(**degrees**\ : *number*\ ): :js:class:`Matrix <common.Matrix>`
      
      Returns the matrix for a clockwise rotation around the Y-axis.
      
      **Parameters**
      
      
         **degrees**\ : *number*
      
      
            The degrees of the rotation.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         The rotation matrix.
      
      



.. js:method:: static common.Matrix.zAxisRotation

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | zAxisRotation(**degrees**\ : *number*\ ): :js:class:`Matrix <common.Matrix>`
      
      Returns the matrix for a clockwise rotation around the Z-axis.
      
      **Parameters**
      
      
         **degrees**\ : *number*
      
      
            The degrees of the rotation.
      
      
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         The rotation matrix.
      
      



.. js:method:: common.Matrix.assign

      .. rst-class:: sig-pretty-signature
      
         | assign(**matrix**\ : :js:class:`Matrix <common.Matrix>`\ ): *this*
      
      Sets the value of this matrix to another.
      
      **Parameters**
      
      
         **matrix**\ : :js:class:`Matrix <common.Matrix>`
      
      
            the matrix whose values will be set.
      
      
      
      **Returns**\ : *this*
      
      
         This matrix object.
      
      



.. js:method:: common.Matrix.copy

      .. rst-class:: sig-pretty-signature
      
         | copy(): :js:class:`Matrix <common.Matrix>`
      
      Creates a copy of this matrix.
      
      **Returns**\ : :js:class:`Matrix <common.Matrix>`
      
      
         Copy of this matrix.
      
      



.. js:method:: common.Matrix.equals

      .. rst-class:: sig-pretty-signature
      
         | equals(**other**\ : :js:class:`Matrix <common.Matrix>`\ ): *boolean*
      
      Strictly compares this matrix with another.
      
      **Parameters**
      
      
         **other**\ : :js:class:`Matrix <common.Matrix>`
      
      
            Matrix to compare with.
      
      
      
      **Returns**\ : *boolean*
      
      
         True if the values of this matrix equal those of the other.
      
      



.. js:method:: common.Matrix.equalsWithTolerance

      .. rst-class:: sig-pretty-signature
      
         | equalsWithTolerance(**other**\ : :js:class:`Matrix <common.Matrix>`\ , **tolerance**\ : *number*\ ): *boolean*
      
      Compares this matrix with another using a tolerance.
      
      **Parameters**
      
      
         **other**\ : :js:class:`Matrix <common.Matrix>`
      
      
            Matrix to compare with.
      
      
         **tolerance**\ : *number*
      
      
            Tolerance to be used in the comparison.
      
      
      
      **Returns**\ : *boolean*
      
      
         True if the values of this matrix equal those of the other.
      
      



.. js:method:: common.Matrix.inverseAndDeterminant

      .. rst-class:: sig-pretty-signature
      
         | inverseAndDeterminant(): [(*None* | :js:class:`Matrix <common.Matrix>`\ ), *number*\ ]
      
      Computes the determinant and inverse of a matrix, if possible.
      
      **Returns**\ : [(*None* \| :js:class:`Matrix <common.Matrix>`\ ), *number*\ ]
      
      
         An array containing the inverse (or null if not invertible) followed by the determinant
      
      



.. js:method:: common.Matrix.isIdentity

      .. rst-class:: sig-pretty-signature
      
         | isIdentity(): *boolean*
      
      **Returns**\ : *boolean*
      



.. js:method:: common.Matrix.loadIdentity

      .. rst-class:: sig-pretty-signature
      
         | loadIdentity(): *this*
      
      Sets the matrix to the identity matrix.
      
      **Returns**\ : *this*
      
      
         This matrix object.
      
      



.. js:method:: common.Matrix.multiplyByScalar

      .. rst-class:: sig-pretty-signature
      
         | multiplyByScalar(**scalar**\ : *number*\ ): *this*
      
      Multiply the matrix by given scalar.
      
      **Parameters**
      
      
         **scalar**\ : *number*
      
      
            Scalar to multiply the matrix with.
      
      
      
      **Returns**\ : *this*
      
      
         This matrix object.
      
      



.. js:method:: common.Matrix.normalMatrix

      .. rst-class:: sig-pretty-signature
      
         | normalMatrix(): (*None* | :js:class:`Matrix <common.Matrix>`\ )
      
      **Returns**\ : (*None* \| :js:class:`Matrix <common.Matrix>`\ )
      
      
         the version of this matrix suitable for applying to normals, i.e. the inverse transpose of the upper-left 3x3 submatrix.
      
      



.. js:method:: common.Matrix.setScaleComponent

      .. rst-class:: sig-pretty-signature
      
         | setScaleComponent(**x**\ : *number*\ , **y**\ : *number*\ , **z**\ : *number*\ ): *this*
      
      Sets the scale components of this matrix.
      
      **Parameters**
      
      
         **x**\ : *number*
      
      
            X scale value.
      
      
         **y**\ : *number*
      
      
            Y scale value.
      
      
         **z**\ : *number*
      
      
            Z scale value.
      
      
      
      **Returns**\ : *this*
      
      
         This matrix object.
      
      



.. js:method:: common.Matrix.setTranslationComponent

      .. rst-class:: sig-pretty-signature
      
         | setTranslationComponent(**x**\ : *number*\ , **y**\ : *number*\ , **z**\ : *number*\ ): *this*
      
      Sets the translation components of this matrix.
      
      **Parameters**
      
      
         **x**\ : *number*
      
      
            X translation value.
      
      
         **y**\ : *number*
      
      
            Y translation value.
      
      
         **z**\ : *number*
      
      
            Z translation value.
      
      
      
      **Returns**\ : *this*
      
      
         This matrix object.
      
      



.. js:method:: common.Matrix.toJson

      .. rst-class:: sig-pretty-signature
      
         | toJson(): *number*\ []
      
      Creates an object ready for JSON serialization.
      
      **Returns**\ : *number*\ []
      
      
         The prepared object.
      
      



.. js:method:: common.Matrix.transform

      .. rst-class:: sig-pretty-signature
      
         | transform(**point**\ : :js:class:`Point3 <common.Point3>`\ , **result**\ : :js:class:`Point3 <common.Point3>`\ ): :js:class:`Point3 <common.Point3>`
      
      Transforms a point according to this matrix. The source and destination points are allowed to be the same object.
      
      **Parameters**
      
      
         **point**\ : :js:class:`Point3 <common.Point3>`
      
      
            The point to be transformed.
      
      
         **result**\ : :js:class:`Point3 <common.Point3>`
      
      
            A Point3 which can hold the result of the transformation.
      
      
      
      **Returns**\ : :js:class:`Point3 <common.Point3>`
      
      
         A new point if result is undefined, result otherwise.
      
      



.. js:method:: common.Matrix.transform4

      .. rst-class:: sig-pretty-signature
      
         | transform4(**point**\ : :js:class:`Point4 <common.Point4>`\ , **result**\ : :js:class:`Point4 <common.Point4>`\ ): :js:class:`Point4 <common.Point4>`
      
      Transforms a point according to this matrix. The source and destination points are allowed to be the same object.
      
      **Parameters**
      
      
         **point**\ : :js:class:`Point4 <common.Point4>`
      
      
            The point to be transformed.
      
      
         **result**\ : :js:class:`Point4 <common.Point4>`
      
      
            A Point3 which can hold the result of the transformation.
      
      
      
      **Returns**\ : :js:class:`Point4 <common.Point4>`
      
      
         A new point if result is undefined, result otherwise.
      
      



.. js:method:: common.Matrix.transformArray

      .. rst-class:: sig-pretty-signature
      
         | transformArray(**inPoints**\ : :js:class:`Point3 <common.Point3>`\ [], **outPoints**\ : :js:class:`Point3 <common.Point3>`\ []): *void*
      
      Transforms an array of points according to this matrix.
      
      **Parameters**
      
      
         **inPoints**\ : :js:class:`Point3 <common.Point3>`\ []
      
      
            an array of points to be transformed.
      
      
         **outPoints**\ : :js:class:`Point3 <common.Point3>`\ []
      
      
            an array that will be populated with transformed points. Note that the results will be pushed onto the end of the array.
      
      
      
      **Returns**\ : *void*
      



.. js:method:: common.Matrix.transformBox

      .. rst-class:: sig-pretty-signature
      
         | transformBox(**inBox**\ : :js:class:`Box <common.Box>`\ ): :js:class:`Box <common.Box>`
      
      **Parameters**
      
      
         **inBox**\ : :js:class:`Box <common.Box>`
      
      
      **Returns**\ : :js:class:`Box <common.Box>`
      



.. js:method:: common.Matrix.transpose

      .. rst-class:: sig-pretty-signature
      
         | transpose(): *this*
      
      Sets this matrix equal to its transpose.
      
      **Returns**\ : *this*
      
      
         This matrix object.
      
      



.. js:method:: common.Matrix.upperLeft3x3Determinant

      .. rst-class:: sig-pretty-signature
      
         | upperLeft3x3Determinant(): *number*
      
      Computes the determinant of the upper-left 3x3 subsection of this matrix.
      
      **Returns**\ : *number*
      




