Package: pyotf
pyotfA simulation software package for modelling optical transfer functions (OTF)/point spread functions (PSF) of optical microscopes written in python.IntroductionThe majority of this package's documentation is included in the source code and should be available in any interactive session. The intent of this document is to give a quick overview of the package's features and potential uses. Much of the code has been designed with interactive sessions in mind but it should still be usable in larger scripts and programs.InstallationInstallation is simplest withcondaorpip:condainstall-cdavid-hoffmanpyotfpipinstallpyotfComponentsThe package is made up of four component modules:otf.pywhich contains classes for generating different types of OTFs and PSFsphase_retrieval.pywhich contains functions and classes to perform iterativephase retrievalof the rear aperature of the optical systemzernike.pywhich contains functions for calculatingZernike Polynomialsutils.pywhich contains various utility functions used throughout the package.otf.pyTwo models of optical imaging systems are available in this module one described byHanser et aland one described byArnison and Sheppard. They are, in fact, mathematically equivalent but in practice each have their strengths and weaknesses. A big benefit ofHanserPSFis that it allows one to calculate selected z planes of the PSF. However, if the choosen z-planes are not equispaced then the field OTF (OTFa) and intensity OTF (OTFi) calculated from the model won't make physical sense.Both theSheppardPSFandHanserPSFhave much the same interface. When instantiating them the user must provide a set of model parameters. To fully describe a PSF or OTF of an objective lens, assuming no abberation, we generally need a few parameters:The wavelength of operation (assume monochromatic light)the numerical aperature of the objectivethe index of refraction of the mediumFor numerical calculations we'll also want to know the x/y resolution and number of points. Note that it is assumed that z is the optical axis of the objective lens.phaseretrieval.pyThe phase retrieval algorithm implemented in this module is described byHanser et. al.An example for how to use these functions can be found at the end of the file:# phase retrieve a pupilfrompathlibimportPathimporttimeimportwarningsimporttifffileastiffrom.utilsimportprep_data_for_PR# read in data from fixtureswithwarnings.catch_warnings():warnings.simplefilter("ignore")data=tif.imread(str(Path(__file__).parent.parent/"fixtures/psf_wl520nm_z300nm_x130nm_na0.85_n1.0.tif"))# prep datadata_prepped=prep_data_for_PR(data,256,1.1)# set up model paramsparams=dict(wl=520,na=0.85,ni=1.0,res=130,zres=300)# retrieve the phasepr_start=time.time()print("Starting phase retrieval ... ",end="",flush=True)pr_result=retrieve_phase(data_prepped,params,100,1e-4,1e-4)pr_time=time.time()-pr_startprint(f"{pr_time:.1f}seconds were required to retrieve the pupil function")# plotpr_result.plot()pr_result.plot_convergence()# fit to zernikeszd_start=time.time()print("Starting zernike decomposition ... ",end="",flush=True)pr_result.fit_to_zernikes(120)pr_result.zd_result.plot()zd_time=time.time()-zd_startprint(f"{zd_time:.1f}seconds were required to fit 120 Zernikes")# plotpr_result.zd_result.plot_named_coefs()pr_result.zd_result.plot_coefs()# showplt.show()Below is a plot of the phase and magnitude of the retrieved pupil function from a PSF recorded fromthisinstrument. To generate this plot we simply call theplotmethod of thePhaseRetrievalResultobject (in this casepr_result).And here the phase and magnitude have been fitted to 120 zernike polynomials. To generate this plot we simply call theplotmethod of theZernikeDecompositionobject (in this casepr_result.zd_result).We can plot the magnitude of the first 15 named phase coefficients by callingpr_result.zd_result.plot_named_coefs().NOTE:If all that is needed is phase, e.g. for adaptive optical correction, then most normal ways of estimating the background should be sufficient and you can use thephase_onlykeyword. However, if you want to properly model your PSF for something like deconvolution then you should be aware that the magnitude estimate isincrediblysensitive to the background correction applied to the data prior to running the algorithm, and multiple background methods/parameters should be tried.zernike.pyZernike Polynomialsare orthonormal functions defined over the unit disk. Being orthonormal any function defined on a unit disk has a unique decomposition into Zernike polynomials. In this package, the Zernike polynomials are used to quantify the abberation of the phase and magnitude of the retrieved back pupil of the optical system. To do so one can call thefit_to_zernikesmethod of aPhaseRetrievalResultobject, which will fit a specified number of Zernike modes to the back pupil's retrieved phase and magnitude, each independently, and return aZernikeDecompositionobject. TheZernikeDecompositionthat is returned is also saved as an attribute of thePhaseRetreivalResultobject on which thefit_to_zernikesmethod was called, for convenience.ZernikeDecompositionobjects have plotting methods so that the user can inspect the decomposition.ZernikeDecompositionobjects also have methods for reconstructing the phase, magnitude or complete complex pupil which can be fed back intoHanserPSFto generate an abberated, but noise free, PSF. The method for doing this simply is currently a member of thePhaseRetreivalResultclass but will probably be moved to theZernikeDecompositionclass later.utils.pyMost of the contents ofutilswon't be useful to the average user save one function:prep_data_for_PR(data, xysize=None, multiplier=1.5).prep_data_for_PRcan, as its name suggests, be used to quickly prep PSF image data for phase retrieval using theretrieve_phasefunction of thephase_retrievalmodule.LabVIEW APIAn example of inputing a 3D stack and running this python function from LabVIEW (>2018) is given in\labview\Test Phase Retrieval.viReferencesHanser, B. M.; Gustafsson, M. G. L.; Agard, D. A.; Sedat, J. W. Phase Retrieval for High-Numerical-Aperture Optical Systems.Optics Letters 2003, 28 (10), 801.Arnison, M. R.; Sheppard, C. J. R. A 3D Vectorial Optical Transfer Function Suitable for Arbitrary Pupil Functions. Optics Communications 2002, 211 (1–6), 53–63.Hanser, B. M.; Gustafsson, M. G. L.; Agard, D. A.; Sedat, J. W. Phase-Retrieved Pupil Functions in Wide-Field Fluorescence Microscopy. Journal of Microscopy 2004, 216 (1), 32–48.