Resample

Image resampling module.

Image resampling can be done on intensity and labelled images.

timagetk.algorithms.resample.ISO_RESAMPLE_METHODS = ['min', 'max']

List of valid isometric resampling methods.

timagetk.algorithms.resample.isometric_resampling(image, method='min', interpolation=None, **kwargs)[source]

Isometric resampling of a SpatialImage.

Parameters:

  • image (timagetk.SpatialImage or timagetk.MultiChannelImage or timagetk.LabelledImage) – The image to resample.

  • method ({'min', 'max', float}, optional) – Change voxel-size to ‘min’, ‘max’ (default) of original voxel-size or to a given value.

  • interpolation ({"nearest", "linear", "cspline", "cellbased"}) – Interpolation method to use. See the “Notes” section for detailled explanations. By default, try to guess it based on the type of input image. Use one of the GRAY_INTERPOLATION_METHODS with grayscale (intensity) images. Use one of the LABEL_INTERPOLATION_METHODS with labelled (segmented) images.

  • channel (str) – If a MultiChannelImage is used as input image, the algorithm will be applied only to this channel. Else it will be applied to all channels of the multichannel image.

  • cell_based_sigma (float) – Required when using “cellbased” interpolation method, sigma for cell-based interpolation. In voxel units!

Returns:

timagetk.SpatialImage or timagetk.MultiChannelImage or timagetk.LabelledImage – The resampled image.

See also

timagetk.third_party.vt_parser.GRAY_INTERPOLATION_METHODS, timagetk.third_party.vt_parser.LABEL_INTERPOLATION_METHODS, timagetk.third_party.vt_parser.DEF_GRAY_INTERP_METHOD, timagetk.third_party.vt_parser.DEF_LABEL_INTERP_METHOD, timagetk.third_party.vt_parser.apply_trsf_kwargs, timagetk.third_party.vt_parser.general_kwargs, timagetk.third_party.vt_parser.parallel_kwargs

Notes

Interpolation methods definitions:

  • nearest: nearest neighbor interpolation (for binary or label images)

  • linear: bi- or tri-linear interpolation (for intensity images)

  • cspline: cubic spline (for intensity images)

  • cellbased: cell based interpolation (for label images)

Using linear interpolation method might decrease the contrast compared to cspline.

Using cspline interpolation method requires a larger amount of memory than the linear interpolation method.

Use nearest interpolation with a binary image.

Examples

>>> from timagetk.algorithms.resample import isometric_resampling
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> # Loading an example grayscale image and show info:
>>> img = imread(shared_dataset("p58")[0])
>>> print(f"Input image ZYX shape: {img.shape}")
Input image ZYX shape: (59, 460, 460)
>>> print(f"Input image ZYX voxel-size: {img.voxelsize}")
Input image ZYX voxel-size: [1.0, 0.20031953747828882, 0.20031953747828882]

>>> # Example #1 - Compute the smallest isometric image w.r.t. voxel-size (smallest shape, maximal voxel-size)
>>> iso_img = isometric_resampling(img, 'max', interpolation='linear')
>>> print(f"Small isometric image ZYX shape: {iso_img.shape}")
Small isometric image ZYX shape: (59, 92, 92)
>>> print(f"Small isometric image ZYX voxel-size: {iso_img.voxelsize}")
Small isometric image ZYX voxel-size: [1.0, 1.0, 1.0]

>>> # Example #2 - Compute the largest isometric image w.r.t. voxel-size (biggest shape, minimal voxel-size)
>>> iso_img = isometric_resampling(img, 'min', interpolation='linear')
>>> print(f"Large isometric image ZYX shape: {iso_img.shape}")
Large sometric image ZYX shape: (295, 460, 460)
>>> print(f"Large isometric image ZYX voxel-size: {iso_img.voxelsize}")
Large isometric image ZYX voxel-size: [0.2003195434808731, 0.2003195434808731, 0.2003195434808731]

>>> # Example #3 - Compute an isometric image to a given voxel-size:
>>> iso_img = isometric_resampling(img, 0.5, interpolation='linear')
>>> print(f"Isometric image ZYX shape: {iso_img.shape}")
Isometric image ZYX shape: (118, 184, 184)
>>> print(f"Isometric image ZYX voxel-size: {iso_img.voxelsize}")
Isometric image ZYX voxel-size: [0.5, 0.5, 0.5]
timagetk.algorithms.resample.new_shape_from_max(shape, max_dim, round_func=<ufunc 'ceil'>, iso_transform=False)[source]

Compute a new shape from a max dimension, only down-sizing the shape.

Parameters:

  • shape (list or tuple) – Current image shape.

  • max_dim (int) – Max allowed dimension for the shape

  • round_func (func, optional) – Function used to round the new shape (to integers).

  • iso_transform (bool, optional) – If True, apply the down-sizing equally to all dimensions.

Returns:

numpy.ndarray – New image shape.

Examples

>>> import numpy as np
>>> from timagetk.algorithms.resample import new_shape_from_max
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> # Loading an example grayscale image and show info:
>>> img = imread(shared_dataset("p58")[0])
>>> current_shape = img.get_shape()
>>> print(current_shape)
[160, 230, 230]
>>> new_shape = new_shape_from_max(current_shape, 200)
>>> print(new_shape)
[160, 200, 200]
>>> new_shape = new_shape_from_max(current_shape, 128)
>>> print(new_shape)
[128, 128, 128]
>>> new_shape = new_shape_from_max(current_shape, 200, iso_transform=True)
>>> print(new_shape)  # default "rounding function" is `np.ceil`
[140, 201, 201]
>>> new_shape = new_shape_from_max(current_shape, 128, iso_transform=True)
>>> print(new_shape)
[90, 128, 128]
timagetk.algorithms.resample.new_voxelsize_from_max_nbytes(image, max_nbytes, decimal=4)[source]

Compute a new voxelsize from a max dimension, only down-sizing the shape.

Parameters:

  • image (SaptialImage) – Current image.

  • max_dim (int) – Max allowed bytes size for the image.

Returns:

list – New image shape as a list of integers.

Examples

>>> import numpy as np
>>> from timagetk.algorithms.resample import new_voxelsize_from_max_nbytes
>>> from timagetk.algorithms.resample import resample
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> # Loading an example grayscale image and show info:
>>> image = imread(shared_dataset("p58")[0])
>>> current_vxs = image.get_voxelsize()
>>> print(current_vxs)
[0.40064001083374023, 0.40064001083374023, 0.40064001083374023]
>>> print(image.nbytes)
8464000
>>> new_vxs = new_voxelsize_from_max_nbytes(image, 846400)
>>> print(new_vxs)
[0.40064001, 0.46073601, 0.46073601]
>>> new_img = resample(image, voxelsize=new_vxs)
>>> print(new_img.get_shape())
>>> print(new_img.get_voxelsize())
>>> print(new_img.nbytes)
timagetk.algorithms.resample.new_voxelsize_from_max_shape(image, max_dim, round_func=<ufunc 'ceil'>, iso_transform=False)[source]

Compute a new voxelsize from a max dimension, only down-sizing the shape.

Parameters:

  • image (SaptialImage) – Current image.

  • max_dim (int) – Max allowed dimension for the shape

  • round_func (func, optional) – Function used to round the new shape (to integers).

  • iso_transform (bool, optional) – If True, apply the down-sizing equally to all dimensions.

Returns:

list – New image shape as a list of integers.

Examples

>>> import numpy as np
>>> from timagetk.algorithms.resample import new_voxelsize_from_max_shape
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> # Loading an example grayscale image and show info:
>>> img = imread(shared_dataset("p58")[0])
>>> current_vxs = img.get_voxelsize()
>>> print(current_vxs)
[0.40064001083374023, 0.40064001083374023, 0.40064001083374023]
>>> new_vxs = new_voxelsize_from_max_shape(img, 200)
>>> print(new_vxs)
[0.40064001 0.46073601 0.46073601]
>>> new_vxs = new_voxelsize_from_max_shape(img, 128)
>>> print(new_vxs)
[0.50080001 0.71990002 0.71990002]
>>> new_vxs = new_voxelsize_from_max_shape(img, 200, iso_transform=True)
>>> print(new_vxs)  # default "rounding function" is `np.ceil`
[0.4578743  0.45844379 0.45844379]
>>> new_vxs = new_voxelsize_from_max_shape(img, 128, iso_transform=True)
>>> print(new_vxs)
[0.71224891 0.71990002 0.71990002]
timagetk.algorithms.resample.resample(image, voxelsize=None, shape=None, interpolation=None, **kwargs)[source]

Resample an image using given shape or voxel-size.

Parameters:

  • image (timagetk.SpatialImage or timagetk.MultiChannelImage or timagetk.LabelledImage) – The image to resample.

  • voxelsize (list, optional) – The (Z)YX sorted voxel-size to use for image resampling.

  • shape (list, optional) – The (Z)YX sorted shape to use for image resampling.

  • interpolation ({"nearest", "linear", "cspline", "cellbased"}, optional) – Interpolation method to use. See the “Notes” section for detailled explanations. By default, try to guess it based on the type of input image. Use one of the GRAY_INTERPOLATION_METHODS with grayscale (intensity) images. Use one of the LABEL_INTERPOLATION_METHODS with labelled (segmented) images.

  • channel (str) – If a MultiChannelImage is used as input image, the algorithm will be applied only to this channel. Else it will be applied to all channels of the multichannel image.

  • cell_based_sigma (float) – Required when using “cellbased” interpolation method, sigma for cell-based interpolation. In voxel units!

Returns:

timagetk.SpatialImage or timagetk.MultiChannelImage or timagetk.LabelledImage – The resampled image.

See also

timagetk.third_party.vt_parser.GRAY_INTERPOLATION_METHODS, timagetk.third_party.vt_parser.LABEL_INTERPOLATION_METHODS, timagetk.third_party.vt_parser.DEF_GRAY_INTERP_METHOD, timagetk.third_party.vt_parser.DEF_LABEL_INTERP_METHOD, timagetk.third_party.vt_parser.template_kwargs, timagetk.third_party.vt_parser.interpolate_kwargs, timagetk.third_party.vt_parser.general_kwargs, timagetk.third_party.vt_parser.parallel_kwargs

Notes

Note that you have to provide either a target voxelsize or shape.

Interpolation methods definitions:

  • nearest: nearest neighbor interpolation (for binary or label images)

  • linear: bi- or tri-linear interpolation (for intensity images)

  • cspline: cubic spline (for intensity images)

  • cellbased: cell based interpolation (for label images)

Using linear interpolation method might decrease the contrast compared to cspline.

Using cspline interpolation method requires a larger amount of memory than the linear interpolation method.

Use nearest interpolation with a binary image.

Examples

>>> import numpy as np
>>> from timagetk.algorithms.resample import resample
>>> from timagetk.algorithms.template import iso_template
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_dataset
>>> from timagetk.visu.mplt import grayscale_imshow
>>> # Loading an example grayscale image and show info:
>>> img = imread(shared_dataset("p58", 'intensity')[0])
>>> print(f"Input image ZYX shape: {img.shape}")
Input image ZYX shape: (160, 230, 230)
>>> print(f"Input image ZYX voxel-size: {img.voxelsize}")
Input image ZYX voxel-size: [0.40064001083374023, 0.40064001083374023, 0.40064001083374023]

>>> # EXAMPLE 1 - Resampling a grayscale image with 'shape':
>>> from timagetk.algorithms.resample import new_shape_from_max
>>> new_shape = new_shape_from_max(img.get_shape(), 200)
>>> print(new_shape)
[59, 256, 256]
>>> out_img = resample(img, shape=new_shape, interpolation='linear')
>>> print(f"Output image ZYX shape: {out_img.shape}")
Output image ZYX shape: (59, 256, 256)
>>> print(f"Output image ZYX voxel-size: {out_img.voxelsize}")
Output image ZYX voxel-size: [1.0, 0.35994917154312134, 0.35994917154312134]
>>> grayscale_imshow([img, out_img], slice_id=20, title=['Original', 'XY rescaled'])

>>> # EXAMPLE 2 - Resampling a grayscale image with 'voxelsize':
>>> out_img = resample(img, voxelsize=[0.4, 0.3, 0.2])
>>> print(f"Output image ZYX shape: {out_img.shape}")
Output image ZYX shape: (148, 307, 461)
>>> print(f"Output image ZYX voxel-size: {out_img.voxelsize}")
Output image ZYX voxel-size: [1.0, 0.35994917154312134, 0.35994917154312134]

>>> # EXAMPLE 3 - Resampling of a LabelledImage:
>>> from timagetk import LabelledImage
>>> img = imread(shared_dataset("sphere", "intensity")[0])
>>> img = LabelledImage(img, not_a_label=0)
>>> print(img.get_voxelsize())
[0.25, 0.25, 0.25]
>>> print(img.get_shape())
[225, 225, 225]
>>> print(len(img.labels()))
64
>>> out_img = resample(img, voxelsize=[0.5, 0.5, 0.5])
>>> print(out_img.get_voxelsize())
[0.5, 0.5, 0.5]
>>> print(out_img.get_shape())
[113, 113, 113]
>>> print(len(out_img.labels()))
64
>>> # EXAMPLE 4 - Effect of resampling method choice (linear vs. cspline) on grayscale image:
>>> img = imread(shared_dataset("p58")[0])
>>> linear_img = resample(img, voxelsize=[0.5, 0.5, 0.5], interpolation='linear')
>>> cspline_img = resample(img, voxelsize=[0.5, 0.5, 0.5], interpolation='cspline')
>>> grayscale_imshow([img, linear_img, cspline_img], slice_id=5, title=['Original', 'Linear', 'Cubic spline'], val_range=['type', 'type', 'type'])