# Package org.apache.sis.referencing.operation.matrix

package org.apache.sis.referencing.operation.matrix
Matrix implementations for spatiotemporal referencing. Matrices can be of arbitrary size, but the most common ones in the context of geospatial coordinate operations are not greater than 5×5 (number of spatiotemporal dimensions + 1). This package differs from other matrix packages by:

- The class specializations for such small matrices.
- Methods specific to coordinate systems support like `Matrices​.createTransform(…)`.
- Matrix inversions tolerant to `NaN` values and non-square matrix in some situations.

This package provides public implementations of small square matrices, with size ranging from 1×1 to 4×4. Those implementations are made public because in many cases, the user know that (s)he is working with (for example) three-dimensional Coordinate Reference Systems (CRS). If the number of CRS dimensions is fixed to 3, then affine transforms between those CRS can be represented by 4×4 matrices, and the derivatives of those transforms can be represented by 3×3 matrices. Since the user know the matrices size, (s)he can use the specific implementation and read or write directly the mrow column field.

Example: in the two dimensional case, an affine transform from a map projection (units in metres) to the screen (units in pixels) can be performed by the following matrix multiplication:

## Extended floating point precision

This package uses extended floating point precision for most arithmetic operations like matrix multiplications and inversions. SIS needs extended precision because affine transforms concatenations like conversion from degrees to radians, followed by some operations, followed by conversion back from radians to degrees, are very frequent. Without extended precision, we often obtain values like 0.99999… where we would expect an identity transform. The usual workaround - namely comparing the floating point values with a small epsilon tolerance value - is dangerous in this particular case because datum shifts, when expressed as a matrix from their Bursa-Wolf parameters, are very close to the identity transform.

The current implementation uses double-double arithmetic. However this may change in any future SIS version.

## Related projects

This package is not designed for large matrices, and is rooted in `org​.apache​.sis​.referencing` for making clearer that this is not a general-purpose library. For computational intensive calculations, better guarantees on numerical stability, sparse matrices support and more, consider using an dedicated library like jblas instead.

The Vecmath library shares similar goals than `MatrixSIS`. Like SIS, Vecmath is optimized for small matrices of interest for 2D and 3D graphics.

Since:
  0.4

Defined in the `sis-referencing` module

- Related Packages
  Package
  Description
  org.apache.sis.referencing.operation
  Relationship between any two Coordinate Reference Systems (CRS).
  org.apache.sis.referencing.operation.builder
  Helper classes for creating Math Transforms from a set of points.
  org.apache.sis.referencing.operation.projection
  Map projection implementations.
  org.apache.sis.referencing.operation.transform
  Conversions or transformations of multi-dimensional coordinate points.
- Class
  Description
  AffineTransforms2D
  Bridge between `Matrix` and Java2D `AffineTransform` instances.
  Matrices
  `Matrix` factory methods and utilities.
  Matrix1
  A matrix of fixed 1×1 size, typically resulting from `MathTransform1D` derivative computation.
  Matrix2
  A matrix of fixed 2×2 size, typically resulting from `MathTransform2D` derivative computation.
  Matrix3
  A matrix of fixed 3×3 size.
  Matrix4
  A matrix of fixed 4×4 size, often used in datum shifts.
  MatrixSIS
  A `Matrix` able to perform some operations of interest to Spatial Information Systems (SIS).
  MismatchedMatrixSizeException
  Thrown when two matrices can not be added or multiplied because the sizes do not match.
  NoninvertibleMatrixException
  Thrown when a matrix can not be inverted.