Miscellaneous Module

nDTomo Utility Tools

This module contains a broad collection of general-purpose functions and tools used across the nDTomo package. These include image and volume processing utilities, geometric transformations, interpolation routines, masking, thresholding, and auxiliary tools for rebinning, visualization, and user-guided input.

Key functionalities: - Circular and binary masking for 2D/3D data - Coordinate transformations (Cartesian <-> Polar) - Cropping, normalization, and padding of images and volumes - Interpolation in 1D, 2D, and 3D - Image segmentation, thresholding, and morphological filling - Matrix size harmonization (even sizing, padding) - Spectral registration and rebinning - Interactive shape fitting (circle/ellipse) - Miscellaneous utility functions (e.g., RGB to grayscale)

These tools serve as foundational operations for pre-processing, simulation, and reconstruction workflows in X-ray chemical tomography.

@author: Antony Vamvakeros

nDTomo.methods.misc.calculate_center_of_mass(spectrum)

Calculate the center of mass of a spectrum with subpixel resolution.

Parameters:

spectrum (list or numpy.ndarray) – A list or numpy array representing the spectrum.

Returns:

The center of mass of the spectrum with subpixel resolution.

Return type:

float

nDTomo.methods.misc.cart2pol(x, y)

Convert Cartesian (x,y) coordinates to polar coordinates (rho, phi).

Parameters:

• x (float) – x-coordinate.

• y (float) – y-coordinate.

Returns:

Polar coordinates (phi, rho).

Return type:

tuple

nDTomo.methods.misc.cart2polim(im, thpix=1024, rpix=1024, ofs=0)

Convert an image from Cartesian to polar coordinates.

Parameters:

• im (numpy.ndarray) – 2D array corresponding to the image.

• thpix (int) – Number of bins for the azimuthal range (default: 1024).

• rpix (int) – Number of bins for the r distance range (default: 1024).

• ofs (float) – Angular offset (default: 0).

Returns:

Image in polar coordinates.

Return type:

numpy.ndarray

nDTomo.methods.misc.cirmask(im, npx=0)

Apply a circular mask to the image/volume.

Parameters:

• im (numpy.ndarray) – Input image or volume.

• npx (int) – Number of pixels to exclude from the circular mask (default: 0).

Returns:

Image or volume with a circular mask applied.

Return type:

numpy.ndarray

nDTomo.methods.misc.compare_spectra(reference_spectrum, translated_spectrum, pixel_range, resolution)

Compare two spectra by translating the second spectrum with subpixel resolution using interpolation.

Parameters:

• reference_spectrum (list or numpy.ndarray) – A list or numpy array representing the reference spectrum.

• translated_spectrum (list or numpy.ndarray) – A list or numpy array representing the spectrum to be translated.

• pixel_range (tuple) – The range of subpixel translation in pixels (e.g., (-0.5, 0.5)).

• resolution (float) – The resolution of subpixel translation (e.g., 0.1).

Returns:

The translated spectrum aligned with the reference spectrum.

Return type:

numpy.ndarray

nDTomo.methods.misc.create_circle(npix_im=512, r0=128)

Create a circular mask for a squared image.

Parameters:

• npix_im (int) – Size of the squared image (default: 512).

• r0 (int) – Radius of the circular mask (default: 128).

Returns:

A binary circular mask with the specified radius.

Return type:

numpy.ndarray

nDTomo.methods.misc.create_cirmask(npix_im=512, npx=0)

Create a circular mask for a squared image.

Parameters:

• npix_im (int) – Size of the squared image (default: 512).

• npx (int) – Number of pixels to exclude from the circular mask (default: 0).

Returns:

A binary circular mask with excluded pixels.

Return type:

numpy.ndarray

nDTomo.methods.misc.crop_ctimage(im, plot=False)

Crop a CT image using a square inside the reconstruction circle. :param im: CT image. :type im: numpy.ndarray :param plot: Flag to display a plot of the cropped image (default: False). :type plot: bool

Returns:

Cropped CT image.

Return type:

numpy.ndarray

nDTomo.methods.misc.crop_ctvolume(vol, plot=False)

Crop a CT volume using a square inside the reconstruction circle.

Parameters:

• vol (numpy.ndarray) – Input CT volume.

• plot (bool) – Flag to display a plot of the cropped volume (default: False).

Returns:

Cropped CT volume.

Return type:

numpy.ndarray

nDTomo.methods.misc.crop_image(im, thr=None, norm=False, plot=False, inds=None)

Crop an image.

Parameters:

• im (numpy.ndarray) – Input image.

• thr (float) – Threshold value to apply for cropping (default: None).

• norm (bool) – Flag to normalize the image (default: False).

• plot (bool) – Flag to display plots of the original and cropped images (default: False).

• inds (list) – List of indices for cropping (default: None).

Returns:

Cropped image. list: List of indices used for cropping.

Return type:

numpy.ndarray

nDTomo.methods.misc.crop_volume(vol, thr=None, plot=False, dtype='float32', inds=None)

Crop a data volume using the average image along the third dimension.

Parameters:

• vol (numpy.ndarray) – Input data volume.

• thr (float) – Threshold value to apply for cropping (default: None).

• plot (bool) – Flag to display a plot of the cropped volume (default: False).

• dtype (str) – Data type of the cropped volume (default: ‘float32’).

• inds (list) – List of indices for cropping (default: None).

Returns:

Cropped data volume.

Return type:

numpy.ndarray

nDTomo.methods.misc.crop_volume_getinds(vol, thr=None)

Crop a data volume using the average image along the third dimension and return the indices.

Parameters:

• vol (numpy.ndarray) – Input data volume.

• thr (float) – Threshold value to apply for cropping (default: None).

Returns:

Tuple of lists containing the row and column indices used for cropping.

Return type:

tuple

nDTomo.methods.misc.even_idx(a)

Return all even elements from a matrix. :param a: Input matrix. :type a: numpy.ndarray

Returns:

Array containing only the even elements.

Return type:

numpy.ndarray

nDTomo.methods.misc.fill_2d_binary(im, thr=None, dil_its=2)

Fill a 2D binary image.

Parameters:

• im (numpy.ndarray) – Input binary image.

• thr (float) – Threshold value to apply for filling (default: None).

• dil_its (int) – Number of dilation iterations (default: 2).

Returns:

Filled binary image.

Return type:

numpy.ndarray

nDTomo.methods.misc.find_first_neighbors_2D(mat, r, c)

Find the first neighbor elements that are non-zero in a binary 2D matrix.

Parameters:

• mat (numpy.ndarray) – Binary 2D matrix.

• r (int) – Row index of the element.

• c (int) – Column index of the element.

Returns:

List of coordinates (row, column) of the first neighbor elements that are non-zero.

Return type:

list

nDTomo.methods.misc.fit_shape_to_points(image, shape='circle')

Fits a circle or ellipse to five user-selected points on an image and overlays it on the original image.

Parameters:

• image (numpy.ndarray) – 2D numpy array representing the image.

• shape (str) – Shape to fit. Options: ‘circle’ (default) or ‘ellipse’.

Returns:

None

nDTomo.methods.misc.image_segm(im, thr, norm=False, plot=False)

Perform simple threshold-based image segmentation.

Parameters:

• im (numpy.ndarray) – Input image.

• thr (float) – Threshold value for segmentation.

• norm (bool) – Flag to normalize the image (default: False).

• plot (bool) – Flag to display a plot of the segmented image (default: False).

Returns:

Segmented image.

Return type:

numpy.ndarray

nDTomo.methods.misc.interpvol(vol, xold, xnew)

Perform linear interpolation on a 3D matrix along the spectral/height dimension.

Parameters:

• vol (numpy.ndarray) – Input 3D matrix.

• xold (numpy.ndarray) – Original x-coordinates along the spectral/height dimension.

• xnew (numpy.ndarray) – New x-coordinates for interpolation.

Returns:

Interpolated 3D matrix.

Return type:

numpy.ndarray

nDTomo.methods.misc.make_matrix_even(mat)

Make the dimensions of a 1D, 2D, or 3D array have even sizes.

Parameters:

mat (numpy.ndarray) – Input array.

Returns:

Array with even dimensions.

Return type:

numpy.ndarray

nDTomo.methods.misc.mask_thr(vol, thr, roi=None, fignum=1)

Apply a threshold-based mask to a 2D or 3D volume.

Parameters:

• vol (numpy.ndarray) – Input 2D or 3D volume.

• thr (float) – Threshold value.

• roi (numpy.ndarray, optional) – Region of interest (default: None).

• fignum (int, optional) – Figure number for displaying the plot (default: 1).

Returns:

Binary mask based on the threshold.

Return type:

numpy.ndarray

nDTomo.methods.misc.maskvolume(vol, msk)

Apply a mask to a 3D array.

Parameters:

• vol (numpy.ndarray) – Input 3D array.

• msk (numpy.ndarray) – Mask array.

Returns:

Resulting masked 3D array.

Return type:

numpy.ndarray

nDTomo.methods.misc.nan_to_number(array, val=0)

Replace NaN values in an array with a specified number.

Parameters:

• array (numpy.ndarray) – Input array.

• val (float) – Value to replace NaN with. Default is 0.

Returns:

Array with NaN values replaced by the specified number.

Return type:

numpy.ndarray

nDTomo.methods.misc.ndtomopath()

Returns the absolute path to the installed nDTomo package directory.

This is useful for locating internal resources such as ‘examples/’ that now live inside the package.

Returns:

Absolute path to the nDTomo package.

Return type:

str

nDTomo.methods.misc.normvol(vol)

Normalize a 3D matrix along the spectral/height dimension.

Parameters:

vol (numpy.ndarray) – Input 3D matrix.

Returns:

Normalized 3D matrix.

Return type:

numpy.ndarray

nDTomo.methods.misc.number_to_nan(array, val=0)

Replace a specified number in an array with NaN values.

Parameters:

• array (numpy.ndarray) – Input array.

• val (float) – Value to replace with NaN. Default is 0.

Returns:

Array with the specified number replaced by NaN values.

Return type:

numpy.ndarray

nDTomo.methods.misc.odd_idx(a)

Return all odd elements from a matrix. :param a: Input matrix. :type a: numpy.ndarray

Returns:

Array containing only the odd elements.

Return type:

numpy.ndarray

nDTomo.methods.misc.pad_zeros(im1, im2, dtype)

Pad two images with zeros to match their sizes.

Parameters:

• im1 (numpy.ndarray) – First input image.

• im2 (numpy.ndarray) – Second input image.

• dtype (str) – Data type for the padded images.

Returns:

Padded images (im1, im2).

Return type:

tuple

nDTomo.methods.misc.pad_zeros_svol(vol, dims, dtype)

Pad a volume with zeros to match a specific size.

Parameters:

• vol (numpy.ndarray) – Input volume.

• dims (tuple) – Target dimensions for the padded volume.

• dtype (str) – Data type for the padded volume.

Returns:

Padded volume.

Return type:

numpy.ndarray

nDTomo.methods.misc.pad_zeros_vol(vol1, vol2, dtype)

Pad two volumes with zeros to match their sizes.

Parameters:

• vol1 (numpy.ndarray) – First volume.

• vol2 (numpy.ndarray) – Second volume.

• dtype (str) – Data type for the padded volumes.

Returns:

Padded vol1. numpy.ndarray: Padded vol2.

Return type:

numpy.ndarray

nDTomo.methods.misc.pol2cart(phi, rho)

Convert polar (rho, phi) coordinates to Cartesian coordinates (x, y).

Parameters:

• phi (float) – Angle in radians.

• rho (float) – Distance from the origin.

Returns:

Cartesian coordinates (x, y).

Return type:

tuple

nDTomo.methods.misc.pol2cartim(imp, im_size=None, thpix=1024, rpix=1024, ofs=0)

Convert an image from polar to Cartesian coordinates.

Parameters:

• imp (numpy.ndarray) – 2D array corresponding to the polar-transformed image.

• im_size (list) – List containing the two dimensions of the image with Cartesian coordinates (default: None).

• thpix (int) – Number of bins for the azimuthal range (default: 1024).

• rpix (int) – Number of bins for the r distance range (default: 1024).

• ofs (float) – Angular offset (default: 0).

Returns:

Image in Cartesian coordinates.

Return type:

numpy.ndarray

nDTomo.methods.misc.rebin1d(x, y, x_new)

Rebin 1D data from original x-axis x to a new x-axis x_new using linear interpolation with weighted averaging.

This function redistributes the values in y (defined on axis x) onto a new set of points x_new by performing distance-weighted averaging to the nearest two neighbors in x_new.

For points in x that lie outside the bounds of x_new, the value of y is assigned directly to the nearest boundary bin.

Parameters:

• x (array-like of shape (N,)) – Original x-axis coordinates.

• y (array-like of shape (N,)) – Data values corresponding to x.

• x_new (array-like of shape (M,)) – New x-axis grid to which y values will be rebinned.

Returns:

rebin_data – Rebinned data values corresponding to x_new.

Return type:

ndarray of shape (M,)

Notes

• The method conserves total weight by proportionally distributing each y[i] value between the two closest points in x_new.

• This approach is useful for spectral regridding or when combining datasets sampled on different 1D grids.

nDTomo.methods.misc.rebinmat(array, factor=2, axis=0)

Rebin a 2D/3D array along an axis

Parameters:

• array – numpy.ndarray.

• factor (int) – Rebinning factor (default: 2).

• axis (int) – Axis for rebinning (default: 0).

Returns:

A rebinned array along an axis

Return type:

numpy.ndarray

nDTomo.methods.misc.rgb2gray(im)

Convert an RGB image to grayscale using the luminosity method. :param im: RGB image. :type im: numpy.ndarray

Returns:

Grayscale image.

Return type:

numpy.ndarray

nDTomo.methods.misc.translate_xy(vol, npix)

Translate the volume along the x-axis by a specified number of pixels.

Parameters:

• vol (numpy.ndarray) – Input volume.

• npix (int) – Number of pixels to translate the volume along the x-axis.

Returns:

Translated volume.

Return type:

numpy.ndarray