sub_pixel_read

sub_pixel_read(image, bounds, output_size, padding=0, stride=1, interpolation='nearest', interpolation_padding=2, read_func=None, pad_mode='constant', pad_constant_values=0, read_kwargs=None, pad_kwargs=None, *, pad_at_baseline)[source]

Read and resize an image region with sub-pixel bounds.

Allows for reading of image regions with sub-pixel coordinates, and out of bounds reads with various padding and interpolation modes.

Illustration for reading a region with fractional coordinates (sub-pixel).
Parameters:

  • image (numpy.ndarray) – Image to read from.

  • bounds (tuple(float)) – Bounds of the image to read in (left, top, right, bottom) format.

  • output_size (tuple(int)) – The desired output size.

  • padding (int or tuple(int)) – Amount of padding to apply to the image region in pixels. Defaults to 0.

  • stride (int or tuple(int)) – Stride when reading from img. Defaults to 1. A tuple is interpreted as stride in x and y (axis 1 and 0 respectively).

  • interpolation (str) – Method of interpolation. Possible values are: nearest, linear, cubic, lanczos, area. Defaults to nearest.

  • pad_at_baseline (bool) – Apply padding in terms of baseline pixels. Defaults to False, meaning padding is added to the output image size in pixels.

  • interpolation_padding (int) – Padding to temporarily apply before rescaling to avoid border effects. Defaults to 2.

  • read_func (collections.abc.Callable) – Custom read function. Defaults to safe_padded_read(). A function which recieves two positional args of the image object and a set of integer bounds in addition to padding key word arguments for reading a pixel-aligned bounding region. This function should return a numpy array with 2 or 3 dimensions. See examples for more.

  • pad_mode (str) – Method for padding when reading areas are outside the input image. Default is constant (0 padding). This is passed to read_func which defaults to safe_padded_read(). See safe_padded_read() for supported pad modes. Setting to “none” or None will result in no padding being applied.

  • pad_constant_values (int, tuple(int)) – Constant values to use when padding with constant pad mode. Passed to the numpy.pad() constant_values argument. Default is 0.

  • read_kwargs (dict) – Arbitrary keyword arguments passed through to read_func.

  • pad_kwargs (dict) – Arbitrary keyword arguments passed through to the padding function numpy.pad().

Returns:

Output image region.

Return type:

numpy.ndimage

Raises:

Examples

>>> # Simple read
>>> bounds = (0, 0, 10.5, 10.5)
>>> sub_pixel_read(image, bounds, pad_at_baseline=False)

>>> # Read with padding applied to bounds before reading:
>>> bounds = (0, 0, 10.5, 10.5)
>>> region = sub_pixel_read(
...     image,
...     bounds,
...     padding=2,
...     pad_mode="reflect",
...     pad_at_baseline=False,
... )

>>> # Read with padding applied after reading:
>>> bounds = (0, 0, 10.5, 10.5)
>>> region = sub_pixel_read(image, bounds, pad_at_baseline=False)
>>> region = np.pad(region, padding=2, mode="reflect")

>>> # Custom read function which generates a diagonal gradient:
>>> bounds = (0, 0, 10.5, 10.5)
>>> def gradient(_, b, **kw):
...     width, height = (b[2] - b[0], b[3] - b[1])
...     return np.mgrid[:height, :width].sum(0)
>>> sub_pixel_read(bounds, read_func=gradient, pad_at_baseline=False)

>>> # Custom read function which gets pixel data from a custom object:
>>> bounds = (0, 0, 10, 10)
>>> def openslide_read(image, bounds, **kwargs):
...     # Note that bounds may contain negative integers
...     left, top, right, bottom = bounds
...     size = (right - left, bottom - top)
...     pil_img = image.read_region((left, top), level=0, size=size)
...     return np.array(pil_img.convert("RGB"))
>>> sub_pixel_read(bounds, read_func=openslide_read, pad_at_baseline=False)