hotopy 0.21__py3-none-any.whl

hotopy/__init__.py

@@ -0,0 +1,42 @@
+"""
+=============================================
+HoToPy: A Holo- and Tomography Python Toolbox
+=============================================
+
+To use any submodule an explicit import is required either via
+ - ``import hotopy.holo`` or
+ - ``from hotopy import holo`` or
+ - ``from hotopy.holo import *``
+
+or the used functions are imported explicitly ``from hotopy.holo import CTF``.
+
+Submodules
+----------
+
+.. autosummary::
+    :toctree: generated/
+
+    holo
+    tomo
+    image
+    datasets
+
+
+Optimization
+------------
+
+.. autosummary::
+    :toctree: generated/
+
+    optimize
+
+
+Utilities and helpers
+----------------------
+
+.. autosummary::
+    :toctree: generated/
+
+    utils
+
+"""

hotopy/datasets/__init__.py

@@ -0,0 +1,76 @@
+"""
+=========================================
+Example datasets (:mod:`hotopy.datasets`)
+=========================================
+
+Experimental holographic datasets
+---------------------------------
+.. autosummary::
+    :toctree: generated/
+
+    beads
+    radiodurans
+    macrophage
+    world_holograms
+    spider
+
+Example:
+
+    >>> from hotopy.datasets import beads
+    >>> data = beads()
+    >>> # list content
+    >>> print(list(data.keys()))   # ['holograms', 'fresnelNumbers']
+
+    Some dataset also have a ``'support'`` field, which can be used for constrained phase retrieval.
+
+    >>> holos, fresnel_nums = data["holograms"], data["fresnelNumbers"]
+    >>> print(holos.shape, fresnel_nums.shape)
+
+    This datasets can be used for phase retrieval, e.g. with CTF or Tikhonov.
+
+    >>> from hotopy.holo import Tikhonov
+    >>> imshape = holos.shape[-2:]
+    >>> alpha = [0, 5e-2]
+    >>> betadelta = 0.01  # 1% effective absorption
+    >>> device = "cpu"  # if CUDA cards are available set ``device="cuda"``.
+    >>> tik = Tikhonov(imshape, fresnel_nums, betadelta=betadelta, alpha=alpha, device=device)
+    >>> rec_tik = tik(holos).cpu().numpy()
+
+
+Simulation phantoms
+-------------------
+.. autosummary::
+    :toctree: generated/
+
+    dicty
+    dicty_multi
+    world
+
+.. author: Jens Lucht, 2023-2024
+"""
+
+from ._holograms import (
+    beads,
+    radiodurans,
+    macrophage,
+    world_holograms,
+    spider,
+    logo_holograms,
+    catparticle,
+)
+from ._phantoms import dicty, dicty_multi, world, balls, checkerboard
+
+__all__ = [
+    "beads",
+    "radiodurans",
+    "macrophage",
+    "world_holograms",
+    "logo_holograms",
+    "catparticle",
+    "spider",
+    "dicty",
+    "dicty_multi",
+    "world",
+    "balls",
+    "checkerboard",
+]

hotopy/datasets/_fetcher.py

@@ -0,0 +1,37 @@
+import numpy as np
+import pooch
+import importlib.resources  # requires python>=3.7
+
+
+class _DataFetcher:
+    def __init__(self):
+        self.storage = pooch.create(
+            path=pooch.os_cache("hotopy/datasets"),
+            base_url="https://gitlab.gwdg.de/irp/",
+            registry=None,
+            env="HOTOPY_DATA_DIR",
+        )
+
+        # find registry
+        self._registry_fp = registry_fp = importlib.resources.files(__package__).joinpath(
+            "registry.txt"
+        )
+        self.storage.load_registry(registry_fp)
+
+    def __call__(self, *args, **kwargs):
+        defaults = {"processor": _process_npz}
+        kwargs = {**defaults, **kwargs}
+        return self.storage.fetch(*args, **kwargs)
+
+
+def _process_npz(fname, *args):
+    return np.load(fname)
+
+
+def _decompress_npz(fname, *args):
+    decompressor = pooch.processors.Decompress()
+    fd_inflated = decompressor(fname, *args)
+    return np.load(fd_inflated)
+
+
+fetcher = _DataFetcher()

hotopy/datasets/_holograms.py

@@ -0,0 +1,54 @@
+"""
+.. autosummary::
+    :toctree: generated/
+
+.. author: Jens Lucht, 2024
+"""
+
+from ._fetcher import fetcher
+from ._fetcher import _decompress_npz
+
+
+def _simple_holograms(name):
+    return fetcher(f"holograms_{name!s}.npz")
+
+
+def radiodurans():
+    return _simple_holograms("radiodurans")
+
+
+def beads():
+    return _simple_holograms("beads")
+
+
+def macrophage():
+    return _simple_holograms("macrophage")
+
+
+def world_holograms():
+    return _simple_holograms("world")
+
+
+def spider():
+    """
+    Single-distance dataset for direct contrast aka TIE regime phase retrieval.
+    """
+    return _simple_holograms("spider")
+
+
+def logo_holograms():
+    """
+    deep-holographic dataset
+    """
+    return _simple_holograms("logo")
+
+
+def catparticle():
+    """
+    Normalized holographic projections (holograms) at two defocus positions of a
+    catalytic nano-particle in the deep-holographic regime.
+    This dataset is at a single tomographic angle.
+
+    For the full tomographic dataset see https://doi.org/10.25625/CQ1EKY
+    """
+    return fetcher("holograms_catparticle.npz.bz2", processor=_decompress_npz)

hotopy/datasets/_phantoms.py

@@ -0,0 +1,120 @@
+"""
+.. autosummary::
+    :toctree: generated/
+
+
+.. author: Jens Lucht, 2023
+"""
+
+from ._fetcher import fetcher
+from ..image import dissect_levels, ball
+import numpy as np
+from functools import reduce
+
+
+def _simple_phantom(name):
+    cnt = fetcher(f"phantom_{name!s}.npz")
+    return cnt["phantom"]
+
+
+def dicty():
+    return _simple_phantom("dicty")
+
+
+# not an actual dataset, but simple wrapper to get a multi-component/material phantom
+def dicty_multi(*lims):
+    """
+    Multi-component/material ``dicty`` phantom.
+
+    See dissect_levels, dicty
+    """
+    im = dicty()
+    return dissect_levels(im, *lims)
+
+
+def world():
+    return _simple_phantom("world").astype(float)
+
+
+def world_uint():
+    # dataset in original datatype
+    return _simple_phantom("world")
+
+
+def _get_default_cen_rad_dens(shape=(120, 128, 128)):
+    ref_length_radii = min(shape)
+    height = shape[0]
+    dist_center = 0.7 * min(shape[1:]) / 2
+
+    centers, radii, densities = [], [], []
+    for z, phi in zip(
+        ((0.3 * height,) * 3 + (0.7 * height,)),
+        2 * np.pi * np.array((0, 0.25, 0.5, 0.25)),
+        strict=True,
+    ):
+        radii.append(ref_length_radii / 15)
+        centers.append((z, dist_center, phi))  # z, r, phi
+        densities.append(1)
+
+    for i, phi in enumerate(2 * np.pi * np.arange(0, 1, 1 / 12)[:-1]):
+        radii.append(ref_length_radii * np.sqrt(i + 1) / 60)
+        centers.append((0.5 * height, dist_center, phi))  # z, r, phi
+        densities.append(2 / np.sqrt(i + 1))
+
+    centers = np.array(centers)
+    # centers: r, phi -> x, y
+    r, phi = centers[:, 1:].T
+    centers[:, 1:] = np.stack(
+        (shape[1] / 2 + r * np.cos(phi), shape[2] / 2 + r * np.sin(phi)), axis=-1
+    )
+    return centers, radii, densities
+
+
+def balls(shape=(120, 128, 128), centers=None, radii=None, densities=1, dtype=np.float32):
+    """generate a volume containing balls of uniform density.
+    The default values yield an example volume for tomography.
+    """
+    # preprocess parameters
+    if centers is None:
+        if len(shape) == 3:
+            centers, radii, densities = _get_default_cen_rad_dens(shape)
+        else:
+            rng = np.random.default_rng(seed=0)
+            centers = shape * rng.random((10, len(shape)))
+    else:
+        centers = np.asarray(centers)
+    if radii is None:
+        radii = min((min(shape) / 2, sum(shape) / len(shape) / 10))
+    radii = np.broadcast_to(radii, len(centers))
+    densities = np.broadcast_to(densities, len(centers))
+
+    # generate phantom
+    phantom = np.zeros(shape, dtype=dtype)
+    for r, cen, d in zip(radii, centers, densities, strict=True):
+        r_px = int(r)
+        cen_px = cen.astype(int)
+        slc = tuple(  # roi in phantom
+            slice(
+                max(0, c_px - r_px),
+                c_px + r_px + 2,
+            )
+            for c_px in cen_px
+        )
+        slc_ball = tuple(  # crop ball at borders of phantom
+            slice(
+                max(0, r_px - c_px),
+                r_px + s - c_px,
+            )
+            for s, c_px in zip(shape, cen_px, strict=True)
+        )
+        phantom[slc] += d * ball(len(shape) * (2 * r_px + 2,), r, center=r_px + cen % 1)[slc_ball]
+    return phantom
+
+
+def checkerboard(shape, boxsize=1):
+    ndim = len(shape)
+    boxsize = np.broadcast_to(boxsize, ndim)
+    coordinates = np.indices(shape)
+    stripes = (coordinates / (2 * np.expand_dims(boxsize, tuple(range(1, ndim + 1))))) % 1
+    stripes = (coordinates / boxsize[(slice(None),) + ndim * (None,)]) % 2 >= 1
+    return reduce(np.logical_xor, stripes)

hotopy/datasets/registry.txt

@@ -0,0 +1,9 @@
+phantom_dicty.npz d80a8ce6b4faef56057e79bee18b2303780f340c462132b398e3b61ad045738d https://gitlab.gwdg.de/irp/datasets/dataset-phantom-dicty/-/raw/master/phantom_dicty.npz
+phantom_world.npz 41ad9834121af5e94200927a0013cb4d9807a384790f1b157b76f87bac569374 https://gitlab.gwdg.de/irp/datasets/dataset-phantom-world/-/raw/master/phantom_world.npz
+holograms_radiodurans.npz 30d1b234124a6f4dd1d0c86bf24429c7ba509cf0e4b2cbdd71c8300f03e76873 https://gitlab.gwdg.de/irp/datasets/dataset-holograms-radiodurans/-/raw/master/holograms_radiodurans.npz
+holograms_beads.npz 27b6648c526f9272e6d492aa7f1de3a35172351fb0ecb84abc68e6711b6b9495 https://gitlab.gwdg.de/irp/datasets/dataset-holograms-beads/-/raw/master/holograms_beads.npz
+holograms_macrophage.npz 2f50a1a06b09cc8cf2246742daec4412fd638f005da5e84892fe3f33a9195c95 https://gitlab.gwdg.de/irp/datasets/dataset-holograms-macrophage/-/raw/master/holograms_macrophage.npz
+holograms_world.npz e9856299ad9d392b5253b3cdfe10edcb08f2e4aca3d67c48d645f74d11a4c78e https://gitlab.gwdg.de/irp/datasets/dataset-holograms-world/-/raw/master/holograms_world.npz
+holograms_spider.npz ea226167db6668b564698d7ce1c2f5c4c61da0ff3b9568ab6e08be1d71ce0dc1 https://gitlab.gwdg.de/irp/datasets/dataset-holograms-spider/-/raw/master/holograms_spider.npz
+holograms_logo.npz 45ae0903c4e79d3b1d56ab880bc290382bfec66577401ab9d01002aace3aad75 https://gitlab.gwdg.de/irp/datasets/dataset-holograms-logo/-/raw/main/holograms_logo.npz
+holograms_catparticle.npz.bz2 d058890d4985706124286cfa608d2a2b879814a1b2683b9272ed8b822e88515f https://gitlab.gwdg.de/irp/datasets/dataset-holograms-catparticle/-/raw/master/holograms_catparticle.npz.bz2

hotopy/holo/__init__.py

@@ -0,0 +1,124 @@
+"""
+=========================================================
+Holographic phase retrieval methods (:mod:`hotopy.holo`)
+=========================================================
+
+.. currentmodule:: hotopy.holo
+
+
+Submodules
+==========
+
+.. autosummary::
+    :toctree: generated/
+
+    propagation
+
+
+(Deep) Holographic regime phase retrieval
+-----------------------------------------
+
+For Fresnel numbers << 1 and monochromatic sources, e.g. at synchrotrons.
+
+.. autosummary::
+    :toctree: generated/
+
+    CTF
+    Tikhonov
+    TikhonovTV
+    AP
+    ICT
+
+
+Transport of Intensity Equation based methods (TIE)
+---------------------------------------------------
+
+Transport of Intensity (TIE) used for laboratory X-ray sources.
+
+.. autosummary::
+    :toctree: generated/
+
+    BronnikovAidedCorrection
+    ModifiedBronnikov
+    Paganin
+    GeneralizedPaganin
+
+
+Propagation methods
+-------------------
+
+Convenience imports from ``propagation`` submodule.
+
+.. autosummary::
+    :toctree: generated/
+
+    simulate_hologram
+
+Helpers
+-------
+
+.. autosummary::
+    :toctree: generated/
+
+    Constraints
+    rescale_defocus_series
+    rescale_defocus_fresnel_numbers
+    twolevel_regularization
+    ctf_erf_filter
+    erf_filter
+    find_fresnel_number
+    pca_decompose_flats
+    pca_synthesize_flat
+"""
+
+from .propagation import (
+    FresnelTFPropagator,
+    simulate_hologram,
+    expand_fresnel_numbers,
+)
+from .constraints import Constraints, WaveConstraints
+from ._tieregime import BronnikovAidedCorrection, ModifiedBronnikov, Paganin, GeneralizedPaganin
+from ._ctf import CTF
+from ._tikhonov import Tikhonov, TikhonovTV, nonlinearity_low_freq_correction
+from ._ap import AP
+from ._pbi import ICT
+from .regularization import erf_filter, ctf_erf_filter, twolevel_regularization
+from ._util import (
+    check_fresnel_number,
+    rescale_defocus_series,
+    rescale_defocus_fresnel_numbers,
+    find_fresnel_number,
+    difference_fresnel_numbers,
+    flatfield_inpainting_correction,
+)
+from ._pca import pca_decompose_flats, pca_synthesize_flat, pca_decompose_arpack
+
+__all__ = [
+    "FresnelTFPropagator",
+    "simulate_hologram",
+    "expand_fresnel_numbers",
+    "BronnikovAidedCorrection",
+    "ModifiedBronnikov",
+    "Paganin",
+    "GeneralizedPaganin",
+    "CTF",
+    "Tikhonov",
+    "TikhonovTV",
+    "ICT",
+    "AP",
+    "Constraints",
+    "WaveConstraints",
+    "nonlinearity_low_freq_correction",
+    "erf_filter",
+    "ctf_erf_filter",
+    "twolevel_regularization",
+    "check_fresnel_number",
+    "rescale_defocus_series",
+    "rescale_defocus_fresnel_numbers",
+    "find_fresnel_number",
+    "difference_fresnel_numbers",
+    "flatfield_inpainting_correction",
+    "pca_decompose_flats",
+    "pca_synthesize_flat",
+    "pca_decompose_arpack",
+]

hotopy/holo/_ap.py

@@ -0,0 +1,103 @@
+"""
+Author: Jens Lucht
+"""
+
+from numpy import ndarray, newaxis
+from torch import ones, as_tensor
+
+from ..optimize import AlternatingProjections
+from .propagation import FresnelTFPropagator
+from .constraints import AmplitudeProjector, ConstraintOperator, WaveConstraints
+
+
+class AP:
+    """Alternating projections for holographic phase retrieval."""
+
+    algorithm = AlternatingProjections
+
+    def __init__(
+        self,
+        shape,
+        fresnel_nums,
+        ndim=2,
+        dtype=None,
+        device=None,
+    ):
+        self.dtype = dtype
+        self.device = device
+        self.ndim = ndim
+
+        self.propagator = FresnelTFPropagator(
+            shape,
+            fresnel_nums,
+            dtype=dtype,
+            device=device,
+            keep_type=False,
+        )
+
+    def __call__(
+        self,
+        holograms,
+        constraints=None,
+        initial_guess=None,
+        max_iter: int = 100,
+        keep_type=False,
+    ):
+        """Reconstruct holograms.
+
+        Parameters
+        ----------
+        holograms :
+            Intensities measured at detector.
+        constraints :
+            Constraints projectors for object/sample. Default Amplitude = 1 constrain for pure-phase object.
+        max_iter : int, Optional
+            Maximal number of iterations.
+        """
+        holograms_t = type(holograms)
+        holograms = as_tensor(holograms, device=self.device)
+        shape = holograms.shape[-self.ndim :]
+
+        # if single image is entered expand to stack of one image
+        single_image = holograms.ndim == self.ndim
+        if single_image:
+            holograms = holograms[newaxis]
+
+        projector_holos = AmplitudeProjector(holograms.sqrt())
+        projector_object = (
+            constraints if constraints is not None else WaveConstraints(betadelta=0.0)
+        )
+
+        # ensure correct device placement
+        if isinstance(projector_object, ConstraintOperator):
+            projector_object.to_device(self.device)
+
+        # initialize with plane wave (ones) or initial guess if given
+        if initial_guess is None:
+            x = ones(shape, device=self.device, dtype=holograms.dtype)
+        else:
+            x = as_tensor(initial_guess, device=self.device)
+
+        # AP
+        ap = self.algorithm(
+            self.propagator,
+            (projector_object, projector_holos),
+            x,
+            max_iter=max_iter,
+        )
+
+        # iterate util stopping condition is met
+        while not ap.done():
+            ap.step()
+
+        # recast into numpy if requested
+        if keep_type and holograms_t is ndarray:
+            out = ap.x.cpu().numpy()
+        else:
+            out = ap.x
+
+        # remove stack axis if single image
+        if single_image:
+            out = out[0]
+
+        return out