# Class MatrixParameters<E>

Object
MatrixParameters<E>

Type Parameters:
  `E` - the type of matrix element values.

All Implemented Interfaces:
  `Serializable`, `CheckedContainer<E>`

Direct Known Subclasses:
  `TensorParameters`

public class MatrixParameters<E> extends Object implements CheckedContainer<E>, Serializable
Builder of parameter groups for matrices or mathematical objects of higher dimensions. While this class is primarily used for reading and writing matrix parameters in Well Known Text format (i.e., in two-dimensional arrays of coefficients for multi-dimensional transforms), this class can also be used for describing parameters in multidimensional arrays. Each group of parameters contains the following elements:

- Parameters for specifying the size along each dimension:
  - number of rows (named `"num_row"` in WKT1 conventions),
  - number of columns (named `"num_col"` in WKT 1 convention),
  - etc. for multi-dimensional arrays of more than two dimensions.
- A maximum of `num_row` × `num_col` × … optional parameters for the matrix element values. The parameter names depend on the formatting convention.

In matrices, the default value is 1 for all elements on the diagonal and 0 everywhere else. For object of higher dimensions, this is generalized to 1 in elements where all indices have the same value. Those default values defines an identity matrix (or more generally, a Kroenecker delta tensor).

## Formatting

In the usual case of a matrix, the parameters are typically formatted as below. Note that in the EPSG convention, the matrix is implicitly affine and of dimension 3×3. The EPSG database also contains A3, A4, A5, A6, A7, A8 and B3 parameters, but they are for polynomial transformations, not for affine transformations.

Well Known Text (WKT) formats for matrix parameters
Using EPSG:9624 names and identifiers | Using OGC names
--- | ---
      Parameter["A0", <value>, Id["EPSG", 8623]],
      Parameter["A1", <value>, Id["EPSG", 8624]],
      Parameter["A2", <value>, Id["EPSG", 8625]],
      Parameter["B0", <value>, Id["EPSG", 8639]],
      Parameter["B1", <value>, Id["EPSG", 8640]],
      Parameter["B2", <value>, Id["EPSG", 8641]]
      Parameter["num_row", 3],
      Parameter["num_col", 3],
      Parameter["elt_0_0", <value>],
      Parameter["elt_0_1", <value>],
      ...
      Parameter["elt_0_<num_col-1>", <value>],
      Parameter["elt_1_0", <value>],
      Parameter["elt_1_1", <value>],
      ...
      Parameter["elt_<num_row-1>_<num_col-1>", <value>]

Those groups are extensible, i.e. the number of `"elt_row_col"` parameters depends on the `"num_row"` and `"num_col"` parameter values. For this reason, the descriptor of matrix parameters is not immutable.

## Usage examples

For creating a new group of parameters for a matrix using the `WKT1` naming conventions, one can use the following code:

    Map<String,?> properties = Map.of(ParameterValueGroup.NAME_KEY, "Affine");
    ParameterValueGroup p = MatrixParameters.WKT1.createValueGroup(properties);

For setting the elements of a few values, the next step is to create a matrix from the parameter values:

    p.parameter("elt_0_0").setValue(4);
    p.parameter("elt_1_1").setValue(6);
    Matrix m = MatrixParameters.WKT1.toMatrix(p);

Since:
  1.5
See Also:
  - `Matrices`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final MatrixParameters<Double>`
  `ALPHANUM`
  Parses and creates matrix parameters with alphanumeric names.
  `static final MatrixParameters<Double>`
  `EPSG`
  Parses and creates matrix parameters with alphanumeric names in the order defined by EPSG.
  `protected final String`
  `prefix`
  The prefix of parameter names for matrix elements.
  `protected final String`
  `separator`
  The separator between row and column in parameter names for matrix elements.
  `static final MatrixParameters<Double>`
  `WKT1`
  Parses and creates matrix parameters with names matching the Well Known Text version 1 (WKT 1) convention.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `MatrixParameters(Class<E> elementType, String prefix, String separator, ParameterDescriptor<Integer>... dimensions)`
  Creates a builder of matrix descriptors.
  `protected`
  `MatrixParameters(MatrixParameters<E> other)`
  Creates a copy of the given builder of matrix descriptors.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected ParameterDescriptor<E>`
  `createElementDescriptor(int[] indices)`
  Creates a new parameter descriptor for a matrix element at the given indices.
  `ParameterValueGroup`
  `createValueGroup(Map<String,?> properties)`
  Creates a new instance of parameter group with default values of 1 on the diagonal, and 0 everywhere else.
  `ParameterValueGroup`
  `createValueGroup(Map<String,?> properties, Matrix matrix)`
  Creates a new instance of parameter group initialized to the given matrix.
  `boolean`
  `equals(Object other)`
  Compares this object with the given object for equality.
  `ParameterDescriptor<?>[]`
  `getAllDescriptors(int... actualSize)`
  Returns all parameters in this group for a matrix of the specified size.
  `protected E`
  `getDefaultValue(int[] indices)`
  Returns the default value for the parameter descriptor at the given indices.
  `final ParameterDescriptor<Integer>`
  `getDimensionDescriptor(int i)`
  Returns the parameter descriptor for the dimension at the given index.
  `final ParameterDescriptor<E>`
  `getElementDescriptor(int... indices)`
  Returns the parameter descriptor for a matrix element at the given indices.
  `final Class<E>`
  `getElementType()`
  Returns the type of matrix element values.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `protected String`
  `indicesToName(int[] indices)`
  Returns the parameter descriptor name of a matrix element at the given indices.
  `protected int[]`
  `nameToIndices(String name)`
  Returns the indices of matrix element for the given parameter name, or `null` if none.
  `final int`
  `order()`
  Returns the number of dimensions of the multi-dimensional array for which this builder will create parameters.
  `protected Map<String,?>`
  `properties(int[] indices)`
  Returns the properties of the parameter descriptor at the given indices.
  `Matrix`
  `toMatrix(ParameterValueGroup parameters)`
  Constructs a matrix from a group of parameters.
  `String`
  `toString()`
  Returns a string representation of this object for debugging purposes.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### WKT1

    public static final MatrixParameters<Double> WKT1
    Parses and creates matrix parameters with names matching the Well Known Text version 1 (WKT 1) convention.
    - First parameter is `"num_row"`.
    - Second parameter is `"num_col"`.
    - All other parameters are of the form `"elt_row_col"` where row and col are zero-based.
    For example, `"elt_1_2"` is the element name for the value at row 1 and column 2 (zero-based indices). There are no alphanumeric aliases for avoiding confusion between `ALPHANUM` and `EPSG`.

  - ### ALPHANUM

    public static final MatrixParameters<Double> ALPHANUM
    Parses and creates matrix parameters with alphanumeric names. Names are made of a letter indicating the row (first row is `"A"`), followed by a digit indicating the column index (first column is `"0"`). Aliases are the names as they were defined in version 1 of Well Known Text (WKT) format.

    Parameter names for a 3×3 matrix
    Primary name | Alias
    --- | ---
           ┌            ┐
           │ A0  A1  A2 │
           │ B0  B1  B2 │
           │ C0  C1  C2 │
           └            ┘
           ┌                             ┐
           │ elt_0_0   elt_0_1   elt_0_2 │
           │ elt_1_0   elt_1_1   elt_1_2 │
           │ elt_2_0   elt_2_1   elt_2_2 │
           └                             ┘

  - ### EPSG

    public static final MatrixParameters<Double> EPSG
    Parses and creates matrix parameters with alphanumeric names in the order defined by EPSG. This is similar to `ALPHANUM`, except that coefficients with index 0 are in the translation column. These parameter names are defined by the Affine parametric transformation (EPSG:9624) operation method. The last row cannot be specified by EPSG names.

    Parameter names for a 3×3 matrix
    Primary name | Alias
    --- | ---
           ┌            ┐
           │ A1  A2  A0 │
           │ B1  B2  B0 │
           │  0   0   1 │
           └            ┘
           ┌                             ┐
           │ elt_0_0   elt_0_1   elt_0_2 │
           │ elt_1_0   elt_1_1   elt_1_2 │
           │ elt_2_0   elt_2_1   elt_2_2 │
           └                             ┘

  - ### prefix

    protected final String prefix
    The prefix of parameter names for matrix elements. This is `"elt_"` in WKT 1.

  - ### separator

    protected final String separator
    The separator between row and column in parameter names for matrix elements. This is `"_"` in WKT 1.

- ## Constructor Details

  - ### MatrixParameters

    protected MatrixParameters(MatrixParameters<E> other)
    Creates a copy of the given builder of matrix descriptors. The new builder will use the same prefix, separator and dimensions than the given builder. This constructor is for subclasses which use an existing instance as a basis, then override methods.
    Parameters:
      `other` - the existing builder from which to copy the prefix, separator and dimensions.

  - ### MatrixParameters

    @SafeVarargs public MatrixParameters(Class<E> elementType, String prefix, String separator, ParameterDescriptor<Integer>... dimensions)
    Creates a builder of matrix descriptors.
    Parameters:
      `elementType` - the type of matrix element values.
      `prefix` - the prefix to insert in front of parameter name for each matrix elements.
      `separator` - the separator between dimension (row, column, …) indices in parameter names.
      `dimensions` - the parameter for the size of each dimension, usually in an array of length 2. Length may be different if the caller wants to generalize usage of this class to multi-dimensional arrays.

- ## Method Details

  - ### getElementType

    public final Class<E> getElementType()
    Returns the type of matrix element values.
    Specified by:
      `getElementType` in interface `CheckedContainer<E>`
    Returns:
      the type of matrix element values.

  - ### order

    public final int order()
    Returns the number of dimensions of the multi-dimensional array for which this builder will create parameters. The number of array dimensions (matrix order) determines the type of objects represented by the parameters:

    Type of mathematical object implied by the number of array dimensions
    dimension | Type | Used with
    --- | --- | ---
    0 | scalar |
    1 | vector |
    2 | matrix | Affine parametric transformation
    k | array of k dimensions

    Returns:
      the number of dimensions of the multi-dimensional array for which to create parameters.

  - ### getDimensionDescriptor

    public final ParameterDescriptor<Integer> getDimensionDescriptor(int i)
    Returns the parameter descriptor for the dimension at the given index.
    Parameters:
      `i` - the dimension index, from 0 inclusive to `order()` exclusive.
    Returns:
      the parameter descriptor for the dimension at the given index.
    See Also:
      - `getElementDescriptor(int...)`
      - `getAllDescriptors(int...)`

  - ### getElementDescriptor

    public final ParameterDescriptor<E> getElementDescriptor(int... indices)
    Returns the parameter descriptor for a matrix element at the given indices. The length of the given `indices` array shall be equal to the dimension. That length is usually 2, where `indices[0]` is the row index and `indices[1]` is the column index.
    Parameters:
      `indices` - the indices of the matrix element for which to get the descriptor, in (row, column, …) order.
    Returns:
      the parameter descriptor for the given matrix element.
    Throws:
      `IllegalArgumentException` - if the given array does not have the expected length or have illegal value.
    See Also:
      - `getDimensionDescriptor(int)`
      - `getAllDescriptors(int...)`

  - ### createElementDescriptor

    protected ParameterDescriptor<E> createElementDescriptor(int[] indices)
    Creates a new parameter descriptor for a matrix element at the given indices. This method is invoked by `getElementDescriptor(int[])` when a new descriptor needs to be created.

    #### Default implementation

    The default implementation converts the given indices to a parameter name by invoking the `indicesToName(int[])` method, then creates a descriptor for an optional parameter of that name. The default value is given by `getDefaultValue(int[])`.

    #### Subclassing

    Subclasses can override this method if they want more control on descriptor properties like identification information, aliases or value domain.
    Parameters:
      `indices` - the indices of the matrix element for which to create a parameter, in (row, column, …) order.
    Returns:
      the parameter descriptor for the given matrix element.
    Throws:
      `IllegalArgumentException` - if the given array does not have the expected length or have illegal value.
    See Also:
      - `indicesToName(int[])`
      - `getDefaultValue(int[])`

  - ### properties

    protected Map<String,?> properties(int[] indices)
    Returns the properties of the parameter descriptor at the given indices. This is an alternative to overriding `createElementDescriptor(int[])` when only the identification (name, aliases, etc.) need to be modified.
    Parameters:
      `indices` - the indices of the matrix element for which to create parameter aliases, in (row, column, …) order.
    Returns:
      the parameter descriptor properties for the matrix element at the given indices.
    Throws:
      `IllegalArgumentException` - if the given array does not have the expected length or have illegal value.

  - ### indicesToName

    protected String indicesToName(int[] indices)
    Returns the parameter descriptor name of a matrix element at the given indices. The returned name shall be parsable by the `nameToIndices(String)` method.

    #### Default implementation

    The default implementation requires an `indices` array having a length equals to the matrix order. That length is usually 2, where `indices[0]` is the row index and `indices[1]` is the column index. Then, this method builds a name with the “`prefix` + row + `separator` + column + …” pattern (e.g. `"elt_0_0"`).

    #### Subclassing

    If a subclass overrides this method for creating different names, then that subclass should also override the `nameToIndices(String)` method for parsing those names.
    Parameters:
      `indices` - the indices of the matrix element for which to create a parameter name, in (row, column, …) order.
    Returns:
      the parameter descriptor name for the matrix element at the given indices.
    Throws:
      `IllegalArgumentException` - if the given array does not have the expected length or have illegal value.

  - ### nameToIndices

    protected int[] nameToIndices(String name)
    Returns the indices of matrix element for the given parameter name, or `null` if none. This method is the converse of the `indicesToName(int[])` method, eventually extended for recognizing also the aliases (if any).

    #### Default implementation

    The default implementation expects a name matching the “`prefix` + row + `separator` + column + …” pattern and returns an array containing the row, column and other indices, in that order.
    Parameters:
      `name` - the parameter name to parse.
    Returns:
      indices of the matrix element of the given name, or `null` if the name is not recognized.
    Throws:
      `IllegalArgumentException` - if the name has been recognized but an error occurred while parsing it (e.g. an `NumberFormatException`, which is an `IllegalArgumentException` subclass).

  - ### getDefaultValue

    protected E getDefaultValue(int[] indices)
    Returns the default value for the parameter descriptor at the given indices. The default implementation returns 1 if all indices are equals, or 0 otherwise.
    Parameters:
      `indices` - the indices of the matrix element for which to get the default value, in (row, column, …) order.
    Returns:
      the default value for the matrix element at the given indices, or `null` if none.
    See Also:
      - `DefaultParameterDescriptor​.getDefaultValue()`

  - ### getAllDescriptors

    public ParameterDescriptor<?>[] getAllDescriptors(int... actualSize)
    Returns all parameters in this group for a matrix of the specified size. The returned array contains all descriptors returned by `getDimensionDescriptor(int)` and `getElementDescriptor(int...)` for all values that exist for the given size.
    Parameters:
      `actualSize` - the matrix size in (`num_row`, `num_col`, …) order.
    Returns:
      the matrix parameters, including all elements.
    See Also:
      - `getDimensionDescriptor(int)`
      - `getElementDescriptor(int...)`

  - ### createValueGroup

    public ParameterValueGroup createValueGroup(Map<String,?> properties)
    Creates a new instance of parameter group with default values of 1 on the diagonal, and 0 everywhere else. The returned parameter group is extensible, i.e. the number of elements will depend upon the value associated to the parameters that define the matrix size.

    The properties map is given unchanged to the identified object constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`

    Parameters:
      `properties` - the properties to be given to the identified object.
    Returns:
      a new parameter group initialized to the default values.

  - ### createValueGroup

    public ParameterValueGroup createValueGroup(Map<String,?> properties, Matrix matrix)
    Creates a new instance of parameter group initialized to the given matrix. This operation is allowed only for two-dimensional arrays.
    Parameters:
      `properties` - the properties to be given to the identified object.
      `matrix` - the matrix to copy in the new parameter group.
    Returns:
      a new parameter group initialized to the given matrix.
    Throws:
      `IllegalStateException` - if `order()` does not return 2.
    See Also:
      - `toMatrix(ParameterValueGroup)`

  - ### toMatrix

    public Matrix toMatrix(ParameterValueGroup parameters)
    Constructs a matrix from a group of parameters. This operation is allowed only for two-dimensional arrays.
    Parameters:
      `parameters` - the group of parameters.
    Returns:
      a matrix constructed from the specified group of parameters.
    Throws:
      `IllegalStateException` - if `order()` does not return 2.
      `InvalidParameterNameException` - if a parameter name was not recognized.
    See Also:
      - `createValueGroup(Map, Matrix)`

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this object.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value.

  - ### equals

    public boolean equals(Object other)
    Compares this object with the given object for equality.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - the other object to compare with this object.
    Returns:
      `true` if both object are equal.

  - ### toString

    public String toString()
    Returns a string representation of this object for debugging purposes.
    Overrides:
      `toString` in class `Object`