Package org.apache.sis.parameter
Class TensorParameters<E>
java.lang.Object
org.apache.sis.parameter.TensorParameters<E>
- Type Parameters:
E
- the type of tensor element values.
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
MatrixParameters
Creates parameter groups for tensors (usually matrices).
Matrices are handled as a special case of tensors (second-order tensors).
Those groups are extensible, i.e. the number of
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.
- number of rows (named
- A maximum of
num_row
×num_col
× … optional parameters for the matrix or tensor element values. Parameter names depend on the formatting convention.
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.Using EPSG:9624 names and identifiers | Using OGC names |
---|---|
Note:
the EPSG database also contains A3, A4, A5, A6, A7, A8 and B3 parameters,
but they are for polynomial transformations, not for affine transformations.
|
"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 theWKT1
naming conventions,
one can use the following code:
For setting the elements of a few values, then create a matrix from the parameter values:
- Since:
- 0.4
- Version:
- 1.2
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final TensorParameters<Double>
Parses and creates matrix parameters with alphanumeric names.private static final int
Maximal cache rank.(package private) static final int
The height and weight of the matrix ofparameters
to cache.private final org.opengis.parameter.ParameterDescriptor<Integer>[]
The parameters that define the number of rows, columns or other dimensions.The type of tensor element values.private E
The elements for the 0 and 1 values, ornull
if unknown.private final org.opengis.parameter.ParameterDescriptor<E>[]
The cached descriptors for each elements in a tensor.protected final String
The prefix of parameter names for tensor elements.protected final String
The separator between row and column in parameter names for tensor elements.private static final long
Serial number for inter-operability with different versions.static final TensorParameters<Double>
Parses and creates matrix parameters with names matching the Well Known Text version 1 (WKT 1) convention.private E
The elements for the 0 and 1 values, ornull
if unknown. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static int
cacheIndex
(int[] indices) Returns the index in the cache for the given indices, or -1 if that elements is not cached.private <T> org.opengis.parameter.ParameterDescriptor<T>[]
protected org.opengis.parameter.ParameterDescriptor<E>
createElementDescriptor
(int[] indices) Creates a new parameter descriptor for a matrix or tensor element at the given indices.org.opengis.parameter.ParameterValueGroup
createValueGroup
(Map<String, ?> properties) Creates a new instance of parameter group with default values of 1 on the diagonal, and 0 everywhere else.org.opengis.parameter.ParameterValueGroup
createValueGroup
(Map<String, ?> properties, org.opengis.referencing.operation.Matrix matrix) Creates a new instance of parameter group initialized to the given matrix.(package private) final org.opengis.parameter.ParameterDescriptor<?>
descriptor
(org.opengis.parameter.ParameterDescriptorGroup caller, String name, int[] actualSize) Returns the descriptor in this group for the specified name.boolean
Compares this object with the given object for equality.org.opengis.parameter.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.final org.opengis.parameter.ParameterDescriptor<Integer>
getDimensionDescriptor
(int i) Returns the parameter descriptor for the dimension at the given index.final org.opengis.parameter.ParameterDescriptor<E>
getElementDescriptor
(int... indices) Returns the parameter descriptor for a matrix or tensor element at the given indices.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.(package private) static boolean
isInBounds
(int[] indices, int[] actualSize) Returnstrue
if the given indices are not out-of-bounds.protected int[]
nameToIndices
(String name) Returns the indices of matrix element for the given parameter name, ornull
if none.private int
numElements
(int[] actualSize) Returns the number of elements (e.g.final int
rank()
Returns the rank of the tensor objects for which this instance will create parameters.private void
Invoked on deserialization for restoring theparameters
array.org.opengis.referencing.operation.Matrix
toMatrix
(org.opengis.parameter.ParameterValueGroup parameters) Constructs a matrix from a group of parameters.private void
verifyRank
(int[] indices) Verifies that the length of the given array is equal to the tensor rank.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
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 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).
TensorParameters
constant cannot be namedEPSG
.- Since:
- 0.6
- EPSG:9624 is for matrices of size 3×3 and does not provide any way to specify the matrix size.
This
-
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. - First parameter is
-
CACHE_SIZE
static final int CACHE_SIZEThe height and weight of the matrix ofparameters
to cache. Descriptors for row or column indices greater than or equal to this value will not be cached. A small value is sufficient since matrix sizes are usually the maximum number of CRS dimensions (usually 4) plus one.- See Also:
-
CACHE_RANK
private static final int CACHE_RANKMaximal cache rank. Memory required by the cache will bepow(CACHE_SIZE, CACHE_RANK)
, so that value is better to be small.- See Also:
-
elementType
The type of tensor element values. -
dimensions
The parameters that define the number of rows, columns or other dimensions. In WKT1, the parameter names are"num_row"
and"num_col"
respectively.The length of this array determine the tensor rank.
-
parameters
The cached descriptors for each elements in a tensor. Descriptors do not depend on tensor element values. Consequently, the same descriptors can be reused for allTensorValues
instances. -
zero
The elements for the 0 and 1 values, ornull
if unknown. Computed bycreateCache()
. -
one
The elements for the 0 and 1 values, ornull
if unknown. Computed bycreateCache()
. -
prefix
The prefix of parameter names for tensor elements. This is"elt_"
in WKT 1. -
separator
The separator between row and column in parameter names for tensor elements. This is"_"
in WKT 1.
-
-
Constructor Details
-
TensorParameters
@SafeVarargs public TensorParameters(Class<E> elementType, String prefix, String separator, org.opengis.parameter.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 Details
-
createCache
private <T> org.opengis.parameter.ParameterDescriptor<T>[] createCache()Initializes the fields used for cached values:zero
,one
and theparameters
array. The latter is not assigned to theparameters
field, but rather returned. Caller shall assign himself the returned value to theparameters
field.This method is invoked by constructor and on deserialization.
-
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.
-
verifyRank
private void verifyRank(int[] indices) Verifies that the length of the given array is equal to the tensor rank. -
getDimensionDescriptor
Returns the parameter descriptor for the dimension at the given index.- Parameters:
i
- the dimension index, from 0 inclusive torank()
exclusive.- Returns:
- the parameter descriptor for the dimension at the given index.
- See Also:
-
getElementDescriptor
Returns the parameter descriptor for a matrix or tensor element at the given indices. The length of the givenindices
array shall be equal to the rank. That length is usually 2, whereindices[0]
is the row index andindices[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:
-
cacheIndex
private static int cacheIndex(int[] indices) Returns the index in the cache for the given indices, or -1 if that elements is not cached. -
createElementDescriptor
protected org.opengis.parameter.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 bygetElementDescriptor(int[])
when a new descriptor needs to be created.Default implementation
The default implementation converts the given indices to a parameter name by invoking theindicesToName(int[])
method, then creates a descriptor for an optional parameter of that name. The default value is given bygetDefaultValue(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
Returns the parameter descriptor name of a matrix or tensor element at the given indices. The returned name shall be parsable by thenameToIndices(String)
method.Default implementation
The default implementation requires anindices
array having a length equals to the rank. That length is usually 2, whereindices[0]
is the row index andindices[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 overridenameToIndices(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
Returns the indices of matrix element for the given parameter name, ornull
if none. This method is the converse ofindicesToName(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. anNumberFormatException
, which is anIllegalArgumentException
subclass).
-
getDefaultValue
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:
-
descriptor
final org.opengis.parameter.ParameterDescriptor<?> descriptor(org.opengis.parameter.ParameterDescriptorGroup caller, String name, int[] actualSize) throws org.opengis.parameter.ParameterNotFoundException Returns the descriptor in this group for the specified name.- Parameters:
caller
- theTensorValues
instance invoking this method, used only in case of errors.name
- the case insensitive name of the parameter to search for.actualSize
- the current values of parameters that define the matrix (or tensor) dimensions.- Returns:
- the parameter for the given name.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if there is no parameter for the given name.
-
isInBounds
static boolean isInBounds(int[] indices, int[] actualSize) Returnstrue
if the given indices are not out-of-bounds.- Parameters:
indices
- the indices parsed from a parameter name.actualSize
- the current values of parameters that define the matrix (or tensor) dimensions.
-
numElements
private int numElements(int[] actualSize) Returns the number of elements (e.g."elt_0_0"
) when formatting the parameter descriptors for a tensor of the given size. This is the total number of elements in the tensor. -
getAllDescriptors
public org.opengis.parameter.ParameterDescriptor<?>[] getAllDescriptors(int... actualSize) Returns all parameters in this group for a tensor of the specified dimensions. The returned array contains all descriptors returned bygetDimensionDescriptor(int)
andgetElementDescriptor(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:
-
createValueGroup
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
orString
AbstractIdentifiedObject.getName()
"alias" GenericName
orCharSequence
(optionally as array)AbstractIdentifiedObject.getAlias()
"identifiers" ReferenceIdentifier
(optionally as array)AbstractIdentifiedObject.getIdentifiers()
"remarks" InternationalString
orString
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 org.opengis.parameter.ParameterValueGroup createValueGroup(Map<String, ?> properties, org.opengis.referencing.operation.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
public org.opengis.referencing.operation.Matrix toMatrix(org.opengis.parameter.ParameterValueGroup parameters) throws org.opengis.parameter.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:
org.opengis.parameter.InvalidParameterNameException
- if a parameter name was not recognized.- See Also:
-
hashCode
public int hashCode()Returns a hash code value for this object. -
equals
Compares this object with the given object for equality. -
readObject
Invoked on deserialization for restoring theparameters
array.- Parameters:
in
- the input stream from which to deserialize a group of tensor parameters.- Throws:
IOException
- if an I/O error occurred while reading or if the stream contains invalid data.ClassNotFoundException
- if the class serialized on the stream is not on the classpath.
-