toupy.utils package

Submodules

toupy.utils.FFT_utils module

toupy.utils.FFT_utils.fastfftn(input_array, **kwargs)[source]

Auxiliary function to use pyFFTW. It does the align, planning and apply FFTW transform

Parameters:

input_array (array_like) – Array to be FFT-transformed via pyFFTW.

Returns:

fftw_array – Fourier transformed array

Return type:

array_like

toupy.utils.FFT_utils.fastifftn(input_array, **kwargs)[source]

Auxiliary function to use pyFFTW. It does the align, planning and apply inverse FFTW transform

Parameters:

input_array (array_like) – Array to be FFT-transformed via pyFFTW.

Returns:

ifftw_array – Inverse Fourier transformed array

Return type:

array_like

toupy.utils.FFT_utils.is_power2(num)[source]

Check whether a number is a power of two.

Parameters:

num (int) – Integer to test.

Returns:

True if num is a non-zero power of two, False otherwise.

Return type:

bool

toupy.utils.FFT_utils.nextpow2(number)[source]

Find the next power of two at or above number for use with FFTs.

Parameters:

number (int or float) – Input value.

Returns:

Smallest power of two n such that n >= number.

Return type:

int

toupy.utils.FFT_utils.nextpoweroftwo(number)[source]

Return the exponent of the next power of two at or above number.

Parameters:

number (int or float) – Input value.

Returns:

Smallest integer k such that 2**k >= number.

Return type:

int

toupy.utils.FFT_utils.padfft(input_array, pad_mode='reflect')[source]

Auxiliary function to pad arrays for Fourier transforms. It accepts 1D and 2D arrays.

Parameters:

  • input_array (array_like) – Array to be padded

  • mode (str) – Padding mode to treat the array borders. See numpy.pad for modes. The default value is reflect.

Returns:

  • array_pad (array_like) – Padded array

  • N_pad (array_like) – padded frequency coordinates

  • padw (int, list of ints) – pad width

toupy.utils.FFT_utils.padrightside(nbins)[source]

Compute the right-side padding width needed to reach the next FFT-fast length.

Uses pyfftw.next_fast_len() to find the smallest length that is efficient for pyFFTW, which may be any highly composite number (not necessarily a power of two).

Parameters:

nbins (int) – Current array length.

Returns:

Number of zeros to append on the right so that the total length is FFT-efficient.

Return type:

int

toupy.utils.FFT_utils.padwidthbothsides(nbins)[source]

Compute the per-side padding width needed to reach the next power of two.

Parameters:

nbins (int) – Current array length.

Returns:

Number of zeros to add on each side so that the total length is a power of two.

Return type:

int

toupy.utils.array_utils module

toupy.utils.array_utils.create_circle(inputimg)[source]

Create circle with apodized edges

Parameters:

inputimg (array_like) – Input image from which to calculate the circle

Returns:

t – Array containing the circular mask with apodized edges.

Return type:

ndarray

toupy.utils.array_utils.create_mask_borders(tomogram, mask_array, threshold=4e-07)[source]

Create mask for border of tomographic volume

Parameters:

  • tomogram (array_like) – Input volume

  • mask (bool array_like) – Input mask

  • threshold (float, optional) – Threshold value. The default value is 4e-7.

Returns:

mask_array – Masked array

Return type:

array_like

toupy.utils.array_utils.crop(input_array, delcropx, delcropy)[source]

Crop images

Parameters:

  • input_array (array_like) – Input image to be cropped

  • delcropx (int) – amount of pixel to be cropped in x

  • delcropy (int) – amount of pixel to be cropped in y

Returns:

Cropped image

Return type:

array_like

toupy.utils.array_utils.cropROI(input_array, roi=[])[source]

Crop ROI

Parameters:

  • input_array (array_like) – Input image to be cropped

  • roi (list of int) – ROI of interest. roi should be [top, bottom, left, right]

Returns:

Cropped image

Return type:

array_like

toupy.utils.array_utils.fract_hanning(outputdim, unmodsize)[source]

Creates a square hanning window if unmodsize = 0 (or ommited), otherwise the output array will contain an array of ones in the center and cosine modulation on the edges, the array of ones will have DC in upper left corner.

Parameters:

  • outputdim (int) – Size of the output array

  • unmodsize (int) – Size of the central array containing no modulation.

Returns:

Square array containing a fractional separable Hanning window with DC in upper left corner.

Return type:

array_like

toupy.utils.array_utils.fract_hanning_pad(outputdim, filterdim, unmodsize)[source]

Creates a square hanning window if unmodsize = 0 (or ommited), otherwise the output array will contain an array of ones in the center and cosine modulation on the edges, the array of ones will have DC in upper left corner.

Parameters:

  • outputdim (int) – Size of the output array

  • filterdim (int) – Size of filter (it will zero pad if filterdim < outputdim)

  • unmodsize (int) – Size of the central array containing no modulation.

Returns:

Square array containing a fractional separable Hanning window with DC in upper left corner.

Return type:

array_like

toupy.utils.array_utils.gauss_kern(size, sizey=None)[source]

Return a normalized 2-D Gaussian kernel array for convolutions.

Parameters:

  • size (int) – Half-width of the kernel along columns (the full extent is 2*size + 1 pixels).

  • sizey (int, optional) – Half-width along rows. If None, defaults to size (square kernel).

Returns:

Normalized 2-D Gaussian kernel of shape (2*sizey+1, 2*size+1).

Return type:

ndarray

Notes

Adapted from http://scipy.org/Cookbook/SignalSmooth

toupy.utils.array_utils.hanning_apod1D(window_size, apod_width)[source]

Create 1D apodization window using Hanning window

Parameters:

  • window_size (int) – Window size

  • apod_width (int) – Apodization width

Returns:

hannwindow1D – 1D Hanning window for the apodization

Return type:

array_like

toupy.utils.array_utils.hanning_apodization(window_size, apod_width)[source]

Create apodization window using Hanning window

Parameters:

  • window_size (tuple) – Window size

  • apod_width (int) – Apodization width

Returns:

hannwindow2D – 2D Hanning window for the apodization

Return type:

array_like

toupy.utils.array_utils.mask_borders(imgarray, mask_array, threshold=4e-07)[source]

Mask borders using the gradient

Parameters:

  • imgarray (array_like) – Input image

  • mask_array (bool array_like) – Input mask

  • threshold (float, optional) – Threshold value. The default value is 4e-7.

Returns:

mask_array – Masked array

Return type:

array_like

toupy.utils.array_utils.normalize_array(input_array)[source]

Normalize an array to the range [0, 1].

Parameters:

input_array (array_like) – Input array to normalize.

Returns:

Array with values scaled linearly to [0, 1].

Return type:

ndarray

toupy.utils.array_utils.padarray_bothsides(input_array, newshape, padmode='edge')[source]

Pad array in both sides

Parameters:

  • input_array (array_like) – Input array

  • newshape (tuple) – New shape of the array to be padded

  • padmode (str) – Padding mode. The default is edge

Returns:

Padded array

Return type:

array_like

toupy.utils.array_utils.polynomial1d(x, order=1, w=1)[source]

Generates a 1D orthonormal polynomial base.

Parameters:

  • x (array_like) – Array containing the values of x for the polynomial

  • order (int, optional) – Order of the polynomial. The defaul value is 1.

  • w (int, optional) – Weights of the coefficients. The defaul value is 1.

Returns:

polyseries – Orthonormal polymonial up to order

Return type:

array_like

Notes

Inspired by legendrepoly1D_2.m created by Manuel Guizar in March 10,2009

toupy.utils.array_utils.projectpoly1d(func1d, order=1, w=1)[source]

Projects a 1D function onto orthonormalized base

Parameters:

  • func1d (array_like) – Array containing the values of the 1D function

  • order (int, optional) – Order of the polynomial. The defaul value is 1.

  • w (int, optional) – Weights of the coefficients. The defaul value is 1.

Returns:

projfunc1d – Projected 1D funtion on orthonormal base

Return type:

array_like

Note

Inspired by projectleg1D_2.m created by Manuel Guizar in March 10,2009

toupy.utils.array_utils.radtap(X, Y, tappix, zerorad)[source]

Create a central cosine tapering mask for beam apodization.

The mask is zero inside the radius zerorad, rises with a cosine taper over tappix pixels, and is unity beyond zerorad + tappix.

Parameters:

  • X (ndarray) – 2-D array of horizontal coordinate values (e.g. from numpy.meshgrid()).

  • Y (ndarray) – 2-D array of vertical coordinate values.

  • tappix (int or float) – Extent of the cosine taper in pixels.

  • zerorad (int or float) – Radius (in pixels) inside which the mask is zero.

Returns:

taperfunc – 2-D apodization mask with the same shape as X and Y, values in [0, 1].

Return type:

ndarray

toupy.utils.array_utils.replace_bad(input_stack, list_bad=[], temporary=False)[source]

correcting bad projections before unwrapping

Parameters:

  • input_stack (array_like) – Stack of projections

  • list_bad (list) – List of bad projections

  • temporary (bool) – If False, the projection will be interpolated with the previous and after projections. If True, the projection will be replaced by the previous projection.

toupy.utils.array_utils.round_to_even(x)[source]

Round a number down to the nearest even integer.

Parameters:

x (float or int) – Input value.

Returns:

Largest even integer less than or equal to x.

Return type:

int

toupy.utils.array_utils.sharpening_image(input_image, filter_size=3, alpha=30)[source]

Sharpen image with a median filter

Parameters:

  • input_image (array_like) – Image to be sharpened

  • filter_size (int) – Size of the filter

  • alpha (float) – Strength of the sharpening

Returns:

Sharpened image

Return type:

array_like

toupy.utils.array_utils.smooth1d(x, window_len=11, window='hanning')[source]

Smooth the data using a window with requested size.

This method is based on the convolution of a scaled window with the signal. The signal is prepared by introducing reflected copies of the signal (with the window size) in both ends so that transient parts are minimized in the begining and end part of the output signal.

Parameters:

  • x (array_like) – The input signal

  • window_len (int, optional,) – The dimension of the smoothing window; should be an odd integer. The default value is 11.

  • window (str, optional) – The type of window from flat, hanning, hamming, bartlett, blackman flat window will produce a moving average smoothing.

Returns:

y – The smoothed signal

Return type:

array_like

Examples

>>> import numpy as np
>>> t=np.linspace(-2,2,0.1)
>>> x=np.sin(t)+np.random.randn(len(t))*0.1
>>> y=smooth(x)

Notes

See also: numpy.hanning(), numpy.hamming(), numpy.bartlett(), numpy.blackman(), numpy.convolve(), scipy.signal.lfilter().

Adapted from https://scipy-cookbook.readthedocs.io/items/SignalSmooth.html

toupy.utils.array_utils.smooth2d(im, n, ny=None)[source]

Blur an image by convolving with a Gaussian kernel.

Parameters:

  • im (array_like) – Input image.

  • n (int) – Half-width of the Gaussian kernel along the horizontal axis.

  • ny (int, optional) – Half-width along the vertical axis. Defaults to n (square kernel).

Returns:

improc – Smoothed image.

Return type:

ndarray

Notes

Adapted from http://scipy.org/Cookbook/SignalSmooth

toupy.utils.array_utils.smooth_image(input_image, filter_size=3)[source]

Smooth image with a median filter

Parameters:

  • input_image (array_like) – Image to be smoothed

  • filter_size (int) – Size of the filter

Returns:

Smoothed image

Return type:

array_like

toupy.utils.array_utils.sort_array(input_array, ref_array)[source]

Sort array based on another array

Parameters:

  • input_array (array_like) – Array to be sorted

  • ref_array (array_like) – Array on which the sorting will be based

Returns:

  • sorted_input_array (array_like) – Sorted input array

  • sorted_ref_array (array_like) – Sorted reference array

toupy.utils.converter_utils module

toupy.utils.converter_utils.convert_to_beta(input_img, energy, voxelsize, apply_log=False)[source]

Convert image gray-levels from amplitude (or log-amplitude) to absorption index beta.

Parameters:

  • input_img (ndarray) – Image with gray-levels proportional to transmitted amplitude.

  • energy (float) – X-ray photon energy in keV.

  • voxelsize (float, list of float, or ndarray) – Voxel size in metres.

  • apply_log (bool, optional) – If True, apply the natural logarithm to input_img before the conversion (for images that have not yet been log-transformed). Default False.

Returns:

  • beta_img (ndarray) – Image with gray-levels in units of absorption index beta.

  • factor (float) – Conversion factor applied.

toupy.utils.converter_utils.convert_to_delta(input_img, energy, voxelsize)[source]

Convert image gray-levels from phase-shifts to refractive index decrement delta.

Parameters:

  • input_img (ndarray) – Image with gray-levels proportional to accumulated phase shift.

  • energy (float) – X-ray photon energy in keV.

  • voxelsize (float, list of float, or ndarray) – Voxel size in metres.

Returns:

  • delta_img (ndarray) – Image with gray-levels in units of delta.

  • factor (float) – Conversion factor applied.

toupy.utils.converter_utils.convert_to_mu(input_img, wavelen)[source]

Convert image gray-levels from absorption index Beta to linear attenuation coefficient mu.

Parameters:

  • input_img (ndarray) – Image with gray-levels proportional to the absorption index Beta.

  • wavelen (float) – X-ray wavelength in metres.

Returns:

Image with gray-levels in units of linear attenuation coefficient mu (m-1).

Return type:

ndarray

toupy.utils.converter_utils.convert_to_rhoe(input_img, wavelen)[source]

Convert image gray-levels from refractive index decrement delta to electron density.

Parameters:

  • input_img (ndarray) – Image with gray-levels proportional to delta.

  • wavelen (float) – X-ray wavelength in metres.

Returns:

Image with gray-levels in units of electron density (electrons m-3).

Return type:

ndarray

toupy.utils.converter_utils.convert_to_rhom(input_img, wavelen, A, Z)[source]

Convert image gray-levels from electron density to mass density.

Parameters:

  • input_img (ndarray) – Image with gray-levels proportional to electron density.

  • wavelen (float) – X-ray wavelength in metres.

  • A (float) – Atomic mass number of the material.

  • Z (float) – Atomic number of the material.

Returns:

Image with gray-levels in units of mass density (g cm-3).

Return type:

ndarray

toupy.utils.fit_utils module

toupy.utils.fit_utils.model_erf(t, *coeffs)[source]

Model for the erf fitting

P0 + P1*t + (P2/2)*(1-erf(sqrt(2)*(x-P3)/(P4)))

Parameters:

  • t (ndarray) – Input coordinates

  • coeffs[0] (float) – P0 (noise)

  • coeffs[1] (float) – P1 (linear term)

  • coeffs[2] (float) – P2 (Maximum amplitude)

  • coeffs[3] (float) – P3 (center)

  • coeffs[4] (float) – P4 (width)

Returns:

Array containing the model

Return type:

ndarray

toupy.utils.fit_utils.model_tanh(t, *coeffs)[source]

Model for the erf fitting

P0 + P1*t + (P2/2)*(1-tanh(sqrt(2)*(x-P3)/P4))

Parameters:

  • t (ndarray) – Input coordinates

  • coeffs[0] (float) – P0 (noise)

  • coeffs[1] (float) – P1 (linear term)

  • coeffs[2] (float) – P2 (Maximum amplitude)

  • coeffs[3] (float) – P3 (center)

  • coeffs[4] (float) – P4 (width)

Returns:

Array containing the model

Return type:

ndarray

toupy.utils.fit_utils.residuals_erf(coeffs, y, t)[source]

Residuals for the least-squares optimization coeffs as the ones of the model erf function

Parameters:

  • y (ndarray) – The data

  • t (ndarray) – Input coordinates

Returns:

Residuals

Return type:

ndarray

toupy.utils.fit_utils.residuals_tanh(coeffs, y, t)[source]

Residuals for the least-squares optimization coeffs as the ones of the model tanh function

Parameters:

  • y (ndarray) – The data

  • t (ndarray) – Input coordinates

Returns:

Residuals

Return type:

ndarray

toupy.utils.funcutils module

toupy.utils.funcutils.checkhostname(func)[source]

Check if running in OAR, if not, exit.

toupy.utils.funcutils.deprecated(func)[source]

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

toupy.utils.funcutils.downloadURL(url, fname)[source]

Download file from a URL.

Parameters:

  • url (str) – URL address

  • fname (str) – Filename as to be stored

toupy.utils.funcutils.downloadURLfile(url, filename)[source]

Download and save file from a URL.

Parameters:

  • url (str) – URL address

  • fname (str) – Filename as to be stored

toupy.utils.funcutils.progress_bar(count, block_size, total_size)[source]

Display a download progress bar in the terminal.

Intended as a reporthook callback for urllib.request.urlretrieve().

Parameters:

  • count (int) – Number of blocks transferred so far.

  • block_size (int) – Size of each block in bytes.

  • total_size (int) – Total file size in bytes. If <= 0 the function returns immediately without printing.

class toupy.utils.funcutils.switch(value)[source]

Bases: object

Provide switch/case functionality for Python.

Mimics the switch statement found in C, Java, and similar languages. Intended to be used in a for loop with a single iteration, where each case is an if guarded by a call to match().

Parameters:

value (object) – The value to compare against in each case.

Examples

>>> for case in switch(x):
...     if case(1):
...         print("one")
...         break
...     if case(2, 3):
...         print("two or three")
...         break
...     if case():  # default
...         print("other")
__iter__()[source]

Return the match method once, then stop.

match(*args)[source]

Indicate whether to enter a case suite.

Parameters:

*args (object) – Values to match against. If no arguments are given (default case), always returns True.

Returns:

True if the switch value matches any of args, or if fall-through is active, or if no args are given.

Return type:

bool

class toupy.utils.funcutils.tqdm(*_, **__)[source]

Bases: Comparable

Decorate an iterable object, returning an iterator which acts exactly like the original iterable, but prints a dynamically updating progressbar every time a value is requested.

Parameters:

  • iterable (iterable, optional) – Iterable to decorate with a progressbar. Leave blank to manually manage the updates.

  • desc (str, optional) – Prefix for the progressbar.

  • total (int or float, optional) – The number of expected iterations. If unspecified, len(iterable) is used if possible. If float(“inf”) or as a last resort, only basic progress statistics are displayed (no ETA, no progressbar). If gui is True and this parameter needs subsequent updating, specify an initial arbitrary large positive number, e.g. 9e9.

  • leave (bool, optional) – If [default: True], keeps all traces of the progressbar upon termination of iteration. If None, will leave only if position is 0.

  • file (io.TextIOWrapper or io.StringIO, optional) – Specifies where to output the progress messages (default: sys.stderr). Uses file.write(str) and file.flush() methods. For encoding, see write_bytes.

  • ncols (int, optional) – The width of the entire output message. If specified, dynamically resizes the progressbar to stay within this bound. If unspecified, attempts to use environment width. The fallback is a meter width of 10 and no limit for the counter and statistics. If 0, will not print any meter (only stats).

  • mininterval (float, optional) – Minimum progress display update interval [default: 0.1] seconds.

  • maxinterval (float, optional) – Maximum progress display update interval [default: 10] seconds. Automatically adjusts miniters to correspond to mininterval after long display update lag. Only works if dynamic_miniters or monitor thread is enabled.

  • miniters (int or float, optional) – Minimum progress display update interval, in iterations. If 0 and dynamic_miniters, will automatically adjust to equal mininterval (more CPU efficient, good for tight loops). If > 0, will skip display of specified number of iterations. Tweak this and mininterval to get very efficient loops. If your progress is erratic with both fast and slow iterations (network, skipping items, etc) you should set miniters=1.

  • ascii (bool or str, optional) – If unspecified or False, use unicode (smooth blocks) to fill the meter. The fallback is to use ASCII characters “ 123456789#”.

  • disable (bool, optional) – Whether to disable the entire progressbar wrapper [default: False]. If set to None, disable on non-TTY.

  • unit (str, optional) – String that will be used to define the unit of each iteration [default: it].

  • unit_scale (bool or int or float, optional) – If 1 or True, the number of iterations will be reduced/scaled automatically and a metric prefix following the International System of Units standard will be added (kilo, mega, etc.) [default: False]. If any other non-zero number, will scale total and n.

  • dynamic_ncols (bool, optional) – If set, constantly alters ncols and nrows to the environment (allowing for window resizes) [default: False].

  • smoothing (float, optional) – Exponential moving average smoothing factor for speed estimates (ignored in GUI mode). Ranges from 0 (average speed) to 1 (current/instantaneous speed) [default: 0.3].

  • bar_format (str, optional) –

    Specify a custom bar string formatting. May impact performance. [default: ‘{l_bar}{bar}{r_bar}’], where l_bar=’{desc}: {percentage:3.0f}%|’ and r_bar=’| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, ‘

    ’{rate_fmt}{postfix}]’

    Possible vars: l_bar, bar, r_bar, n, n_fmt, total, total_fmt,

    percentage, elapsed, elapsed_s, ncols, nrows, desc, unit, rate, rate_fmt, rate_noinv, rate_noinv_fmt, rate_inv, rate_inv_fmt, postfix, unit_divisor, remaining, remaining_s, eta.

    Note that a trailing “: “ is automatically removed after {desc} if the latter is empty.

  • initial (int or float, optional) – The initial counter value. Useful when restarting a progress bar [default: 0]. If using float, consider specifying {n:.3f} or similar in bar_format, or specifying unit_scale.

  • position (int, optional) – Specify the line offset to print this bar (starting from 0) Automatic if unspecified. Useful to manage multiple bars at once (eg, from threads).

  • postfix (dict or *, optional) – Specify additional stats to display at the end of the bar. Calls set_postfix(**postfix) if possible (dict).

  • unit_divisor (float, optional) – [default: 1000], ignored unless unit_scale is True.

  • write_bytes (bool, optional) – Whether to write bytes. If (default: False) will write unicode.

  • lock_args (tuple, optional) – Passed to refresh for intermediate output (initialisation, iterating, and updating).

  • nrows (int, optional) – The screen height. If specified, hides nested bars outside this bound. If unspecified, attempts to use environment height. The fallback is 20.

  • colour (str, optional) – Bar colour (e.g. ‘green’, ‘#00ff00’).

  • delay (float, optional) – Don’t display until [default: 0] seconds have elapsed.

  • gui (bool, optional) – WARNING: internal parameter - do not use. Use tqdm.gui.tqdm(…) instead. If set, will attempt to use matplotlib animations for a graphical output [default: False].

Returns:

out

Return type:

decorated iterator.

__iter__()[source]

Backward-compatibility to use: for x in tqdm(iterable)

clear(nolock=False)[source]

Clear current bar display.

close()[source]

Cleanup and (if leave=False) close the progressbar.

display(msg=None, pos=None)[source]

Use self.sp to display msg in the specified pos.

Consider overloading this function when inheriting to use e.g.: self.some_frontend(**self.format_dict) instead of self.sp.

Parameters:

  • msg (str, optional. What to display (default: repr(self)).)

  • pos (int, optional. Position to moveto) – (default: abs(self.pos)).

classmethod external_write_mode(file=None, nolock=False)[source]

Disable tqdm within context and refresh tqdm when exits. Useful when writing to standard output stream

property format_dict

Public API for read-only member access.

static format_interval(t)[source]

Formats a number of seconds as a clock time, [H:]MM:SS

Parameters:

t (int) – Number of seconds.

Returns:

out – [H:]MM:SS

Return type:

str

static format_meter(n, total, elapsed, ncols=None, prefix='', ascii=False, unit='it', unit_scale=False, rate=None, bar_format=None, postfix=None, unit_divisor=1000, initial=0, colour=None, **extra_kwargs)[source]

Return a string-based progress bar given some parameters

Parameters:

  • n (int or float) – Number of finished iterations.

  • total (int or float) – The expected total number of iterations. If meaningless (None), only basic progress statistics are displayed (no ETA).

  • elapsed (float) – Number of seconds passed since start.

  • ncols (int, optional) – The width of the entire output message. If specified, dynamically resizes {bar} to stay within this bound [default: None]. If 0, will not print any bar (only stats). The fallback is {bar:10}.

  • prefix (str, optional) – Prefix message (included in total width) [default: ‘’]. Use as {desc} in bar_format string.

  • ascii (bool, optional or str, optional) – If not set, use unicode (smooth blocks) to fill the meter [default: False]. The fallback is to use ASCII characters “ 123456789#”.

  • unit (str, optional) – The iteration unit [default: ‘it’].

  • unit_scale (bool or int or float, optional) – If 1 or True, the number of iterations will be printed with an appropriate SI metric prefix (k = 10^3, M = 10^6, etc.) [default: False]. If any other non-zero number, will scale total and n.

  • rate (float, optional) – Manual override for iteration rate. If [default: None], uses n/elapsed.

  • bar_format (str, optional) –

    Specify a custom bar string formatting. May impact performance. [default: ‘{l_bar}{bar}{r_bar}’], where l_bar=’{desc}: {percentage:3.0f}%|’ and r_bar=’| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, ‘

    ’{rate_fmt}{postfix}]’

    Possible vars: l_bar, bar, r_bar, n, n_fmt, total, total_fmt,

    percentage, elapsed, elapsed_s, ncols, nrows, desc, unit, rate, rate_fmt, rate_noinv, rate_noinv_fmt, rate_inv, rate_inv_fmt, postfix, unit_divisor, remaining, remaining_s, eta.

    Note that a trailing “: “ is automatically removed after {desc} if the latter is empty.

  • postfix (*, optional) – Similar to prefix, but placed at the end (e.g. for additional stats). Note: postfix is usually a string (not a dict) for this method, and will if possible be set to postfix = ‘, ‘ + postfix. However other types are supported (#382).

  • unit_divisor (float, optional) – [default: 1000], ignored unless unit_scale is True.

  • initial (int or float, optional) – The initial counter value [default: 0].

  • colour (str, optional) – Bar colour (e.g. ‘green’, ‘#00ff00’).

Returns:

out

Return type:

Formatted meter and stats, ready to display.

static format_num(n)[source]

Intelligent scientific notation (.3g).

Parameters:

n (int or float or Numeric) – A Number.

Returns:

out – Formatted number.

Return type:

str

static format_sizeof(num, suffix='', divisor=1000)[source]

Formats a number (greater than unity) with SI Order of Magnitude prefixes.

Parameters:

  • num (float) – Number ( >= 1) to format.

  • suffix (str, optional) – Post-postfix [default: ‘’].

  • divisor (float, optional) – Divisor between prefixes [default: 1000].

Returns:

out – Number with Order of Magnitude SI unit postfix.

Return type:

str

classmethod get_lock()[source]

Get the global lock. Construct it if it does not exist.

monitor = None
monitor_interval = 10
moveto(n)[source]
classmethod pandas(**tqdm_kwargs)[source]
Registers the current tqdm class with

pandas.core. ( frame.DataFrame | series.Series | groupby.(generic.)DataFrameGroupBy | groupby.(generic.)SeriesGroupBy ).progress_apply

A new instance will be created every time progress_apply is called, and each instance will automatically close() upon completion.

Parameters:

tqdm_kwargs (arguments for the tqdm instance)

Examples

>>> import pandas as pd
>>> import numpy as np
>>> from tqdm import tqdm
>>> from tqdm.gui import tqdm as tqdm_gui
>>>
>>> df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
>>> tqdm.pandas(ncols=50)  # can use tqdm_gui, optional kwargs, etc
>>> # Now you can use `progress_apply` instead of `apply`
>>> df.groupby(0).progress_apply(lambda x: x**2)

References

<https://stackoverflow.com/questions/18603270/ progress-indicator-during-pandas-operations-python>

refresh(nolock=False, lock_args=None)[source]

Force refresh the display of this bar.

Parameters:

  • nolock (bool, optional) – If True, does not lock. If [default: False]: calls acquire() on internal lock.

  • lock_args (tuple, optional) – Passed to internal lock’s acquire(). If specified, will only display() if acquire() returns True.

reset(total=None)[source]

Resets to 0 iterations for repeated use.

Consider combining with leave=True.

Parameters:

total (int or float, optional. Total to use for the new bar.)

set_description(desc=None, refresh=True)[source]

Set/modify description of the progress bar.

Parameters:

  • desc (str, optional)

  • refresh (bool, optional) – Forces refresh [default: True].

set_description_str(desc=None, refresh=True)[source]

Set/modify description without ‘: ‘ appended.

classmethod set_lock(lock)[source]

Set the global lock.

set_postfix(ordered_dict=None, refresh=True, **kwargs)[source]

Set/modify postfix (additional stats) with automatic formatting based on datatype.

Parameters:

  • ordered_dict (dict or OrderedDict, optional)

  • refresh (bool, optional) – Forces refresh [default: True].

  • kwargs (dict, optional)

set_postfix_str(s='', refresh=True)[source]

Postfix without dictionary expansion, similar to prefix handling.

static status_printer(file)[source]

Manage the printing and in-place updating of a line of characters. Note that if the string is longer than a line, then in-place updating may not work (it will print a new line at each refresh).

unpause()[source]

Restart tqdm timer from last print time.

update(n=1)[source]

Manually update the progress bar, useful for streams such as reading files. E.g.: >>> t = tqdm(total=filesize) # Initialise >>> for current_buffer in stream: … … … t.update(len(current_buffer)) >>> t.close() The last line is highly recommended, but possibly not necessary if t.update() will be called in such a way that filesize will be exactly reached and printed.

Parameters:

n (int or float, optional) – Increment to add to the internal counter of iterations [default: 1]. If using float, consider specifying {n:.3f} or similar in bar_format, or specifying unit_scale.

Returns:

out – True if a display() was triggered.

Return type:

bool or None

classmethod wrapattr(stream, method, total=None, bytes=True, **tqdm_kwargs)[source]

stream : file-like object. method : str, “read” or “write”. The result of read() and

the first argument of write() should have a len().

>>> with tqdm.wrapattr(file_obj, "read", total=file_obj.size) as fobj:
...     while True:
...         chunk = fobj.read(chunk_size)
...         if not chunk:
...             break
classmethod write(s, file=None, end='\n', nolock=False)[source]

Print a message via tqdm (without overlap with bars).

toupy.utils.plot_utils module

class toupy.utils.plot_utils.RegisterPlot(**params)[source]

Bases: object

Manage live plot updates during tomographic projection alignment.

Provides two high-level entry points:

Architecture

Vertical alignment

  • fig_proj — small static figure (projection + ROI), shown once at initialisation and never updated.

  • fig_main — unified 6-panel diagnostic figure, updated every iteration via its _out_main Output widget.

Horizontal alignment

  • fig_main — unified 6-panel diagnostic figure (single figure).

Display strategy

Jupyter / ``%matplotlib widget``

Figures are rendered to PNG bytes via savefig() and shown via IPython DisplayHandle objects obtained from IPython.display.display(..., display_id=True). Subsequent updates call handle.update(new_png) — no clear_output is ever called, so the figure display items are never accidentally removed. The verbose text printed by the alignment loop is similarly updated in-place via a second DisplayHandle that holds an HTML block; the loop redirects stdout to a StringIO buffer and calls _verbose_update() after each iteration.

Terminal

Figures are redrawn via canvas.draw_idle() + plt.pause().

param **params:

Algorithm parameters forwarded to the canvas helpers. Must contain at least 'slicenum', 'sinohigh', and 'sinolow'.

plotshorizontal(recons, sinoorig, sinocurr, sinocomp, deltaslice, metric_error, count)[source]

Display or update the horizontal-alignment diagnostic figure.

First call — creates the unified 6-panel fig_main.

Subsequent calls — delegates to updatehorizontal() which updates artists in-place and refreshes fig_main.

Parameters:

  • recons (ndarray) – Current reconstructed slice.

  • sinoorig (ndarray) – Original sinogram (fixed reference, never updated after iter 0).

  • sinocurr (ndarray) – Current aligned sinogram.

  • sinocomp (ndarray) – Synthetic sinogram computed from the reconstruction.

  • deltaslice (ndarray) – Current horizontal shift estimates.

  • metric_error (list of float) – Error metric history.

  • count (int) – Current iteration number.

plotsvertical(proj, lims, vertfluctinit, vertfluctcurr, deltastack, metric_error, count, max_correction=None)[source]

Display or update the vertical-alignment diagnostic figures.

First call — creates fig_proj (static, shown once) and fig_main (unified 6-panel, updated each iteration).

Subsequent calls — delegates to updatevertical() which updates artists in-place and refreshes only fig_main.

Parameters:

  • proj (ndarray) – Current projection image (displayed once as ROI overlay).

  • lims (tuple) – (limrow, limcol) ROI boundary indices.

  • vertfluctinit (ndarray) – Initial vertical fluctuations (fixed reference).

  • vertfluctcurr (ndarray) – Current vertical fluctuations (updated each iteration).

  • deltastack (ndarray) – Current vertical shift estimates.

  • metric_error (list of float) – Error metric history (grows by one element per iteration).

  • count (int) – Current iteration number.

  • max_correction (float or None) – Maximum absolute vertical shift change this iteration (pixels). Displayed in the figure suptitle when provided.

updatehorizontal()[source]

Update the horizontal-alignment diagnostic figure in-place.

Modifies existing artist objects — no new figures or axes are created.

Panels updated

  • recon — reconstructed slice (sharpens as alignment improves).

  • synthsino — synthetic sinogram.

  • currsino — current sinogram.

  • shifts — shift curves for all projections.

  • error — error-metric curve (grows one point per iteration).

  • fig_main.suptitle — iteration counter and latest error value.

updatevertical()[source]

Update the vertical-alignment diagnostic figure in-place.

Modifies existing artist objects — no new figures or axes are created. Only fig_main is refreshed; fig_proj is static.

Panels updated

  • curr2d — current 2-D integral image.

  • curr1d — current 1-D integral line plots and mean overlay.

  • shifts — shift curves for all projections.

  • error — error-metric curve (grows one point per iteration).

  • fig_main.suptitle — iteration counter and latest error value.

class toupy.utils.plot_utils.ShowProjections[source]

Bases: object

Show projections and probe

static probe2HSV(probe)[source]

Special tricks for the probe display in HSV

show_projections(obj, probe, idxp)[source]

Show the object and the probe :param obj: Object to show :type obj: ndarray :param probe: Probe to show :type probe: ndarray :param idxp: Projection number :type idxp: int

update_show()[source]

Update the canvas

toupy.utils.plot_utils.animated_image(stack_array, *args)[source]

Iterative plot of the images using animation module of Matplotlib

Parameters:

  • stack_array (ndarray) – Array containing the stack of images to animate. The first index corresponds to the image number in the sequence of images.

  • args[0] (list of ints) – Row limits to display

  • args[1] (list of ints) – Column limits to display

toupy.utils.plot_utils.autoscale_y(ax, margin=0.1)[source]

This function rescales the y-axis based on the data that is visible given the current xlim of the axis.

Parameters:

  • ax (object) – A matplotlib axes object

  • margin (float) – The fraction of the total height of the y-data to pad the upper and lower ylims

toupy.utils.plot_utils.display_slice(recons, colormap='bone', vmin=None, vmax=None)[source]

Display tomographic slice

Parameters:

  • recons (array_like) – Tomographic slice

  • colormap (str, optional) – Colormap name. The default value is bone

  • vmin (float, None) – Minimum gray-level. The default value is None

  • vmax (float, None) – Maximum gray-level. The default value is None

toupy.utils.plot_utils.isnotebook()[source]

Check if code is executed in the IPython notebook. This is important because jupyter notebook does not support iterative plots

toupy.utils.plot_utils.iterative_show(stack_array, limrow=[], limcol=[], airpixel=[], onlyroi=False, colormap='bone', vmin=None, vmax=None)[source]

Iterative plot of the images

Parameters:

  • stack_array (ndarray) – Array containing the stack of images to animate. The first index corresponds to the image number in the sequence of images.

  • limrow (list of ints) – Limits of rows in the format [begining, end]

  • limcol (list of ints) – Limits of cols in the format [begining, end]

  • airpixel (list of ints) – Position of pixel in the air/vacuum

  • onlyroi (bool) – If True, it displays only the ROI. If False, it displays the entire image.

  • colormap (str, optional) – Colormap name. The default value is bone

  • vmin (float, None, optional) – Minimum gray-level. The default value is None

  • vmax (float, None, optional) – Maximum gray-level. The default value is None

toupy.utils.plot_utils.plot_checkangles(angles)[source]

Plot the angles for each projections and the derivatives to check for anomalies

Parameters:

angles (array_like) – Array of angles

toupy.utils.plot_utils.show_figure(fig=None, close=True)[source]

Display a figure in the current environment and optionally close it.

In Jupyter: switches the figure’s canvas to a plain Agg renderer, renders to a PNG via savefig, and shows it as a static display.Image. Switching to Agg before savefig is necessary because the default ipympl canvas (FigureCanvasWebAggCore) routes savefig through canvas.draw() → manager.refresh_all(), which raises AttributeError when manager is None (e.g. when plt.ion() was never called). The Agg canvas has no manager dependency.

In terminal: calls plt.show(block=False).

Parameters:

  • fig (matplotlib Figure, optional) – Figure to display. Defaults to the current figure (plt.gcf()).

  • close (bool, optional) – If True (default), close the figure after displaying it in Jupyter. Set to False for figures that will be reused or updated.

toupy.utils.plot_utils.show_fsc_curve(fn, FSC, T, snrt, ndim)[source]

Plot the FSC and threshold curves, save to disk, and display.

Draws the FSC curve, the threshold, a vertical dashed line at the estimated resolution crossing, and an informative title. The figure is saved to FSC_2D.png or FSC_3D.png and then displayed.

Parameters:

  • fn (ndarray) – Spatial frequencies normalised by the Nyquist frequency.

  • FSC (ndarray) – Fourier Shell Correlation curve (real part).

  • T (ndarray) – Threshold curve.

  • snrt (float) – SNR threshold value used to select the threshold label: 0.2071 → "1/2 bit threshold", 0.5 → "1 bit threshold", anything else → f"Threshold SNR = {snrt:g}".

  • ndim (int) – Number of dimensions of the original data (2 or 3).

Return type:

None

toupy.utils.plot_utils.show_fsc_images(img1_apod, img2_apod)[source]

Display the two apodized images used in the FSC computation.

Parameters:

  • img1_apod (ndarray) – First apodized image (or sagittal slice for 3D).

  • img2_apod (ndarray) – Second apodized image (or sagittal slice for 3D).

toupy.utils.plot_utils.show_linearphase(image, mask, *args)[source]

Display a phase projection with an overlaid mask and a horizontal line cut.

Parameters:

  • image (ndarray, shape (nr, nc)) – Phase image to display.

  • mask (ndarray, shape (nr, nc)) – Mask added to image for the 2-D panel.

  • *args –

    args[0]int or str, optional

    Projection index used in the figure title. Defaults to an empty string if not provided.

toupy.utils.plot_utils.show_random_fsc_curve(fn, fsc_obs, fsc_rand, fsc_corr, T, cutoff_fn, ndim)[source]

Plot the phase-randomization FSC test results and save to disk.

Left panel: FSC_obs, FSC_rand, FSC_corr, the threshold T, and a vertical dotted line at the randomisation cutoff frequency. Right panel: FSC_obs − FSC_rand (genuine signal above the cutoff), with a horizontal dashed line at zero.

The figure is saved to RandomFSC.png and then displayed.

Parameters:

  • fn (ndarray) – Spatial frequencies normalised by the Nyquist frequency.

  • fsc_obs (ndarray) – Observed (standard) FSC curve.

  • fsc_rand (ndarray) – Phase-randomized FSC curve (noise floor).

  • fsc_corr (ndarray) – Corrected FSC, defined as (FSC_obs - FSC_rand) / (1 - FSC_rand).

  • T (ndarray) – Threshold curve.

  • cutoff_fn (float) – Normalised cutoff frequency (cutoff_shell / fnyquist) at which phase randomisation begins.

  • ndim (int) – Number of dimensions of the original data (2 or 3). Currently used only for potential future labelling.

Return type:

None

toupy.utils.plot_utils.show_resolution_map(rmap, ndim, title, filename, slice_idx=None, axis=0, cmap='viridis_r', vmin=None, vmax=None)[source]

Display a 2-D or 3-D local resolution map and save it to disk.

For a 3-D map a single slice is extracted along axis and shown as a 2-D image. The slice index and axis are appended to the title. For a 2-D map the full array is shown. A colorbar labelled "Local resolution (pixels)" is added, and the figure is saved to filename before being displayed.

Parameters:

  • rmap (ndarray) – Local resolution map. May be 2-D or 3-D.

  • ndim (int) – Number of dimensions of the original data (2 or 3). Must match rmap.ndim.

  • title (str) – Base title string. For 3-D data the slice information is appended automatically.

  • filename (str) – Output filename (e.g. "LocalFSC_resmap.png"). Saved with bbox_inches='tight'.

  • slice_idx (int or None, optional) – Index of the slice to display along axis. Defaults to the central slice (rmap.shape[axis] // 2) when None. Ignored for 2-D input.

  • axis (int, optional) – Axis along which to extract the slice (3-D only). Default 0.

  • cmap (str, optional) – Matplotlib colormap name. Default 'viridis_r'.

  • vmin (float or None, optional) – Lower colour-scale limit. None uses the data minimum.

  • vmax (float or None, optional) – Upper colour-scale limit. None uses the data maximum.

Return type:

None

toupy.utils.plot_utils.show_ssnr_curve(fn, FSC, SSNR, SSNR_T, snrt, ndim)[source]

Plot the SSNR curve with its threshold, resolution line, and asymptote.

The figure shows the Spectral Signal-to-Noise Ratio (SSNR) and its frequency-dependent threshold on a semi-logarithmic scale, together with a horizontal dotted line at the asymptotic threshold value and a vertical dashed line at the estimated resolution crossing. The figure is saved to SSNR_2D.png or SSNR_3D.png and then displayed.

Parameters:

  • fn (ndarray) – Spatial frequencies normalised by the Nyquist frequency.

  • FSC (ndarray) – Fourier Shell/Ring Correlation curve (real part), included for potential future use but not plotted directly.

  • SSNR (ndarray) – Spectral Signal-to-Noise Ratio curve, derived from FSC via SSNR = 2 * FSC / (1 - FSC).

  • SSNR_T (ndarray) – Frequency-dependent SSNR threshold curve, derived from the FSC threshold T via SSNR_T = 2 * T / (1 - T).

  • snrt (float) – SNR threshold value used to compute the asymptote and select the threshold name: 0.2071 → "half-bit", anything else → "one-bit".

  • ndim (int) – Number of dimensions of the original data (2 or 3).

Return type:

None