Code reference¶
bg_estimate (background-estimation)¶
Constants¶
-
qpimage.bg_estimate.
VALID_FIT_OFFSETS
= ['fit', 'gauss', 'mean', 'mode']¶ valid values for keyword argument fit_offset in
estimate()
-
qpimage.bg_estimate.
VALID_FIT_PROFILES
= ['ramp', 'offset']¶ valid values for keyword argument fit_profile in
estimate()
Methods¶
-
qpimage.bg_estimate.
estimate
(data, fit_offset='average', fit_profile='ramp', border_px=0, from_binary=None, ret_binary=False)[source]¶ Estimate the background value of an image
Parameters: - data (np.ndarray) – Data from which to compute the background value
- fit_profile (str) –
- The type of background profile to fit:
- ”ramp”: 2D linear ramp with offset (default)
- ”offset”: offset only
- fit_offset (str) –
- The method for computing the profile offset
- ”fit”: offset as fitting parameter
- ”gauss”: center of a gaussian fit
- ”mean”: simple average
- ”mode”: mode (see qpimage.bg_estimate.mode)
- border_px (float) – Assume that a frame of border_px pixels around the image is background.
- from_binary (boolean np.ndarray or None) – Use a boolean array to define the background area. The binary image must have the same shape as the input data. True elements are used for background estimation.
- ret_binary (bool) – Return the binary image used to compute the background.
Notes
If both border_px and from_binary are given, the intersection of the two is used, i.e. the positions where both, the binary frame and from_binary, are True.
-
qpimage.bg_estimate.
offset_gaussian
(data)[source]¶ Fit a gaussian model to data and return its center
-
qpimage.bg_estimate.
offset_mode
(data)[source]¶ Compute Mode using a histogram with sqrt(data.size) bins
core (QPImage)¶
Constants¶
-
qpimage.core.
VALID_INPUT_DATA
= ['field', 'hologram', 'phase', ('phase', 'amplitude'), ('phase', 'intensity')]¶ valid combinations for keyword argument which_data
Classes¶
-
class
qpimage.core.
QPImage
(data=None, bg_data=None, which_data='phase', meta_data={}, h5file=None, h5mode='a')[source]¶ Quantitative phase image manipulation
This class implements various tasks for quantitative phase imaging, including phase unwrapping, background correction, numerical focusing, and data export.
Parameters: - data (2d ndarray (float or complex) or list) – The experimental data (see which_data)
- bg_data (2d ndarray (float or complex), list, or None) – The background data (must be same type as data)
- which_data (str) – String or comma-separated list of strings indicating the order and type of input data. Valid values are “field”, “phase”, “phase,amplitude”, or “phase,intensity”, where the latter two require an indexable object with the phase data as first element.
- meta_data (dict) – Meta data associated with the input data.
see
qpimage.meta.META_KEYS
- h5file (str, h5py.Group, h5py.File, or None) – A path to an hdf5 data file where all data is cached. If
set to None (default), all data will be handled in
memory using the “core” driver of the
h5py
’sFile
class. If the file does not exist, it is created. If the file already exists, it is opened with the file mode defined by hdf5_mode. If this is an instance of h5py.Group or h5py.File, then this will be used to internally store all data. - h5mode (str) –
- Valid file modes are (only applies if h5file is a path)
- ”r”: Readonly, file must exist
- ”r+”: Read/write, file must exist
- ”w”: Create file, truncate if exists
- ”w-” or “x”: Create file, fail if exists
- ”a”: Read/write if exists, create otherwise (default)
Notes
QPImage is slicable; the following returns a new QPImage with the same meta data, but with all background corrections merged into the raw data:
qpi = QPImage(data=...) qpi_scliced = qpi[10:20, 40:30]
-
bg_amp
¶ background amplitude image
-
bg_pha
¶ background phase image
-
amp
¶ background-corrected amplitude image
-
field
¶ background-corrected complex field
-
info
¶ list of tuples with QPImage meta data
-
meta
¶ dictionary with imaging meta data
-
pha
¶ background-corrected phase image
-
raw_amp
¶ raw amplitude image
-
raw_pha
¶ raw phase image
-
shape
¶ size of image dimensions
-
clear_bg
(which_data=('amplitude', 'phase'), keys='fit')[source]¶ Clear background correction
Parameters: - which_data (str or list of str) – From which type of data to remove the background information. The list contains either “amplitude”, “phase”, or both.
- keys (str or list of str) –
- Which type of background data to remove. One of:
- ”fit”: the background data computed with
qpimage.QPImage.compute_bg()
- ”data”: the experimentally obtained background image
- ”fit”: the background data computed with
-
compute_bg
(which_data='phase', fit_offset='average', fit_profile='ramp', border_m=0, border_perc=0, border_px=0, from_binary=None, ret_binary=False)[source]¶ Compute background correction
Parameters: - which_data (str or list of str) – From which type of data to remove the background information. The list contains either “amplitude”, “phase”, or both.
- fit_profile (str) –
- The type of background profile to fit:
- ”ramp”: 2D linear ramp with offset (default)
- ”offset”: offset only
- fit_offset (str) –
- The method for computing the profile offset
- ”fit”: offset as fitting parameter
- ”gauss”: center of a gaussian fit
- ”mean”: simple average
- ”mode”: mode (see qpimage.bg_estimate.mode)
- border_m (float) – Assume that a frame of border_m meters around the image is background. The value is converted to pixels and rounded.
- border_perc (float) – Assume that a frame of border_perc percent around the image is background. The value is converted to pixels and rounded. If the aspect ratio of the image is not one, then the average of the data’s shape is used to compute the percentage in pixels.
- border_px (float) – Assume that a frame of border_px pixels around the image is background.
- from_binary (boolean np.ndarray or None) – Use a boolean array to define the background area. The binary image must have the same shape as the input data. True elements are used for background estimation.
- ret_binary (bool) – Return the binary image used to compute the background.
Notes
The border_* values are translated to pixel values and the largest pixel border is used to generate a binary image for background computation.
If any of the border_* arguments are non-zero and from_binary is given, the intersection of the two is used, i.e. the positions where both, the binary frame and from_binary, are True.
See also
-
copy
(h5file=None)[source]¶ Create a copy of the current instance
This is done by recursively copying the underlying hdf5 data.
Parameters: h5file (str, h5py.File, h5py.Group, or None) – see QPImage.__init__
-
refocus
(distance, method='helmholtz')[source]¶ Numerically refocus the current field
Parameters: See also
-
set_bg_data
(bg_data, which_data=None)[source]¶ Set background amplitude and phase data
Parameters: - bg_data (2d ndarray (float or complex), list, QPImage, or None) – The background data (must be same type as data). If set to None, the background data is reset.
- which_data (str) – String or comma-separated list of strings indicating the order and type of input data. Valid values are “field”, “phase”, “phase,amplitude”, or “phase,intensity”, where the latter two require an indexable object for bg_data with the phase data as first element.
holo (hologram analysis)¶
Methods¶
-
qpimage.holo.
find_sideband
(data)[source]¶ Find the side band position of a hologram
The hologram is Fourier-transformed and the side band is determined by finding the maximum amplitude in Fourier space.
Parameters: data (2d ndarray) – hologram image Returns: sb_loc – (x,y) coordinates of the side band in Fourier space measured from the center in the shifted Fourier transform. Return type: tuple of floats
-
qpimage.holo.
get_field
(data, sb_loc=None, filt_size=None, filt_type='gauss')[source]¶ Computes phase and amplitude from a holographic image
Parameters: - data (2d ndarray) – Hologram data
- sb_loc (tuple of floats (x0,y0)) – Coordinates of the side band in Fourier space.
- filt_size (float) – Radius of the filter in Fourier space in px. If set to None, the radius will be estimated using sb_loc.
- filt_type (float) – One of {“disk”, “gauss”}
- and y0 are center of the filter (x0) –
- is factor for "radius" of filter (sqrt(x0² + y0²)/np.pi) (R) –
- can be "disk" or "gauss" (filter_type) –
Notes
sb_loc are in FT of zero-padded image, see
fourier2dpad()
.
image_data (basic image management)¶
Constants¶
-
qpimage.image_data.
COMPRESSION
= 'gzip'¶ default hdf5 compression method
-
qpimage.image_data.
VALID_BG_KEYS
= ['data', 'fit']¶ valid background data identifiers
Classes¶
-
class
qpimage.image_data.
Amplitude
(h5)[source]¶ Bases:
qpimage.image_data.ImageData
Dedicated class for amplitude image data
For amplitude image data, background correction is defined by dividing the raw image by the background image.
Parameters: h5 (h5py.Group) – HDF5 group where all data is kept
-
class
qpimage.image_data.
Phase
(h5)[source]¶ Bases:
qpimage.image_data.ImageData
Dedicated class for phase image data
For phase image data, background correction is defined by subtracting the background image from the raw image.
Parameters: h5 (h5py.Group) – HDF5 group where all data is kept
-
class
qpimage.image_data.
ImageData
(h5)[source]¶ Base class for image management
See also
Parameters: h5 (h5py.Group) – HDF5 group where all data is kept -
bg
¶ combined background image data
-
image
¶ background corrected image data
-
info
¶ list of background correction parameters
-
raw
¶ raw (uncorrected) image data
-
del_bg
(key)[source]¶ Remove the background image data
Parameters: key (str) – One of VALID_BG_KEYS
-
estimate_bg
(fit_offset='mean', fit_profile='ramp', border_px=0, from_binary=None, ret_binary=False)[source]¶ Estimate image background
Parameters: - fit_profile (str) –
- The type of background profile to fit:
- ”ramp”: 2D linear ramp with offset (default)
- ”offset”: offset only
- fit_offset (str) –
- The method for computing the profile offset
- ”fit”: offset as fitting parameter
- ”gauss”: center of a gaussian fit
- ”mean”: simple average
- ”mode”: mode (see qpimage.bg_estimate.mode)
- border_px (float) – Assume that a frame of border_px pixels around the image is background.
- from_binary (boolean np.ndarray or None) – Use a boolean array to define the background area. The binary image must have the same shape as the input data.`True` elements are used for background estimation.
- ret_binary (bool) – Return the binary image used to compute the background.
Notes
If both border_px and from_binary are given, the intersection of the two resulting binary images is used.
The arguments passed to this method are stored in the hdf5 file self.h5 and are used for optional integrity checking using qpimage.integrity_check.check.
See also
- fit_profile (str) –
-
get_bg
(key=None, ret_attrs=False)[source]¶ Get the background data
Parameters: - key (None or str) – A user-defined key that identifies the background data.
Examples are “data” for experimental data, or “fit”
for an estimated background correction
(see
VALID_BG_KEYS
). If set to None, returns the combined background image (ImageData.bg
). - ret_attrs (bool) – Also returns the attributes of the background data.
- key (None or str) – A user-defined key that identifies the background data.
Examples are “data” for experimental data, or “fit”
for an estimated background correction
(see
-
set_bg
(bg, key='data', attrs={})[source]¶ Set the background data
Parameters: - bg (int, float, 2d ndarray, or same subclass of ImageData) – The background data. If set to None, the data will be removed.
- key (str) – One of
VALID_BG_KEYS
) - attrs (dict) – List of background attributes
See also
del_bg()
- removing background data
-
integrity_check (check QPImage data)¶
Exceptions¶
Methods¶
-
qpimage.integrity_check.
check
(qpi_or_h5file, checks=['attributes', 'background'])[source]¶ Checks various properties of a
qpimage.core.QPImage
instanceParameters: - qpi_or_h5file (qpimage.core.QPImage or str) – A QPImage object or a path to an hdf5 file
- checks (list of str) – Which checks to perform (“attributes” and/or “background”)
Raises: IntegrityCheckError
– if the checks fail
-
qpimage.integrity_check.
check_attributes
(qpi)[source]¶ Check QPimage attributes
Parameters: qpi (qpimage.core.QPImage) – Raises: IntegrityCheckError
– if the check fails
-
qpimage.integrity_check.
check_background
(qpi)[source]¶ Check QPimage background data
Parameters: qpi (qpimage.core.QPImage) – Raises: IntegrityCheckError
– if the check fails
meta (definitions for QPImage meta data)¶
Constants¶
-
qpimage.meta.
META_KEYS
= ['medium index', 'pixel size', 'time', 'wavelength', 'dm exclude', 'sim center', 'sim index', 'sim radius', 'identifier', 'qpimage version']¶ valid
qpimage.core.QPImage
meta data keys
Classes¶
-
class
qpimage.meta.
MetaDict
(*args, **kwargs)[source]¶ Bases:
dict
Management of meta data variables
Valid key names are combined in the
qpimage.meta.META_KEYS
variable.
series (QPSeries)¶
Classes¶
-
class
qpimage.series.
QPSeries
(qpimage_list=[], meta_data={}, h5file=None, h5mode='a', identifier=None)[source]¶ Quantitative phase image series
Parameters: - qpimage_list (list of QPImage) – A list of instances of
qpimage.QPImage
. - meta_data (dict) – Meta data associated with the input data
(see
qpimage.META_KEYS
). This overrides the meta data of the QPImages in qpimage_list and, if h5file is given and h5mode is not “r”, overrides the meta data in h5file. - h5file (str, h5py.Group, h5py.File, or None) – A path to an hdf5 data file where all data is cached. If
set to None (default), all data will be handled in
memory using the “core” driver of the
h5py
’sFile
class. If the file does not exist, it is created. If the file already exists, it is opened with the file mode defined by hdf5_mode. If this is an instance of h5py.Group or h5py.File, then this will be used to internally store all data. If h5file is given and qpimage_list is not empty, all QPImages in qpimage_list are appended to h5file in the given order. - h5mode (str) –
- Valid file modes are (only applies if h5file is a path)
- ”r”: Readonly, file must exist
- ”r+”: Read/write, file must exist
- ”w”: Create file, truncate if exists
- ”w-” or “x”: Create file, fail if exists
- ”a”: Read/write if exists, create otherwise (default)
-
identifier
¶ unique identifier of the series
- qpimage_list (list of QPImage) – A list of instances of