openpDPC_condenser

Table of Contents

• MM2_pDPC
  • Overview
    • Introduction
    • Important notes
    • Useful external links
  • Installation
  • Pre-requisite for python-based features
  • User guide
    • Live
    • Recon
    • Cali
    • LiveSplit
    • Special notes
      • Launch/Stop python background process
      • Parameters \& Presets
        • Physical meaning of pDPC parameters
  • References

MM2_pDPC

Overview

Introduction

This is a plugin for μManager (MM) (version 2.0 or later) to perform image processing etc. for polarisation-resolved differential phase contrast (pDPC) microscopy. For details on the pDPC technique, see Ref. [1].

This plugin provides four main features:

• Live:

  Reconstruct phase from the raw camera image acquired by MM LiveSnap and then live display the reconstructed phase image.

• Recon:

  Reconstruct phase from raw image(s) (single TIFF file) loaded from a given path and then save the reconstructed phase image(s) to a specified path also as single TIFF file.

• Cali:

  Calibrate the response matrices for the pDPC system using a set of calibration images loaded from given paths.

• LiveSplit:

  Interleave the raw camera image acquired by MM LiveSnap into four sub channel images and then live display the four sub channel images.

The python code for the phase reconstruction process in this plugin is based on the DPC principle in Ref. [2-4] and adapted from Ref. [5-6].

Important notes

• Among above features, Live, Recon, and Cali rely on image processing in python and cannot be used simultaneously, while LiveSplit does not.
• The python-based features do not require the user to run python scripts directly, but instead the user need:
  1. Before launching the plugin, setup a proper Anaconda environment with all required python packages installed (see here for details).
  2. Before/after using the feature(s) in the plugin, launch/stop python background process (see here for details).
• Live and Recon features use current_settings in Preset Panel to reconstruct phase (see here for details on parameters & presets).
• Live and LiveSplit features use whatever camera currently set as Core-Camera in MM.

  • Demo videos below use MMConfig_Demo.cfg, which is a demo configuration provided by MM, for illustration purposes only.

    Core-Camera in this demo configuration is set as DCam (a virtual camera).

  • In practice, Core-Camera should be set as the polarisation camera used for pDPC imaging.

Useful external links

• μManager 2.0
• Anaconda tutorial & conda commands

Installation

1. Install μManager (version 2.0.0 or later) if not yet.
2. Download MM2_pDPC.jar from this repo and place it in the mmplugins folder under the μManager installation root.

To check if the plugin is successfully installed, launch μManager and check if the plugin name, pDPC, appears in the Plugins menu as shown in the figure below.

Pre-requisite for python-based features

To use the python-based features of this plugin, one MUST make sure that there is at least one Anaconda environment with the required python packages installed.

1. Install Anaconda if not yet.

2. Record the path to Anaconda installation directory.

   This path will be used in the plugin to identify available environments and locate their corr. python executables.

3. Setup an Anaconda environment with the required python packages if not yet.

   This plugin requires the following python packages:

   • opencv-python
   • numpy
   • tifffile
   • PyQt5
   • magicgui
   • scipy

   Below is an example of how to create a new Anaconda environment and install all required python packages.

    conda create -n pdpc-env python=3.10 
    conda activate pdpc-env 
    conda install -c conda-forge opencv numpy tifffile pyqt magicgui scipy 
   

User guide

Live

If video is not shown in browser, click here to download and view it.

Empirically, set binning to 2 is a good trade-off between speed and resolution for phase reconstruction on live.

Recon

If video is not shown in browser, click here to download and view it.

Cali

If video is not shown in browser, click here to download and view it.

LiveSplit

If video is not shown in browser, click here to download and view it.

Special notes

Launch/Stop python background process

• Launch python process

  If video is not shown in browser, click here to download and view it.

  Updates:

  • 2024-Oct-29: Added two settings to be set before launching python process: Socket BufSize and Do Absorption, highlighted by green and orange circles in the figure below respectively. Note that both need to be set before launching python process to really take effect.

  

    - `Socket BufSize` is the socket buffer size that python will use to receive data from the plugin.
    By default, it is set as 1024. When long params are passed to python, 
    e.g., a `dark_bkg_path` or `light_bkg_path` with a long path string, 
    one can increase this value to avoid data truncation during data transmission and hence avoid error raised from python side.
    - `Do Absorption` is a boolean flag to specify whether to save the absorption image calculated as well.
    If set as true, the absorption image will be saved to the same folder as the phase image.
        - If the name of saved phase image is `phase*`, the absorption image will be saved as `absorption*`.
        - Otherwise, the absorption image will be saved by adding `absorption_` to the name of saved phase image.
  

• Stop python process

  If video is not shown in browser, click here to download and view it.

Parameters & Presets

If video is not shown in browser, click here to download and view it.

preset name is the identifier used to update/add/remove preset.

If Use advanced pDPC params is not selected, only basic parameters in Current settings will be passed to python for phase reconstruction with default ideal values used for advanced parameters.

Physical meaning of pDPC parameters

• Basic parameters:
  • NA_illu: maximum illumination NA;
  • lbd_um: illumination wavelength in um;
  • NA_img: objective NA;
  • mag: magnification of the microscope configuration;
  • seq: 0-7 integer, to specify the order of the QP w.r.t. the camera sub polarization channels; usually sweeped to find the correct value;
  • binning: binning factor during reconstruction;
  • use_pupil: always false for condenser-based pDPC;
  • reg_p: regularization parameter for phase reconstruction; empirically set; usually 0.001 - 0.01;
  • reg_u: regularization parameter for amplitude reconstruction; empirically set; usually 1e-5;
  • px_cam_um: camera sensor physical pixel size in um; always 3.45 for FLIR Blackfly PolCam we’ve been used;
• Advanced parameters:
  • Q2S: QPs to sub polarization channels mapping matrix, in string format; 4x4 matrix; ideally should be “[[1.0, 0.5, 0.5, 0.0], [0.5, 1.0, 0.0, 0.5], [ 0.5, 0.0, 1.0, 0.5], [ 0.0, 0.5, 0.5, 1.0]]”;
  • quadGap_mm: Gap width between neighbor QP apertures in mm, at condenser back focal plane; default 0; depending on actual QP mask;
  • quadRotate_rad: Rotation angle of the QP mask w.r.t. the camera sub polarization channels; default 0;
  • S_OffAxisYX_mm: Off-axis distance of the QP mask w.r.t. optical axis in mm; default 0;
  • P_OffAxisYX_mm: Off-axis distance of the objective w.r.t. optical axis in mm; default 0;
  • condenser_f_mm: condenser focal length in mm; default 30;
  • objective_f_mm: objective focal length in mm; default 18;
  • quadNorm_coeff: system transmission for each QP, in string format; 1x4 matrix; default “[1.0, 1.0, 1.0, 1.0]”;
  • sp_pattern: 0-2 integer, to specify how sub polarisation channel images are used during phase reconstruction; should always be 1 (default) for now;
  • dark_bkg_path: path to the dark background image file; default “None”;
  • light_bkg_path: path to the light background image file; default “None”;

References

[1] R. Kalita, W. Flanagan, J. Lightley, S. Kumar, Y. Alexandrov, E. Garcia, M. Hintze, M. Barkoulas, C. Dunsby, P.M.W. French, Single-shot phase contrast microscopy using polarisation-resolved differential phase contrast, J. Biophotonics (2021). https://doi.org/10.1002/jbio.202100144.
[2] L. Tian, L. Waller, Quantitative differential phase contrast imaging in an LED array microscope, Opt. Express 23 (2015). https://doi.org/10.1364/oe.23.011394.
[3] Z.F. Phillips, M. Chen, L. Waller, Single-shot quantitative phase microscopy with color-multiplexed differential phase contrast (cDPC), PLoS One 12 (2017). https://doi.org/10.1371/journal.pone.0171228.
[4] M. Chen, Z.F. Phillips, L. Waller, Quantitative differential phase contrast (DPC) microscopy with computational aberration correction, Opt. Express 26 (2018) 32888–32899. https://doi.org/10.1364/OE.26.032888.
[5] https://github.com/Waller-Lab/DPC
[6] https://github.com/Waller-Lab/DPC_withAberrationCorrection

This site is open source. Improve this page.