symjax.tensor.interpolation

map_coordinates(input, coordinates, order[, …])	Map the input array to new coordinates by interpolation.
upsample_1d(tensor, repeat[, axis, mode, …])	1-d upsampling of tensor
hermite_1d(samples, knots, values, derivatives)	Real interpolation with hermite cubic spline.
hermite_2d(values, n_x, n_y)	TODO: test and finalize this
thin_plate_spline(input, dest_offsets[, …])	applies a thin plate spline transformation [2] on the input as in [1]_.
affine_transform(input, theta[, order, …])	Spatial transformer layer The layer applies an affine transformation on the input.

Detailed Descriptions

symjax.tensor.interpolation.map_coordinates(input, coordinates, order, mode='constant', cval=0.0)

Map the input array to new coordinates by interpolation.

LAX-backend implementation of map_coordinates(). Only nearest neighbor (order=0), linear interpolation (order=1) and modes 'constant', 'nearest' and 'wrap' are currently supported. Note that interpolation near boundaries differs from the scipy function, because we fixed an outstanding bug (https://github.com/scipy/scipy/issues/2640); this function interprets the mode argument as documented by SciPy, but not as implemented by SciPy.

Original docstring below.

The array of coordinates is used to find, for each point in the output, the corresponding coordinates in the input. The value of the input at those coordinates is determined by spline interpolation of the requested order.

The shape of the output is derived from that of the coordinate array by dropping the first axis. The values of the array along the first axis are the coordinates in the input array at which the output value is found.

Parameters:

• input (array_like) – The input array.
• coordinates (array_like) – The coordinates at which input is evaluated.
• order (int, optional) – The order of the spline interpolation, default is 3. The order has to be in the range 0-5.
• mode ({'reflect', 'constant', 'nearest', 'mirror', 'wrap'}, optional) – The mode parameter determines how the input array is extended beyond its boundaries. Default is ‘constant’. Behavior for each valid value is as follows:
• cval (scalar, optional) – Value to fill past edges of input if mode is ‘constant’. Default is 0.0.

Returns:

map_coordinates – The result of transforming the input. The shape of the output is derived from that of coordinates by dropping the first axis.

Return type:

ndarray

See also

spline_filter(), geometric_transform(), scipy.interpolate()

Examples

>>> from scipy import ndimage
>>> a = np.arange(12.).reshape((4, 3))
>>> a
array([[  0.,   1.,   2.],
       [  3.,   4.,   5.],
       [  6.,   7.,   8.],
       [  9.,  10.,  11.]])
>>> ndimage.map_coordinates(a, [[0.5, 2], [0.5, 1]], order=1)
array([ 2.,  7.])

Above, the interpolated value of a[0.5, 0.5] gives output[0], while a[2, 1] is output[1].

>>> inds = np.array([[0.5, 2], [0.5, 4]])
>>> ndimage.map_coordinates(a, inds, order=1, cval=-33.3)
array([  2. , -33.3])
>>> ndimage.map_coordinates(a, inds, order=1, mode='nearest')
array([ 2.,  8.])
>>> ndimage.map_coordinates(a, inds, order=1, cval=0, output=bool)
array([ True, False], dtype=bool)

symjax.tensor.interpolation.upsample_1d(tensor, repeat, axis=-1, mode='constant', value=0.0, boundary_condition='periodic')

1-d upsampling of tensor

allow to upsample a tensor by an arbitrary (integer) amount on a given axis by applying a univariate upsampling strategy.

Parameters:

• tensor (tensor) – the input tensor to upsample
• repeat (int) – the amount of new values ot insert between each value
• axis (int) – the axis to upsample
• mode (str) – the type of upsample to perform (linear, constant, nearest)
• value (float (default=0)) – the value ot use for the case of constant upsampling

symjax.tensor.interpolation.hermite_1d(samples, knots, values, derivatives)

Real interpolation with hermite cubic spline.

Parameters:

• knots (array-like) – The knots onto the function is defined (derivative and antiderivative) tensor of knots can be given in which case the shape is (…, N_KNOTS) the first dimensions are treated independently.
• samples (array-like) – The points where the interpolation is required of shape (TIME). If the shape is more, the first dimensions must be broadcastable agains knots.
• values (array-like) – The real values of amplitude onto knots, same shape as knots.
• derivative (array-like) – The real values of derivatives onto knots, same shape as knots.

Returns:

yi – The interpolated real-valued function. :param derivatives:

Return type:

array-like

symjax.tensor.interpolation.hermite_2d(values, n_x, n_y)

TODO: test and finalize this

Parameters:

• values (array-like) – the values, and 2 directional derivatives and the cross derivative for the 4 knots per region, hence it should be of shape n,N,M,4 values vx vy vxy
• n_x (int) – the number of points in x per region
• n_y (int) – the number of points in y per region

Returns:

interpolation

Return type:

array-like

symjax.tensor.interpolation.thin_plate_spline(input, dest_offsets, order=1, downsample_factor=1, border_mode='nearest')

applies a thin plate spline transformation [2] on the input as in [1]_.

The thin plate spline transform is determined based on the movement of some number of control points. The starting positions for these control points are fixed. The output is interpolated with a bilinear transformation.

Implementation based on Lasagne

Parameters:

• incoming (Tensor) – The input to be transformed, should be a 4D tensor, with shape (batch_size, num_input_channels, input_rows, input_columns).
• dest_offsets (Tensor) – The parameters of the thin plate spline transformation as the x and y coordinates of the destination offsets of each control point. This should be a 2D tensor, with shape (batch_size, 2 * num_control_points). The number of control points to be used for the thin plate spline transformation. These points will be arranged as a grid along the image, so the value must be a perfect square. Default is 16.
• order (int (default 1)) – The order of the interpolation
• downsample_factor (float or iterable of float) – A float or a 2-element tuple specifying the downsample factor for the output image (in both spatial dimensions). A value of 1 will keep the original size of the input. Values larger than 1 will downsample the input. Values below 1 will upsample the input.
• border_mode ('nearest', 'mirror', or 'wrap') – Determines how border conditions are handled during interpolation. If ‘nearest’, points outside the grid are clipped to the boundary’. If ‘mirror’, points are mirrored across the boundary. If ‘wrap’, points wrap around to the other side of the grid. See http://stackoverflow.com/q/22669252/22670830#22670830 for details.

References

[1]	Max Jaderberg, Karen Simonyan, Andrew Zisserman, Koray Kavukcuoglu (2015): Spatial Transformer Networks. NIPS 2015, http://papers.nips.cc/paper/5854-spatial-transformer-networks.pdf

[2]	(1, 2) Fred L. Bookstein (1989): Principal warps: thin-plate splines and the decomposition of deformations. IEEE Transactions on Pattern Analysis and Machine Intelligence. http://doi.org/10.1109/34.24792

symjax.tensor.interpolation.affine_transform(input, theta, order=1, downsample_factor=1, border_mode='nearest')

Spatial transformer layer The layer applies an affine transformation on the input. The affine transformation is parameterized with six learned parameters [1]_. The output is interpolated with a bilinear transformation if order is 1.

It is also convenient to interpret (each) \(\theta \in \mathbb{R}^6\) vector in term of an affine transformation of the image coordinates. In that case the 2d coordinates x are transformed to Ax+b with A a 2x2 matrix and b a 2d bias vector with

\[\begin{split}A = \begin{pmatrix} \theta [0]& \theta[1]\\ \theta[3]& \theta[4] \end{pmatrix}, b = \begin{pmatrix} \theta [2]\\ \theta[5] \end{pmatrix}.\end{split}\]

Parameters:

• incoming (Tensor) – The input which should be a 4D tensor, with shape (batch_size, num_input_channels, input_rows, input_columns).
• theta (Tensor) – The parameters of the affine transformation. See the example for how to initialize to the identity transform.
• order (int (default 1)) – The order of the interpolation
• downsample_factor (float or iterable of float) – A float or a 2-element tuple specifying the downsample factor for the output image (in both spatial dimensions). A value of 1 will keep the original size of the input. Values larger than 1 will downsample the input. Values below 1 will upsample the input.
• border_mode ('nearest', 'mirror', or 'wrap') – Determines how border conditions are handled during interpolation. If ‘nearest’, points outside the grid are clipped to the boundary. If ‘mirror’, points are mirrored across the boundary. If ‘wrap’, points wrap around to the other side of the grid. See http://stackoverflow.com/q/22669252/22670830#22670830 for details.

References

[1]	Max Jaderberg, Karen Simonyan, Andrew Zisserman, Koray Kavukcuoglu (2015): Spatial Transformer Networks. NIPS 2015, http://papers.nips.cc/paper/5854-spatial-transformer-networks.pdf