janssen.plots

Plotting utilities for optical data visualization.

Extended Summary

Functions for visualizing optical wavefronts, diffraction patterns, and other data structures from the janssen package.

Routine Listings

plot_amplitude()

Plot the amplitude of an optical wavefront.

plot_complex_wavefront()

Plot a complex optical wavefront using HSV color mapping.

plot_intensity()

Plot the intensity of an optical wavefront.

plot_phase()

Plot the phase of an optical wavefront using HSV color mapping.

Notes

These plotting functions are designed for data visualization only and do not require JAX compatibility. They accept PyTree data structures from the janssen package.

janssen.plots.plot_amplitude(wavefront: OpticalWavefront, figsize: tuple[float, float] = (6, 5), cmap: str = 'gray', colorbar_location: Literal['top', 'bottom', 'left', 'right'] = 'right', colorbar_min: float | None = None, scalebar_length: float | None = None, scalebar_units: str = 'm', title: str | None = None) → tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] | tuple[matplotlib.figure.Figure, tuple[matplotlib.axes.Axes, matplotlib.axes.Axes]]

Plot the amplitude of an optical wavefront.

Parameters:

• wavefront (OpticalWavefront) – The optical wavefront to plot. Contains field, wavelength, dx, z_position, and polarization attributes.

• figsize (Tuple[float, float], optional) – Figure size in inches (width, height). Default is (6, 5).

• cmap (str, optional) – Colormap for the amplitude plot. Default is “gray”.

• colorbar_location (Literal[``”top”, ``"bottom", "left", "right"], optional) – Location of the colorbar. Default is “right”.

• colorbar_min (float | None, optional) – Minimum value for the colorbar. If None, uses the minimum value of the amplitude data. Default is None.

• scalebar_length (Optional[float], optional) – Length of the scalebar in the units specified by scalebar_units. If None, matplotlib-scalebar will choose automatically.

• scalebar_units (str, optional) – Units for the scalebar. Default is “m” (meters).

• title (Optional[str], optional) – Title for the figure. If None, no title is added.

Return type:

Union[tuple[Figure, Axes], tuple[Figure, tuple[Axes, Axes]]]

Returns:

• fig (Figure) – The matplotlib Figure object.

• ax (Axes or Tuple[Axes, Axes]) – The matplotlib Axes object. For polarized wavefronts, returns a tuple of two Axes (Ex, Ey).

Notes

The function plots the amplitude |U(x,y)| of the complex field. A colorbar is included to show the amplitude scale, sized to match the image dimensions.

A scalebar is added based on the wavefront’s dx (pixel size) parameter.

For polarized wavefronts (3D field with shape [H, W, 2]), two side-by-side plots are created showing Ex and Ey components.

janssen.plots.plot_complex_wavefront(wavefront: OpticalWavefront, figsize: tuple[float, float] = (6, 5), scalebar_length: float | None = None, scalebar_units: str = 'm', title: str | None = None) → tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] | tuple[matplotlib.figure.Figure, tuple[matplotlib.axes.Axes, matplotlib.axes.Axes]]

Plot a complex optical wavefront using HSV color mapping.

Parameters:

• wavefront (OpticalWavefront) – The optical wavefront to plot. Contains field, wavelength, dx, z_position, and polarization attributes.

• figsize (Tuple[float, float], optional) – Figure size in inches (width, height). Default is (6, 5).

• scalebar_length (Optional[float], optional) – Length of the scalebar in the units specified by scalebar_units. If None, matplotlib-scalebar will choose automatically.

• scalebar_units (str, optional) – Units for the scalebar. Default is “m” (meters).

• title (Optional[str], optional) – Title for the figure. If None, no title is added.

Return type:

Union[tuple[Figure, Axes], tuple[Figure, tuple[Axes, Axes]]]

Returns:

• fig (Figure) – The matplotlib Figure object.

• ax (Axes or Tuple[Axes, Axes]) – The matplotlib Axes object. For polarized wavefronts, returns a tuple of two Axes (Ex, Ey).

Notes

The function creates a single plot using HSV color mapping where:

• Hue: Represents the phase arg(U(x,y)), mapped from [-π, π] to [0, 1]

• Saturation: Set to 1 (fully saturated colors)

• Value: Represents the amplitude |U(x,y)|, normalized to [0, 1]

This representation allows simultaneous visualization of both amplitude and phase in a single image. Bright colors indicate high amplitude, while dark regions indicate low amplitude. The color itself encodes the phase.

A scalebar is added based on the wavefront’s dx (pixel size) parameter.

For polarized wavefronts (3D field with shape [H, W, 2]), two side-by-side plots are created showing Ex and Ey components.

janssen.plots.plot_intensity(wavefront: OpticalWavefront, figsize: tuple[float, float] = (6, 5), cmap: str = 'gray', colorbar_location: Literal['top', 'bottom', 'left', 'right'] = 'right', colorbar_min: float | None = None, scalebar_length: float | None = None, scalebar_units: str = 'm', title: str | None = None) → tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] | tuple[matplotlib.figure.Figure, tuple[matplotlib.axes.Axes, matplotlib.axes.Axes]]

Plot the intensity of an optical wavefront.

Parameters:

• wavefront (OpticalWavefront) – The optical wavefront to plot. Contains field, wavelength, dx, z_position, and polarization attributes.

• figsize (Tuple[float, float], optional) – Figure size in inches (width, height). Default is (6, 5).

• cmap (str, optional) – Colormap for the intensity plot. Default is “gray”.

• colorbar_location (Literal[``”top”, ``"bottom", "left", "right"], optional) – Location of the colorbar. Default is “right”.

• colorbar_min (float | None, optional) – Minimum value for the colorbar. If None, uses the minimum value of the intensity data. Default is None.

• scalebar_length (Optional[float], optional) – Length of the scalebar in the units specified by scalebar_units. If None, matplotlib-scalebar will choose automatically.

• scalebar_units (str, optional) – Units for the scalebar. Default is “m” (meters).

• title (Optional[str], optional) – Title for the figure. If None, no title is added.

Return type:

Union[tuple[Figure, Axes], tuple[Figure, tuple[Axes, Axes]]]

Returns:

• fig (Figure) – The matplotlib Figure object.

• ax (Axes or Tuple[Axes, Axes]) – The matplotlib Axes object. For polarized wavefronts, returns a tuple of two Axes (Ex, Ey).

Notes

The function plots the intensity |U(x,y)|² of the complex field. A colorbar is included to show the intensity scale, sized to match the image dimensions.

A scalebar is added based on the wavefront’s dx (pixel size) parameter.

For polarized wavefronts (3D field with shape [H, W, 2]), two side-by-side plots are created showing Ex and Ey components.

janssen.plots.plot_phase(wavefront: OpticalWavefront, figsize: tuple[float, float] = (6, 5), scalebar_length: float | None = None, scalebar_units: str = 'm', title: str | None = None) → tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] | tuple[matplotlib.figure.Figure, tuple[matplotlib.axes.Axes, matplotlib.axes.Axes]]

Plot the phase of an optical wavefront using HSV color mapping.

Parameters:

• wavefront (OpticalWavefront) – The optical wavefront to plot. Contains field, wavelength, dx, z_position, and polarization attributes.

• figsize (Tuple[float, float], optional) – Figure size in inches (width, height). Default is (6, 5).

• scalebar_length (Optional[float], optional) – Length of the scalebar in the units specified by scalebar_units. If None, matplotlib-scalebar will choose automatically.

• scalebar_units (str, optional) – Units for the scalebar. Default is “m” (meters).

• title (Optional[str], optional) – Title for the figure. If None, no title is added.

Return type:

Union[tuple[Figure, Axes], tuple[Figure, tuple[Axes, Axes]]]

Returns:

• fig (Figure) – The matplotlib Figure object.

• ax (Axes or Tuple[Axes, Axes]) – The matplotlib Axes object. For polarized wavefronts, returns a tuple of two Axes (Ex, Ey).

Notes

The function plots the phase arg(U(x,y)) using HSV color mapping where:

• Hue: Represents the phase, mapped from [-π, π] to [0, 1]

• Saturation: Set to 1 (fully saturated colors)

• Value: Set to 1 (full brightness)

This creates a uniform brightness image where only the color encodes the phase information. The cyclic nature of HSV hue naturally represents the cyclic nature of phase.

A scalebar is added based on the wavefront’s dx (pixel size) parameter.

For polarized wavefronts (3D field with shape [H, W, 2]), two side-by-side plots are created showing Ex and Ey components.