The ImageEM class — PhaseLAB documentation 4.0 documentation

Public properties
name	type	description
`Microscope`	Microscope	Microscope object
`Illumination`	Illumination	Illumination object
`comment`	char	Any comment on the image

Read-only properties
name	type	description
`Ex`	double array	\(x\) component image of the electric field
`Ey`	double array	\(y\) component image of the electric field
`Ez`	double array	\(z\) component image of the electric field
`Einc`	ImageEM	Incident electric field
name	type	description
`Nx`	double	Number of columns
`Ny`	double	Number of rows
`E2`	double	Image of the Efield intensity
`E`	double	Amplitude of the Efield
`Ph`	double	Phase image

alpha_ImageProfile
Return the polarisability, optical volume and dry mass of small objects.

Synthax

% prototype
params = obj.alpha_ImageProfile(Name,Value);

% examples
params = obj.alpha_ImageProfile();
params = obj.alpha_ImageProfile('nmax', 100, 'nBkg', 4);

Description

This method of the ImageEM and ImageQLSI classes returns the polarisability, OV and DM of small objects, using a radial profile method. The algorithm involves a sum of the pixels on a circular area. The method opens a window with the image. First, click on the OPD image to zoom in on the particle of interest, and press ‘z’ when the zoom is correct. Second, click on the center of the particle. A new figure will show up, plotting the pixel summation as a function of the radius of the circular area, from 0 to 100 px. Finally, click two times on the graph to define the range of values corresponding to a proper convergence of the integration. In practice, the line shape should feature a plateau, and the user should click at the beginning and at the end of the plateau. For instance, in this example, the user could click on \(x=18\) and \(x=40\):

Finally, the values of polarisability, and optical volume are returned as a structure, containing the fields alpha, OV and OVw. OVw is the weighted optical volume as defined in Ref. 1.

1: Biomass measurements of single neurites in vitro using optical wavefront microscopy, L. Durdevic, A. Resano Gines, A. Roueff, G. Blivet, G. Baffou, Biomedical Optics Express 13, 6550-6560 (2022)

Name-Value inputs

Several Name-Value inputs can be used to adjust the way the procedure works:

'nmax', default value: 40

Maximum radius of the integration area.
'nBkg', default value: 3

Width of the boundary considered to calculate the zero value of the background.
'NNP', default value: 1

Number of particles to be clicked on the image. The procedure stops after N particles are processed, and the returned data is an array of values.
'zoom', default value: true

Enables the user to first zoom before clicking on the particle
'step', default value: 1

The integration as a function of the radius will be calculated only every N pixels, where N is the step value. Specifying a value larger than 1 can make the processing faster.
'keepPoint', default value: false

Keeps the same clicking point from one image to another. It can save time if many images need to be processed, and if the NP does not move from one image to another.
'display', default value: false

Displays the results of all the measurements in a single graph. Makes sense only if multiple measurements are made within a single call of the function.

applyPCmask
Returns a re-calculated image with a phase contrast mask in the objective lens.

Synthax

obj = obj0.applyPCmask(mask);
objList = objList0.applyPCmask(mask);

Description

obj = obj0.applyPCmask(mask); recalculate the \(E\) field at the image plane when adding a phase mask at the pupil of the objective. It is used to model Zernike phase-contrast microscopy. mask is a PCmask object.

objList = objList0.applyPCmask(mask);: ImageEM object vectors can also be used with this method. The transformation applies then to all the objects of the vector.

applyPhaseShift
Apply a phase shift to the whole image.

Synthax

obj = obj0.applyPhaseShift(phi);

Description

obj = obj0.applyPhaseShift(phi); applies a phase shift phi to the whole image. Used to model phase-shifting techniques, not really useful in CGM/QLSI.

binning
Performs 2x2 or 3x3 pixel binning of the images of the ImageEM object.

Synthax

obj.binning()
obj.binning(n)
obj2 = obj.binning(___);

Description

The binning method applies a binning to all the images of the object.

obj.binning() performs, by default, a 3x3 binning of the images of obj.

obj.binning(n) performs, \(n\times n\) binning of the images of obj. Only works with n = 2, 3, 4, 6.

If an output argument is specified, obj is not modified, but duplicated.

crop
Crop the images of the object.

Synthax

obj.crop()
obj.crop(Name, Value)
objList.crop(___)
obj2 = obj.crop(___);
[obj2, params] = obj.crop(___);

Description

obj.crop() crops the \(E\) fields of the object and of the Ref object, identically. A figure window opens, inviting the user to click on the image to define a square area centered in the middle of the image.

Objects vectors can also be used with this method. The transformation applies then to all the objects of the vector.

If an output is used, obj2, then the object is not modified, but duplicated.

If a second output is specified, then the crop parameters are returned as a 4-vector params = [x1, x2, y1, y2];

Name-value arguments

Note

Specify optional pairs of arguments as Name1 = Value1, ..., NameN = ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example:

obj.crop(___,'Center','Manual','Size',300)

'Center'

With crop(___,'Center','Manual'), the user has to first click on the center of the reference area. If the argument is set to 'Auto', then this step is skipped, and the center is automatically set to the center of the image. Also, the user can indicate the coordinates of the center using crop(___,'Center',[x_c, y_c]).
'Size'

With crop(___,'Size','Manual'), once the center is defined (either manually or automatically), the user has to click on the figure to define the shape of the area, around the center point. The user can also indicate the dimensions of the reference area using crop(___,'Size',Npx) for a square area, or crop(___,'Size',[Nx, Ny]) for a rectangular area.
'twoPoints'

Instead of using the 'Center' and 'Size' keywords, one can also click on two opposite corners of the reference area, using crop(___,'twoPoints',true).
'params'

One can also direclty write the coordinates of the crops, using crop(___,'params', [x1, x2, y1, y2]). In this case, no figure opens.

Here is an example of a code that crops a first object manually, and applies automatically the same crop to a second object:

[IMc(1) params] = IM(1).crop('Center', 'Manual', 'Size', 'Manual');
IMc(2) = IM(2).crop('params', params);

Note that this code is equivalent to:

IMc = IM.crop('Center', 'Manual', 'Size', 'Manual');

CrossSections
Return the polarisability and cross sections of a NP image.

Synthax

val = obj.CrossSections()

Description

This function applies when dealing with the image of a single nanoparticle. It computes the optical properties of a nanoparticle from its image, according to the theory introduced in Ref 2.

obj can by a vector of ImageEM objects. In this case, the calculation will be performed on all the objects of the list.

val = obj.CrossSections() return a NPprop object containing the complex optical polarisability of the NP, and the 3 cross-sections.

2: Full optical characterization of single nanoparticles using quantitative phase imaging, S. Khadir, Daniel Andrén, P. C. Chaumet, S. Monneret, N. Bonod, M. Käll, A. Sentenac, G. Baffou, Optica 7, 243-248 (2020)

dmd
Return the dry mass density (DMD) image.

Synthax

val = obj.dmd();

Description

val is the DMD image, in pg/µm². This function actually just consists of multiplying the OPD in [nm] by 5.56e-3.

dxSize
Return the dexel size.

Synthax

val = obj.dxSize();

Description

Returns the dexel size (i.e. the camera pixel size), val = obj.Microscope.CGcam.dxSize;.

Note

This method returns the effective dexel size, which is not necessarily the actual dexel size of the camera sensor. When there is a RL, applying a zoom \(Z\) to the system, the {RL, camera} system is equivalent to a single camera with a dexel size divided by the zoom. This method returns the dexel size of this equivalent camera, called the effective dexel size.

EE0
Return the value of the incident field at the center of the field of view.

Synthax

val = obj.EE0()

Description

This method returns the value of the incident field, at the center of the field of view, at the sample plane (not at the image plane), at \(z=0\). If obj is already an incident field, it simply returns its value at the center of the field of view.

EE0n
Return the value of the norm of the incident field at the center of the field of view.

Synthax

val = obj.EE0n()

Description

This method returns the norm of the incident field at the center of the field of view, at the sample plane (not at the image plane). If obj is already an incident field, it simply returns the norm of the field at the center of the field of view.

obj can by a vector of ImageEM objects. In that case, the treatment will be perform on all the objects of the list.

Escat
Return the image of the scattered electric field as an ImageEM object.

Synthax

obj_sca = obj.Escat();
objList_sca = objList.Escat();

Description

This method returns the scattered \(E\) field image, as a new ImageEM object.

figure
Display the PhaseLAB GUI

Synthax

obj.figure()
app = obj.figure();

Description

This method displays the images of the obj within the GUI (graphical user interface) of PhaseLAB. See the GUI of PhaseLAB section for details.

flipud
Flips the images of the object about the horizontal axis.

Synthax

obj.flipud();
objList.flipud();
obj2 = obj.flipud();

Description

Methods that flips all the images of the object about the horizontal axis (flips upside-down).

ImageEM object vectors can also be used with this method. The transformation applies then to all the objects of the vector.

If an output obj2 is used, then the object is duplicated before being modified.

fliplr
Flips the images of the object about the vertical axis.

Synthax

obj.fliplr();
objList.fliplr();
obj2 = obj.fliplr();

Description

Methods that flips all the images of the object about the vertical axis (flips left-right).

ImageEM objects vectors can also be used with this method. The transformation applies then to all the objects of the vector.

If an output obj2 is used, then the object is duplicated before being modified.

FT
Return the Fourier transform of the E field.

Synthax

I = obj.FT();

Description

I = obj.FT() returns the square of the norm I of the Fourier transform of the \(E\) field:

\[I = \vert \mathcal{F}[Ex]\vert^2 + \vert\mathcal{F}[Ey]\vert^2\]

imageHSV
display a mix of the T an OPD images according to a HSV colorscale pattern.

Synthax

imageHSV(obj);

Description

The imageHSV method displays a mix of the intensity an OPD images according to a HSV pattern. Just like the RVB coding, HSV coding codes any color with 3 numbers:

H means Hue and represents the color on a chromatic circle
S means Saturation and tells if the colors are vivid or pale.
V means Value and tells if the color is bright or dark.

Here is a picture that explains the HSV color coding:

Example

The imageHSV method assigns the OPD image to the Hue (the colorscale), and the intensity image to the Saturation (this way, areas with low intensity appear dark), and keeping the Value to 1.

Jones
apply Jones matrices to the E field of the images.

Synthax

% general forms
obj = obj0.Jones([a, b; c, d]);
obj = obj0.crop(Name, Value);

% examples
obj2 = obj.Jones([1 0; 0 0]);
obj2 = obj.Jones('P', 0, 'HWP', 45, 'QWP', 45);

Description

The Jones function models the application of polarizers and wave plates to the image, with a Jones matrix formalism. For a given electric field \(E = (E_x, E_y)\), the new field \(E'\) reads

\[\begin{split}\begin{bmatrix} E_x' \\ E_y' \end{bmatrix} = \begin{bmatrix} a & b \\ c & d \end{bmatrix} \cdot \begin{bmatrix} E_x \\ E_y \end{bmatrix}\end{split}\]

\([a, b; c, d]\) is the Jones matrix. For instance, for a polarizer along the \(x\) axis, it reads

\[\begin{split}P = \begin{bmatrix} 1 & 0 \\ 0 & 0 \end{bmatrix}\end{split}\]

For a half wave plate with fast axis along \(x\), it reads

\[\begin{split}H = \begin{bmatrix} 1 & 0 \\ 0 & -1 \end{bmatrix}\end{split}\]

And for a half wave plate rotated by an angle \(\theta\), it reads

\[\begin{split}H(\theta) = \begin{bmatrix} cos 2\theta & sin 2\theta \\ sin 2\theta & -cos 2\theta \end{bmatrix}\end{split}\]

obj = obj0.Jones([a, b; c, d]); applies the Jones matrix to every pixel of the E field, and incident E field of the ImageEM object.

obj = obj0.Jones(Name, Value); applies the optical component Name placed at an angle Value. Several name-value pairs can be used: Name1 = Value1, ..., NameN = ValueN. They will be applied to the images in the order they are specified.

Here are the possible 'Name' keywords:

'P'

Models the application of a linear polarizer. The associated value is the angle of the polarizer.
'HWP'

Models the application of a half wave plate. The associated value is the angle of the fast axis of the wave plate.
'QWP'

Models the application of a quarter wave plate. The associated value is the angle of the fast axis of the wave plate.

lambda
Return the wavelength of the illumination.

Synthax

val = obj.lambda();

Description

This method returns the wavelength of the illumination used to acquire the image, val = obj.Illumination.lambda;.

MakeMoviedx
Make a movie from a series of image objects

Synthax

% prototypes
objList.makeMoviedx(videoName)
objList.makeMoviedx(videoName, Name, Value)

% examples
objList.makeMoviedx('movie/bacteria.avi')
objList.makeMoviedx('movie/bacteria.avi', )
objList.makeMoviedx('movie/bacteria.avi','theta',0,'phi',0,'rate',2,'zrange',[-10 10])

Description

The MakeMoviedx method creates an .avi movie from an ImageEM or ImageQLSI object array. Two inputs are required, the image object array IM and the path/name of the movie file to be created videoname. It calls the method opendx, from the same class.

Many Name-value options can be specified to change the rendering.

'persp' (default: 1)

With 'persp' set to 1, the video uses the opendx method to create a nice 3D rendering of the image. Set this option to 0 to cancel this effect.
'phi' (default: 45) and 'theta' (default: 45)

Position of the camera in (theta, phi). (0,0) corresponds to the top view.
'ampl' (default: 3)

sets the magnitude of the 3D visual topography
'zrange'

2-vector setting the limits of the \(z\) axis.
'colorMap' (default: Parula)

Color map.
'title'

Title to display on the movie, if any.
'factor' (default: 1)

Correction factor to the OPD, for instance 5.55e-3 to convert the OPD into DM.
'label' (default: 'Optical path difference (nm)')

Label to put on the color scale.
'imType' (default: 'OPD')

Cell array of the images of the object to be displayed within the figure of the movie, side by side: 'OPD', 'T', 'DWx', 'DWy', 'Ph'.
'axisDisplay' (default: true)

Display the axes or not.
'rate' (default: 25)

Video rate in frames per second.
'frameTime' (default: [])

Time between successive frames. If specified, the time is displayed on each frame.
'timeUnit' (default: s)

Unit of the time to be displayed. Can be 's', 'min' or 'h'.
'timeFontSize' (default: [])

Set the font size displayed on the movie.
'timeFontColor' (default: [0, 0, 0])

Set the color of the displayed time label. By default it is black, but depending on the colormap of the image, it may be necessary to use a brighter color. White is [1, 1, 1].
'timeSize'

If the default size is not appropriate, choose a specific one using this option. 16 can be a good starting value.

opendx
Display a 3D rendering of the image

Synthax

% prototypes
opendx(obj)
opendx(obj, Name, Value)

% examples
opendx(IM)
objList.makeMoviedx(IM, 'theta', 10, 'phi', 30, 'zrange', [-10 120]*1e-9, 'ampl', 4)

Description

The opendx method diplays images from ImageEM or ImageQLSI objects with a nice 3D rendering.

Many Name-value options can be specified to change the rendering.

'persp' (default: 1)

With 'persp' set to 1, the video uses the opendx method to create a nnince 3D rendering of the image. Set this option to 0 to cancel this effect.
'phi' (default: 45) and 'theta' (default: 45)

Position of the camera in \((\theta, \phi)\)
'ampl' (default: 3)

sets the magnitude of the 3D relief
'zrange'

2-vector setting the limits of the z axis.
'colorMap' (default: parula)

Color map.
'title'

Title to display on the movie, if any.
'factor' (default: 1)

Correction factor to the OPD, for instance 5.55e-3 to convert the OPD into DM.
'label' (default: 'Optical path difference (nm)')

Label to put on the color scale.
'imType' (default: 'OPD')

Cell array of the properties of the object to be displayed: 'OPD', 'T', 'DWx', 'DWy', 'Ph'.
'axisDisplay' (default: true)

Display the axes or not.

overview
Display all the images of an object array in a single figure

Synthax

objList.overview();
objList.overview('types', typeList)

Description

This method displays all the images of an object array in a single figure. Here is an example of what it gives with an array of 15 objects:

pxSize
Return the image pixel size at the sample plane.

Synthax

val = obj.pxSize();

Description

Returns the pixel size at the sample plane.

rot90
Rotate the images of the object by multiples of 90°.

Synthax

obj.rot90();
obj.rot90(k);
objList.rot90(___);
obj2 = obj.rot90(___);

Description

obj.rot90() rotates the images of the object by 90°, counterclockwise.

obj.rot90(k) rotates the images of the object by \(k\times90°\), counterclockwise. k must be an integer and can be negative.

ImageEM object vectors can also be used with this method. The transformation applies then to all the objects of the vector.

If an output obj2 is used, then the object is not modified, and duplicated.

Rytov
Return the Rytov image.

Synthax

val = obj.Rytov();

Description

Method that returns the Rytov image, defined by 3

\[I_\mathrm{Rytov} = \left\vert\frac{\lambda n}{\pi}\left[\frac{ln(T)}{2}+i\varphi\right]\right\vert^2\]

where \(\lambda\) is the wavelength, \(n\) the refractive index of the surrounding medium, \(T\) the intensity image and \(\varphi\) the phase image.

3: Label-Free Single Nanoparticle Identification and Characterization in Demanding Environment, Including Infectious Emergent Virus, Nguyen et al., Small 2304564 (2023)

save
Export the T and OPD images as jpg and txt files.

Synthax

% general patterns
obj.save(folder)
obj.save(folder, Names)

% Examples,
obj.save('savedData', 'T')
obj.save('savedData', 'OPD')
obj.save('savedData', 'T', 'OPD')
obj.save('savedData', 'T', 'OPD', 'Ex', 'Ey')

Description

Export the intensity, wavefront, phase, and/or E fields of the ImageEM object into a folder, as .txt and .jpg files. To indicate which images are saved, a list a Names has to be indicated as separated arguments, corresponding to the names of the properties, e.g., 'T', 'OPD', 'Ex', 'Ey'.

sizeof
sizeof

Returns the size of the object in Kb.

Synthax

obj.sizeof()
val = obj.sizeof();

Description

Returns or display the size of the object (list) occupied on the hard drive. If not output is specified, it displays the size, in Mb, or Kb, in the command window. Otherwise, it returns the size in bytes.

sum
Coherent sum of the fields.

Synthax

obj = sum(objList);

Description

The method uses the overloaded operator + to sum all the E fields or list of ImageEM E fields in objList. It simply sums the electromagnetic fields associated to all 2 ImageEM objects. Note that it also sums the incident fields.

Warning

This method is relevant if the different images correspond to the same sample, for instance an object illuminated with various plane waves with different incidence angles at the same time.

When the list of images does not correspond to the same sample, for instance when it consists of different nanoparticles at different locations, one should not use this method to get the image of all the nanoparticles at the same time. There will be no self-consistent optical coupling between these objects, and the incident E fields should be sumed in this case. Prefer summing dipoles (DIlist=DI1+DI2) and then imaging the dipole array(DIlist.imaging()), which will run a DDA self consistent calculation of the dipolar moments.

write
copy the properties of an ImageEM object into another.

Synthax

write(obj, obj_in)
obj.write(obj_in)

Description

The method copies all the properties of obj_in into the prexisting object obj, without creating a new handle.

+
Defines the addition between two ImageEM objects: IM1 + IM2.

Synthax

obj = plus(obj1, obj2);
obj = obj1 + obj2;
obj = obj1 + obj2 + ... + objN;

Description

The method overloads the operator + by defining the method plus. It simply sums the electromagnetic fields associated to the 2 ImageEM objects. Note that it also sums the incident fields. It is relevant to use when the sample is illuminated at the same time with different plane waves at different angles for instance.

Warning

By summing images of different particles/dipoles, there is no self-consistent optical coupling between these objects. Prefer summing dipoles and then imaging the dipole array, which will run a DDA self consistent calculation of the dipolar moments.

The method also work with several additions at a time: obj = obj1 + obj2 + ... + objN;. When all these images are in a ImageEM array, one can write obj = sum(objList).

The ImageEM class

Properties

ImageEM methods