waveOrder

https://waveorder.readthedocs.io/en/latest/
Admin
waveOrder is a generalist Python framework for label-agnostic computational microscopy, enabling...
Tokens:46,444
Snippets:257
Trust Score:9.6
Update:2 hours ago
Show doc for...
Tokens:
Raw
### Install latest waveorder from GitHub with all dependencies

Source: https://waveorder.readthedocs.io/en/latest/

Install the latest version of waveorder from GitHub with all visualization dependencies (napari, jupyter), clone the repository, and run an example script.

```bash
pip install "git+https://github.com/mehta-lab/waveorder.git@main#egg=waveorder[all]"
git clone https://github.com/mehta-lab/waveorder.git
python waveorder/docs/examples/models/phase_thick_3d.py
```

--------------------------------

### Install waveorder with acquisition dependencies

Source: https://waveorder.readthedocs.io/en/latest/guide/QLIPP.html

Installs waveorder along with napari (with PyQt6) and pycro-manager dependencies using pip.

```bash
pip install waveorder[all]
```

--------------------------------

### Install waveorder without optional dependencies

Source: https://waveorder.readthedocs.io/en/latest/guide/QLIPP.html

Installs waveorder without napari, Qt bindings (PyQt/PySide), and pycro-manager dependencies.

```bash
pip install waveorder
```

--------------------------------

### Install waveorder in editable mode with development dependencies

Source: https://waveorder.readthedocs.io/en/latest/guide/development-guide.html

Installs waveorder in editable mode with all and dev extras. Run from the cloned waveorder directory.

```bash
cd waveorder
pip install -e ".[all,dev]"
```

--------------------------------

### Simulate and reconstruct with inplane_oriented_thick_pol3d_vector

Source: https://waveorder.readthedocs.io/en/latest/_downloads/5dfbce112adb9019c5779ae4ab82584a/inplane_oriented_thick_pol3d_vector.ipynb

This script demonstrates the full workflow: parameter setup, phantom generation, transfer function calculation, data simulation, and regularized inverse reconstruction. It uses napari for visualization and requires consistent units for all length parameters. The script pauses for user input between visualization steps.

```python
import napari
import torch

from waveorder.models import inplane_oriented_thick_pol3d_vector

# Parameters
# all lengths must use consistent units e.g. um
zyx_shape = (101, 256, 256)
swing = 0.1
scheme = "5-State"
yx_pixel_size = 6.5 / 63
z_pixel_size = 0.15
wavelength_illumination = 0.532
z_padding = 0
index_of_refraction_media = 1.3
numerical_aperture_illumination = 0.5
numerical_aperture_detection = 1.2
fourier_oversample_factor = 1

# Create a phantom
fzyx_object = inplane_oriented_thick_pol3d_vector.generate_test_phantom(
    zyx_shape
)

# Calculate transfer function
(
    sfZYX_transfer_function,
    intensity_to_stokes_matrix,
    singular_system,
) = inplane_oriented_thick_pol3d_vector.calculate_transfer_function(
    swing,
    scheme,
    zyx_shape,
    yx_pixel_size,
    z_pixel_size,
    wavelength_illumination,
    z_padding,
    index_of_refraction_media,
    numerical_aperture_illumination,
    numerical_aperture_detection,
    fourier_oversample_factor=fourier_oversample_factor,
)

# Display transfer function
viewer = napari.Viewer()
inplane_oriented_thick_pol3d_vector.visualize_transfer_function(
    viewer,
    sfZYX_transfer_function,
    zyx_scale=(z_pixel_size, yx_pixel_size, yx_pixel_size),
)

input("Showing transfer functions. Press <enter> to continue...")
viewer.layers.select_all()
viewer.layers.remove_selected()

# Simulate
szyx_data = inplane_oriented_thick_pol3d_vector.apply_transfer_function(
    fzyx_object,
    sfZYX_transfer_function,
    intensity_to_stokes_matrix,
)

# Display
arrays = [
    (szyx_data, "Data"),
    (fzyx_object, "Object"),
]

for array in arrays:
    viewer.add_image(torch.real(array[0]).cpu().numpy(), name=array[1])


# Reconstruct
for reg_strength in [0.005, 0.008, 0.01, 0.05, 0.1]:
    fzyx_object_recon = (
        inplane_oriented_thick_pol3d_vector.apply_inverse_transfer_function(
            szyx_data,
            singular_system,
            intensity_to_stokes_matrix,
            regularization_strength=reg_strength,
        )
    )
    viewer.add_image(
        torch.real(fzyx_object_recon).cpu().numpy(),
        name=f"Object - recon, reg_strength={reg_strength}",
    )

viewer.grid.enabled = True
viewer.grid.shape = (2, 5)
viewer.dims.axis_labels = ["COMPONENT", "Z", "Y", "X"]

input("Showing object, data, and recon. Press <enter> to quit...")
```

--------------------------------

### Plot OTF support with multiple color schemes and 3D viewer setup

Source: https://waveorder.readthedocs.io/en/latest/_downloads/c69307eb7ed739b3f2dcfcc2a88ab124/plot_vector_transfer_function_support.ipynb

This snippet demonstrates how to plot the OTF support for a given illumination and detection NA using waveorder's plot_otf_support. It iterates over a list of color and azimuth value pairs, then configures a napari viewer for 3D display with a dark theme, custom camera view, and grid. The script pauses for user input between plots.

```python
my_colors = [
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0.5) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0.5) % 1.0,
        ],
    ],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0) % 1.0,
        ],
    ],
    [["red", "red"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0.5) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0.5) % 1.0,
        ],
    ],
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [["cyan", "cyan"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0) % 1.0,
        ],
    ],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0.5) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0.5) % 1.0,
        ],
    ],
]

for my_color in my_colors:
    plot_otf_support(
        ill_na,
        det_na,
        N_theta=N_theta,
        N_phi=N_phi,
        top_cmap=my_color[0][0],
        bottom_cmap=my_color[0][1],
        top_azimuth_vals=my_color[1][0],
        bottom_azimuth_vals=my_color[1][1],
    )

viewer.theme = "dark"
viewer.dims.ndisplay = 3
viewer.camera.set_view_direction(
    view_direction=[-0.1, -1, -1], up_direction=[1, 0, 0]
)
viewer.camera.zoom = 250
viewer.grid.enabled = True
viewer.grid.stride = 2
viewer.grid.shape = (-1, 3)


input("Press Enter to close...")
plot_otf_support(
    det_na * 0.98,
    det_na,
    N_theta=N_theta,
    N_phi=N_phi,
    top_cmap="red",
    bottom_cmap="red",
    top_azimuth_vals=np.ones((N_phi,)),
    bottom_azimuth_vals=np.ones((N_phi,)),
)

input("Press Enter to close...")
```

--------------------------------

### Simulate and reconstruct isotropic fluorescent thick 3D data

Source: https://waveorder.readthedocs.io/en/latest/_downloads/2ed1c319efa18852845247f3e21adde8/isotropic_fluorescent_thick_3d.ipynb

This example uses waveorder's isotropic_fluorescent_thick_3d module to generate a test phantom, calculate the optical transfer function, simulate data, and reconstruct it. It requires napari for visualization and numpy. The simulation arguments specify a 3D shape of (200, 256, 256) with pixel sizes in micrometers. The transfer function arguments include emission wavelength, z-padding, refractive index, and numerical aperture. The script displays the transfer function and then the phantom, data, and reconstruction in napari, pausing for user input between displays.

```python
import napari
import numpy as np

from waveorder.models import isotropic_fluorescent_thick_3d

# Parameters
# all lengths must use consistent units e.g. um
simulation_arguments = {
    "zyx_shape": (200, 256, 256),
    "yx_pixel_size": 6.5 / 63,
    "z_pixel_size": 0.25,
}
phantom_arguments = {"sphere_radius": 5}
transfer_function_arguments = {
    "wavelength_emission": 0.532,
    "z_padding": 0,
    "index_of_refraction_media": 1.3,
    "numerical_aperture_detection": 1.2,
}

# Create a phantom
zyx_fluorescence_density = (
    isotropic_fluorescent_thick_3d.generate_test_phantom(
        **simulation_arguments, **phantom_arguments
    )
)

# Calculate transfer function
optical_transfer_function = (
    isotropic_fluorescent_thick_3d.calculate_transfer_function(
        **simulation_arguments, **transfer_function_arguments
    )
)

# Display transfer function
viewer = napari.Viewer()
zyx_scale = np.array(
    [
        simulation_arguments["z_pixel_size"],
        simulation_arguments["yx_pixel_size"],
        simulation_arguments["yx_pixel_size"],
    ]
)
isotropic_fluorescent_thick_3d.visualize_transfer_function(
    viewer,
    optical_transfer_function,
    zyx_scale,
)
input("Showing OTFs. Press <enter> to continue...")
viewer.layers.select_all()
viewer.layers.remove_selected()

# Simulate
zyx_data = isotropic_fluorescent_thick_3d.apply_transfer_function(
    zyx_fluorescence_density,
    optical_transfer_function,
    transfer_function_arguments["z_padding"],
)

# Reconstruct
zyx_recon = isotropic_fluorescent_thick_3d.apply_inverse_transfer_function(
    zyx_data,
    optical_transfer_function,
    transfer_function_arguments["z_padding"],
)

# Display
viewer.add_image(
    zyx_fluorescence_density.numpy(), name="Phantom", scale=zyx_scale
)
viewer.add_image(zyx_data.numpy(), name="Data", scale=zyx_scale)
viewer.add_image(zyx_recon.numpy(), name="Reconstruction", scale=zyx_scale)
input("Showing object, data, and recon. Press <enter> to quit...")
```

--------------------------------

### Create and activate conda environment for waveorder

Source: https://waveorder.readthedocs.io/en/latest/guide/QLIPP.html

Creates a new conda environment named 'waveorder' with Python 3.12 and activates it. This is an optional but recommended step before installing waveorder.

```bash
conda create -y -n waveorder python=3.12
conda activate waveorder
```

--------------------------------

### Convert GUI .ui file to .py with pyuic5

Source: https://waveorder.readthedocs.io/en/latest/guide/development-guide.html

Converts the Qt Creator .ui file to a Python file. pyuic5 is installed with PyQt5 in the waveorder conda environment.

```bash
pyuic5 -x gui.ui -o gui.py
```

--------------------------------

### Launch napari with waveorder plugin

Source: https://waveorder.readthedocs.io/en/latest/guide/QLIPP.html

Opens napari with the waveorder plugin enabled, providing access to the graphical user interface for reconstructions.

```bash
napari -w waveorder
```

--------------------------------

### View waveorder command-line help

Source: https://waveorder.readthedocs.io/en/latest/guide/software-installation-guide.html

Displays command-line help for waveorder.

```bash
waveorder
```

--------------------------------

### Module docstring and imports for waveorder.stokes

Source: https://waveorder.readthedocs.io/en/latest/_modules/waveorder/stokes.html

The module docstring describes the organization of functions and usage examples. It includes imports for numpy and torch.

```python
"""
Overview
--------

This module collects Stokes- and Mueller-related calculations.

The functions are roughly organized into groups:

1) Polarimeter instrument matrix functions
S2I = calculate_stokes_to_intensity_matrix(swing, scheme="5-State")
I2S = calculate_intensity_to_stokes_matrix(swing, scheme="5-State")

2) Forward functions (Stokes parameters following a optical element)
s0, s1, s2, s3 = stokes_after_adr(retardance, orientation, transmittance, depolarization, input="cpl")
s0, s1, s2 = stokes012_after_ar(retardance, orientation, transmittance, input="cpl")

3) Inverse functions (optical elements from Stokes parameters)
retardance, orientation, transmittance, depolarization = estimate_adr_from_stokes(s0, s1, s2, s3, input="cpl")
retardance, orientation, transmittance = estimate_ar_from_stokes012(s0, s1, s2, input="cpl")

4) A function for recovering Mueller matrices from Stokes vector
M = mueller_from_stokes(
    s0, s1, s2, s3, model="ar", direction="forward", input="cpl"
)

5) A convenience function for applying Mueller and instrument matrices
y = mmul(A, x)

Usage
-----

All functions are intended to be used with torch.Tensors with Stokes- or
Mueller-indices as the first axes.

For example, the following usage modes of stokes_after_adr are valid:

>>> stokes_after_adr(1, 1, 1, 1)

>>> retardance = torch.ones((2,3,4,5))
>>> orientation = torch.ones((2,3,4,5))
>>> transmittance = torch.ones((2,3,4,5))
>>> depolarization = torch.ones((2,3,4,5))
>>> stokes_after_adr(retardance, orientation, transmittance, depolarization)

>>> adr_params = torch.ones((4,2,3,4,5)) # first axis contains the Stokes indices
>>> stokes_after_adr(*adr_params) # * expands along the first axis

"""

import numpy as np
import torch
```

--------------------------------

### Configure napari viewer for 3D display

Source: https://waveorder.readthedocs.io/en/latest/_downloads/26a9bee9bb265871b6bfc27719de3205/plot_vector_transfer_function_support.py

Sets viewer theme to dark, enables 3D display, sets camera view direction and zoom, and enables grid with stride 2 and shape (-1, 3).

```python
viewer.theme = "dark"
viewer.dims.ndisplay = 3
viewer.camera.set_view_direction(
    view_direction=[-0.1, -1, -1], up_direction=[1, 0, 0]
)
viewer.camera.zoom = 250
viewer.grid.enabled = True
viewer.grid.stride = 2
viewer.grid.shape = (-1, 3)
```

--------------------------------

### Main loop for plotting OTF support with multiple colormaps

Source: https://waveorder.readthedocs.io/en/latest/_downloads/26a9bee9bb265871b6bfc27719de3205/plot_vector_transfer_function_support.py

Sets up output directory, defines parameters (N_phi, N_theta, det_na, ill_na), and iterates over a list of colormap configurations to call plot_otf_support for each.

```python
output_dir = "./output"
if not os.path.exists(output_dir):
    os.makedirs(output_dir)

N_phi = 50
N_theta = 100
det_na = 0.75
ill_na = 0.5

my_colors = [
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0) % 1.0,
        ],
    ],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0.5) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0.5) % 1.0,
        ],
    ],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0) % 1.0,
        ],
    ],
    [["red", "red"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0.5) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0.5) % 1.0,
        ],
    ],
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [["cyan", "cyan"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [["green", "purple"], [np.ones((N_phi,)), np.ones((N_phi,))]],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0) % 1.0,
        ],
    ],
    [
        ["hsv", "hsv"],
        [
            (np.linspace(0, 2, N_phi) + 0.5) % 1.0,
            -(np.linspace(0, 2, N_phi) + 0.5) % 1.0,
        ],
    ],
]

for my_color in my_colors:
    plot_otf_support(
        ill_na,
        det_na,
        N_theta=N_theta,
        N_phi=N_phi,
        top_cmap=my_color[0][0],
        bottom_cmap=my_color[0][1],
        top_azimuth_vals=my_color[1][0],
        bottom_azimuth_vals=my_color[1][1],
    )
```

--------------------------------

### Simulate and reconstruct 3D ODT with phase_thick_3d

Source: https://waveorder.readthedocs.io/en/latest/_downloads/e4de100f599575485fc0fc0a7424b8d4/phase_thick_3d.ipynb

This script demonstrates the full workflow for 3D partially coherent optical diffraction tomography using the waveorder.models.phase_thick_3d module. It creates a test phantom, calculates the transfer function, visualizes it with napari, simulates data, and reconstructs the phase. All lengths must use consistent units (e.g., micrometers). The script pauses for user input to view the transfer functions and final results.

```python
import napari
import numpy as np

from waveorder.models import phase_thick_3d

# Parameters
# all lengths must use consistent units e.g. um
simulation_arguments = {
    "zyx_shape": (100, 256, 256),
    "yx_pixel_size": 6.5 / 63,
    "z_pixel_size": 0.25,
    "index_of_refraction_media": 1.3,
}
phantom_arguments = {"index_of_refraction_sample": 1.50, "sphere_radius": 5}
transfer_function_arguments = {
    "z_padding": 0,
    "wavelength_illumination": 0.532,
    "numerical_aperture_illumination": 0.9,
    "numerical_aperture_detection": 1.2,
}

# Create a phantom
zyx_phase = phase_thick_3d.generate_test_phantom(
    **simulation_arguments, **phantom_arguments
)

# Calculate transfer function
(
    real_potential_transfer_function,
    imag_potential_transfer_function,
) = phase_thick_3d.calculate_transfer_function(
    **simulation_arguments, **transfer_function_arguments
)

# Display transfer function
viewer = napari.Viewer()
zyx_scale = np.array(
    [
        simulation_arguments["z_pixel_size"],
        simulation_arguments["yx_pixel_size"],
        simulation_arguments["yx_pixel_size"],
    ]
)
phase_thick_3d.visualize_transfer_function(
    viewer,
    real_potential_transfer_function,
    imag_potential_transfer_function,
    zyx_scale,
)
input("Showing OTFs. Press <enter> to continue...")
viewer.layers.select_all()
viewer.layers.remove_selected()

# Simulate
zyx_data = phase_thick_3d.apply_transfer_function(
    zyx_phase,
    real_potential_transfer_function,
    transfer_function_arguments["z_padding"],
    brightness=1e3,
)

# Reconstruct
zyx_recon = phase_thick_3d.apply_inverse_transfer_function(
    zyx_data,
    real_potential_transfer_function,
    imag_potential_transfer_function,
    transfer_function_arguments["z_padding"],
)

# Display
viewer.add_image(zyx_phase.numpy(), name="Phantom", scale=zyx_scale)
viewer.add_image(zyx_data.numpy(), name="Data", scale=zyx_scale)
viewer.add_image(zyx_recon.numpy(), name="Reconstruction", scale=zyx_scale)
input("Showing object, data, and recon. Press <enter> to quit...")
```

--------------------------------

### waveorder.cli.settings.FourierApplyInverseSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for applying inverse Fourier reconstruction.

```APIDOC
## FourierApplyInverseSettings

### Description
Settings class for applying inverse Fourier reconstruction.

### Module
waveorder.cli.settings

### Attributes
- **reconstruction_algorithm** - Algorithm used for reconstruction.
- **regularization_strength** - Strength of regularization.
- **TV_iterations** - Number of total variation iterations.
- **TV_rho_strength** - Strength of total variation rho.

### Methods
No methods documented.
```

--------------------------------

### waveorder.cli.settings.MyBaseModel

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Base model class in waveorder.cli.settings.

```APIDOC
## MyBaseModel

### Description
Base model class for settings.

### Module
waveorder.cli.settings

### Attributes
No attributes documented.

### Methods
No methods documented.
```

--------------------------------

### waveorder.cli.settings.PhaseSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for phase reconstruction.

```APIDOC
## PhaseSettings

### Description
Settings class for phase reconstruction.

### Module
waveorder.cli.settings

### Attributes
- **apply_inverse** - Attribute indicating whether to apply inverse.
- **transfer_function** - Attribute for transfer function settings.

### Methods
No methods documented.
```

--------------------------------

### Simulate and reconstruct 3D ODT with isotropic_thin_3d

Source: https://waveorder.readthedocs.io/en/latest/_downloads/d1a21e98ba9ec87534c73ffd3f806fdf/isotropic_thin_3d.ipynb

This Python script sets up simulation parameters, generates a test phantom, calculates transfer functions and singular system, simulates data, and reconstructs absorption and phase. It uses napari for visualization and requires consistent units (e.g., um). The script includes interactive inputs to pause between visualization steps.

```python
import napari
import numpy as np

from waveorder.models import isotropic_thin_3d

# Parameters
# all lengths must use consistent units e.g. um
simulation_arguments = {
    "yx_shape": (256, 256),
    "yx_pixel_size": 6.5 / 63,
    "wavelength_illumination": 0.532,
    "index_of_refraction_media": 1.3,
}
phantom_arguments = {"index_of_refraction_sample": 1.33, "sphere_radius": 5}
z_shape = 100
z_pixel_size = 0.25
zyx_scale = np.array(
    [
        z_pixel_size,
        simulation_arguments["yx_pixel_size"],
        simulation_arguments["yx_pixel_size"],
    ]
)
transfer_function_arguments = {
    "z_position_list": (np.arange(z_shape) - z_shape // 2) * z_pixel_size,
    "numerical_aperture_illumination": 0.9,
    "numerical_aperture_detection": 1.2,
}

# Create a disk phantom
yx_absorption, yx_phase = isotropic_thin_3d.generate_test_phantom(
    **simulation_arguments, **phantom_arguments
)
yx_absorption[:, 128:] = 0  # half absorbing
yx_phase[128:] = 0  # half phase

# Calculate transfer function
(
    absorption_2d_to_3d_transfer_function,
    phase_2d_to_3d_transfer_function,
) = isotropic_thin_3d.calculate_transfer_function(
    **simulation_arguments, **transfer_function_arguments
)

# Calculate singular system
singular_system = isotropic_thin_3d.calculate_singular_system(
    absorption_2d_to_3d_transfer_function,
    phase_2d_to_3d_transfer_function,
)

# Display transfer function
viewer = napari.Viewer()
zyx_scale = np.array(
    [
        z_pixel_size,
        simulation_arguments["yx_pixel_size"],
        simulation_arguments["yx_pixel_size"],
    ]
)
isotropic_thin_3d.visualize_transfer_function(
    viewer,
    absorption_2d_to_3d_transfer_function,
    phase_2d_to_3d_transfer_function,
)
input("Showing OTFs. Press <enter> to continue...")
viewer.layers.select_all()
viewer.layers.remove_selected()

# Simulate
zyx_data = isotropic_thin_3d.apply_transfer_function(
    yx_absorption,
    yx_phase,
    absorption_2d_to_3d_transfer_function,
    phase_2d_to_3d_transfer_function,
)

# Reconstruct
(
    yx_absorption_recon,
    yx_phase_recon,
) = isotropic_thin_3d.apply_inverse_transfer_function(
    zyx_data,
    singular_system,
    regularization_strength=1e-2,
)

# Display
arrays = [
    (yx_absorption, "Phantom - absorption"),
    (yx_phase, "Phantom - phase"),
    (zyx_data, "Data"),
    (yx_absorption_recon, "Reconstruction - absorption"),
    (yx_phase_recon, "Reconstruction - phase"),
]

for array in arrays:
    scale = zyx_scale[1:] if array[0].ndim == 2 else zyx_scale
    viewer.add_image(array[0].cpu().numpy(), name=array[1], scale=scale)

viewer.grid.enabled = True
viewer.dims.current_step = (z_shape // 2, 0, 0)

input("Showing object, data, and recon. Press <enter> to quit...")
```

--------------------------------

### waveorder.cli.settings.BirefringenceSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for birefringence reconstruction.

```APIDOC
## BirefringenceSettings

### Description
Settings class for birefringence reconstruction.

### Module
waveorder.cli.settings

### Attributes
- **apply_inverse** - Attribute indicating whether to apply inverse.
- **transfer_function** - Attribute for transfer function settings.

### Methods
No methods documented.
```

--------------------------------

### Run automated tests with pytest

Source: https://waveorder.readthedocs.io/en/latest/guide/development-guide.html

Runs the test suite. First run downloads ~50 MB of test data from Zenodo; subsequent runs reuse the downloaded data.

```bash
pytest
```

--------------------------------

### waveorder.cli.settings.ReconstructionSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for reconstruction.

```APIDOC
## ReconstructionSettings

### Description
Settings class for reconstruction.

### Module
waveorder.cli.settings

### Attributes
- **birefringence** - Birefringence settings.
- **fluorescence** - Fluorescence settings.
- **input_channel_names** - Names of input channels.
- **phase** - Phase settings.
- **reconstruction_dimension** - Dimension of reconstruction.
- **time_indices** - Time indices.

### Methods
- **validate_reconstruction_types()** - Class method to validate reconstruction types.
```

--------------------------------

### Activate waveorder environment

Source: https://waveorder.readthedocs.io/en/latest/guide/napari-plugin-guide.html

Activates the conda environment named 'waveorder' before launching napari.

```bash
conda activate waveorder
```

--------------------------------

### waveorder.cli.settings.FluorescenceSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for fluorescence reconstruction.

```APIDOC
## FluorescenceSettings

### Description
Settings class for fluorescence reconstruction.

### Module
waveorder.cli.settings

### Attributes
- **apply_inverse** - Attribute indicating whether to apply inverse.
- **transfer_function** - Attribute for transfer function settings.

### Methods
No methods documented.
```

--------------------------------

### Clone waveorder repository

Source: https://waveorder.readthedocs.io/en/latest/guide/development-guide.html

Clones the waveorder repository from GitHub to the current directory.

```bash
git clone https://github.com/mehta-lab/waveorder.git
```

--------------------------------

### Imports and base model for CLI settings

Source: https://waveorder.readthedocs.io/en/latest/_modules/waveorder/cli/settings.html

Imports required modules and defines MyBaseModel, which forbids extra parameters to guard against typos.

```python
import os
import warnings
from pathlib import Path
from typing import List, Literal, Optional, Union

from pydantic.v1 import (
    BaseModel,
    Extra,
    NonNegativeFloat,
    NonNegativeInt,
    PositiveFloat,
    root_validator,
    validator,
)

# This file defines the configuration settings for the CLI.

# Example settings files in `/docs/examples/settings/` are autmatically generated
# by the tests in `/tests/cli_tests/test_settings.py` - `test_generate_example_settings`.

# To keep the example settings up to date, run `pytest` locally when this file changes.


# All settings classes inherit from MyBaseModel, which forbids extra parameters to guard against typos

[docs]
class MyBaseModel(BaseModel, extra=Extra.forbid):
    pass
```

--------------------------------

### 3D ODT Simulation and Reconstruction with phase_thick_3d

Source: https://waveorder.readthedocs.io/en/latest/_downloads/a618ebc8ef09f4a1fddb271baaab82ba/phase_thick_3d.py

Complete script for simulating 3D partially coherent ODT. It generates a test phantom, calculates the transfer function, visualizes it, simulates data, and reconstructs the phase. Requires napari and numpy. All lengths must use consistent units (e.g., um). The script pauses for user input between visualization steps.

```python
"""
phase thick 3d
======================

# 3D partially coherent optical diffraction tomography (ODT) simulation
# 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)
"""

import napari
import numpy as np

from waveorder.models import phase_thick_3d

# Parameters
# all lengths must use consistent units e.g. um
simulation_arguments = {
    "zyx_shape": (100, 256, 256),
    "yx_pixel_size": 6.5 / 63,
    "z_pixel_size": 0.25,
    "index_of_refraction_media": 1.3,
}
phantom_arguments = {"index_of_refraction_sample": 1.50, "sphere_radius": 5}
transfer_function_arguments = {
    "z_padding": 0,
    "wavelength_illumination": 0.532,
    "numerical_aperture_illumination": 0.9,
    "numerical_aperture_detection": 1.2,
}

# Create a phantom
zyx_phase = phase_thick_3d.generate_test_phantom(
    **simulation_arguments, **phantom_arguments
)

# Calculate transfer function
(
    real_potential_transfer_function,
    imag_potential_transfer_function,
) = phase_thick_3d.calculate_transfer_function(
    **simulation_arguments, **transfer_function_arguments
)

# Display transfer function
viewer = napari.Viewer()
zyx_scale = np.array(
    [
        simulation_arguments["z_pixel_size"],
        simulation_arguments["yx_pixel_size"],
        simulation_arguments["yx_pixel_size"],
    ]
)
phase_thick_3d.visualize_transfer_function(
    viewer,
    real_potential_transfer_function,
    imag_potential_transfer_function,
    zyx_scale,
)
input("Showing OTFs. Press <enter> to continue...")
viewer.layers.select_all()
viewer.layers.remove_selected()

# Simulate
zyx_data = phase_thick_3d.apply_transfer_function(
    zyx_phase,
    real_potential_transfer_function,
    transfer_function_arguments["z_padding"],
    brightness=1e3,
)

# Reconstruct
zyx_recon = phase_thick_3d.apply_inverse_transfer_function(
    zyx_data,
    real_potential_transfer_function,
    imag_potential_transfer_function,
    transfer_function_arguments["z_padding"],
)

# Display
viewer.add_image(zyx_phase.numpy(), name="Phantom", scale=zyx_scale)
viewer.add_image(zyx_data.numpy(), name="Data", scale=zyx_scale)
viewer.add_image(zyx_recon.numpy(), name="Reconstruction", scale=zyx_scale)
input("Showing object, data, and recon. Press <enter> to quit...")
```

--------------------------------

### MyBaseModel

Source: https://waveorder.readthedocs.io/en/latest/api/settings.html

Base model class for settings, likely providing common Pydantic functionality.

```APIDOC
## MyBaseModel

### Description
Base model class for settings, likely providing common Pydantic functionality.

### Class
`waveorder.cli.settings.MyBaseModel`

```

--------------------------------

### Plot Green's tensor spectrum with napari

Source: https://waveorder.readthedocs.io/en/latest/_downloads/0dd61aec2177bae383cde09aaf2e3924/plot_greens_tensor.py

This script calculates the Green's tensor spectrum using waveorder's optics.generate_greens_tensor_spectrum, applies a spherical shell mask, and visualizes positive and negative imaginary parts as surfaces in napari. It sets up a 3D viewer, iterates over tensor components, and saves screenshots. Requires napari, torch, scipy, skimage, and waveorder.

```python
import os

import napari
import numpy as np
import torch
from napari.experimental import link_layers
from scipy.ndimage import gaussian_filter
from skimage import measure

from waveorder import optics, util

# Parameters
# all lengths must use consistent units e.g. um
output_dirpath = "./greens_plots"
os.makedirs(output_dirpath, exist_ok=True)
grid_size = 100  # 300 for publication
blur_width = grid_size // 35  # blurring to smooth sharp corners
zyx_shape = 3 * (grid_size,)
yx_pixel_size = 6.5 / 63
z_pixel_size = 6.5 / 63
wavelength_illumination = 0.532
index_of_refraction_media = 1.3
threshold = 0.5  # for marching cubes


# Calculate coordinate grids
zyx_pixel_size = (z_pixel_size, yx_pixel_size, yx_pixel_size)
y_frequencies, x_frequencies = util.generate_frequencies(
    zyx_shape[1:], yx_pixel_size
)
radial_frequencies = torch.sqrt(x_frequencies**2 + y_frequencies**2)
z_position_list = torch.fft.ifftshift(
    (torch.arange(zyx_shape[0]) - zyx_shape[0] // 2) * z_pixel_size
)
z_frequencies = torch.fft.fftfreq(zyx_shape[0], d=z_pixel_size)

freq_shape = z_position_list.shape + x_frequencies.shape
z_broadcast = torch.broadcast_to(z_frequencies[:, None, None], freq_shape)
y_broadcast = torch.broadcast_to(y_frequencies[None, :, :], freq_shape)
x_broadcast = torch.broadcast_to(x_frequencies[None, :, :], freq_shape)
nu_rr = torch.sqrt(z_broadcast**2 + y_broadcast**2 + x_broadcast**2)

freq_voxel_size = [1 / (d * n) for d, n in zip(zyx_pixel_size, zyx_shape)]

# Calculate Greens tensor spectrum
G_3D = optics.generate_greens_tensor_spectrum(
    zyx_shape=zyx_shape,
    zyx_pixel_size=zyx_pixel_size,
    wavelength=wavelength_illumination / index_of_refraction_media,
)

# Mask to zero outside of a spherical shell
wavelength = wavelength_illumination / index_of_refraction_media
nu_max = (33 / 32) / (wavelength)
nu_min = (31 / 32) / (wavelength)
mask = torch.logical_and(nu_rr < nu_max, nu_rr > nu_min)
G_3D *= mask

# Split into positve and negative imaginary parts
G3D_imag = torch.imag(torch.fft.fftshift(G_3D, dim=(-3, -2, -1)))
G_pos = G3D_imag * (G3D_imag > 0)
G_neg = G3D_imag * (G3D_imag < 0)

# Blur to reduce aliasing
sigma = (
    0,
    0,
) + 3 * (blur_width,)
G_pos = gaussian_filter(np.array(G_pos), sigma=sigma)
G_neg = gaussian_filter(np.array(G_neg), sigma=sigma)

# Add to napari
viewer = napari.Viewer()

viewer.theme = "light"
viewer.dims.ndisplay = 3
viewer.camera.zoom = 100

for i in range(3):
    for j in range(3):
        name = f"{i}_{j}"

        volume = G_pos[i, j]
        verts, faces, normals, _ = measure.marching_cubes(
            volume, level=threshold * np.max(volume)
        )
        viewer.add_surface(
            (verts, faces),
            name=name + "-positive-surface",
            colormap="greens",
            scale=freq_voxel_size,
            shading="smooth",
        )

        volume = -G_neg[i, j]
        if i != j:
            verts, faces, normals, _ = measure.marching_cubes(
                volume, level=threshold * np.max(volume)
            )
            viewer.add_surface(
                (verts, faces),
                opacity=1.0,
                name=name + "-negative-surface",
                colormap="I Purple",
                scale=freq_voxel_size,
                blending="translucent",
                shading="smooth",
            )
        else:
            viewer.add_surface(
                (
                    np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]]),
                    np.array([[0, 1, 2]]),
                ),
                opacity=1.0,
                name=name + "-dummy-surface",
                colormap="gray",
                scale=freq_voxel_size,
                blending="translucent",
                shading="smooth",
            )
        link_layers(viewer.layers[-2:])

        print(f"Screenshotting {i}_{j}")
        viewer.camera.set_view_direction(
            view_direction=[-1, -1, -1], up_direction=[0, 0, 1]
        )
        viewer.screenshot(
            os.path.join(output_dirpath, f"{i}_{j}.png"), scale=2
        )
        viewer.layers[-1].visible = False
        viewer.layers[-2].visible = False

# Show in complete grid
for layer in viewer.layers:
    layer.visible = True
viewer.grid.enabled = True
viewer.grid.stride = 2
viewer.grid.shape = (-1, 3)
viewer.theme = "dark"
napari.run()
```

--------------------------------

### Two-step reconstruction with compute-tf and apply-inv-tf

Source: https://waveorder.readthedocs.io/en/latest/guide/reconstruction-guide.html

Equivalent to the single 'reconstruct' call, this workflow first computes the transfer function with 'compute-tf' and then applies it with 'apply-inv-tf'. Saving the transfer function can save time when applying to many datasets.

```shell
waveorder compute-tf `
    -i ./data.zarr/0/0/0 `
    -c ./config.yml `
    -o ./tf.zarr

waveorder apply-inv-tf
    -i ./data.zarr/*/*/* `
    -t ./tf.zarr `
    -c ./config.yml `
    -o ./reconstruction.zarr
```

--------------------------------

### waveorder.cli.settings.FluorescenceTransferFunctionSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for fluorescence transfer function.

```APIDOC
## FluorescenceTransferFunctionSettings

### Description
Settings class for fluorescence transfer function.

### Module
waveorder.cli.settings

### Attributes
- **wavelength_emission** - Emission wavelength.

### Methods
- **warn_unit_consistency()** - Class method to warn about unit consistency.
```

--------------------------------

### Replace PyQt5 imports with qtpy in gui.py (macOS)

Source: https://waveorder.readthedocs.io/en/latest/guide/development-guide.html

Modifies gui.py to import qtpy instead of PyQt5 for napari plugin best practices. This command is for BSD sed; omit '' with GNU sed.

```bash
sed -i '' 's/from PyQt5/from qtpy/g' gui.py
```

--------------------------------

### BirefringenceApplyInverseSettings with background_path validator

Source: https://waveorder.readthedocs.io/en/latest/_modules/waveorder/cli/settings.html

Defines apply-inverse settings for birefringence, including a validator that checks the background_path directory exists.

```python
[docs]
class BirefringenceApplyInverseSettings(WavelengthIllumination):
    background_path: Union[str, Path] = ""
    remove_estimated_background: bool = False
    flip_orientation: bool = False
    rotate_orientation: bool = False


[docs]
    @validator("background_path")
    def check_background_path(cls, v):
        if v == "":
            return v

        raw_dir = r"{}".format(v)
        if not os.path.isdir(raw_dir):
            raise ValueError(f"{v} is not a existing directory")
        return raw_dir
```

--------------------------------

### Simulate and reconstruct in-plane oriented thick pol3d

Source: https://waveorder.readthedocs.io/en/latest/_downloads/1ef732dc605723bd8fac220a1f1c0ab8/inplane_oriented_thick_pol3d.py

This script creates a phantom, calculates the transfer function, visualizes it, simulates data, reconstructs the object, and displays results in napari. It requires consistent units for lengths and uses the '5-State' scheme with a swing of 0.1.

```python
import napari

from waveorder.models import inplane_oriented_thick_pol3d

# Parameters
# all lengths must use consistent units e.g. um
simulation_arguments = {"yx_shape": (256, 256)}
transfer_function_arguments = {"swing": 0.1, "scheme": "5-State"}

# Create a phantom
inplane_oriented_parameters = (
    inplane_oriented_thick_pol3d.generate_test_phantom(**simulation_arguments)
)

# Calculate transfer function
intensity_to_stokes_matrix = (
    inplane_oriented_thick_pol3d.calculate_transfer_function(
        **transfer_function_arguments
    )
)

# Display transfer function
viewer = napari.Viewer()
inplane_oriented_thick_pol3d.visualize_transfer_function(
    viewer, intensity_to_stokes_matrix
)
input("Showing transfer functions. Press <enter> to continue...")
viewer.layers.select_all()
viewer.layers.remove_selected()

# Simulate
czyx_data = inplane_oriented_thick_pol3d.apply_transfer_function(
    *inplane_oriented_parameters,
    intensity_to_stokes_matrix,
)

# Reconstruct
inplane_oriented_parameters_recon = (
    inplane_oriented_thick_pol3d.apply_inverse_transfer_function(
        czyx_data, intensity_to_stokes_matrix
    )
)

# Display
arrays = [
    (inplane_oriented_parameters_recon[3], "Depolarization - recon"),
    (inplane_oriented_parameters_recon[2], "Transmittance - recon"),
    (inplane_oriented_parameters_recon[1], "Orientation (rad) - recon"),
    (inplane_oriented_parameters_recon[0], "Retardance (rad) - recon"),
    (czyx_data, "Data"),
    (inplane_oriented_parameters[3], "Depolarization"),
    (inplane_oriented_parameters[2], "Transmittance"),
    (inplane_oriented_parameters[1], "Orientation (rad)"),
    (inplane_oriented_parameters[0], "Retardance (rad)"),
]

for array in arrays:
    viewer.add_image(array[0].cpu().numpy(), name=array[1])

viewer.grid.enabled = True
viewer.grid.shape = (2, 5)
input("Showing object, data, and recon. Press <enter> to quit...")
```

--------------------------------

### waveorder.cli.settings.BirefringenceApplyInverseSettings

Source: https://waveorder.readthedocs.io/en/latest/genindex.html

Class in waveorder.cli.settings that defines settings for applying inverse birefringence reconstruction.

```APIDOC
## BirefringenceApplyInverseSettings

### Description
Settings class for applying inverse birefringence reconstruction.

### Module
waveorder.cli.settings

### Attributes
- **background_path** - Path to background image.
- **flip_orientation** - Flag to flip orientation.
- **remove_estimated_background** - Flag to remove estimated background.
- **rotate_orientation** - Flag to rotate orientation.

### Methods
- **check_background_path()** - Class method to check the background path.
```

--------------------------------

### PhaseSettings

Source: https://waveorder.readthedocs.io/en/latest/api/settings.html

Top-level settings for phase reconstruction, containing transfer function and apply-inverse settings.

```APIDOC
## PhaseSettings

### Description
Top-level settings for phase reconstruction, containing transfer function and apply-inverse settings.

### Class
`waveorder.cli.settings.PhaseSettings`

### Fields
- **transfer_function** (PhaseTransferFunctionSettings) - Default: `PhaseTransferFunctionSettings(wavelength_illumination=0.532, yx_pixel_size=0.325, z_pixel_size=2.0, z_padding=0, z_focus_offset=0, index_of_refraction_media=1.3, numerical_aperture_detection=1.2, numerical_aperture_illumination=0.5, invert_phase_contrast=False)` - Transfer function settings.
- **apply_inverse** (FourierApplyInverseSettings) - Default: `FourierApplyInverseSettings(reconstruction_algorithm='Tikhonov', regularization_strength=0.001, TV_rho_strength=0.001, TV_iterations=1)` - Apply inverse settings.

```

--------------------------------

### Run single-step reconstruction with waveorder reconstruct

Source: https://waveorder.readthedocs.io/en/latest/guide/reconstruction-guide.html

Performs a full reconstruction in one call using the 'reconstruct' subcommand. The input flag accepts a list of positions via wildcards, and the configuration file specifies reconstruction parameters.

```shell
waveorder reconstruct `
    -i ./data.zarr/*/*/* `
    -c ./config.yml `
    -o ./reconstruction.zarr
```
Tokens:
Raw