ptyrax.initializers

ptyrax.initializers#

Functions

aperture(sampling[, radius, dtype, scale, ...])

Generates a corresponding to an aperture.

binary_complex_image(sampling, image_path[, ...])

Load an image and produce a binary complex-valued initializer.

binary_reflection_image(sampling, image_path)

Build a binary complex reflection-image initializer from an input image.

custom(sampling[, weight, std, radius, ...])

Compose a custom initializer by mixing a Gaussian probe with a shifted variant.

from_test_images(sampling[, ...])

Create a complex initializer from two test images (amplitude and phase).

gaussian(sampling[, std, radius, ...])

Create a Gaussian-like initializer on the given sampling grid.

probe_initializer_from_gt(sampling, pixel_size)

Initialize a probe field from a ground-truth HDF5 file.

random(sampling, *args, **kwargs)

Random complex initializer on sampling.

random_phase_mask(sampling[, scale, normalize])

Create a random phase mask initializer.

separate_sampling_grid(func)

Decorator to adapt initializer functions to accept a chromatix SamplingGrid.

siemens_star(sampling[, num_spokes, radius, ...])

Generate a Siemens star test pattern on the given sampling grid.

speckle(sampling[, std, radius, ...])

Create a speckle-pattern initializer on a sampling grid.

support(sampling[, size, decay_length, ...])

Generate a support constraint weight map.

uniform(sampling, *args[, scale, normalize])

Uniform initializer that returns a constant complex field on sampling.

usaf_test_target(sampling[, high_amplitude, ...])

Create a USAF 1951 resolution test target initializer from SVG.
ptyrax.initializers.aperture(sampling, radius=None, dtype=<class 'jax.numpy.complex64'>, scale=(1+0j), normalize=True, defocus=0.0, **kwargs)[source]#

Generates a corresponding to an aperture.

Parameters:

  • shape (tuple[int, ...]) – The shape of the field.

  • radius (Union[None, float, jnp.ndarray]) – The radius of the aperture.

  • dtype (jnp.dtype) – The data type of the field.

  • scale (Union[None, complex, float]) – scales the field by a constant multiplier.

  • **kwargs – Additional keyword arguments.

  • sampling (SamplingGrid)

  • normalize (bool)

  • defocus (float)

Returns:

The generated aperture field as an (M, N, 1) jax array.

Return type:

Array

ptyrax.initializers.binary_complex_image(sampling, image_path, image_pixel_size=1.0, scale=1.0, image_shift=(0.0, 0.0), threshold=0.5, high_amplitude=1.0, high_phase=0.0, low_amplitude=0.0, low_phase=0.0, normalize=False)[source]#

Load an image and produce a binary complex-valued initializer.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid for the initializer.

  • image_path (Path | str) – Path to the input image.

  • image_pixel_size (float) – Pixel size of the input image.

  • image_shift (tuple[float, float]) – (x,y) shift to apply when mapping to the target grid.

  • threshold (float) – Threshold to binarize the image.

  • scale (float)

  • high_amplitude (float)

  • high_phase (float)

  • low_amplitude (complex)

  • low_phase (complex)

  • normalize (bool)

Returns:

Complex array shaped to sampling representing the binary initializer.

Return type:

Complex[Array, ‘m n’]

ptyrax.initializers.binary_reflection_image(sampling, image_path, image_pixel_size=1.0, image_shift=(0.0, 0.0), threshold=0.5, high_refl_material='Al', high_trans_material=None, low_refl_material='Si', low_trans_material=None, wavelength=1.0, angle_of_incidence=0.0, thickness=0.0, thickness_wavelength_units=False, polarization='p')[source]#

Build a binary complex reflection-image initializer from an input image.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • image_path (Path | str) – Path to the input image.

  • image_pixel_size (float) – Pixel size of the input image.

  • threshold (float) – Threshold to binarize.

  • high_refl_material/low_refl_material – Material identifiers for reflection coefficients.

  • image_shift (tuple[float, float])

  • high_refl_material (str)

  • high_trans_material (str)

  • low_refl_material (str)

  • low_trans_material (str)

  • wavelength (float)

  • angle_of_incidence (float)

  • thickness (float)

  • thickness_wavelength_units (bool)

  • polarization (Literal['s', 'p'])

Returns:

Complex array shaped to sampling representing reflection coefficients.

Return type:

Complex[Array, ‘m n’]

ptyrax.initializers.custom(sampling, weight=1.0, std=None, radius=None, noise_level=0.1, defocus=0.0, scale=1.0, *, key, **kwargs)[source]#

Compose a custom initializer by mixing a Gaussian probe with a shifted variant.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • weight (float) – Mixing weight between base and shifted probe.

  • std (float | tuple[float, float] | Array | ndarray | bool | number | bool | int | complex | LiteralArray)

  • radius (float)

  • noise_level (float)

  • defocus (float)

  • scale (float)

  • key (Key)

Returns:

Complex array shaped to sampling.

Return type:

Array | ndarray | bool | number | bool | int | float | complex | LiteralArray

ptyrax.initializers.from_test_images(sampling, amplitude_image='camera', phase_image='astronaut')[source]#

Create a complex initializer from two test images (amplitude and phase).

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • amplitude_image (str) – Name of skimage test image to use for amplitude.

  • phase_image (str) – Name of skimage test image to use for phase.

Returns:

Complex array shaped to sampling.

Return type:

Complex[Array, ‘m n’]

ptyrax.initializers.gaussian(sampling, std=None, radius=None, noise_level=0.0, defocus=0.0, NA=None, wavelength=1.0, scale=1 + 0j, normalize=False, *, key=None, **kwargs)[source]#

Create a Gaussian-like initializer on the given sampling grid.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • std (float) – Standard deviation (or radius) of the Gaussian in pixels.

  • noise_level (float) – Uniform noise amplitude to add.

  • defocus (float | tuple[float, float]) – Optional defocus phase to multiply with.

  • radius (float)

  • NA (float | tuple[float, float])

  • wavelength (float)

  • scale (complex)

  • normalize (bool)

  • key (Key)

Returns:

Complex or real array shaped to sampling representing the Gaussian initializer.

Return type:

Array | ndarray | bool | number | bool | int | float | complex | LiteralArray

ptyrax.initializers.probe_initializer_from_gt(sampling, pixel_size, dtype=<class 'jax.numpy.complex64'>)[source]#

Initialize a probe field from a ground-truth HDF5 file.

Loads probe data from data/SI0007_ground_truth.hdf5, rescales to match the target pixel size, and crops or pads to fit the sampling grid.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • pixel_size (Array | ndarray | bool | number | bool | int | float | complex | LiteralArray) – Desired pixel size for the output probe.

  • dtype (dtype) – Data type for the returned array.

Returns:

Complex probe array shaped to sampling.

Return type:

ndarray

ptyrax.initializers.random(sampling, *args, **kwargs)[source]#

Random complex initializer on sampling.

Parameters:

sampling (SamplingGrid) – Target sampling grid.

Returns:

Random complex array shaped to sampling.

Return type:

Float[Array, ‘* m n’]

ptyrax.initializers.random_phase_mask(sampling, scale=1.0, normalize=False, *, key, **kwargs)[source]#

Create a random phase mask initializer.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • scale (float) – Scaling factor for phase amplitude.

  • normalize (bool) – Whether to normalize the output.

  • key (Key)

Returns:

Complex phase mask array shaped to sampling.

Return type:

Float[Array, ‘m n’]

ptyrax.initializers.separate_sampling_grid(func)[source]#

Decorator to adapt initializer functions to accept a chromatix SamplingGrid.

Converts a function that takes (shape, pixel_size, ...) into one that takes (sampling: SamplingGrid, ...) by extracting shape and pixel_size from the grid.

Parameters:

func (Callable) – Initializer function with signature (shape, pixel_size, ...).

Returns:

Wrapped function accepting a SamplingGrid as first argument.

Return type:

Callable

ptyrax.initializers.siemens_star(sampling, num_spokes=36, radius=None, anti_aliasing_factor=1.0, normalize=True, min_value=0.0, max_value=1.0, **kwargs)[source]#

Generate a Siemens star test pattern on the given sampling grid.

Uses chromatix to generate the spoke pattern and applies an anti-aliasing low-pass filter in the far field.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • num_spokes (int) – Number of spokes in the star.

  • radius (float) – Physical radius of the star; defaults to quarter of grid size.

  • anti_aliasing_factor (float | tuple[float, float]) – Low-pass cutoff scaling for anti-aliasing.

  • normalize (bool) – If True, normalize the output by its norm.

  • min_value (float) – Minimum intensity value in the pattern.

  • max_value (float) – Maximum intensity value in the pattern.

Returns:

Real array shaped to sampling representing the Siemens star.

Return type:

Float[Array, ‘m n’]

ptyrax.initializers.speckle(sampling, std=None, radius=None, noise_level=0.0, defocus=0.0, NA=None, wavelength=1.0, scale=1 + 0j, normalize=False, *, key=None, **kwargs)[source]#

Create a speckle-pattern initializer on a sampling grid.

Generates a random speckle field by applying a random phase in the far-field plane and inverse-transforming, modulated by a Gaussian envelope.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • std (float) – Standard deviation of the real-space Gaussian envelope.

  • radius (float) – Alternative to std for specifying envelope size.

  • noise_level (float) – Amplitude of additive uniform noise.

  • defocus (float | tuple[float, float]) – Defocus parameter (unused in speckle generation).

  • NA (float | tuple[float, float]) – Numerical aperture controlling the far-field cutoff.

  • wavelength (float) – Wavelength for far-field coordinate computation.

  • scale (complex) – Multiplicative scale factor.

  • normalize (bool) – If True, normalize the output by its norm.

  • key (Key) – JAX PRNG key for random phase generation.

Returns:

Complex speckle field array shaped to sampling.

Return type:

Float[Array, ‘m n’]

ptyrax.initializers.support(sampling, size=None, decay_length=1.0, linear_power=2, linear_size=None)[source]#

Generate a support constraint weight map.

Produces a smooth penalty that increases away from the center, useful as a regularization weight for sample boundaries.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • size (Array | ndarray | bool | number | bool | int | float | complex | LiteralArray) – Characteristic size of the support region (x, y).

  • decay_length (float) – Controls the smoothness of the transition at the boundary.

  • linear_power (int) – Exponent for the linear penalty term.

  • linear_size (Array | ndarray | bool | number | bool | int | float | complex | LiteralArray) – Size parameter for the linear growth region.

Returns:

Real weight array shaped to sampling.

Return type:

Float[Array, ‘n m’]

ptyrax.initializers.uniform(sampling, *args, scale=1.0, normalize=True, **kwargs)[source]#

Uniform initializer that returns a constant complex field on sampling.

Parameters:

  • sampling (SamplingGrid) – Target sampling grid.

  • normalize (bool) – If True, normalize the returned field.

  • scale (float)

Returns:

Complex array shaped to sampling.

Return type:

Float[Array, ‘* m n’]

ptyrax.initializers.usaf_test_target(sampling, high_amplitude=1.0, high_phase=0.0, low_amplitude=0.0, low_phase=0.0, scale=1.0, center=(0.0, 0.0), normalize=False, svg_path=None, binarization_threshold=200, svg_physical_size_m=0.1)[source]#

Create a USAF 1951 resolution test target initializer from SVG.

Loads the USAF 1951 test target from an SVG file and scales it according to the sampling grid’s pixel size and the scale parameter.

The USAF 1951 standard dimensions: - Group 0, Element 1: 1.0 lp/mm (0.5 mm line width) - The SVG should be designed with these standard physical dimensions

Parameters:

  • sampling (SamplingGrid) – Target sampling grid (pixel_size should be in meters).

  • high_amplitude (float) – Amplitude for the bars (test pattern).

  • high_phase (float) – Phase for the bars (radians).

  • low_amplitude (float) – Amplitude for the background.

  • low_phase (float) – Phase for the background (radians).

  • scale (float) – Overall scale factor for the pattern size (default=1.0 uses actual USAF dimensions). Use scale > 1 to make the pattern larger, < 1 to make it smaller.

  • center (tuple[float, float]) – (x, y) center position of the pattern in physical units (meters).

  • normalize (bool) – If True, normalize the output.

  • svg_path (str) – Path to the USAF SVG file. If None, uses default location.

  • binarization_threshold (int)

  • svg_physical_size_m (float)

Returns:

Complex array shaped to sampling representing the USAF test target.

Return type:

Complex[Array, ‘m n’]

Contents