org.firstinspires.ftc.robotcore.external.matrices

## Class MatrixF

- java.lang.Object
- - org.firstinspires.ftc.robotcore.external.matrices.MatrixF

- Direct Known Subclasses:
    ColumnMatrixF, DenseMatrixF, RowMatrixF, SliceMatrixF

      public abstract class MatrixF
      extends java.lang.Object

  `MatrixF` represents a matrix of floats of a defined dimensionality but abstracts the means by which a particular element of the matrix is retrieved or updated. `MatrixF` is an abstract class: it is never instantiated; rather, only instances of its subclasses are made.
  See Also:
    Matrix (mathematics), Matrix multiplication, `OpenGLMatrix`, `GeneralMatrixF`, `SliceMatrixF`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `numCols`
    `protected int` | `numRows`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MatrixF(int numRows, int numCols)` Creates a matrix containing the indicated number of rows and columns.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected VectorF` | `adaptHomogeneous(VectorF him)` Automatically adapts vectors to and from homogeneous coordinates according to the size of the receiver matrix.
    `void` | `add(float[] him)`
    `void` | `add(MatrixF addend)` Adds a matrix, in place, to the receiver
    `void` | `add(VectorF him)`
    `MatrixF` | `added(float[] him)`
    `MatrixF` | `added(MatrixF addend)` Returns a new matrix whose elements are the sum of the corresponding elements of the receiver and the addend
    `MatrixF` | `added(VectorF him)`
    `static MatrixF` | `diagonalMatrix(int dim, float scale)` Returns a new matrix which is zero everywhere except on the diagonal, where it has an indicated value.
    `static MatrixF` | `diagonalMatrix(VectorF vector)` Returns a new matrix which is zero everywhere, except on the diagonal, where its values are taken from an indicated vector
    `protected java.lang.RuntimeException` | `dimensionsError()`
    `protected static java.lang.RuntimeException` | `dimensionsError(int numRows, int numCols)`
    `abstract MatrixF` | `emptyMatrix(int numRows, int numCols)` Returns a new empty matrix of the indicated dimensions.
    `java.lang.String` | `formatAsTransform()` A simple utility that extracts positioning information from a transformation matrix and formats it in a form palatable to a human being.
    `java.lang.String` | `formatAsTransform(AxesReference axesReference, AxesOrder axesOrder, AngleUnit unit)` A simple utility that extracts positioning information from a transformation matrix and formats it in a form palatable to a human being.
    `abstract float` | `get(int row, int col)` Returns a particular element of this matrix
    `VectorF` | `getColumn(int col)` Returns a vector containing data of a particular column of the receiver.
    `VectorF` | `getRow(int row)` Returns a vector containing data of a particular row of the receiver.
    `VectorF` | `getTranslation()` Assumes that the receiver is non-perspective transformation matrix.
    `static MatrixF` | `identityMatrix(int dim)` Returns an identity matrix of the indicated dimension.
    `MatrixF` | `inverted()` Returns a matrix which is the matrix-multiplication inverse of the receiver.
    `MatrixF` | `multiplied(float scale)` Returns a new matrix in which all the entries of the receiver have been scaled by an indicated value.
    `VectorF` | `multiplied(float[] him)` Multiplies the receiver by the indicated vector, considered as a column matrix.
    `MatrixF` | `multiplied(MatrixF him)` Returns a matrix which is the multiplication of the recevier with another matrix.
    `VectorF` | `multiplied(VectorF him)` Multiplies the receiver by the indicated vector, considered as a column matrix.
    `void` | `multiply(float scale)`
    `void` | `multiply(float[] him)`
    `void` | `multiply(MatrixF him)` Updates the receiver to be the product of itself and another matrix.
    `void` | `multiply(VectorF him)`
    `int` | `numCols()` Returns the number of columns in this matrix
    `int` | `numRows()` Returns the number of rows in this matrix
    `abstract void` | `put(int row, int col, float value)` Updates a particular element of this matrix
    `SliceMatrixF` | `slice(int numRows, int numCols)` Returns a matrix which is a submatrix of the receiver starting at (0,0)
    `SliceMatrixF` | `slice(int row, int col, int numRows, int numCols)` Returns a matrix which a submatrix of the receiver.
    `void` | `subtract(float[] him)`
    `void` | `subtract(MatrixF subtrahend)` Subtracts a matrix, in place, from the receiver.
    `void` | `subtract(VectorF him)`
    `MatrixF` | `subtracted(float[] him)`
    `MatrixF` | `subtracted(MatrixF subtrahend)` Returns a new matrix whose elements are the difference of the corresponding elements of the receiver and the subtrahend
    `MatrixF` | `subtracted(VectorF him)`
    `java.lang.String` | `toString()`
    `VectorF` | `toVector()` If the receiver is one-dimensional in one of its dimensions, returns a vector containing the data of the receiver; otherwise, an exception is thrown.
    `VectorF` | `transform(VectorF him)` Transforms the vector according to this matrix interpreted as a transformation matrix.
    `MatrixF` | `transposed()` Returns a matrix which is the transposition of the receiver matrix.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### numRows

          protected int numRows

    - #### numCols

          protected int numCols

  - ### Constructor Detail

    - #### MatrixF

          public MatrixF(int numRows,
                         int numCols)

      Creates a matrix containing the indicated number of rows and columns.

  - ### Method Detail

    - #### slice

          @Const
          public SliceMatrixF slice(int row,
                                           int col,
                                           int numRows,
                                           int numCols)

      Returns a matrix which a submatrix of the receiver.
      Parameters:
        `row` - the row in the receiver at which the submatrix is to start
        `col` - the column in the receiver at which the submatrix is to start
        `numRows` - the number of rows in the submatrix
        `numCols` - the number of columns in the submatrix
      Returns:
        the newly created submatrix
      See Also:
        `slice(int, int)`

    - #### slice

          @Const
          public SliceMatrixF slice(int numRows,
                                           int numCols)

      Returns a matrix which is a submatrix of the receiver starting at (0,0)
      Parameters:
        `numRows` - the number of rows in the submatrix
        `numCols` - the number of columns in the submatrix
      Returns:
        the newly created submatrix
      See Also:
        `slice(int, int, int, int)`

    - #### identityMatrix

          public static MatrixF identityMatrix(int dim)

      Returns an identity matrix of the indicated dimension. An identity matrix is zero everywhere except on the diagonal, where it is one.
      Parameters:
        `dim` - the size of the indentity matrix to return
      Returns:
        the new identity matrix

    - #### diagonalMatrix

          public static MatrixF diagonalMatrix(int dim,
                                               float scale)

      Returns a new matrix which is zero everywhere except on the diagonal, where it has an indicated value.
      Parameters:
        `dim` - the size of the matrix to return
        `scale` - the value to place on its diagonal
      Returns:
        the new matrix

    - #### diagonalMatrix

          public static MatrixF diagonalMatrix(VectorF vector)

      Returns a new matrix which is zero everywhere, except on the diagonal, where its values are taken from an indicated vector
      Parameters:
        `vector` - the values to place on the diagonal
      Returns:
        the new matrix

    - #### emptyMatrix

          @Const
          public abstract MatrixF emptyMatrix(int numRows,
                                                     int numCols)

      Returns a new empty matrix of the indicated dimensions. If a specific implementation associated with the receiver can be used with these dimensions, then such is used; otherwise a general matrix implementation will be used.
      Returns:
        a new empty matrix of the indicated dimensions
      See Also:
        `OpenGLMatrix.emptyMatrix(int, int)`

    - #### numRows

          @Const
          public int numRows()

      Returns the number of rows in this matrix
      Returns:
        the number of rows in this matrix

    - #### numCols

          @Const
          public int numCols()

      Returns the number of columns in this matrix
      Returns:
        the number of columns in this matrix

    - #### get

          @Const
          public abstract float get(int row,
                                           int col)

      Returns a particular element of this matrix
      Parameters:
        `row` - the index of the row of the element to return
        `col` - the index of the column of the element to return
      Returns:
        the element at the indicated row and column
      See Also:
        `put(int, int, float)`

    - #### put

          @NonConst
          public abstract void put(int row,
                                             int col,
                                             float value)

      Updates a particular element of this matrix
      Parameters:
        `row` - the index of the row of the element to update
        `col` - the index of the column of the element to update
        `value` - the new value for the indicated element

    - #### getRow

          @Const
          public VectorF getRow(int row)

      Returns a vector containing data of a particular row of the receiver.
      Parameters:
        `row` - the row to extract
      Returns:
        a vector containing the data of the indicated row

    - #### getColumn

          @Const
          public VectorF getColumn(int col)

      Returns a vector containing data of a particular column of the receiver.
      Parameters:
        `col` - the column to extract
      Returns:
        a vector containing data of the indicated column

    - #### toString

          @Const
          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### transform

          @Const
          public VectorF transform(VectorF him)

      Transforms the vector according to this matrix interpreted as a transformation matrix. Conversion to homogeneous coordinates is automatically provided.
      Parameters:
        `him` - the 3D coordinate or 3D homogeneous coordinate that is to be transformed
      Returns:
        the normalized homogeneous coordinate resulting from the transformation.
      See Also:
        Homogeneous coordinates, Transformation Matrix, `VectorF.normalized3D()`

    - #### adaptHomogeneous

          @Const
          protected VectorF adaptHomogeneous(VectorF him)

      Automatically adapts vectors to and from homogeneous coordinates according to the size of the receiver matrix.
      See Also:
        `transform(VectorF)`, Homogeneous coordinates

    - #### formatAsTransform

          public java.lang.String formatAsTransform()

      A simple utility that extracts positioning information from a transformation matrix and formats it in a form palatable to a human being. This should only be invoked on a matrix which is a transformation matrix. We report here using an extrinsic angle reference, meaning that all three angles are rotations in the (fixed) field coordinate system, as this is perhaps easiest to conceptually understand. And we use an angle order of XYZ, which results in the Z angle, being applied last (after X and Y rotations) and so representing the robot's heading on the field, which is often what is of most interest in robot navigation.
      Returns:
        a description of the angles represented by this transformation matrix.
      See Also:
        `formatAsTransform(AxesReference, AxesOrder, AngleUnit)`, Transformation Matrix

    - #### formatAsTransform

          public java.lang.String formatAsTransform(AxesReference axesReference,
                                                    AxesOrder axesOrder,
                                                    AngleUnit unit)

      A simple utility that extracts positioning information from a transformation matrix and formats it in a form palatable to a human being. This should only be invoked on a matrix which is a transformation matrix.
      Parameters:
        `axesReference` - the reference frame of the angles to use in reporting the transformation
        `axesOrder` - the order of the angles to use in reporting the transformation
        `unit` - the angular unit to use in reporting the transformation
      Returns:
        a description of the angles represented by this transformation matrix.
      See Also:
        `formatAsTransform()`, Transformation Matrix

    - #### transposed

          @Const
          public MatrixF transposed()

      Returns a matrix which is the transposition of the receiver matrix.
      Returns:
        a matrix which is the transposition of the receiver matrix.

    - #### multiply

          @NonConst
          public void multiply(MatrixF him)

      Updates the receiver to be the product of itself and another matrix.
      Parameters:
        `him` - the matrix with which the receiver is to be multiplied.

    - #### multiplied

          @Const
          public MatrixF multiplied(MatrixF him)

      Returns a matrix which is the multiplication of the recevier with another matrix.
      Parameters:
        `him` - the matrix with which the receiver is to be multiplied.
      Returns:
        a matrix which is the product of the two matrices

    - #### multiplied

          @Const
          public MatrixF multiplied(float scale)

      Returns a new matrix in which all the entries of the receiver have been scaled by an indicated value.
      Parameters:
        `scale` - the factor with which to scale each entry of the receiver
      Returns:
        the new, scaled matrix

    - #### multiply

          @NonConst
          public void multiply(float scale)

    - #### multiplied

          @Const
          public VectorF multiplied(VectorF him)

      Multiplies the receiver by the indicated vector, considered as a column matrix.
      Parameters:
        `him` - the vector with which the receiver is to be multiplied
      Returns:
        a matrix which is the product of the receiver and the vector

    - #### multiply

          @NonConst
          public void multiply(VectorF him)

    - #### multiplied

          @Const
          public VectorF multiplied(float[] him)

      Multiplies the receiver by the indicated vector, considered as a column matrix.
      Parameters:
        `him` - the vector with which the receiver is to be multiplied
      Returns:
        a matrix which is the product of the receiver and the vector

    - #### multiply

          @NonConst
          public void multiply(float[] him)

    - #### toVector

          @Const
          public VectorF toVector()

      If the receiver is one-dimensional in one of its dimensions, returns a vector containing the data of the receiver; otherwise, an exception is thrown.
      Returns:
        a vector containing the data of the receiver

    - #### added

          @Const
          public MatrixF added(MatrixF addend)

      Returns a new matrix whose elements are the sum of the corresponding elements of the receiver and the addend
      Parameters:
        `addend` - the matrix which is to be added to the receiver
      Returns:
        the new matrix

    - #### add

          @NonConst
          public void add(MatrixF addend)

      Adds a matrix, in place, to the receiver
      Parameters:
        `addend` - the matrix which is to be added to the receiver

    - #### subtracted

          @Const
          public MatrixF subtracted(MatrixF subtrahend)

      Returns a new matrix whose elements are the difference of the corresponding elements of the receiver and the subtrahend
      Parameters:
        `subtrahend` - the matrix which is to be subtracted from the receiver
      Returns:
        the new matrix

    - #### subtract

          @NonConst
          public void subtract(MatrixF subtrahend)

      Subtracts a matrix, in place, from the receiver.
      Parameters:
        `subtrahend` - the matrix which is to be subtracted from the receiver

    - #### added

          @Const
          public MatrixF added(VectorF him)

      See Also:
        `added(MatrixF)`

    - #### added

          @Const
          public MatrixF added(float[] him)

      See Also:
        `added(VectorF)`

    - #### subtracted

          @Const
          public MatrixF subtracted(VectorF him)

      See Also:
        `subtracted(MatrixF)`

    - #### subtracted

          @Const
          public MatrixF subtracted(float[] him)

      See Also:
        `subtracted(VectorF)`

    - #### add

          @NonConst
          public void add(VectorF him)

      See Also:
        `add(MatrixF)`

    - #### add

          @NonConst
          public void add(float[] him)

      See Also:
        `add(VectorF)`

    - #### subtract

          @NonConst
          public void subtract(VectorF him)

      See Also:
        `subtract(MatrixF)`

    - #### subtract

          @NonConst
          public void subtract(float[] him)

      See Also:
        `subtract(VectorF)`

    - #### getTranslation

          @Const
          public VectorF getTranslation()

      Assumes that the receiver is non-perspective transformation matrix. Returns the translation component of the transformation.
      Returns:
        the translation component of the transformation

    - #### dimensionsError

          protected java.lang.RuntimeException dimensionsError()

    - #### dimensionsError

          protected static java.lang.RuntimeException dimensionsError(int numRows,
                                                                      int numCols)

    - #### inverted

          @Const
          public MatrixF inverted()

      Returns a matrix which is the matrix-multiplication inverse of the receiver.
      Returns:
        a matrix which is the matrix-multiplication inverse of the receiver