pirt.splinegrid - Representing data using grids¶

The splinegrid module implements functionality for spline grids. A spline grid is used to representa field (i.e. data) using a grid. Essentially, spline grids allow the interpolation of sparse data in an optimally smooth way by adopting a multiscale approach. The only type of spline that makes sense for this purpose is the B-spline.

In Pirt, spline grids are used to represent deformations, but any kind of data can be represented, like e.g. image data.

The GridInterface class is the base class that enables basic grid properties and functionality. The SplineGrid class implements an actual grid that represents a scalar field. The GridContainer class can be used to wrap multiple SplineGrid instances in order to represent a vector/tensor field (such as color channels or deformations).

class pirt.GridInterface(field, sampling=5)¶

Abstract class to define the interface of a spline grid. Implemented by the Grid and GridContainer classes.

This class provides some generic methods and properties for grids in general. Most importantly, it handles initialization of the desctiption of the grid (dimensionality, shape and sampling of the underlying field, and the shape and sampling of the grid itself).

Parameters:	field : shape-tuple, numpy-array, Aarray, or FieldDescription A description of the field that this grid applies to. The field itself is not stored, only the field’s shape and sampling are of interest. sampling : number The spacing of the knots in the field. (For anisotropic fields, the spacing is expressed in world units.)

add(other_grid)¶: Create a new grid by adding this grid and the given grid.

copy()¶: Return a deep copy of the grid.

field_sampling¶: For each dim, the sampling of the field, i.e. the distance (in world units) between pixels/voxels (all 1’s if isotropic).

field_shape¶: The shape of the underlying field. (i.e. the size in each dim.)

grid_sampling¶: A scalar indicating the spacing (in world units) between the knots.

grid_sampling_in_pixels¶: For each dim, the spacing (in sub-pixels) between the knots. A dimension that has a low field sampling will have a high grid sampling in pixels (since the pixels are small, more fit between two knots).

grid_shape¶: The shape of the grid. (i.e. the size in each dim.)

ndim¶: The number of dimensions of this grid.

refine()¶: Refine the grid, returning a new grid instance (of the same type) that represents the same field, but with half the grid_sampling.

resize_field(new_shape)¶

Create a new grid, where the underlying field is reshaped. The field is still the same; it only has a different shape and sampling.

The parameter new_shape can be anything that can be converted to a FieldDescription instance.

Note that the knots arrays are shallow copied (which makes this function very efficient).

class pirt.SplineGrid(field, sampling=5)¶

A SplineGrid is a representation of a scalar field in N dimensions. This field is represented in a sparse way using knots, which are distributed in a uniform grid.

The manner in which these knots describe the field depends on the underlying spline being used, which is a Cubic B-spline. This spline adopts a shape corresponding to minimum bending energy, which makes them the preferred choice for many interpolation tasks. (Earlier versions of Pirt allowed setting the spline types, but to make things easier, and because the B-spline is the only sensible choice, this option was removed.)

Parameters:	field : shape-tuple, numpy-array, Aarray, FieldDescription A description of the field that this grid applies to. The field itself is not stored, only the field’s shape and sampling are of interest. sampling : number The spacing of the knots in the field. (For anisotropic fields, the spacing is expressed in world units.)

classmethod from_field(field, sampling, weights=None)¶

Create a SplineGrid from a given field. Note that the smoothness of the grid and the extent to which the grid follows the given values. Also see from_field_multiscale()

The optional weights array can be used to individually weight the field elements. Where the weight is zero, the values are not evaluated. The speed can therefore be significantly improved if there are relatively few nonzero elements.

Parameters:	field : numpy array or shape The field to represent with this grid. sampling : scalar The sampling of the returned grid. weights : (optional) numpy array This array can be used to weigh the contributions of the individual elements.

classmethod from_field_multiscale(field, sampling, weights=None)¶

Create a SplineGrid from the given field. By performing a multi-scale approach the grid adopts a minimal bending to conform to the given field.

The optional weights array can be used to individually weight the field elements. Where the weight is zero, the values are not evaluated. The speed can therefore be significantly improved if there are relatively few nonzero elements.

Parameters:	field : numpy array or shape The field to represent with this grid. sampling : scalar The sampling of the returned grid. weights : (optional) numpy array This array can be used to weigh the contributions of the individual elements.

Notes

The algorithmic is based on: Lee, Seungyong, George Wolberg, and Sung Yong Shin. 1997. “Scattered Data Interpolation with Multilevel B-splines”. IEEE TRANSACTIONS ON VISUALIZATION AND COMPUTER GRAPHICS 3 (3): 228-244.

classmethod from_points(field, sampling, pp, values)¶

Create a SplineGrid from the values specified at a set of points. Note that the smoothness of the grid and the extent to which the grid follows the given values. Also see from_points_multiscale()

Parameters:	field : numpy array or shape The image (of any dimension) to which the grid applies. sampling : scalar The sampling of the returned grid. pp : PointSet, 2D ndarray The positions (in world coordinates) at which the values are given. values : list or numpy array The values specified at the given positions.

classmethod from_points_multiscale(field, sampling, pp, values)¶

Create a SplineGrid from the values specified at a set of points. By performing a multi-scale approach the grid adopts a minimal bending to conform to the given values.

Parameters:	field : numpy array or shape The image (of any dimension) to which the grid applies. sampling : scalar The sampling of the returned grid. pp : PointSet, 2D ndarray The positions (in world coordinates) at which the values are given. values : list or numpy array The values specified at the given positions.

Notes

The algorithmic is based on: Lee, Seungyong, George Wolberg, and Sung Yong Shin. 1997. “Scattered Data Interpolation with Multilevel B-splines”. IEEE TRANSACTIONS ON VISUALIZATION AND COMPUTER GRAPHICS 3 (3): 228-244.

get_field()¶: Obtain the full field that this grid represents.

get_field_in_points(pp)¶: Obtain the field in the specied points (in world coordinates).

get_field_in_samples(pp)¶: Obtain the field in the specied samples (a tuple with pixel coordinates, in x-y-z order).

knots¶: A numpy array that represent the values of the knots.

show(axes=None, axesAdjust=True, showGrid=True)¶

For 2D grids, shows the field and the knots of the grid. The image is displayed in the given (or current) axes. By default the positions of the underlying knots are also shown using markers. Returns the texture object of the field image.

Requires visvis.

class pirt.GridContainer(field, sampling=5)¶

Abstract base class that represents multiple SplineGrid instances. Since each SplineGrid instance describes a field of scalar values, the GridContainer can be used to describe vectors/tensors. Examples are color and 2D/3D deformations.

The implementing class should:

instantiate SplineGrid instances and append them to ‘_grids’
implement methods to set the grid accordingly, probably using classmethods such as from_points, from_field, etc.

grids¶: A tuple of subgrids.

class pirt.FieldDescription(*args)¶

Describes the dimensions of a field (i.e. Aarray). It stores the following properties: shape, sampling, origin

This class can for example be used to instantiate a new grid without requiring the actual field.

This class can be instantiated with a shape and sampling tuple, or with any object that describes a field in a way that we know of (e.g. SplineGrid and DeformationField instances).

Examples

FieldDescription(shape, sampling=None, origin=None)
FieldDescription(grid)
FieldDescription(Aarray)
FieldDescription(np.ndarray) # assumes unit sampling and zero origin

defined_origin¶: Whether the origin was explicitly defined.

defined_sampling¶: Whether the sampling was explicitly defined.

ndim¶: The number of dimensions of the field.

origin¶: The origin (spatial offset) of the field.

sampling¶: The sampling between the pixels of the field.

shape¶: The shape of the field.