plenoptic.process.upsample_blur

plenoptic.process.upsample_blur(image, odd, n_scales=1, filtname='binom5', scale_filter=True)

Upsample by 2 and convolve with named filter.

When upsampling an image, we need some way to estimate the new pixels; convolving with a filter allows us to interpolate these pixels from their neighbors.

Parameters:

• image (Tensor) – Image, or batch of images, of shape (batch, channel, height, width). Batches and channels are handled independently.

• odd (tuple[int, int]) – This should contain two integers of value 0 or 1, which determines whether the output height and width should be even (0) or odd (1).

• n_scales (int (default: 1)) – Apply the blur and downsample procedure recursively n_scales times. Must be positive.

• filtname (str (default: 'binom5')) – Name of the filter. See named_filter for options.

• scale_filter (bool (default: True)) – If True, the filter sums to 4 (i.e., it does not affect the DC component of the signal and the output’s mean will approximately match that of the input). If False, the filter sums to 2 (and the output’s mean will be roughly half that of the input).

Return type:

Tensor

Returns:

upsampled_image – The upsampled image.

Raises:

ValueError – If n_scales is not positive.

See also

upsample_convolve

Perform this operation once using a user-specified filter.

blur_downsample

Perform the inverse operation, correlating and downsampling a user-specified number of times using a named filter.

expand

An alternative upsampling operation.

Examples

>>> import plenoptic as po
>>> import torch
>>> img = po.data.einstein()
>>> upsampled = po.process.upsample_blur(img, odd=[0, 0])
>>> upsampled.shape
torch.Size([1, 1, 512, 512])
>>> po.plot.imshow([img, upsampled], title=["image", "upsampled"])
<PyrFigure...>

(png, hires.png, pdf)

Note that the dimensions have changed.

The odd argument allows for choosing whether the output width and/or height should be even or odd:

>>> upsampled_even = po.process.upsample_blur(img, odd=[0, 0])
>>> upsampled_even.shape
torch.Size([1, 1, 512, 512])
>>> upsampled_odd = po.process.upsample_blur(img, odd=[1, 1])
>>> upsampled_odd.shape
torch.Size([1, 1, 511, 511])
>>> upsampled_mixed_odd_even = po.process.upsample_blur(img, odd=[1, 0])
>>> upsampled_mixed_odd_even.shape
torch.Size([1, 1, 511, 512])

The n_scales argument allows for applying the upsampling and blurring recursively:

>>> upsampled_2 = po.process.upsample_blur(img, odd=[0, 0], n_scales=2)
>>> upsampled_2.shape
torch.Size([1, 1, 1024, 1024])
>>> upsampled_4 = po.process.upsample_blur(img, odd=[0, 0], n_scales=4)
>>> upsampled_4.shape
torch.Size([1, 1, 4096, 4096])
>>> po.plot.imshow(
...     [img, upsampled_2, upsampled_4],
...     title=["image", "upsampled x2", "upsampled x4"],
... )
<PyrFigure...>

(png, hires.png, pdf)

In Plenoptic, we typically use a fifth order binomial filter, but many other filters are available, see pyrtools.pyramids.filters.named_filter for a list.

>>> named_filters = [
...     "binom2",
...     "binom3",
...     "binom4",
...     "haar",
...     "qmf8",
...     "daub2",
...     "qmf5",
... ]
>>> upsampled_filter = [
...     po.process.upsample_blur(img, n_scales=2, odd=[0, 0], filtname=filt)
...     for filt in named_filters
... ]
>>> po.plot.imshow(
...     [img] + upsampled_filter,
...     title=["image"] + named_filters,
...     col_wrap=4,
...     vrange=(0, 1),
... )
<PyrFigure...>

(png, hires.png, pdf)

Note that this operation can change the minimum and maximum, and different filters can do so differently:

>>> img.min()
tensor(0.0039)
>>> img.max()
tensor(1.)
>>> for filter_name, upsampled in zip(named_filters, upsampled_filter):
...     print(
...         f"filter: {filter_name}, "
...         f"min={upsampled.min():.2f}, "
...         f"max={upsampled.max():.2f}"
...     )
filter: binom2, min=0.00, max=1.00
filter: binom3, min=0.00, max=1.00
filter: binom4, min=0.02, max=0.94
filter: haar, min=0.00, max=1.00
filter: qmf8, min=-0.07, max=1.07
filter: daub2, min=-0.24, max=1.24
filter: qmf5, min=-0.26, max=1.29