torchlib.misc package

Submodules

torchlib.misc.draw_shapes module

torchlib.misc.draw_shapes.draw_eclipse(x, centroids, aradii, bradii, edgecolors=[255, 0, 0], linewidths=1, fillcolors=None, axes=(- 2, - 1))
torchlib.misc.draw_shapes.draw_rectangle(x, rects, edgecolors=[[255, 0, 0]], linewidths=[1], fillcolors=[None], axes=(- 3, - 2))

Draw rectangles in a tensor

Parameters

  • x (Tensor) – The input with any size.

  • rects (list or tuple) – The coordinates of the rectangles [[lefttop, rightbottom]].

  • edgecolors (list, optional) – The color of edge.

  • linewidths (int, optional) – The linewidths of edge.

  • fillcolors (int, optional) – The color for filling.

  • axes (int, optional) – The axes for drawing the rect (default [(-3, -2)]).

torchlib.misc.mapping_operation module

torchlib.misc.mapping_operation.mapping(X, drange=(0.0, 255.0), mode='amplitude', method='2Sigma', odtype='auto')

convert to image

Convert data to image data \(\bm X\) with dynamic range \(d=[min, max]\).

Parameters

  • X (tensor) – data to be converted

  • drange (tuple, optional) – dynamic range (the default is (0., 255.))

  • mode (str, optional) – data mode in X, 'amplitude' (default) or 'power'.

  • method (str, optional) – converting method, surpported values are '1Sigma', '2Sigma', '3Sigma' (the default is ‘2Sigma’, which means two-sigma mapping)

  • odtype (str or None, optional) – output data type, supportted are 'auto' (auto infer, default), or torch tensor’s dtype string. If the type of odtype is not string, the output data type is 'th.float32'.

Returns

Y – converted image data

Return type

tensor

torchlib.misc.noising module

torchlib.misc.noising.awgn(sig, snr=30, peak=1, pmode='db', measMode='measured')

AWGN Add white Gaussian noise to a signal.

Y = AWGN(X,snr) adds white Gaussian noise to X. The snr is in dB. The power of X is assumed to be 0 dBW. If X is complex, then AWGN adds complex noise.

Parameters

  • sig (tensor) – Signal that will be noised.

  • snr (float, optional) – Signal Noise Ratio (the default is 30)

  • peak (float, optional) – Peak value (the default is 1)

  • pmode (str, optional) – Power mode 'linear', 'db' (the default is ‘db’)

  • measMode (str, optional) – the method for computing power (the default is ‘measured’, which sigPower = th.sum(th.abs(sig) ** 2) / sig.numel())

Returns

noised data

Return type

tensor

Raises
torchlib.misc.noising.imnoise(img, noise='wgn', snr=30, peak=None, fmt='chnllast')

Add noise to image

Add noise to image

Parameters

  • img (tensor) – image aray

  • noise (str, optional) – noise type (the default is ‘wgn’, which [default_description])

  • snr (float, optional) – Signal-to-noise ratio (the default is 30, which [default_description])

  • peak (None, str or float) – Peak value in input, if None, auto detected (default), if 'maxv', use the maximum value as peak value.

  • fmt (str or None, optional) – for color image, fmt should be specified with 'chnllast' or 'chnlfirst', for gray image, fmt should be setted to None.

Returns

Images with added noise.

Return type

tensor

torchlib.misc.noising.matnoise(mat, noise='awgn', snr=30, peak='maxv')

add noise to an matrix

Add noise to an matrix (real or complex)

Parameters

mat (tensor) – can be real or complex valued

Keyword Arguments

  • noise (str) – type of noise (default: 'awgn')

  • snr (float) – Signal-to-noise ratio (default: 30)

  • peak (None or float) – Peak value in input, for complex data, peak=[peakr, peaki], if None, auto detected, if 'maxv', use the maximum value as peak value. (default)

torchlib.misc.noising.wgn(shape, p, peak=1, pmode='dbw', dtype='real', seed=None)

WGN Generate white Gaussian noise.

Y = WGN((M,N),P) generates an M-by-N matrix of white Gaussian noise. P specifies the power of the output noise in dBW. The unit of measure for the output of the wgn function is Volts. For power calculations, it is assumed that there is a load of 1 Ohm.

Parameters

  • shape (tuple) – Shape of noising matrix

  • p (float) – P specifies the power of the output noise in dBW.

  • peak (float, optional) – Peak value (the default is 1)

  • pmode (str, optional) – Power mode of the output noise (the default is ‘dbw’)

  • dtype (str, optional) – data type, real or complex (the default is ‘real’, which means real-valued)

  • seed (int, optional) – Seed for random number generator. (the default is None, which means different each time)

Returns

Matrix of white Gaussian noise (real or complex).

Return type

tensor

torchlib.misc.sampling module

torchlib.misc.sampling.dnsampling(x, ratio=1.0, axis=- 1, smode='uniform', omode='discard', seed=None, extra=False)

Summary

Parameters

  • x (Tensor) – The Input tensor.

  • ratio (float, optional) – Downsampling ratio.

  • axis (int, optional) – Downsampling axis (default -1).

  • smode (str, optional) – Downsampling mode: 'uniform', 'random', 'random2'.

  • omode (str, optional) – output mode: 'discard' for discarding, 'zero' for zero filling.

  • seed (int or None, optional) – seed for torch’s random.

  • extra (bool, optional) – If True, also return sampling mask.

Returns

Description

Return type

(Tensor)

Raises
torchlib.misc.sampling.patch2tensor(p, size=(256, 256), axis=(1, 2), mode='nfirst')

merge patch to a tensor

Parameters

  • p (Tensor) – A tensor of patches.

  • size (tuple, optional) – Merged tensor size in the dimension (the default is (256, 256)).

  • axis (tuple, optional) – Merged axis of patch (the default is (1, 2))

  • mode (str, optional) – Patch mode 'nfirst' or 'nlast' (the default is ‘nfirst’, which means the first dimension is the number of patches)

Returns

Merged tensor.

Return type

Tensor

torchlib.misc.sampling.read_samples(datafiles, keys=[['SI', 'ca', 'cr']], nsamples=[10], groups=[1], mode='sequentially', axis=0, parts=None, seed=None)

Read samples

Parameters

  • datafiles (list) – list of path strings

  • keys (list, optional) – data keys to be read

  • nsamples (list, optional) – number of samples for each data file

  • groups (list, optional) – number of groups in each data file

  • mode (str, optional) – sampling mode for all datafiles

  • axis (int, optional) – sampling axis for all datafiles

  • parts (None, optional) – number of parts (split samples into some parts)

  • seed (None, optional) – the seed for random stream

Returns

samples

Return type

tensor

Raises

ValueError – nsamples should be large enough

torchlib.misc.sampling.sample_tensor(x, n, axis=0, groups=1, mode='sequentially', seed=None, extra=False)

sample a tensor

Sample a tensor sequentially/uniformly/randomly.

Parameters

  • x (torch.Tensor) – a torch tensor to be sampled

  • n (int) – sample number

  • axis (int, optional) – the axis to be sampled (the default is 0)

  • groups (int, optional) – number of groups in this tensor (the default is 1)

  • mode (str, optional) –

    • 'sequentially': evenly spaced (default)

    • 'uniformly': [0, int(n/groups)]

    • 'randomly': randomly selected, non-returned sampling

  • seed (None or int, optional) – only work for 'randomly' mode (the default is None)

  • extra (bool, optional) – If True, also return the selected indexes, the default is False.

Returns

Sampled torch tensor. idx (list): Sampled indexes, if extra is True, this will also be returned.

Return type

y (torch.Tensor)

Example

setseed(2020, 'torch')

x = th.randint(1000, (20, 3, 4))
y1, idx1 = sample_tensor(x, 10, axis=0, groups=2, mode='sequentially', extra=True)
y2, idx2 = sample_tensor(x, 10, axis=0, groups=2, mode='uniformly', extra=True)
y3, idx3 = sample_tensor(x, 10, axis=0, groups=2, mode='randomly', extra=True)

print(x.shape)
print(y1.shape)
print(y2.shape)
print(y3.shape)
print(idx1)
print(idx2)
print(idx3)

the outputs are as follows:

torch.Size([20, 3, 4])
torch.Size([10, 3, 4])
torch.Size([10, 3, 4])
torch.Size([10, 3, 4])
[0, 1, 2, 3, 4, 10, 11, 12, 13, 14]
[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
[3, 1, 5, 8, 7, 17, 18, 13, 16, 10]
Raises

ValueError – The tensor does not has enough samples.

torchlib.misc.sampling.shuffle_tensor(x, axis=0, groups=1, mode='inter', seed=None, extra=False)

shuffle a tensor

Shuffle a tensor randomly.

Parameters

  • x (Tensor) – A torch tensor to be shuffled.

  • axis (int, optional) – The axis to be shuffled (default 0)

  • groups (number, optional) – The number of groups in this tensor (default 1)

  • mode (str, optional) –

    • 'inter': between groups (default)

    • 'intra': within group

    • 'whole': the whole

  • seed (None or number, optional) – random seed (the default is None)

  • extra (bool, optional) – If True, also returns the shuffle indexes, the default is False.

Returns

Shuffled torch tensor. idx (list): Shuffled indexes, if extra is True, this will also be returned.

Return type

y (Tensor)

Example

setseed(2020, 'torch')

x = th.randint(1000, (20, 3, 4))
y1, idx1 = shuffle_tensor(x, axis=0, groups=4, mode='intra', extra=True)
y2, idx2 = shuffle_tensor(x, axis=0, groups=4, mode='inter', extra=True)
y3, idx3 = shuffle_tensor(x, axis=0, groups=4, mode='whole', extra=True)

print(x.shape)
print(y1.shape)
print(y2.shape)
print(y3.shape)
print(idx1)
print(idx2)
print(idx3)

the outputs are as follows:

torch.Size([20, 3, 4])
torch.Size([20, 3, 4])
torch.Size([20, 3, 4])
torch.Size([20, 3, 4])
[1, 0, 3, 4, 2, 8, 6, 5, 9, 7, 13, 11, 12, 14, 10, 18, 15, 17, 16, 19]
[0, 1, 2, 3, 4, 10, 11, 12, 13, 14, 5, 6, 7, 8, 9, 15, 16, 17, 18, 19]
[1, 13, 12, 5, 19, 9, 11, 6, 4, 16, 17, 3, 8, 18, 7, 10, 15, 0, 14, 2]
torchlib.misc.sampling.slidegrid(start, stop, step, shake=0, n=None)

generates sliding grid indexes

Generates n sliding grid indexes from start to stop with step size step.

Parameters

  • start (int or list) – start sampling point

  • stop (int or list) – stop sampling point

  • step (int or list) – sampling stepsize

  • shake (float) – the shake rate, if shake is 0, no shake, (default), if positive, add a positive shake, if negative, add a negative.

  • n (int or None) – the number of samples (default None, int((stop0 - start0) / step0) * int((stop1 - start1) / step1)…).

Returns

for multi-dimension, return a 2-d tensor, for 1-dimension, return a 1d-tensor.

Raises

TypeError – The number of samples should be an integer or None.

see randperm(), randgrid().

torchlib.misc.sampling.split_tensor(x, ratios=[0.7, 0.2, 0.1], axis=0, shuffle=False, seed=None, extra=False)

split tensor

split a tensor into some parts.

Parameters

  • x (Tensor) – A torch tensor.

  • ratios (list, optional) – Split ratios (the default is [0.7, 0.2, 0.05])

  • axis (int, optional) – Split axis (the default is 0)

  • shuffle (bool, optional) – Whether shuffle (the default is False)

  • seed (int, optional) – Shuffule seed (the default is None)

  • extra (bool, optional) – If True, also return the split indexes, the default is False.

Returns

Splitted tensors.

Return type

(list of Tensor)

torchlib.misc.sampling.tensor2patch(x, n=None, size=(256, 256), axis=(0, 1), start=(0, 0), stop=(None, None), step=(1, 1), shake=(0, 0), mode='slidegrid', seed=None)

sample patch from a tensor

Sample some patches from a tensor, tensor and patch can be any size.

Parameters

  • x (Tensor) – Tensor to be sampled.

  • n (int, optional) – The number of pactches, the default is None, auto computed, equals to the number of blocks with specified step

  • size (tuple or int, optional) – The size of patch (the default is (256, 256))

  • axis (tuple or int, optional) – The sampling axis (the default is (0, 1))

  • start (tuple or int, optional) – Start sampling index for each axis (the default is (0, 0))

  • stop (tuple or int, optional) – Stopp sampling index for each axis. (the default is (None, None), which [default_description])

  • step (tuple or int, optional) – Sampling stepsize for each axis (the default is (1, 1), which [default_description])

  • shake (tuple or int or float, optional) – float for shake rate, int for shake points (the default is (0, 0), which means no shake)

  • mode (str, optional) – Sampling mode, 'slidegrid', 'randgrid', 'randperm' (the default is ‘slidegrid’)

  • seed (int, optional) – Random seed. (the default is None, which means no seed.)

Returns

A Tensor of sampled patches.

Return type

(Tensor)

torchlib.misc.transform module

torchlib.misc.transform.ct2rt(x, axis=0)

Converts a complex-valued tensor to a real-valued tensor

Converts a complex-valued tensor \({\bf x}\) to a real-valued tensor with FFT and conjugate symmetry.

Parameters

  • x (Tensor) – The input tensor \({\bf x}\in {\mathbb C}^{H×W}\).

  • axis (int) – The axis for excuting FFT.

Returns

The output tensor \({\bf y}\in {\mathbb R}^{2H×W}\) ( axis = 0 ), \({\bf y}\in {\mathbb R}^{H×2W}\) ( axis = 1 )

Return type

Tensor

torchlib.misc.transform.db20(x)

Computes dB value of a tensor

Parameters

x (Tensor) – The input tensor.

Returns

The output tensor (dB)

Return type

Tensor

torchlib.misc.transform.quantization(X, idrange=None, odrange=[0, 31], odtype='auto', extra=False)

Quantize data.

\[x \in [a, b] \rightarrow y \in [c, d] \]
\[y = (d-c)(x-a) / (b-a) + c. \]
Parameters

  • X (tensor) – The data to be quantized with shape \(N_a×N_r ∈ {\mathbb R}\), or \(N_a×N_r ∈ {\mathbb C}\).

  • idrange (tuple, list, optional) – Specifies the range of data. Default [min(X), max(X)].

  • odrange (tuple, list, optional) – Specifies the range of data after beening quantized. Default [0, 31].

  • odtype (str, None, optional) – output data type, supportted are 'auto' (auto infer, default), or torch tensor’s dtype string. If the type of odtype is not string(such as None), the type of output data is the same with input.

  • extra (bool) – If True, also return st and idrange.

Returns

  • out (tensor) – Quantized data tensor, if the input is complex, will return a tensor with shape \(N_a×N_r×2 ∈ {\mathbb R}\).

  • idrange, odrange (list or tuple) – If extra is true, also be returned

torchlib.misc.transform.rt2ct(y, axis=0)

Converts a real-valued tensor to a complex-valued tensor

Converts a real-valued tensor \({\bf y}\) to a complex-valued tensor with FFT and conjugate symmetry.

Parameters

  • y (Tensor) – The input tensor \({\bf y}\in {\mathbb C}^{2H×W}\).

  • axis (int) – The axis for excuting FFT.

Returns

The output tensor \({\bf x}\in {\mathbb R}^{H×W}\) ( axis = 0 ), \({\bf x}\in {\mathbb R}^{H×W}\) ( axis = 1 )

Return type

Tensor

torchlib.misc.transform.scale(X, st=[0, 1], sf=None, istrunc=True, extra=False)

Scale data.

\[x \in [a, b] \rightarrow y \in [c, d] \]
\[y = (d-c)(x-a) / (b-a) + c. \]
Parameters

  • X (tensor_like) – The data to be scaled.

  • st (tuple, list, optional) – Specifies the range of data after beening scaled. Default [0, 1].

  • sf (tuple, list, optional) – Specifies the range of data. Default [min(X), max(X)].

  • istrunc (bool) – Specifies wether to truncate the data to [a, b], For example, If sf == [a, b] and ‘istrunc’ is true, then X[X < a] == a and X[X > b] == b.

  • extra (bool) – If True, also return st and sf.

Returns

  • out (tensor) – Scaled data tensor.

  • st, sf (list or tuple) – If extra is true, also be returned

torchlib.misc.transform.standardization(X, mean=None, std=None, axis=None, extra=False)
\[\bar{X} = \frac{X-\mu}{\sigma} \]
Parameters

  • X (tensor) – data to be normalized,

  • mean (list or None, optional) – mean value (the default is None, which means auto computed)

  • std (list or None, optional) – standard deviation (the default is None, which means auto computed)

  • axis (list or int, optional) – specify the axis for computing mean and standard deviation (the default is None, which means all elements)

  • extra (bool, optional) – if True, also return the mean and std (the default is False, which means just return the standardized data)

Module contents