waveorder 2.2.1__py3-none-any.whl → 3.0.0__py3-none-any.whl

waveorder/models/isotropic_fluorescent_thin_3d.py

@@ -0,0 +1,331 @@
+from typing import Literal, Tuple
+
+import numpy as np
+import torch
+from torch import Tensor
+
+from waveorder import optics, sampling, util
+from waveorder.filter import apply_filter_bank
+
+
+def generate_test_phantom(
+    yx_shape: tuple[int, int],
+    yx_pixel_size: float,
+    sphere_radius: float,
+) -> Tensor:
+    """Generate a test phantom for fluorescent thin object.
+
+    Parameters
+    ----------
+    yx_shape : tuple[int, int]
+        Shape of YX dimensions
+    yx_pixel_size : float
+        Pixel size in YX plane
+    wavelength_emission : float
+        Emission wavelength
+    sphere_radius : float
+        Radius of spherical phantom
+
+    Returns
+    -------
+    Tensor
+        YX fluorescence density map
+    """
+    sphere, _, _ = util.generate_sphere_target(
+        (3,) + yx_shape,
+        yx_pixel_size,
+        z_pixel_size=1.0,
+        radius=sphere_radius,
+        blur_size=2 * yx_pixel_size,
+    )
+
+    # Use middle slice as thin fluorescent object
+    yx_fluorescence_density = sphere[1]
+
+    return yx_fluorescence_density
+
+
+def calculate_transfer_function(
+    yx_shape: tuple[int, int],
+    yx_pixel_size: float,
+    z_position_list: list,
+    wavelength_emission: float,
+    index_of_refraction_media: float,
+    numerical_aperture_detection: float,
+    confocal_pinhole_diameter: float | None = None,
+) -> Tensor:
+    """Calculate transfer function for fluorescent thin object imaging.
+
+    Parameters
+    ----------
+    yx_shape : tuple[int, int]
+        Shape of YX dimensions
+    yx_pixel_size : float
+        Pixel size in YX plane
+    z_position_list : list
+        List of Z positions for defocus stack
+    wavelength_emission : float
+        Emission wavelength
+    index_of_refraction_media : float
+        Refractive index of imaging medium
+    numerical_aperture_detection : float
+        Numerical aperture of detection objective
+    confocal_pinhole_diameter : float | None, optional
+        Diameter of confocal pinhole. Not implemented for 2D fluorescence.
+
+    Returns
+    -------
+    Tensor
+        Fluorescent 2D-to-3D transfer function
+
+    Raises
+    ------
+    NotImplementedError
+        If confocal_pinhole_diameter is not None
+    """
+    if confocal_pinhole_diameter is not None:
+        raise NotImplementedError(
+            "Confocal reconstruction is not implemented for 2D fluorescence"
+        )
+
+    transverse_nyquist = sampling.transverse_nyquist(
+        wavelength_emission,
+        numerical_aperture_detection,  # ill = det for fluorescence
+        numerical_aperture_detection,
+    )
+    yx_factor = int(np.ceil(yx_pixel_size / transverse_nyquist))
+
+    fluorescent_2d_to_3d_transfer_function = (
+        _calculate_wrap_unsafe_transfer_function(
+            (
+                yx_shape[0] * yx_factor,
+                yx_shape[1] * yx_factor,
+            ),
+            yx_pixel_size / yx_factor,
+            z_position_list,
+            wavelength_emission,
+            index_of_refraction_media,
+            numerical_aperture_detection,
+        )
+    )
+
+    fluorescent_2d_to_3d_transfer_function_out = torch.zeros(
+        (len(z_position_list),) + tuple(yx_shape), dtype=torch.complex64
+    )
+
+    for z in range(len(z_position_list)):
+        fluorescent_2d_to_3d_transfer_function_out[z] = (
+            sampling.nd_fourier_central_cuboid(
+                fluorescent_2d_to_3d_transfer_function[z], yx_shape
+            )
+        )
+
+    return fluorescent_2d_to_3d_transfer_function_out
+
+
+def calculate_singular_system(
+    fluorescent_2d_to_3d_transfer_function: Tensor,
+) -> Tuple[Tensor, Tensor, Tensor]:
+    """Calculates the singular system of the fluorescent transfer function.
+
+    The transfer function has shape (Z, Vy, Vx), where (Z,) is the data-space
+    dimension, and (Vy, Vx) are the spatial frequency dimensions.
+
+    The SVD is computed over the (Z,) dimension.
+
+    Parameters
+    ----------
+    fluorescent_2d_to_3d_transfer_function : Tensor
+        ZYX transfer function for fluorescence
+
+    Returns
+    -------
+    Tuple[Tensor, Tensor, Tensor]
+        U, S, Vh components of the SVD
+    """
+    # For fluorescence, we have only one object property (fluorescence density)
+    # Input shape: (Z, Vy, Vx)
+
+    # We need to create the format: (1, Z, Vy, Vx) where 1 represents single object type
+    sfYX_transfer_function = fluorescent_2d_to_3d_transfer_function[None]
+
+    # Permute to: (Vy, Vx, 1, Z) for SVD
+    YXsf_transfer_function = sfYX_transfer_function.permute(2, 3, 0, 1)
+    Up, Sp, Vhp = torch.linalg.svd(YXsf_transfer_function, full_matrices=False)
+    # SVD gives us: Up: (Vy, Vx, 1, min(1,Z)), Sp: (Vy, Vx, min(1,Z)), Vhp: (Vy, Vx, min(1,Z), Z)
+
+    # Permute back to match expected format:
+    U = Up.permute(2, 3, 0, 1)  # (1, min(1,Z), Vy, Vx) -> (1, Z, Vy, Vx)
+    S = Sp.permute(2, 0, 1)  # (min(1,Z), Vy, Vx) -> (1, Vy, Vx)
+    Vh = Vhp.permute(2, 3, 0, 1)  # (min(1,Z), Z, Vy, Vx) -> (1, 1, Vy, Vx)
+    return U, S, Vh
+
+
+def _calculate_wrap_unsafe_transfer_function(
+    yx_shape: tuple[int, int],
+    yx_pixel_size: float,
+    z_position_list: list,
+    wavelength_emission: float,
+    index_of_refraction_media: float,
+    numerical_aperture_detection: float,
+) -> Tensor:
+    """Calculate wrap-unsafe transfer function for fluorescent imaging."""
+    radial_frequencies = util.generate_radial_frequencies(
+        yx_shape, yx_pixel_size
+    )
+
+    det_pupil = optics.generate_pupil(
+        radial_frequencies,
+        numerical_aperture_detection,
+        wavelength_emission,
+    )
+
+    propagation_kernel = optics.generate_propagation_kernel(
+        radial_frequencies,
+        det_pupil,
+        wavelength_emission / index_of_refraction_media,
+        torch.tensor(z_position_list),
+    )
+
+    zyx_shape = (len(z_position_list),) + tuple(yx_shape)
+    fluorescent_2d_to_3d_transfer_function = torch.zeros(
+        zyx_shape, dtype=torch.complex64
+    )
+
+    for z in range(len(z_position_list)):
+        # For fluorescent imaging, the transfer function is the squared magnitude
+        # of the coherent transfer function (incoherent imaging)
+        point_spread_function = (
+            torch.abs(torch.fft.ifft2(propagation_kernel[z], dim=(0, 1))) ** 2
+        )
+        fluorescent_2d_to_3d_transfer_function[z] = torch.fft.fft2(
+            point_spread_function
+        )
+
+    # Normalize
+    max_val = torch.max(torch.abs(fluorescent_2d_to_3d_transfer_function))
+    if max_val > 0:
+        fluorescent_2d_to_3d_transfer_function /= max_val
+
+    return fluorescent_2d_to_3d_transfer_function
+
+
+def visualize_transfer_function(
+    viewer,
+    fluorescent_2d_to_3d_transfer_function: Tensor,
+    zyx_scale: tuple[float, float, float],
+) -> None:
+    """Visualize the fluorescent transfer function in napari."""
+    arrays = [
+        (
+            torch.imag(fluorescent_2d_to_3d_transfer_function),
+            "Im(fluorescent TF)",
+        ),
+        (
+            torch.real(fluorescent_2d_to_3d_transfer_function),
+            "Re(fluorescent TF)",
+        ),
+    ]
+
+    for array in arrays:
+        lim = (0.5 * torch.max(torch.abs(array[0]))).item()
+        viewer.add_image(
+            torch.fft.ifftshift(array[0], dim=(1, 2)).cpu().numpy(),
+            name=array[1],
+            colormap="bwr",
+            contrast_limits=(-lim, lim),
+            scale=zyx_scale,
+        )
+    viewer.dims.order = (2, 0, 1)
+
+
+def apply_transfer_function(
+    yx_fluorescence_density: Tensor,
+    fluorescent_2d_to_3d_transfer_function: Tensor,
+    background: int = 10,
+) -> Tensor:
+    """Simulate fluorescent imaging by applying the transfer function.
+
+    Parameters
+    ----------
+    yx_fluorescence_density : Tensor
+        2D fluorescence density map
+    fluorescent_2d_to_3d_transfer_function : Tensor
+        3D transfer function
+    background : int, optional
+        Background counts, by default 10
+
+    Returns
+    -------
+    Tensor
+        Simulated 3D fluorescent data stack
+    """
+    # Simulate fluorescent object imaging
+    yx_fluorescence_hat = torch.fft.fftn(yx_fluorescence_density)
+    zyx_fluorescence_data_hat = yx_fluorescence_hat[None] * torch.real(
+        fluorescent_2d_to_3d_transfer_function
+    )
+    zyx_fluorescence_data = torch.real(
+        torch.fft.ifftn(zyx_fluorescence_data_hat, dim=(1, 2))
+    )
+
+    # Add background
+    data = zyx_fluorescence_data + background
+    return data
+
+
+def apply_inverse_transfer_function(
+    zyx_data: Tensor,
+    singular_system: Tuple[Tensor, Tensor, Tensor],
+    reconstruction_algorithm: Literal["Tikhonov", "TV"] = "Tikhonov",
+    regularization_strength: float = 1e-3,
+    TV_rho_strength: float = 1e-3,
+    TV_iterations: int = 10,
+) -> Tensor:
+    """Reconstruct fluorescence density from zyx_data and singular system.
+
+    Parameters
+    ----------
+    zyx_data : Tensor
+        3D raw data, fluorescence defocus stack
+    singular_system : Tuple[Tensor, Tensor, Tensor]
+        Singular system of the fluorescent transfer function
+    reconstruction_algorithm : Literal["Tikhonov", "TV"], optional
+        Reconstruction algorithm, by default "Tikhonov"
+        "TV" is not implemented
+    regularization_strength : float, optional
+        Regularization parameter, by default 1e-3
+    TV_rho_strength : float, optional
+        TV-specific regularization parameter, by default 1e-3
+        "TV" is not implemented
+    TV_iterations : int, optional
+        TV-specific number of iterations, by default 10
+        "TV" is not implemented
+
+    Returns
+    -------
+    Tensor
+        YX fluorescence density reconstruction
+
+    Raises
+    ------
+    NotImplementedError
+        TV is not implemented
+    """
+    if reconstruction_algorithm == "Tikhonov":
+        print("Computing inverse filter")
+        U, S, Vh = singular_system
+        S_reg = S / (S**2 + regularization_strength)
+        sfyx_inverse_filter = torch.einsum(
+            "sj...,j...,jf...->fs...", U, S_reg, Vh
+        )
+
+        # Apply filter bank - returns tuple but we only have one object type
+        yx_fluorescence_density = apply_filter_bank(
+            sfyx_inverse_filter, zyx_data
+        )[0]
+
+    elif reconstruction_algorithm == "TV":
+        raise NotImplementedError("TV reconstruction is not implemented")
+
+    return yx_fluorescence_density

waveorder/models/isotropic_thin_3d.py

@@ -5,6 +5,7 @@ import torch
 from torch import Tensor
 
 from waveorder import optics, sampling, util
+from waveorder.filter import apply_filter_bank
 
 
 def generate_test_phantom(
@@ -29,7 +30,7 @@ def generate_test_phantom(
         / wavelength_illumination
     )  # phase in radians
 
-    yx_absorption = 0.02 * sphere[1]
+    yx_absorption = torch.clone(yx_phase)
 
     return yx_absorption, yx_phase
 
@@ -103,9 +104,17 @@ def _calculate_wrap_unsafe_transfer_function(
     numerical_aperture_detection: float,
     invert_phase_contrast: bool = False,
 ) -> Tuple[Tensor, Tensor]:
-    if invert_phase_contrast:
-        z_position_list = torch.flip(torch.tensor(z_position_list), dims=(0,))
+    if numerical_aperture_illumination >= numerical_aperture_detection:
+        print(
+            "Warning: numerical_aperture_illumination is >= "
+            "numerical_aperture_detection. Setting "
+            "numerical_aperture_illumination to 0.9 * "
+            "numerical_aperture_detection to avoid singularities."
+        )
+        numerical_aperture_illumination = 0.9 * numerical_aperture_detection
 
+    if invert_phase_contrast:
+        z_position_list = [-1 * x for x in z_position_list]
     radial_frequencies = util.generate_radial_frequencies(
         yx_shape, yx_pixel_size
     )
@@ -148,6 +157,45 @@ def _calculate_wrap_unsafe_transfer_function(
     )
 
 
+def calculate_singular_system(
+    absorption_2d_to_3d_transfer_function: Tensor,
+    phase_2d_to_3d_transfer_function: Tensor,
+) -> Tuple[Tensor, Tensor, Tensor]:
+    """Calculates the singular system of the absoprtion and phase transfer
+    functions.
+
+    Together, the transfer functions form a (2, Z, Vy, Vx) tensor, where
+    (2,) is the object-space dimension (abs, phase), (Z,) is the data-space
+    dimension, and (Vy, Vx) are the spatial frequency dimensions.
+
+    The SVD is computed over the (2, Z) dimensions.
+
+    Parameters
+    ----------
+    absorption_2d_to_3d_transfer_function : Tensor
+        ZYX transfer function for absorption
+    phase_2d_to_3d_transfer_function : Tensor
+        ZYX transfer function for phase
+
+    Returns
+    -------
+    Tuple[Tensor, Tensor, Tensor]
+    """
+    sfYX_transfer_function = torch.stack(
+        (
+            absorption_2d_to_3d_transfer_function,
+            phase_2d_to_3d_transfer_function,
+        ),
+        dim=0,
+    )
+    YXsf_transfer_function = sfYX_transfer_function.permute(2, 3, 0, 1)
+    Up, Sp, Vhp = torch.linalg.svd(YXsf_transfer_function, full_matrices=False)
+    U = Up.permute(2, 3, 0, 1)
+    S = Sp.permute(2, 0, 1)
+    Vh = Vhp.permute(2, 3, 0, 1)
+    return U, S, Vh
+
+
 def visualize_transfer_function(
     viewer,
     absorption_2d_to_3d_transfer_function: Tensor,
@@ -166,7 +214,7 @@ def visualize_transfer_function(
     ]
 
     for array in arrays:
-        lim = 0.5 * torch.max(torch.abs(array[0]))
+        lim = (0.5 * torch.max(torch.abs(array[0]))).item()
         viewer.add_image(
             torch.fft.ifftshift(array[0], dim=(1, 2)).cpu().numpy(),
             name=array[1],
@@ -188,7 +236,7 @@ def visualize_point_spread_function(
     ]
 
     for array in arrays:
-        lim = 0.5 * torch.max(torch.abs(array[0]))
+        lim = (0.5 * torch.max(torch.abs(array[0]))).item()
         viewer.add_image(
             torch.fft.ifftshift(array[0], dim=(1, 2)).cpu().numpy(),
             name=array[1],
@@ -202,8 +250,8 @@ def visualize_point_spread_function(
 def apply_transfer_function(
     yx_absorption: Tensor,
     yx_phase: Tensor,
-    phase_2d_to_3d_transfer_function: Tensor,
     absorption_2d_to_3d_transfer_function: Tensor,
+    phase_2d_to_3d_transfer_function: Tensor,
 ) -> Tensor:
     # Very simple simulation, consider adding noise and bkg knobs
 
@@ -233,14 +281,13 @@ def apply_transfer_function(
 
 def apply_inverse_transfer_function(
     zyx_data: Tensor,
-    absorption_2d_to_3d_transfer_function: Tensor,
-    phase_2d_to_3d_transfer_function: Tensor,
+    singular_system: Tuple[Tensor, Tensor, Tensor],
     reconstruction_algorithm: Literal["Tikhonov", "TV"] = "Tikhonov",
-    regularization_strength: float = 1e-6,
+    regularization_strength: float = 1e-3,
     reg_p: float = 1e-6,  # TODO: use this parameter
     TV_rho_strength: float = 1e-3,
     TV_iterations: int = 10,
-    bg_filter: bool = True,
+    bg_filter: bool = False,
 ) -> Tuple[Tensor, Tensor]:
     """Reconstructs absorption and phase from zyx_data and a pair of
     3D-to-2D transfer functions named absorption_2d_to_3d_transfer_function and
@@ -251,15 +298,13 @@ def apply_inverse_transfer_function(
     ----------
     zyx_data : Tensor
         3D raw data, label-free defocus stack
-    absorption_2d_to_3d_transfer_function : Tensor
-        3D-to-2D absorption transfer function, see calculate_transfer_function above
-    phase_2d_to_3d_transfer_function : Tensor
-        3D-to-2D phase transfer function, see calculate_transfer_function above
-    reconstruction_algorithm : Literal["Tikhonov", "TV"], optional
+    singular_system : Tuple[Tensor, Tensor, Tensor]
+        singular system of the transfer function bank
+    reconstruction_algorithm : Literal["Tikhonov";, "TV";], optional
         "Tikhonov" or "TV", by default "Tikhonov"
         "TV" is not implemented.
     regularization_strength : float, optional
-        regularization parameter, by default 1e-6
+        regularization parameter, by default 1e-3
     reg_p : float, optional
         TV-specific phase regularization parameter, by default 1e-6
         "TV" is not implemented.
@@ -268,7 +313,7 @@ def apply_inverse_transfer_function(
         "TV" is not implemented.
     bg_filter : bool, optional
         option for slow-varying 2D background normalization with uniform filter
-        by default True
+        by default False
 
     Returns
     -------
@@ -281,66 +326,22 @@ def apply_inverse_transfer_function(
     NotImplementedError
         TV is not implemented
     """
-    zyx_data_normalized = util.inten_normalization(
-        zyx_data, bg_filter=bg_filter
-    )
+    # Normalize
+    zyx = util.inten_normalization(zyx_data, bg_filter=bg_filter)
 
-    zyx_data_hat = torch.fft.fft2(zyx_data_normalized, dim=(1, 2))
-
-    # TODO AHA and b_vec calculations should be moved into tikhonov/tv calculations
-    # TODO Reformulate to use filter.apply_filter_bank
-    AHA = [
-        torch.sum(torch.abs(absorption_2d_to_3d_transfer_function) ** 2, dim=0)
-        + regularization_strength,
-        torch.sum(
-            torch.conj(absorption_2d_to_3d_transfer_function)
-            * phase_2d_to_3d_transfer_function,
-            dim=0,
-        ),
-        torch.sum(
-            torch.conj(
-                phase_2d_to_3d_transfer_function,
-            )
-            * absorption_2d_to_3d_transfer_function,
-            dim=0,
-        ),
-        torch.sum(
-            torch.abs(
-                phase_2d_to_3d_transfer_function,
-            )
-            ** 2,
-            dim=0,
-        )
-        + reg_p,
-    ]
-
-    b_vec = [
-        torch.sum(
-            torch.conj(absorption_2d_to_3d_transfer_function) * zyx_data_hat,
-            dim=0,
-        ),
-        torch.sum(
-            torch.conj(
-                phase_2d_to_3d_transfer_function,
-            )
-            * zyx_data_hat,
-            dim=0,
-        ),
-    ]
-
-    # Deconvolution with Tikhonov regularization
+    # TODO Consider refactoring with vectorial transfer function SVD
     if reconstruction_algorithm == "Tikhonov":
-        absorption, phase = util.dual_variable_tikhonov_deconvolution_2d(
-            AHA, b_vec
+        print("Computing inverse filter")
+        U, S, Vh = singular_system
+        S_reg = S / (S**2 + regularization_strength)
+        sfyx_inverse_filter = torch.einsum(
+            "sj...,j...,jf...->fs...", U, S_reg, Vh
         )
 
+        absorption_yx, phase_yx = apply_filter_bank(sfyx_inverse_filter, zyx)
+
     # ADMM deconvolution with anisotropic TV regularization
     elif reconstruction_algorithm == "TV":
         raise NotImplementedError
-        absorption, phase = util.dual_variable_admm_tv_deconv_2d(
-            AHA, b_vec, rho=TV_rho_strength, itr=TV_iterations
-        )
-
-    phase -= torch.mean(phase)
 
-    return absorption, phase
+    return absorption_yx, phase_yx

waveorder/models/phase_thick_3d.py

@@ -10,15 +10,95 @@ from waveorder.models import isotropic_fluorescent_thick_3d
 from waveorder.reconstruct import tikhonov_regularized_inverse_filter
 from waveorder.visuals.napari_visuals import add_transfer_function_to_viewer
 
+"""
+Phase Thick 3D Model - Units and Conventions
+=============================================
+
+This module implements phase-from-defocus optical diffraction tomography (ODT) 
+for thick phase objects using the weak object transfer function (first Born 
+approximation).
+
+Units Convention
+----------------
+This model uses "cycles" as the fundamental unit for phase:
+    - 1 cycle = 2π radians = 1 wavelength of optical path difference
+
+Phantom (input):
+    Phase in cycles per voxel = (Δn × z_pixel_size) / λ_medium
+    where:
+        - Δn = n_sample - n_media (refractive index difference)
+        - z_pixel_size = voxel thickness
+        - λ_medium = λ_vacuum / n_media (wavelength in medium)
+
+Reconstruction (output):
+    Phase in cycles per voxel (same units as phantom)
+
+Converting Between Units
+------------------------
+From cycles to radians:
+    phase_radians = 2 * np.pi * phase_cycles
+
+From cycles to refractive index difference:
+    wavelength_medium = wavelength_vacuum / n_media
+    delta_n = phase_cycles * wavelength_medium / z_pixel_size
+
+From cycles to optical path length:
+    optical_path_length = phase_cycles * wavelength_medium
+
+Physics Background
+------------------
+The weak object approximation (first Born approximation) assumes:
+1. Small refractive index variations: |Δn| << n_media
+2. Weak scattering: no multiple scattering
+3. Linear relationship between object and measured intensity
+
+Reference
+---------
+J. M. Soto, J. A. Rodrigo, and T. Alieva, "Label-free quantitative 3D
+tomographic imaging for partially coherent light microscopy,"
+Opt. Express 25, 15699-15712 (2017)
+"""
+
 
 def generate_test_phantom(
     zyx_shape: tuple[int, int, int],
     yx_pixel_size: float,
     z_pixel_size: float,
+    wavelength_illumination: float,
     index_of_refraction_media: float,
     index_of_refraction_sample: float,
     sphere_radius: float,
 ) -> np.ndarray:
+    """
+    Generate a spherical phantom with phase in cycles per voxel.
+
+    Parameters
+    ----------
+    zyx_shape : tuple[int, int, int]
+        Shape of the 3D volume (Z, Y, X)
+    yx_pixel_size : float
+        Pixel size in transverse (Y, X) dimensions (length)
+    z_pixel_size : float
+        Pixel size in axial (Z) dimension (length)
+    wavelength_illumination : float
+        Wavelength of illumination light (length, same units as pixel sizes)
+    index_of_refraction_media : float
+        Refractive index of the surrounding medium
+    index_of_refraction_sample : float
+        Refractive index of the sphere
+    sphere_radius : float
+        Radius of the sphere (length, same units as pixel sizes)
+
+    Returns
+    -------
+    np.ndarray
+        3D array of phase in cycles per voxel.
+        Units: (n_sample - n_media) × z_pixel_size / λ_medium [cycles/voxel]
+
+        Each voxel value represents the phase shift (in cycles) that light
+        acquires when passing through that voxel. This matches the units
+        returned by apply_inverse_transfer_function().
+    """
     sphere, _, _ = util.generate_sphere_target(
         zyx_shape,
         yx_pixel_size,
@@ -26,9 +106,13 @@ def generate_test_phantom(
         radius=sphere_radius,
         blur_size=2 * yx_pixel_size,
     )
-    zyx_phase = sphere * (
-        index_of_refraction_sample - index_of_refraction_media
-    )  # refractive index increment
+
+    # Compute refractive index difference
+    delta_n = sphere * (index_of_refraction_sample - index_of_refraction_media)
+
+    # Convert to phase in cycles per voxel
+    wavelength_medium = wavelength_illumination / index_of_refraction_media
+    zyx_phase = delta_n * z_pixel_size / wavelength_medium
 
     return zyx_phase
 
@@ -234,7 +318,22 @@ def apply_inverse_transfer_function(
     Returns
     -------
     Tensor
-        zyx_phase (radians)
+        zyx_phase : Phase in cycles per voxel
+            Units: (Δn × z_pixel_size) / λ_medium [cycles/voxel]
+
+            Each voxel represents the phase shift (in cycles) that light acquires
+            when passing through that voxel. This matches the units of the input
+            phantom from generate_test_phantom().
+
+            To convert to phase in radians:
+                phase_radians = 2 * np.pi * zyx_phase
+
+            To convert to refractive index difference:
+                wavelength_medium = wavelength_illumination / index_of_refraction_media
+                delta_n = zyx_phase * wavelength_medium / z_pixel_size
+
+            Note: One cycle corresponds to 2π radians of phase shift, or one
+            wavelength of optical path length difference.
 
     Raises
     ------