Package org.apache.sis.parameter

## Class TensorParameters<E>

- Object
- - TensorParameters<E>

- Type Parameters:
    `E` - the type of tensor element values.
  All Implemented Interfaces:
    `Serializable`

      public class TensorParameters<E>
      extends Object
      implements Serializable

  Creates parameter groups for tensors (usually matrices). Matrices are handled as a special case of tensors (second-order tensors).

  Each group of parameters contains the following elements:

  - Parameters (usually mandatory) for the tensor dimensions:
    - number of rows (named `"num_row"` in WKT1 conventions),
    - number of columns (named `"num_col"` in WKT1 conventions),
    - etc. for third-order or higher-order tensors.
  - A maximum of `num_row` × `num_col` × … optional parameters for the matrix or tensor element values. Parameter names depend on the formatting convention.
  For all matrix or tensor elements, the default value is 1 for elements on the diagonal (where all indices have the same value) and 0 for all other elements. Those default values defines an identity matrix, or (more generally) Kroenecker delta tensor.

  Parameters are not an efficient storage format for large tensors. Parameters are used only for small matrices/tensors to be specified in coordinate operations or processing libraries. In particular, those parameters integrate well in Well Known Text (WKT) format. For a more efficient matrix storage, see the matrix package.

  Formatting
  In the particular case of a tensor of rank 2 (i.e. 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.

  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]]
  > Note: the EPSG database contains also A3, A4, A5, A6, A7, A8 and B3 parameters, but they are for polynomial transformations, not for affine transformations. |
  >     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 or tensor 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 = Collections.singletonMap(ParameterValueGroup.NAME_KEY, "Affine");
  >     ParameterValueGroup p = TensorParameters.WKT1.createValueGroup(properties);

  For setting the elements of a few values, then create a matrix from the parameter values:

  >     p.parameter("elt_0_0").setValue(4);    // "A0" also accepted as a synonymous of "elt_0_0".
  >     p.parameter("elt_1_1").setValue(6);    // "B1" also accepted as a synonymous of "elt_1_1".
  >     Matrix m = TensorParameters.WKT1.toMatrix(p);

  Since:
    0.4
  See Also:
    `Matrices`, Serialized Form

  Defined in the `sis-referencing` module

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TensorParameters​(Class<E> elementType, String prefix, String separator, ParameterDescriptor<Integer>... dimensions)` | Constructs a descriptors provider.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected ParameterDescriptor<E>` | `createElementDescriptor​(int[] indices)` | Creates a new parameter descriptor for a matrix or tensor 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 tensor of the specified dimensions.
    `protected E` | `getDefaultValue​(int[] indices)` | Returns the default value for the parameter descriptor at the given indices.
    `ParameterDescriptor<Integer>` | `getDimensionDescriptor​(int i)` | Returns the parameter descriptor for the dimension at the given index.
    `ParameterDescriptor<E>` | `getElementDescriptor​(int... indices)` | Returns the parameter descriptor for a matrix or tensor element at the given indices.
    `Class<E>` | `getElementType()` | Returns the type of tensor 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 or tensor 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.
    `int` | `rank()` | Returns the rank of the tensor objects for which this instance will create parameters.
    `Matrix` | `toMatrix​(ParameterValueGroup parameters)` | Constructs a matrix from a group of parameters.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### ALPHANUM

          public static final TensorParameters<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 │
      >     └                             ┘

      Relationship with EPSG
      The above-cited group of parameters are close, but not identical, to the definitions provided by the "Affine parametric transformation" (EPSG:9624) operation method. The differences are:
      - EPSG:9624 is for matrices of size 3×3 and does not provide any way to specify the matrix size. This `ALPHANUM` convention extends the definition to matrices of arbitrary size and accepts `"num_row"` and `"num_col"` as optional parameters.
      - EPSG:9624 is restricted to affine matrices and consequently define parameters only for the two first rows. This class accepts also parameters for the last row (namely `"C0"`, `"C1"` and `"C2"` in a 3×3 matrices).
      Because of the above-cited extensions, this `TensorParameters` constant can not be named `EPSG`.
      Since:
        0.6

    - #### WKT1

          public static final TensorParameters<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`"`. Those parameters have alias of the form `"A0"`, `"A1"`, etc. where the letter indicates the row (first row is `"A"`) and the digit is the column index (first column is `"0"`).
      Example: `"elt_1_2"` is the element name for the value at row 1 and column 2. Its alias is `"B2"`, which is the EPSG name for the same parameter.

    - #### prefix

          protected final String prefix

      The prefix of parameter names for tensor elements. This is `"elt_"` in WKT 1.

    - #### separator

          protected final String separator

      The separator between row and column in parameter names for tensor elements. This is `"_"` in WKT 1.

  - ### Constructor Detail

    - #### TensorParameters

          @SafeVarargs
          public TensorParameters​(Class<E> elementType,
                                  String prefix,
                                  String separator,
                                  ParameterDescriptor<Integer>... dimensions)

      Constructs a descriptors provider.
      Parameters:
        `elementType` - the type of tensor element values.
        `prefix` - the prefix to insert in front of parameter name for each tensor 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 tensors.

  - ### Method Detail

    - #### getElementType

          public final Class<E> getElementType()

      Returns the type of tensor element values.
      Returns:
        the type of tensor element values.

    - #### rank

          public final int rank()

      Returns the rank of the tensor objects for which this instance will create parameters. The rank determines the type of objects represented by the parameters:

      Tensor types implied by rank
      Rank | Type | Used with
      --- | --- | ---
      0 | scalar |
      1 | vector |
      2 | matrix | Affine parametric transformation
      k | rank k tensor

      Returns:
        the rank of the tensors 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 `rank()` 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 or tensor element at the given indices. The length of the given `indices` array shall be equals to the rank. 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 tensor element for which to get the descriptor.
      Returns:
        the parameter descriptor for the given tensor 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)
                                                            throws IllegalArgumentException

      Creates a new parameter descriptor for a matrix or tensor 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 tensor element for which to create a parameter.
      Returns:
        the parameter descriptor for the given tensor element.
      Throws:
        `IllegalArgumentException` - if the given array does not have the expected length or have illegal value.
      See Also:
        `indicesToName(int[])`, `getDefaultValue(int[])`

    - #### indicesToName

          protected String indicesToName​(int[] indices)
                                  throws IllegalArgumentException

      Returns the parameter descriptor name of a matrix or tensor 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 rank. 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 shall also override `nameToIndices(String)` for parsing those names.
      Parameters:
        `indices` - the indices of the tensor element for which to create a parameter name.
      Returns:
        the parameter descriptor name for the tensor 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)
                                 throws IllegalArgumentException

      Returns the indices of matrix element for the given parameter name, or `null` if none. This method is the converse of `indicesToName(int[])`.
      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 tensor 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 tensor element for which to get the default value.
      Returns:
        the default value for the tensor element at the given indices, or `null` if none.
      Since:
        0.6
      See Also:
        `DefaultParameterDescriptor​.getDefaultValue()`

    - #### getAllDescriptors

          public ParameterDescriptor<?>[] getAllDescriptors​(int... actualSize)

      Returns all parameters in this group for a tensor of the specified dimensions. The returned array contains all descriptors returned by `getDimensionDescriptor(int)` and `getElementDescriptor(int...)`.
      Parameters:
        `actualSize` - the matrix (or tensor) dimensions for which to get the parameters.
      Returns:
        the tensor parameters, including all elements.
      Since:
        0.6
      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 (or tensor) dimension.

      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" | `ReferenceIdentifier` or `String` | `AbstractIdentifiedObject.getName()`
      "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
      "identifiers" | `ReferenceIdentifier` (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 tensors of rank 2.
      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.
      See Also:
        `toMatrix(ParameterValueGroup)`

    - #### toMatrix

          public Matrix toMatrix​(ParameterValueGroup parameters)
                          throws InvalidParameterNameException

      Constructs a matrix from a group of parameters. This operation is allowed only for tensors of rank 2.
      Parameters:
        `parameters` - the group of parameters.
      Returns:
        a matrix constructed from the specified group of parameters.
      Throws:
        `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.