pyPhase package

dataset module

class dataset.Backend(name: str, path: str = '.', version: str = 'master')

Bases: object

class dataset.Dataset(name: str, path: str = '.', version: str = 'master')

Bases: object

Abstract class representing a set of recorded images, acquisition parameters, reconstructed images and any intermediary images.

Parameters

namestr

Name of the dataset. Corresponds to the name of the file(s) or directory(ies) of the recorded data.

pathstr, optional

Path to the file(s) or directory(ies) of the recorded data

versionstr, optional.

Version of dataset file. To permit tests of different alignment and reconstruction parameters.

property Lambda

Wavelength in m, calculated from energy.

align_projection(*, projection=0, save_projection=False)

Aligns images at different positions at one projection angle

Aligns (registers) images taken at different positions using the default registration algorithm (pyphase.registrator).

Parameters:

• projection (int, optional) – Number of projection to register.

• save_projection (bool, optional) – Save aligned images to file (creates new data files)

align_projections(*, projections)

Align a series of projections.

Parameters:

projections (tuple of ints) – In the form [start, end]

get_alignment(*, projection, position)

Get transform parameters for alignment.

Parameters:

projection (int, optional) – Number of projection to register.

Returns:

transform_parameters (numpy array) – Array of transform parameters. Size depends on transform used.

property nfx

property nfy

class dataset.EDF(name: str, path: str = '.', version: str = 'master')

Bases: Backend

property backend_initialized

get_image(*, projection, image_type='phase', Fourier=False, pad=True)

Get reconstructed images (phase by default)

Parameters:

• projection (int) – Number of the projection.

• image_type (str, optional) – Can be phase or attenuation.

• Fourier (bool) – Return Fourier transform of image.

• pad (bool) – Return padded image.

Returns:

image (ndarray)

initialize_backend()

read_parameters_backend()

Reads the associated backend parameter file.

write_image(*, image, projection, projection_type)

Saves images into file.

Parameters:

• data (ndarray) – An ndarray of the image to save.

• projection_number (int) – The number of the projection to be saved.

• proj_type (str) – A string containing the prefix for the name of the file to be saved.

• args (int) – Number of the distance of the projection.

Returns:

None – Saves the images into the file [prefix]_[projection_number].edf or [prefix]_[distance]_[projection_number].edf into the name_ directory.

class dataset.ESRF(name: str, path: str = '.', version: str = 'master')

Bases: object

Legacy code for ESRF datasets.

Note

Will be aligned with Nanomax functionality.

GetSinogram(distance=1)

Return projections as sinogram

Parameters:

distance (int) – Number of the distance of the projection.

Returns:

sinogram – Returns projections stacked as sinogram

align(interval=100)

Align(self, RA, interval=100) Align complete data set.

TODO: Should probably check for the last projection also so that it is always included

align_projection(projection)

projection = number of projection to register

calculate_axis_position(distance)

Calculates the axis position at one position

calculate_axis_positions()

Calculates all axis positions.

calculate_motion()

Estimates motion in the scans based on supplementary images.

calculate_reference_position()

Calculates and sets reference position based on motion

display_alignment(projection=0)

Displays alignment and fit.

fit_alignment()

Fits measured alignment parameters with polynomials

get_alignment(projection, distance)

Returns the transform parameters for alignment at one projection and position

get_image(*, projection, image_type='phase', Fourier=False, pad=False)

Get reconstructed images (phase by default)

Parameters:

• projection (int) – Number of the projection.

• image_type (str, optional) – Can be phase or attenuation.

• Fourier (bool) – Return Fourier transform of image.

• pad (bool) – Return padded image.

Returns:

image (ndarray)

get_motion(projection, distance)

Returns estimation motion at one projection and position.

get_projection(*, projection, position, pad=True, Fourier=False, aligned=True, magnification=True)

property nfx

property nfy

populate()

Tries to find the dataset parameters in the accompanying .info and xml files. It is called when a parameter file pyphase_parameter.yml is not found.

Returns:

self – Returns self with the updated attributes.

preprocess()

Runs all preprocessing on the dataset: axis positions, motion, reference position, alignment

write_image(*, image, projection, projection_type)

Saves images into file.

Parameters:

• data (ndarray) – An ndarray of the image to save.

• projection_number (int) – The number of the projection to be saved.

• proj_type (str) – A string containing the prefix for the name of the file to be saved.

• args (int) – Number of the distance of the projection.

Returns:

None – Saves the images into the file [prefix]_[projection_number].edf or [prefix]_[distance]_[projection_number].edf into the name_ directory.

class dataset.ESRF_dev(name: str, path: str = '.', version: str = 'master')

Bases: Dataset, HDF5

get_projection(*, projection, position, pad=True, Fourier=False, aligned=True, magnification=True)

read_parameters_frontend()

class dataset.Elettra(name: str, path: str = '.', version: str = 'ḿaster')

Bases: Dataset, HDF5

Class for raw Elettra Synchrotron data sets.

Variables:

• ztot (float) – Focus to detector distance in m.

• path (str) – Path to dataset.

• version (str) – Version of Dataset backend structure, e.g. ‘TIEHOM’

• name (str) – Name of dataset

• projection_prefix (str) – HDF5 path to projection data.

• reference_position (int) – Position number as reference for alignment (usually highest resolution)

• darkfield_prefix (str) – HDF5 path prefix to darkfields

• flatfield_prefix (str) – HDF5 path prefix to flatfields

• aligned (int) – Flag if dataset is aligned or not.

get_projection(*, projection, position=0, pad=True, magnification=True, aligned=True, Fourier=False)

Read one recorded image.

Parameters:

• projection (int) – Number of projection to read.

• position (int) – Number of positiion (“distance”) to read.

• pad (bool, optional) – Pads the image.

• magnification (bool, optional) – Brings the image to the magnification of reference_position.

• aligned (bool, optional) – Corrects alignment (requires alignment of projections).

• Fourier (bool) – Returns the Fourier transform of the image.

read_parameters_frontend()

class dataset.HDF5(name: str, path: str = '.', version: str = 'master')

Bases: Backend

property backend_initialized

get_image(*, projection, image_type='phase', Fourier=False, pad=False)

Get reconstructed images (phase by default)

Parameters:

• projection (int) – Number of the projection.

• image_type (str, optional) – Can be phase or attenuation.

• Fourier (bool) – Return Fourier transform of image.

• pad (bool) – Return padded image.

Returns:

image (ndarray)

initialize_backend()

property preprocessing_initialised

read_parameters_backend()

write_dark(darkfield, position)

Writes a tensor of dark images to file

write_flat(flatfield, position)

Writes a tensor of flat field images to file

write_image(*, image, projection, projection_type)

Saves images into file.

Parameters:

• image (ndarray) – An ndarray of the image to save.

• projection (int) – The number of the projection to be saved.

• proj_type (str) – A string containing the prefix for the name of the file to be saved.

• position (int) – Number of the position of the projection (for propagation).

Returns:

None – Saves the images into the file [prefix]_[projection_number].edf or [prefix]_[distance]_[projection_number].edf into the name_ directory.

class dataset.ID16B(name: str, path: str = '.', version: str = 'master')

Bases: ESRF_dev, HDF5

class dataset.ID19(name: str, path: str = '.', version: str = 'master')

Bases: ESRF_dev, HDF5

read_parameters_frontend()

class dataset.Nanomax(name: str, path: str = '.', version: str = 'master')

Bases: Dataset, HDF5

Class for raw Nanomax data sets.

Variables:

• ztot (float) – Focus to detector distance in m.

• path (str) – Path to dataset.

• version (str) – Version of Dataset backend structure, e.g. ‘TIEHOM’

• name (str) – Name of dataset

• frames_per_position (int) – Number of frames per position.

• initial_frame (int) – Number of the initial frame.

• projection_prefix (str) – HDF5 path to projection data.

• reference_position (int) – Position number as reference for alignment (usually highest resolution)

• diode_name (str) – Name of diode (HDF path) for normalisation

• darkfield_prefix (str) – HDF5 path prefix to darkfields

• flatfield_prefix (str) – HDF5 path prefix to flatfields

• cpr_prefix (str) – HDF5 path prefix to flatfield corrected images

• phase_prefix (str) – HDF5 path prefix to phase maps

• attenuation_prefix (str) – HDF5 path prefix to attenuation images

• aligned (int) – Flag if dataset is aligned or not.

get_projection(*, projection, position, pad=True, magnification=True, aligned=True, Fourier=False)

Read one recorded image.

Parameters:

• projection (int) – Number of projection to read.

• position (int) – Number of positiion (“distance”) to read.

• pad (bool, optional) – Pads the image.

• magnification (bool, optional) – Brings the image to the magnification of reference_position.

• aligned (bool, optional) – Corrects alignment (requires alignment of projections).

• Fourier (bool) – Returns the Fourier transform of the image.

read_parameters_frontend()

class dataset.NanomaxPreprocessed(name: str, path: str = '.', version: str = 'master')

Bases: Dataset, HDF5

Class for preprocessed Nanomax datasets.

Variables:

• ztot (float) – Focus to detector distance in m.

• path (str) – Path to dataset.

• version (str) – Version of Dataset backend structure, e.g. ‘TIEHOM’

• name (str) – Name of dataset

• correct_alignent (int) – Flag to correct alignment.

• aligned (int) – Flag for dataset aligned.

• phase_prefix (str) – HDF5 path prefix to phase maps

• attenuation_prefix (str) – HDF5 path prefix to attenuation images

• projection_prefix (str) – HDF5 path to corrected projections

• reference_position (int) – Position number as reference for alignment (usually highest resolution)

• energy (float) – Energy in keV

• ny (nx,) – Number of pixels, horizontal, vertical

• padding (int) – Padding factor

• detector_pixel_size (float) – The detector pixel size in µm

• alpha (tuple of floats) – Regularization parameter in the form [LF, HF]

read_parameters_frontend()

class dataset.NanomaxPreprocessed2D(name: str, path: str = '.', version: str = 'master')

Bases: NanomaxPreprocessed, HDF5

Class for single projection Nanomax data.

get_projection(*, projection, position, pad=True, magnification=True, aligned=True, Fourier=False)

Read one recorded image.

Parameters:

• projection (int) – Number of projection to read.

• position (int) – Number of positiion (“distance”) to read.

• pad (bool, optional) – Pads the image.

• magnification (bool, optional) – Brings the image to the magnification of reference_position.

• aligned (bool, optional) – Corrects alignment (requires alignment of projections).

• Fourier (bool) – Returns the Fourier transform of the image.

read_parameters_frontend()

class dataset.NanomaxPreprocessedTomo(name: str, path: str = '.', version: str = 'master')

Bases: NanomaxPreprocessed, HDF5

Class for preprocessed Nanomax tomographic datasets.

Variables:

• data_basename (str) – File prefix to projection data files.

• magnification_x,y (numpy array) – Magnification factors for each position, horizontal, vertical

• pixel_size_x,y (numpy array) – Effective pixel size for each position

• pixel_size (numpy array) – Effective pixel size at reconstruction position

get_projection(*, projection, position, pad=True, magnification=True, aligned=True, Fourier=False)

Read one recorded image.

Parameters:

• projection (int) – Number of projection to read.

• position (int) – Number of positiion (“distance”) to read.

• pad (bool, optional) – Pads the image.

• magnification (bool, optional) – Brings the image to the magnification of reference_position.

• aligned (bool, optional) – Corrects alignment (requires alignment of projections).

• Fourier (bool) – Returns the Fourier transform of the image.

read_parameters_frontend()

parallelizer module

class parallelizer.OAR

Bases: object

Legacy class for parallellisation on OAR. Will be reimplemented as decorator

Launch(dataset, operator, **kwargs)

WriteOarFiles(DS)

parallelizer.SLURM(func)

Decorator for parallellisation on SLURM

parallelizer.Serial(func)

Decorator for serial processing. Parallelisation decorators work on functions with signature (self, *, dataset, projections)

phaseretrieval module

class phaseretrieval.ADMM_CTF(dataset=None, PSF=[], support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Alternating Direction Method of Multipliers based on CTF (homogeneous) linearization [1]

Parameters:

• ADMM_iterations (int) – Number of ADMM-CTF iterations

• tau (float) – Penalty parameter of augmented Lagrangian

• alpha (float) – Penalty parameter of Total Variation (TV) regularization

• beta_over_delta (float) – Refractive index ratio between beta and delta

• phys (int) – 0 : No physical constraints 1 : Positivity of attenuation and phase as a constraint

References

[1] Villanueva-Perez Optics Letters 42(6) (2017)

inv_block_toeplitz_ctf_betaoverdelta(b, tau, beta_over_delta, OTF=[])

Inverse of CTF operator assuming beta over delta

Parameters:

• u (real np.array) – Input image

• tau (float) – Penalty parameter of augmented Lagrangian

• beta_over_delta (float) – Refractive index ratio between beta and delta

Returns:

denominator (real np.array) – Inverse of CTF operator

operator_ctf_adjoint(b, beta_over_delta, FPSF=[])

Compute adjoint of CTF operator assuming beta over delta

Parameters:

• b (real np.array) – Input image

• beta_over_delta (float) – Refractive index ratio between beta and delta

Returns:

numerator (real np.array) – Adjoint of CTF operator

class phaseretrieval.CTF(dataset=None, **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Contrast Transfer Function [1].

References

[1] Cloetens et al. Appl. Phys. Lett. 75 (1999) 2912

create_multimaterial_prior(data)

Generate a multi-material prior from a tomographic reconstruction of a contact plane scan

Note

Legacy code to be refactored.

class phaseretrieval.CTFHOM(dataset=None, delta_beta=500, **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Contrast Transfer Function for homogeneous objects [1].

References

[1] Turner et al. Optics Express 12 (2004)

property delta_beta

Material dependent ratio delta over beta (float).

class phaseretrieval.CTFPurePhase(dataset=None, **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Contrast Transfer Function for pure phase objects [1].

References

[1] Cloetens et al. J. Phys. D: Appl. Phys 29 (1996) 133

class phaseretrieval.GDTV(dataset=None, PSF=[], support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Gradient Descent with (smooth) total variation regularization

Parameters:

• iterations (int) – Number of GD iterations

• epsilon (float) – Smoothing factor of Total Variation (TV) norm

• alpha (float) – Penalization for Total Variation (TV) regularization

• tau (float) – Step size

• self.omega (float) – Penalization for positivity regularization

• self.omega_augment_factor (float) – Multiplicative factor for positivity regularization

• phys (int) – 0 : No physical constraints 1 : Positivity of attenuation and phase as a constraint 2 : Positivity of attenuation and phase as a regularization

References

[1]

class phaseretrieval.GradientDescent(dataset=None, PSF=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Gradient descent algorithm.

Parameters:

PSF (ndarray with the same shape as images) – Point spread function (optional)

property alpha

property retriever

class phaseretrieval.HIO_ER(dataset=None, support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Sequence of Hybrid Input Output [1] and Error Reduction [2].

Variables:

• retriever (PhaseRetrievalAlgorithm2D) – Algorithm for initialisation

• iterations (int) – Number of global iterations

• iterations_hio (int) – Number of HIO iterations per iteration

• iterations_er (int) – Number of ER iterations per iteration

• step_size_phase (float) – Update step size for the phase

• step_size_attenuation (float) – Update step size for the attenuation

References

[1] Fienup Appl. Opt. 21 (1982) 2758 [2] Gerchberg & Saxton Optik 35 (1972) 237

error_reduction(wavefront, support)

One iteration of Error Reduction.

Parameters:

• wavefront (complex np.array) – wavefront to update.

• support (np.array) – Support constraint.

Returns:

wavefront_updated (complex np.array) – Updated wavefront.

hybrid_input_output(wavefront, initial_wavefront, support, step_size_attenuation, step_size_phase)

One iteration of the Hybrid Input Output algorithm.

Parameters:

• wavefront (complex np.array) – Constrained wavefront.

• initial_wavefront (complex np.array) – Wavefront to update.

• support (np.array) – Support of object.

• step_size_attenuation (float) – Step size for attenuation update.

• step_size_phase (float) – Step size for phase update.

Returns:

wavefront_updated (complex np.array) – Updated wavefront.

reconstruct_projection(dataset, projection=0, positions=None, pad=False)

Reconstruct one projection from a Dataset object and saves the result.

Parameters:

• dataset (Dataset) – Dataset object to use (not necessarily the same as initialised).

• projection (int, optional) – Number of projection to reconstruct.

• positions (int or list of ints, optional) – Subset of positions to use for reconstruction

Returns:

• phase (np.array) – Reconstructed phase.

• attenuation (np.array) – Reconstructed attenuation.

property retriever

class phaseretrieval.HPR(dataset=None, support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Hybrid Projection Reflection [1]

Variables:

• retriever (PhaseRetrievalAlgorithm2D) – Algorithm for initialisation

• iterations (int) – Number of HPR iterations

• step_size_phase (float) – Update step size for the phase

• step_size_attenuation (float) – Update step size for the attenuation

References

[1] Bauschke & Combettes OSA 20(6) (2003) 1025-1034

hybrid_projection_reflection(wavefront, initial_wavefront, support, step_size_attenuation, step_size_phase)

One iteration of the Hybrid Projection Reflection.

Parameters:

• wavefront (complex np.array) – Constrained wavefront.

• initial_wavefront (complex np.array) – Wavefront to update.

• support (np.array) – Support of object.

• step_size_attenuation (float) – Step size for attenuation update.

• step_size_phase (float) – Step size for phase update.

Returns:

wavefront_updated (complex np.array) – Updated wavefront.

reconstruct_projection(dataset, projection=0, positions=None, pad=False)

Reconstruct one projection from a Dataset object and saves the result.

Parameters:

• dataset (Dataset) – Dataset object to use (not necessarily the same as initialised).

• projection (int, optional) – Number of projection to reconstruct.

• positions (int or list of ints, optional) – Subset of positions to use for reconstruction

Returns:

• phase (np.array) – Reconstructed phase.

• attenuation (np.array) – Reconstructed attenuation.

property retriever

class phaseretrieval.IRGN(dataset=None, PSF=[], support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Iteratively Regularized Gauss Newton Method [1]

Parameters:

• GaussNewton_iterations (int) – Number of Gauss-Newton iterations

• ConjugateGradient_iterations (float) – Number of Conjugate Gradient iterations per Gauss-Newton iterations

• threshold_CG (float) – Threshold for Conjugate Gradient method

• tau (float) – Step size for Gauss-Newton

• alpha_reduce_factor (float) – Reduction factor for Tikhonov regularization

• omega (float) – Penalization for positivity regularization

• omega_augment_factor (float) – Multiplicative factor for positivity regularization

• sobolev_exponent (float) – Exponent of Sobolev norm for regularization

• phys (int) – 0 : No physical constraints 1 : Positivity of attenuation and phase as a regularization

References

[1] Maretzke OSA 24(6) (2016) 6490-6506

Frechet_derivative(f, P, epsilon, Gx, ND)

Frechet derivative of forward operator.

Parameters:

• f (complex np.array) – f = φ - iB parametrizes the phase shifts φ and attenuation B, position the derivative is to be computed

• P (complex np.array) – Fresnel propagator.

• epsilon (complex np.array) – Input of Frechet derivative

• Gx (real np.array) – Gramian matrix of regularization term

• ND (int) – Number of positions

Returns:

frechet (real np.array) – Frechet derivative with respect to f at epsilon

adjoint_Frechet_derivative(f, P, epsilon, Gx, ND, support, quotient_beta_delta=[])

Frechet derivative of forward operator.

Parameters:

• f (complex np.array) – f = φ - iB parametrizes the phase shifts φ and attenuation B, position the derivative is to be computed

• P (complex np.array) – Fresnel propagator.

• epsilon (complex np.array) – Input of Frechet derivative

• Gx (real np.array) – Gramian matrix of regularization term

• ND (int) – Number of positions

• support (np.array) – Support of object.

• quotient_beta_delta (float) – Beta over Delta factor if homogeneous object

Returns:

adjoint_frechet (complex np.array) – Adjoint of the Frechet derivative with respect to f at epsilon

operator_to_inverse(f, P, epsilon, alpha_reg, gamma, Gx, ND, support)

(Linear) Operator to inverse with conjugate gradient method

Parameters:

• f (complex np.array) – f = φ - iB parametrizes the phase shifts φ and attenuation B, position the derivative is to be computed

• P (complex np.array) – Fresnel propagator.

• epsilon (complex np.array) – Input of Frechet derivative

• alpha_reg (float) – Penalization for Thikonov regularization

• omega (float) – Penalization for positivity regularization

• Gx (real np.array) – Gramian matrix of regularization term

• ND (int) – Number of positions

• support (np.array) – Support of object.

Returns:

adjoint_gradient_inverse (complex np.array) – Operator to inverse with respect to f at epsilon

class phaseretrieval.Mixed(dataset=None, **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Mixed approach phase retrieval

Note

Legacy code to be aligned with current APIxs

Lcurve(dataset, projection)

Calculate the L-curve (for finding regularisation parameter)

display_Lcurve(dataset)

Displays the L-curve

get_prior(projection)

Generates a prior estimate of the phase

class phaseretrieval.NLCG(dataset=None, PSF=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Non-Linear Conjugate Gradient algorithm.

Parameters:

PSF (ndarray with the same shape as images) – Point spread function (optional)

property alpha

property retriever

class phaseretrieval.NLPDHGM(dataset=None, PSF=[], support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Exact and Linearised : NonLinear Primal Dual Hybrid Gradient Method [1]

Parameters:

• iterations (int) – Number of NL-PDHGM iterations

• sigma (float) – Step size for dual variables

• tau (float) – Step size for primal variables

• alpha_TGV, beta_TGV (float) – Penalizations for Second order Total Generalized Variation (TGV) for attenuation

• delta_TV (float) – Penalization for Total Variation (TV) for phase

• gamma (float in [0,1]) – Over-relaxation parameters for primal variables

• omega (float) – Penalization for positivity regularization

• omega_augment_factor (float) – Multiplicative factor for positivity regularization

• phys (int) – 0 : No physical constraints 1 : Positivity of attenuation and phase as a constraint 2 : Positivity of attenuation and phase as a regularization

References

[1] Valkonen Inverse Problems 30 (2014) 055012

reconstruct_projection(dataset, projection=0, positions=None, pad=False)

Reconstruct one projection from a Dataset object and saves the result.

Parameters:

• dataset (Dataset) – Dataset object to use (not necessarily the same as initialised).

• projection (int, optional) – Number of projection to reconstruct.

• positions (int or list of ints, optional) – Subset of positions to use for reconstruction

Returns:

• phase (np.array) – Reconstructed phase.

• attenuation (np.array) – Reconstructed attenuation.

class phaseretrieval.PDHGM_CTF(dataset=None, PSF=[], support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Chambolle-Pock [1] (PDHGM) CTF-linearization based

Parameters:

• iterations (int) – Number of PDHGM iterations

• sigma (float) – Step size for dual variables

• tau (float) – Step size for primal variables

• alpha, beta (float) – Penalization for Second order Total Generalized Variation (TGV) for attenuation

• delta (float) – Penalization for Total Variation (TV) for phase

• gamma (float in [0,1]) – Over-relaxation parameters for primal variables

• omega (float) – Penalization for positivity regularization

• omega_augment_factor (float) – Multiplicative factor for positivity regularization

• phys (int) – 0 : No physical constraints 1 : Positivity of attenuation and phase as a constraint 2 : Positivity of attenuation and phase as a regularization

References

[1] Chambolle & Pock : Journal of Mathematical Imaging and Vision 40 (2011) 120–145

class phaseretrieval.PhaseRetrievalAlgorithm2D(dataset=None, **kwargs)

Bases: object

Base class for 2D phase retrieval algorithms.

Parameters:

• dataset (pyphase.Dataset, optional) – A Dataset type object.

• shape (tuple of ints, optional) – Size of images (ny, nx) for creation of frequency variables etc.

• pixel_size (float, optional) – In m.

• distance (list of floats, optional) – Effective propagation distances in m.

• energy (float, optional) – Effective energy in keV.

• alpha (tuple of floats, optional) – Regularisation parameters. First entry for LF, second for HF. Typically [1e-8, 1e-10].

• pad (int) – Padding factor (default 2).

Variables:

• nx (int) – Number of pixels in horizontal direction.

• ny (int) – Number of pixels in horizontal direction.

• pixel_size (tuple of floats) – Pixel size [x, y] in µm.

• ND (int) – Number of positions.

• energy (float) – Energy in keV.

• alpha (tuple of floats) – First entry for LF, second for HF. Tyically [1e-8, 1e-10].

• distance (numpy array) – Effective propagation distances in m.

• padding (int) – Padding factor.

• sample_frequency (float) – Reciprocal of pixel size in lengthscale.

• nfx (int) – Number of samples in Fourier domain (horizontal).

• nfy (int) – Number of samples in Fourier domain (vertical).

• fx (numpy array) – Frequency variable (horizontal), calculated by frequency_variable.

• fy (numpy array) – Freuency variable (vertical).

• alpha_cutoff (float) – Cutoff frequency for regularization parameter in normalized frequency.

• alpha_slope (float) – Slope in regularization parameter.

Notes

Takes either a Dataset type object with keyword dataset (which contains all necessary parameters), or parameters as above.

property Alpha

Image implementation of regularisation parameter (np.array)

property Fresnel_number

Fresnel number at each position, calculated from energy and distance (float)

property Lambda

Wavelength based on energy (float)

frequency_variable(nfx, nfy, sample_frequency)

Calculate frequency variables.

Parameters:

• nfx (int) – Number of samples in x direction

• nfy (int) – Number of samples in y direction

• sample_frequency (float) – Reciprocal of pixel size in 1/m

Returns:

nparray – Frequency variables as an array of size [nfy, nfx, 2]

Notes

Follows numpy FFT convention. Zero frequency at [0,0], [1:n//2] contain the positive frequencies, [n//2 + 1:] n the negative frequencies in increasing order starting from the most negative frequency.

property nfx

property nfy

reconstruct_image(image, positions=None, pad=False)

Template for reconstructing an image given as argument.

Parameters:

• image (numpy.array) – A phase contrast image or an ndarray of images stacked along the first dimension.

• positions (int or list of ints, optional) – Subset of positions to use for reconstruction.

Note

Calls _algorithm (container purely for algorithm part).

Returns:

• phase (numpy.array)

• attenuation (numpy.array)

reconstruct_projection(dataset, projection=0, positions=None, pad=True)

Reconstruct one projection from a Dataset object and saves the result.

Parameters:

• dataset (Dataset) – Dataset object to use (not necessarily the same as initialised).

• projection (int, optional) – Number of projection to reconstruct.

• positions (int or list of ints, optional) – Subset of positions to use for reconstruction

Returns:

• phase (np.array) – Reconstructed phase.

• attenuation (np.array) – Reconstructed attenuation.

reconstruct_projections(*, dataset, projections)

Reconstruct a range of projections (parallelized function).

Parameters:

• dataset (pyphase.Dataset) – Dataset to reconstruct.

• projections (list of int) – In the form [start, end]

simple_propagator(pxs, Lambda, z)

Creates a Fresnel propagator.

Parameters:

• pxs (float) – Pixel size in µm.

• Lambda (float) – Wavelength in m.

• z (float) – Effective propagation distance in m.

Returns:

H (nparray) – Fresnel propagator.

Notes

Temporary implementation by Y. Zhang. Will be integrated with the propagator module.

class phaseretrieval.RAAR(dataset=None, support=[], **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Relaxed averaged alternating reflections [1]

Variables:

• retriever (PhaseRetrievalAlgorithm2D) – Algorithm for initialisation

• iterations (int) – Number of RAAR iterations

• step_size_phase (float) – Update step size for the phase

• step_size_attenuation (float) – Update step size for the attenuation

References

[1] Luke Inverse Problems 21 (2005) 3750

reconstruct_projection(dataset, projection=0, positions=None, pad=False)

Reconstruct one projection from a Dataset object and saves the result.

Parameters:

• dataset (Dataset) – Dataset object to use (not necessarily the same as initialised).

• projection (int, optional) – Number of projection to reconstruct.

• positions (int or list of ints, optional) – Subset of positions to use for reconstruction

Returns:

• phase (np.array) – Reconstructed phase.

• attenuation (np.array) – Reconstructed attenuation.

relaxed_averaged_alternating_reflections(wavefront, initial_wavefront, support, step_size_attenuation, step_size_phase)

One iteration of the Relaxed Averaged Alternating Reflections algorithm.

Parameters:

• wavefront (complex np.array) – Constrained wavefront.

• initial_wavefront (complex np.array) – Wavefront to update.

• support (np.array) – Support of object.

• step_size_attenuation (float) – Step size for attenuation update.

• step_size_phase (float) – Step size for phase update.

Returns:

wavefront_updated (complex np.array) – Updated wavefront.

property retriever

class phaseretrieval.TIEHOM(dataset=None, delta_beta=500, **kwargs)

Bases: PhaseRetrievalAlgorithm2D

Transport of Intensity Equation for homogeneous objects (or “Paganin’s algorithm”) [1]

Parameters:

delta_beta (float, optional) – Material dependent ratio delta over beta.

References

[1] Paganin et al. J. Microsc. 206 (2002) 33

property delta_beta

Material dependent ratio delta over beta (float).

propagator module

class propagator.CTF(*, dataset=None, shape=None, energy=None, pixel_size=None, distance=None, pad=2, oversampling=4)

Bases: Propagator

Propagates using the CTF. Legacy code to be aligned with Fresnel.

PropagateProjection(dataset, projection, distance)

class propagator.Fresnel(*, dataset=None, shape=None, energy=None, pixel_size=None, distance=None, pad=2, oversampling=4)

Bases: Propagator

Propagator using Fresnel transform

class propagator.Propagator(*, dataset=None, shape=None, energy=None, pixel_size=None, distance=None, pad=2, oversampling=4)

Bases: object

propagate_image(amplitude, phase, position_number=None, oversampled=False)

Propagate a wavefront created from two images.

propagate_projection(dataset, position_number=None, projection=None, oversampled=False)

Propagate one projection.

Parameters:

• dataset (pyphase.Dataset, optional) – Datset with projection data.

• position_number (int, optional) – Which position to propagate to

• projection (int, optional) – Which projection to propagate

• phase (ndarray, optional) – Phase of wave to propagate

• attenuation (ndarray, optional) – Amplitude of wave to propagate

• position (float) – Effective propagation distance

• oversampled (bool) – True if imput images are already oversampled

tomography module

class tomography.PyHST

Bases: object

Tomographic operations with PyHST

ForwardProject(DS, volume='phase')

Generate projections from a reconstructed dataset

reconstruct(DS, volume='phase')

Tomographic reconstruction

class tomography.Tomography

Bases: object

Class for tomographic operations, for use with 3D iterative methods

Note

Legacy code to be aligned with current API

utilities module

class utilities.ElastixAffine

Bases: RegistrationAlgorithm

Affine registration algorithm using Elastix.

Variables:

• parameters (Parameters) – Elastix standard parameters

• number_of_parameters (int, default=6) – Number of parameters in the transform

class utilities.ElastixRigid

Bases: RegistrationAlgorithm

Rigid registration algorithm using Elastix.

Variables:

• parameters (Parameters) – Elastix standard parameters

• number_of_parameters (int, default=3) – Number of parameters in the transform

class utilities.ElastixSimilar

Bases: RegistrationAlgorithm

Similarity transform registration algorithm using Elastix

Variables:

• parameters (Parameters) – Elastix standard parameters

• number_of_parameters (int, default=4) – Number of parameters in the transform

class utilities.ImageDisplayer

Bases: object

Wrapper class for image display.

class utilities.PyplotImageDisplayer

Bases: ImageDisplayer

Interface to Pyplot for image display.

Notes

With the idea to make the choice of display package flexible.

close_all()

display(image, title='', vmin=None, vmax=None)

Display an image

Parameters:

• image (nparray) – The image to be displayed.

• title (str, optional) – Title of figure.

• vmin (optional) – Lower limit of contrast range.

• vmax (optional) – Upper limit of contrast range.

display_stack(stack)

class utilities.RegistrationAlgorithm

Bases: object

Abstract class for registration algorithms

Properties

apply_transformation(image, transform_parameters, **kwargs)

Apply an image transform from image registration.

Parameters:

• image (ndarray) – The image to transform.

• transform_parameters (array) – Parameters of the transform (length depends on registration algorithm used (number_of_parameters))

Returns:

transformed_image – The transformed image.

register(moving_image, stationary_image)

Register moving_image to stationary_image.

Parameters:

• moving_image (ndarray) – The image to register.

• stationary_image (ndarray) – The image to register to.

Returns:

• field (ndarray) – The calculated deformation field.

• transformed_moving_image (ndarray) – The deformed moving image.

• result_transform (array) – The calculated transform parameters. Lenght varies with the number of parameters in the chosen algorithm (number_of_parameters)

class utilities.StackViewer(X, ax)

Bases: object

Functionality to browse stacks.

utilities.resize(image, shape, pad_type='edge')

Resizes an image by either cutting out the centre or padding.

Assumes images are stored along fist dimension.

utilities.update(title, position, target)

operators module

operators.adjoint_frechet_derivative(f, P, epsilon, gram=[])

Frechet derivative of forward operator.

Parameters:

• f (complex np.array) – f = B + iφ parametrizes the phase shifts φ and attenuation B, position the derivative is to be computed

• P (complex np.array) – Fresnel propagator.

• epsilon (complex np.array) – Input of Frechet derivative

• gram (real np.array) – Gramian matrix of regularization term

Returns:

adjoint_frechet (complex np.array) – Adjoint of the Frechet derivative with respect to f at epsilon

operators.amplitude_constraint(wavefront, amplitude, propagator, mask=[])

Apply amplitude constraint.

Parameters:

• wavefront (complex np.array) – Wavefront to constrain.

• amplitude (np.array) – Amplitude to impose.

• propagator (complex np.array) – Propagator corresponding to effective distance of amplitude.

• mask (np.array, optional) – Zone to apply constraint.

Returns:

wavefront_constrained (complex np.array) – Wavefront after applied constraint.

operators.div(P)

Divergence operator.

Parameters:

P (complex np.array) – Image whose divergence is to be computed.

Returns:

divergence (complex np.array) – Divergence of image P.

operators.error_estimate(wavefront, amplitude, propagator, mask=[])

Estimate fit to data.

Parameters:

• wavefront (complex np.array) – Wavefront for estimation.

• amplitude (np.array) – Amplitude from measured image.

• propagator (complex np.array) – Fresnel propagator corresponding to effective propagation distance in measured image.

• mask (np.array) – Restrict estimate to a region of interest.

Returns:

error (float) – MSE calculated and measured amplitude.

operators.forward(f, P)

Forward operator.

Parameters:

• f (complex np.array) – f = B + iφ parametrizes the phase shifts φ and attenuation B, position the derivative is to be computed

• P (complex np.array) – Fresnel propagator.

Returns:

forward (real np.array) – Intensity image

operators.frechet_derivative(f, P, epsilon)

Frechet derivative of forward operator.

Parameters:

• f (complex np.array) – f = B + iφ parametrizes the phase shifts φ and attenuation B, position the derivative is to be computed

• P (complex np.array) – Fresnel propagator.

• epsilon (complex np.array) – Input of Frechet derivative

Returns:

frechet (real np.array) – Frechet derivative with respect to f at epsilon

operators.grad(M)

Gradient operator.

Parameters:

M (complex np.array) – Image whose gradient is to be computed.

Returns:

gradient (complex np.array) – Gradient of image M.

operators.shrinkage(u, kappa)

Shrinkage operation

Parameters:

• u (real np.array) – Input image.

• kappa (float)

Returns:

u (real np.array) – max(0, |u| - kappa) * sign(u)