Utilities

Utility functions.

torchray.utils.get_config()

Read the TorchRay config file.

Read the config file from the current directory or the user’s home directory and return the configuration.

Returns

configuration.

Return type

dict

torchray.utils.get_device(gpu=0)

Get the :class`torch.device` to use; specify device with gpu.

Parameters

gpu (int, optional) – Index of the GPU device; specify None to force CPU. Default: 0.

Returns

device to use.

Return type

torch.device

torchray.utils.im_to_numpy(tensor)

Convert a tensor image to a NumPy image.

The function converts the \(K\times H\times W\) tensor tensor to a corresponding \(H\times W\times K\) NumPy array.

Parameters

tensor (torch.Tensor) – input tensor.

Returns

NumPy array.

Return type

numpy.ndarray

torchray.utils.imarraysc(tiles, spacing=0, quiet=False, lim=None, interpolation='lanczos')

Display or arrange an image or tensor batch as a mosaic.

The function displays the tensor tiles as a set of tiles. tiles has shape \(K\times C\times H\times W\) and the generated mosaic is a new tensor with shape \(C\times (MH) \times (NW)\) where \(MN \geq K\).

Missing tiles are filled with zeros.

The range of each tile is individually scaled to the range [0, 1].

Parameters

• tiles (torch.Tensor) – tensor to display or rearrange.

• spacing (int, optional) – thickness of the border (infilled with zeros) around each tile. Default: 0.

• quiet (bool, optional) – If False, do not display the mosaic. Default: False.

• lim (list, optional) – maximum and minimum intensity value for rescaling. Default: None.

• interpolation (str, optional) – interpolation to use with matplotlib.pyplot.imshow(). Default: 'lanczos'.

Returns

torch.Tensor: The rearranged tensor.

Return type

class

torchray.utils.imread(file, as_pil=False, resize=None, to_rgb=False)

Read an image as a tensor.

The function reads the image file as a PyTorch tensor. file can also be an URL.

To reshape the image use the option reshape, passing the desired shape (W, H) as tuple. Passing an integer sets the shortest side to that length while preserving the aspect ratio.

Parameters

• file (str) – Path or ULR to the image.

• resize (float, int, tuple or list) – Resize the image to this size.

• as_pil (bool) – If True, returns the PIL image instead of converting to a tensor.

• to_rgb (optional, bool) – If True, convert the PIL image to RGB. Default: False.

Returns

The image read as a \(3\times H\times W\) tensor in the [0, 1] range.

Return type

torch.Tensor

torchray.utils.imsc(img, *args, quiet=False, lim=None, interpolation='lanczos', **kwargs)

Rescale and displays an image represented as a img.

The function scales the img im to the [0 ,1] range. The img is assumed to have shape \(3\times H\times W\) (RGB) \(1\times H\times W\) (grayscale).

Parameters

• img (torch.Tensor or PIL.Image) – image.

• quiet (bool, optional) – if False, do not display image. Default: False.

• lim (list, optional) – maximum and minimum intensity value for rescaling. Default: None.

• interpolation (str, optional) – The interpolation mode to use with matplotlib.pyplot.imshow() (e.g. 'lanczos' or 'nearest'). Default: 'lanczos'.

Returns

Rescaled image img.

Return type

torch.Tensor

torchray.utils.imsmooth(tensor, sigma, stride=1, padding=0, padding_mode='constant', padding_value=0)

Apply a 2D Gaussian filter to a tensor.

The 2D filter itself is implementing by separating the 2D convolution in two 1D convolutions, first along the vertical direction and then along the horizontal one. Each 1D Gaussian kernel is given by:

\[f_i \propto \exp\left(-\frac{1}{2} \frac{i^2}{\sigma^2} \right), ~~~ i \in \{-W,\dots,W\}, ~~~ W = \lceil 4\sigma \rceil.\]

This kernel is normalized to sum to one exactly. Given the latter, the function calls torch.nn.functional.conv2d to perform the actual convolution. Various padding parameters and the stride are passed to the latter.

Parameters

• tensor (torch.Tensor) – \(N\times C\times H\times W\) image tensor.

• sigma (float) – standard deviation of the Gaussian kernel.

• stride (int, optional) – subsampling factor. Default: 1.

• padding (int, optional) – extra padding. Default: 0.

• padding_mode (str, optional) – 'constant', 'reflect' or 'replicate'. Default: 'constant'.

• padding_value (float, optional) – constant value for the constant padding mode. Default: 0.

Returns

\(N\times C\times H\times W\) tensor with the smoothed images.

Return type

torch.Tensor

torchray.utils.is_url(obj)

Check if an object is an URL.

Parameters

obj (object) – object to test.

Returns

True if x is an URL string; otherwise False.

Return type

bool

torchray.utils.pil_to_tensor(pil_image)

Convert a PIL image to a tensor.

Parameters

pil_image (PIL.Image) – PIL image.

Returns

the image as a \(3\times H\times W\) tensor in the [0, 1] range.

Return type

torch.Tensor

torchray.utils.resample(source, target_size, transform)

Spatially resample a tensor.

The function resamples the source tensor generating a target tensors of size target_size. Resampling uses the transform transform, specified as a \(2\times 2\) matrix in the form

\[\begin{split}\begin{bmatrix} s_u & t_u\\ s_v & t_v \end{bmatrix}\end{split}\]

where \(s_u\) is the scaling factor along the horizontal spatial direction, \(t_u\) the horizontal offset, and \(s_v, t_v\) the corresponding quantity for the vertical direction.

Internally, the function uses torch.nn.functional.grid_sample() with bilinear interpolation and zero padding.

The transformation defines the forward mapping, so that a pixel \((u,v)\) in the source tensro is mapped to pixel \(u' = s_u u + t_u, v' = s_v v + tv\).

The reference frames are defined as follows. Pixels are unit squares, so that a \(H\times W\) tensor maps to the rectangle \([0, W) \times [0, H)\). Hence element \(x_{ncij}\) of a tensor \(x\) maps to a unit square whose center is \((u,v) = (i + 1/2, j+1/2)\).

Example

In order to stretch an \(H \times W\) source tensor to a target \(H' \times W'\) tensor, one would use the transformation matrix

\[\begin{split}\begin{bmatrix} W'/W & 0\\ H'/H & 0\\ \end{bmatrix}\end{split}\]

Parameters

• source (torch.Tensor) – \(N\times C\times H\times W\) tensor.

• target_size (tuple of int) – target size.

• transform (torch.Tensor) – \(2\times 2\) transformation tensor.

Returns

resampled tensor.

Return type

torch.Tensor

torchray.utils.tensor_to_im(tensor)

Reshape a tensor as a grayscale image stack.

The function reshapes the tensor x of size \(N\times K\times H\times W\) to have shape \((NK)\times 1\times H\times W\).

Parameters

tensor (torch.Tensor) – tensor to rearrange.

Returns

Reshaped tensor.

Return type

torch.Tensor

torchray.utils.xmkdir(path)

Create a directory path recursively.

The function creates path if the directory does not exist.

Args::

path (str): path to create.