waveorder 3.0.0a2__py3-none-any.whl → 3.0.0a3__py3-none-any.whl

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
     ------