pyTEMlib 0.2025.4.2__py3-none-any.whl → 0.2025.9.1__py3-none-any.whl

pyTEMlib/image/image_atoms.py

@@ -0,0 +1,270 @@
+""" Atom detection
+
+All atom detection is done here
+Everything is in unit of pixel!!
+
+Author: Gerd Duscher
+
+part of pycroscopy.image
+
+the core pycroscopy package
+"""
+import numpy as np
+
+import skimage
+import sklearn
+import scipy
+
+import sidpy
+from tqdm.auto import trange
+
+
+def make_gauss(size_x: [int, float], size_y: [int, float], width: float = 1.0, x0: float = 0.0,
+               y0: float = 0.0, intensity: float = 1.0) -> np.ndarray:
+    """
+    Generates a 2D Gaussian-shaped probe array.
+    Parameters
+    ----------
+    size_x : int or float
+        The size of the probe along the x-axis.
+    size_y : int or float
+        The size of the probe along the y-axis.
+    width : float, optional
+        The standard deviation (spread) of the Gaussian (default is 1.0).
+    x0 : float, optional
+        The x-coordinate of the Gaussian center (default is 0.0).
+    y0 : float, optional
+        The y-coordinate of the Gaussian center (default is 0.0).
+    intensity : float, optional
+        The total intensity (sum) of the probe (default is 1.0).
+    Returns
+    -------
+    probe : numpy.ndarray
+        A 2D array representing the normalized Gaussian probe.
+    """
+    size_x = size_x/2
+    size_y = size_y/2
+    x, y = np.mgrid[-size_x:size_x, -size_y:size_y]
+    g = np.exp(-((x-x0)**2 + (y-y0)**2) / 2.0 / width**2)
+    probe = g / g.sum() * intensity
+
+    return probe
+
+
+def find_atoms(image: sidpy.Dataset, atom_size: float = 0.1, threshold: float = 0.) -> np.ndarray:
+    """ Find atoms is a simple wrapper for blob_log in skimage.feature
+
+    threshold for blob finder is usually between 0.001 and 1.0, 
+    note: for threshold <= 0 we use the RMS contrast
+
+    Parameters
+    ----------
+    image: sidpy.Dataset
+        the image to find atoms
+    atom_size: float
+        visible size of atom blob diameter in nm gives minimal distance between found blobs
+    threshold: float
+        threshold for blob finder; 
+
+    Returns
+    -------
+    atoms: numpy array(Nx3)
+        atoms positions and radius of blob
+    """
+
+    if not isinstance(image, sidpy.Dataset):
+        raise TypeError('We need a sidpy.Dataset')
+    if image.data_type.name != 'IMAGE':
+        raise TypeError('We need sidpy.Dataset of sidpy.Datatype: IMAGE')
+    if not isinstance(atom_size, (float, int)):
+        raise TypeError('atom_size parameter has to be a number')
+    if not isinstance(threshold, float):
+        raise TypeError('threshold parameter has to be a float number')
+
+    scale_x = np.unique(np.gradient(image.dim_0.values))[0]
+    im = np.array(image-image.min())
+    im = im/im.max()
+    if threshold <= 0.:
+        threshold = np.std(im)
+    atoms = skimage.feature.blob_log(im, max_sigma=atom_size/scale_x, threshold=threshold)
+
+    return atoms
+
+
+def atoms_clustering(atoms: np.ndarray, mid_atoms: np.ndarray,
+                     number_of_clusters: int = 3, nearest_neighbours: int = 7) -> tuple:
+    """ A wrapper for sklearn.cluster kmeans clustering of atoms.
+
+    Parameters
+    ----------
+    atoms: list or np.array (Nx2)
+        list of all atoms
+    mid_atoms: list or np.array (Nx2)
+        atoms to be evaluated
+    number_of_clusters: int
+        number of clusters to sort (ini=3)
+    nearest_neighbours: int
+        number of nearest neighbours evaluated
+
+    Returns
+    -------
+    clusters, distances, indices: numpy arrays
+    """
+
+    # get distances
+    nn_tree = scipy.spatial.KDTree(np.array(atoms)[:, 0:2])
+
+    distances, indices = nn_tree.query(np.array(mid_atoms)[:, 0:2], nearest_neighbours)
+
+    # Clustering
+    k_means = sklearn.cluster.KMeans(n_clusters=number_of_clusters, random_state=0)
+    k_means.fit(distances)
+    clusters = k_means.predict(distances)
+
+    return clusters, distances, indices
+
+
+def gauss_difference(params: list[float], area: np.ndarray) -> np.ndarray:
+    """
+    Difference between part of an image and a Gaussian
+    This function is used int the atom refine function of pyTEMlib
+
+    Parameters
+    ----------
+    params: list
+        list of Gaussian parameters [width, position_x, position_y, intensity]
+    area:  numpy array
+        2D matrix = part of an image
+
+    Returns
+    -------
+    numpy array: flattened array of difference
+
+    """
+    gauss = make_gauss(area.shape[0], area.shape[1], width=params[0], x0=params[1],
+                       y0=params[2], intensity=params[3])
+    return (area - gauss).flatten()
+
+
+def atom_refine(image: [np.ndarray, sidpy.Dataset], atoms: [np.ndarray, list], radius: float,
+                max_int: float = 0, min_int: float = 0, max_dist: float = 4) -> dict:
+    """Fits a Gaussian in a blob of an image
+
+    Parameters
+    ----------
+    image: np.array or sidpy Dataset
+    atoms: list or np.array
+        positions of atoms
+    radius: float
+        radius of circular mask to define fitting of Gaussian
+    max_int: float
+        optional - maximum intensity to be considered for fitting (to exclude contaminated areas)
+    min_int: float
+        optional - minimum intensity to be considered for fitting (to exclude contaminated holes )
+    max_dist: float
+        optional - maximum distance of movement of Gaussian during fitting
+
+    Returns
+    -------
+    sym: dict
+        dictionary containing new atom positions and other output such as intensity of Gaussian
+    """
+    rr = int(radius + 0.5)  # atom radius
+    print('using radius ', rr, 'pixels')
+
+    pixels = np.linspace(0, 2 * rr, 2 * rr + 1) - rr
+    x, y = np.meshgrid(pixels, pixels)
+    mask = (x ** 2 + y ** 2) < rr ** 2
+
+    guess = [rr * 2, 0.0, 0.0, 1]
+
+    sym = {'number_of_atoms': len(atoms)}
+
+    volume = []
+    position = []
+    intensities = []
+    maximum_area = []
+    new_atoms = []
+    gauss_width = []
+    gauss_amplitude = []
+    gauss_intensity = []
+
+    for i in trange(len(atoms)):
+        x, y = atoms[i][0:2]
+        x = int(x)
+        y = int(y)
+
+        area = image[x - rr:x + rr + 1, y - rr:y + rr + 1]
+
+        append = False
+
+        if x-rr<0 or y-rr < 0 or x+rr+1 > image.shape[0] or y+rr+1 > image.shape[1]:
+            position.append(-1)
+            intensities.append(-1.)
+            maximum_area.append(-1.)
+        else:  # atom found
+            position.append(1)
+            intensities.append((area * mask).sum())
+            maximum_area.append((area * mask).max())
+
+        if max_int > 0:
+            if area.sum() < max_int:
+                if area.sum() > min_int:
+                    append = True
+        elif area.sum() > min_int:
+            append = True
+
+        pout = [0, 0, 0, 0]
+        if append:
+            if x-rr < 0 or y-rr < 0 or x+rr+1 > image.shape[0] or y+rr+1 > image.shape[1]:
+                pass
+            else:
+                [pout, _] = scipy.optimize.leastsq(gauss_difference, guess, args=area)
+
+            if (abs(pout[1]) > max_dist) or (abs(pout[2]) > max_dist):
+                pout = [0, 0, 0, 0]
+
+        volume.append(2 * np.pi * pout[3] * pout[0] * pout[0])
+
+        new_atoms.append([x + pout[1], y + pout[2]])  # ,pout[0],  volume)) #,pout[3]))
+        if all(v == 0 for v in pout):
+            gauss_intensity.append(0.)
+        else:
+            gauss = make_gauss(area.shape[0], area.shape[1], width=pout[0], x0=pout[1], y0=pout[2],
+                                           intensity=pout[3])
+            gauss_intensity.append((gauss * mask).sum())
+        gauss_width.append(pout[0])
+        gauss_amplitude.append(pout[3])
+
+    sym['inside'] = position
+    sym['intensity_area'] = intensities
+    sym['maximum_area'] = maximum_area
+    sym['atoms'] = new_atoms
+    sym['gauss_width'] = gauss_width
+    sym['gauss_amplitude'] = gauss_amplitude
+    sym['gauss_intensity'] = gauss_intensity
+    sym['gauss_volume'] = volume
+
+    return sym
+
+
+def intensity_area(image: np.ndarray, atoms: np.ndarray, radius: float) -> list[float]:
+    """
+    integrated intensity of atoms in an image with a mask around each atom of radius radius
+    """
+    rr = int(radius + 0.5)  # atom radius
+    print('using radius ', rr, 'pixels')
+
+    pixels = np.linspace(0, 2 * rr, 2 * rr + 1) - rr
+    x, y = np.meshgrid(pixels, pixels)
+    mask = np.array((x ** 2 + y ** 2) < rr ** 2)
+    intensities = []
+    for atom in atoms:
+        x = int(atom[1])
+        y = int(atom[0])
+        area = image[x - rr:x + rr + 1, y - rr:y + rr + 1]
+        if area.shape == mask.shape:
+            intensities.append((area * mask).sum())
+        else:
+            intensities.append(-1)
+    return intensities

pyTEMlib/image/image_clean.py

@@ -0,0 +1,197 @@
+"""
+image cleaning functions part of image part of pycroscopy
+"""
+import numpy as np
+import sidpy
+from tqdm import tqdm
+import sklearn.feature_extraction
+from sklearn.utils.extmath import randomized_svd
+import skimage
+
+
+# Image cleaning functions
+
+def clean_svd(im, pixel_size=1, source_size=5):
+    """De-noising of image by using first component of single value decomposition"""
+
+    if not isinstance(im, sidpy.Dataset):
+        raise TypeError('We need a sidpy.Dataset')
+    if im.data_type.name != 'IMAGE':
+        raise TypeError('We need sidpy.Dataset of sidpy.Datatype: IMAGE')
+
+    patch_size = int(source_size/pixel_size)
+    patch_size = max(patch_size, 3)
+
+    patches = sklearn.feature_extraction.image.extract_patches_2d(np.array(im),
+                                                                  (patch_size,
+                                                                   patch_size))
+    patches = patches.reshape(patches.shape[0], patches.shape[1]*patches.shape[2])
+
+    num_components = 32
+
+    u, _, _ = randomized_svd(patches, num_components)
+    u_im_size = int(np.sqrt(u.shape[0]))
+    reduced_image = u[:, 0].reshape(u_im_size, u_im_size)
+    reduced_image = reduced_image/reduced_image.sum()*im.sum()
+    out_dataset = im.like_data(reduced_image)
+    out_dataset.title = 'Major SVD component'
+    out_dataset.data_type = 'image'
+    return out_dataset
+
+def background_correction(image, value=12):
+    """Background correction of an image with difference of Gaussians
+    
+    Parameters
+    ----------  
+    image: numpy array or sidpy.Dataset
+        2D image to be corrected
+    value: int
+        value for the difference of Gaussians, larger values result in more smoothing   
+
+    Returns
+    -------
+    bgd_corr: numpy array or sidpy.Dataset
+        background corrected image
+    """
+
+    if image.ndim != 2:
+        raise ValueError('Input image must be 2D')
+
+    bgd_corr = skimage.filters.difference_of_gaussians(np.array(image), 1, int(value))
+    if isinstance(image, sidpy.Dataset):
+        bgd_corr = image.like_data(bgd_corr)
+        bgd_corr.title = 'Background Corrected ' + image.title
+        bgd_corr.source = image.title
+        bgd_corr.metadata = image.metadata.copy()
+        if 'analysis' not in bgd_corr.metadata:
+            bgd_corr.metadata['analysis'] = {}
+        bgd_corr.metadata['analysis']['background_correction'] = {'value': value,
+                                                                  'input_dataset': image.source}
+    return bgd_corr
+
+# Deconvolution
+
+def make_gauss(size_x, size_y, width=1.0, x0=0.0, y0=0.0, intensity=1.0):
+    """Make a Gaussian shaped probe """
+    size_x = size_x/2
+    size_y = size_y/2
+    x, y = np.mgrid[-size_x:size_x, -size_y:size_y]
+    g = np.exp(-((x-x0)**2 + (y-y0)**2) / 2.0 / width**2)
+    probe = g / g.sum() * intensity
+
+    return probe
+
+
+def decon_lr(o_image, resolution=0.1,  verbose=False):
+
+    """
+    # This task generates a restored image from an input image and point spread function (PSF) using
+    # the algorithm developed independently by Lucy (1974, Astron. J. 79, 745) and Richardson
+    # (1972, J. Opt. Soc. Am. 62, 55) and adapted for HST imagery by Snyder
+    # (1990, in Restoration of HST Images and Spectra, ST ScI Workshop Proceedings; see also
+    # Snyder, Hammoud, & White, JOSA, v. 10, no. 5, May 1993, in press).
+    # Additional options developed by Rick White (STScI) are also included.
+    #
+    # The Lucy-Richardson method can be derived from the maximum likelihood expression 
+    # for data with a Poisson noise distribution. Thus, it naturally applies to optical 
+    # imaging data such as HST. The method forces the restored image to be positive, 
+    # in accord with photon-counting statistics.
+    #
+    # The Lucy-Richardson algorithm generates a restored image through an iterative method. 
+    # The essence of the iteration is as follows: the (n+1)th estimate of the restored image 
+    # is given by the nth estimate of the restored image multiplied by a correction image. 
+    # That is,
+    #
+    #                            original data
+    #       image    = image    ---------------  * reflect(PSF)
+    #            n+1        n     image * PSF
+    #                                  n
+
+    # where the *'s represent convolution operators and reflect(PSF) is the reflection of the PSF, 
+    # i.e. reflect((PSF)(x,y)) = PSF(-x,-y). When the convolutions are carried out using fast 
+    # Fourier transforms (FFTs), one can use the fact that FFT(reflect(PSF)) = conj(FFT(PSF)), 
+    # where conj is the complex conjugate operator.
+
+    Parameters
+    ----------
+    o_image: sidpy_Dataset with DataType='image'
+        the image to be dconvoluted
+    resolution:
+        width of resolution function
+    Returns
+    -------
+    out_dataset: sidpy.Dataset
+        the deconvoluted dataset
+
+    """
+
+    if len(o_image) < 1:
+        return o_image
+
+    image_dimensions = o_image.get_image_dims(return_axis=True)
+    scale_x = image_dimensions[0].slope
+    gauss_diameter = resolution/scale_x
+    probe = make_gauss(o_image.shape[0], o_image.shape[1], gauss_diameter)
+
+    probe_c = np.ones(probe.shape, dtype=np.complex64)
+    probe_c.real = probe
+
+    error = np.ones(o_image.shape, dtype=np.complex64)
+    est = np.ones(o_image.shape, dtype=np.complex64)
+    source = np.ones(o_image.shape, dtype=np.complex64)
+    source.real = o_image
+
+    response_ft = np.fft.fft2(probe_c)
+
+    # dx = scale_x
+    # dk = 1.0 / float(image_dimensions[0][-1])  # last value of x axis is field of view
+    # screen_width = 1 / dx
+
+    aperture = np.ones(o_image.shape, dtype=np.complex64)
+    # Mask for the aperture before the Fourier transform
+    # n = o_image.shape[0]
+    size_x = o_image.shape[0]
+    size_y = o_image.shape[1]
+
+    theta_x = np.array(-size_x / 2. + np.arange(size_x))
+    theta_y = np.array(-size_y / 2. + np.arange(size_y))
+    t_xv, t_yv = np.meshgrid(theta_x, theta_y)
+
+    tp1 = t_xv ** 2 + t_yv ** 2 >= o_image.shape[0]*4/5 ** 2
+    aperture[tp1.T] = 0.
+    # print(app_ratio, screen_width, dk)
+
+
+    progress = tqdm(total=500)
+    # de = 100
+    dest = 100
+    i = 0
+    while abs(dest) > 0.0001:  # or abs(de)  > .025:
+        i += 1
+        error_old = np.sum(error.real)
+        est_old = est.copy()
+        error = source / np.real(np.fft.fftshift(np.fft.ifft2(np.fft.fft2(est) * response_ft)))
+        est = est * np.real(np.fft.fftshift(np.fft.ifft2(np.fft.fft2(error) * np.conjugate(response_ft))))
+
+        error_new = np.real(np.sum(np.power(error, 2))) - error_old
+        dest = np.sum(np.power((est - est_old).real, 2)) / np.sum(est) * 100
+
+        if error_old != 0:
+            de = error_new / error_old * 1.0
+        else:
+            de = error_new
+
+        if verbose:
+            print(f' LR Deconvolution - Iteration: {i:d} Error: {error_new:.2f} = '+
+                  f'change: {de:.5f}%, {abs(dest):.5f}%')
+        if i > 500:
+            dest = 0.0
+            print('terminate')
+        progress.update(1)
+    progress.write(f"converged in {i} iterations")
+    print('\n Lucy-Richardson deconvolution converged in ' + str(i) + '  iterations')
+    # est2 = np.real(np.fft.ifft2(np.fft.fft2(est) * np.fft.fftshift(aperture)))
+    out_dataset = o_image.like_data(np.real(est))
+    out_dataset.title = 'Lucy Richardson deconvolution'
+    out_dataset.data_type = 'image'
+    return out_dataset