Use Case: DSTL01-TRANSFORMATION-MATRIX

[paulc-dstl]

Use Case DSTL01

Transformation Matrices

As a GeoSPARQL data user I would like to transform geometry coordinates using a matrix. Matrix operations can be defined using 2x2 or 3x3 matrices for two- and three-dimensional transformations respectively. Providing a generic matrix based transformation function allows for a comprehensive range of basic geometry operations in 2D or 3D. A generic matrix transformation can be parameterized and used as the basis for a wide range of other functions. Matrices can be multiplied to provide compound transformations.

Transformations can be considered simple and working in cartesian 2D/3D coordinate space only. For more complex transformations on geometries, use eg PROJ.

A matrix based transformation can be used to:

• Translate in two or three dimensions
• Scale along one, two or three axes
• Rotate about any point or axis
• Shear along any axis
• Reflect in any line (2d) or plane (3d)
• Project
• Compound transformation comprising any of the above

Examples:

• scale (in 2d) by k in the x-axis:

$$\begin{bmatrix}k&0\\0&1\end{bmatrix}$$

• scale (in 2d) by k in the y-axis:

$$\begin{bmatrix}1&0\\0&k\end{bmatrix}$$

• rotate by angle $$\Theta$$ about the origin:

$$\begin{bmatrix}\cos \theta& -\sin \theta\\ \sin \theta & \cos \theta \end{bmatrix}$$

• rotate by angle $$\Theta$$ about an axis defined by a unit vector (x,y,z):

$$\begin{bmatrix}xx(1-\cos \theta)+\cos\theta & yx(1-\cos\theta)-z\sin\theta & zx(1-\cos\theta)+y\sin\theta\\ xy(1-\cos\theta)+z\sin\theta & yy(1-\cos\theta)+\cos\theta & zy(1-\cos\theta)-x\sin\theta \\ xz(1-\cos\theta)-y\sin\theta & yz(1-\cos\theta)+x\sin\theta & zz(1-\cos\theta)+\cos\theta \end{bmatrix}$$

Function signature:

matrixTransform(geometry_in: ogc:geomLiteral, transform: ex:matrix): geometry_out: ogc:geomLiteral

Actor

GeoSPARQL data user (human or software agent querying RDF dataset with GeoSPARQL)

Preconditions

Geometries with 2D or 3D representations are present in a dataset to be queried.
There exists some usable definition of a matrix datatype to be specified as the type to be used for the function parameter transform. This should be equivalent to the numpy.array or JSON Schema datatypes: eg [[1,0],[0,1]] and should allow for the specification of MxN matrices, typically 2x2 or 3x3 matrices.

Postconditions

A SPARQL query can be executed that includes a function to return geometry with coordinates transformed from input geometry coordinate using a matrix which specifies a transformation.

Steps

Actor: discovers the matrix transformation function
Actor: executes a SPARQL query containing a matrix transformation function with arguments for a) a geometry and b) a matrix representing the desired transformation.
System: returns a SPARQL result with a geometry object translated from the input geometry using the input matrix.

[paulc-dstl]

Looking at existing use cases, this generic transformation matrix function can also support the following the following use cases:

• Use Case ONTO24: Translate By Vector #602
• Use Case ONTO19: Flip XY Coordinates #576
• Use Case ONOT9: Shift up or down 3D geometry (add to Z coordinates) #559
• Use Case ONTO10: Multiply Z coordinates #560
• Use Case ONTO1: Flattening 3D Geometry to 2D #547

[ar-chad]

Yes, so there will be question if, at least some of, those simpler functions should be still in GeoSPARQL or matrix transform would be the one to keep.

[paulc-dstl]

I think likely keep the simpler ones also - if a users wants to eg scale along z-axis, i imagine many users would prefer to use a simple dedicated function rather than work out a matrix transformation. Even if when it comes to implementation, the simpler functions become wrappers which call the matrix function.

[situx]

@paulc-dstl maybe I have missed it, but I think we would need to define a literal type for the matrix representation, correct?