{"id":15576803,"url":"https://github.com/tlambert03/psfmodels","last_synced_at":"2025-09-11T00:34:41.145Z","repository":{"id":42026818,"uuid":"207698001","full_name":"tlambert03/PSFmodels","owner":"tlambert03","description":"Python bindings for scalar and vectorial models of the 3D microscope point spread function. ","archived":false,"fork":false,"pushed_at":"2024-05-20T14:18:03.000Z","size":1021,"stargazers_count":49,"open_issues_count":5,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-19T08:13:49.856Z","etag":null,"topics":["microscopy","psf"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tlambert03.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-09-11T01:42:01.000Z","updated_at":"2025-01-29T15:59:58.000Z","dependencies_parsed_at":"2022-09-10T00:40:46.254Z","dependency_job_id":"295a4cbb-7797-4fd7-9850-fe6a481c003c","html_url":"https://github.com/tlambert03/PSFmodels","commit_stats":{"total_commits":99,"total_committers":1,"mean_commits":99.0,"dds":0.0,"last_synced_commit":"00a275947dd0d762fa0632b6167bd40ac769be27"},"previous_names":["tlambert03/psfmodels-py"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FPSFmodels","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FPSFmodels/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FPSFmodels/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FPSFmodels/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tlambert03","download_url":"https://codeload.github.com/tlambert03/PSFmodels/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250478444,"owners_count":21437170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["microscopy","psf"],"created_at":"2024-10-02T18:58:23.308Z","updated_at":"2025-04-23T17:23:30.801Z","avatar_url":"https://github.com/tlambert03.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# psfmodels\n\n[![PyPI](https://img.shields.io/pypi/v/psfmodels.svg?color=green)](https://pypi.org/project/psfmodels)\n[![Python\nVersion](https://img.shields.io/pypi/pyversions/psfmodels.svg?color=green)](https://python.org)\n[![CI](https://github.com/tlambert03/psfmodels/actions/workflows/ci.yml/badge.svg)](https://github.com/tlambert03/psfmodels/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/tlambert03/psfmodels/branch/main/graph/badge.svg)](https://codecov.io/gh/tlambert03/psfmodels)\n\nPython bindings for scalar and vectorial models of the point spread function.\n\nOriginal C++ code and MATLAB MEX bindings Copyright \u0026copy; 2006-2013, [Francois\nAguet](http://www.francoisaguet.net/software.html), distributed under GPL-3.0\nlicense. Python bindings by Talley Lambert\n\nThis package contains three models:\n\n1. The vectorial model is described in Auget et al 2009\u003csup\u003e1\u003c/sup\u003e. For more\ninformation and implementation details, see Francois' Thesis\u003csup\u003e2\u003c/sup\u003e.\n2. A scalar model, based on Gibson \u0026 Lanni\u003csup\u003e3\u003c/sup\u003e.\n3. A gaussian approximation (both paraxial and non-paraxial), using paramters from Zhang et al (2007)\u003csup\u003e4\u003c/sup\u003e.\n\n\u003csmall\u003e\n\n\u003csup\u003e1\u003c/sup\u003e [F. Aguet et al., (2009) Opt. Express 17(8), pp.\n6829-6848](https://doi.org/10.1364/OE.17.006829)\n\n\u003csup\u003e2\u003c/sup\u003e [F. Aguet. (2009) Super-Resolution Fluorescence Microscopy Based on\nPhysical Models. Swiss Federal Institute of Technology Lausanne, EPFL Thesis no.\n4418](http://bigwww.epfl.ch/publications/aguet0903.html)\n\n\u003csup\u003e3\u003c/sup\u003e [F. Gibson and F. Lanni (1992) J. Opt. Soc. Am. A, vol. 9, no. 1, pp. 154-166](https://opg.optica.org/josaa/abstract.cfm?uri=josaa-9-1-154)\n\n\u003csup\u003e4\u003c/sup\u003e [Zhang et al (2007). Appl Opt\n. 2007 Apr 1;46(10):1819-29.](https://doi.org/10.1364/AO.46.001819)\n\n\u003c/small\u003e\n\n### see also:\n\nFor a different (faster) scalar-based Gibson–Lanni PSF model, see the\n[MicroscPSF](https://github.com/MicroscPSF) project, based on [Li et al\n(2017)](https://doi.org/10.1364/JOSAA.34.001029) which has been implemented in\n[Python](https://github.com/MicroscPSF/MicroscPSF-Py),\n[MATLAB](https://github.com/MicroscPSF/MicroscPSF-Matlab), and\n[ImageJ/Java](https://github.com/MicroscPSF/MicroscPSF-ImageJ)\n\n## Install\n\n```sh\npip install psfmodels\n```\n\n### from source\n\n```sh\ngit clone https://github.com/tlambert03/PSFmodels.git\ncd PSFmodels\npip install -e \".[dev]\"  # will compile c code via pybind11\n```\n\n## Usage\n\nThere are two main functions in `psfmodels`: `vectorial_psf` and `scalar_psf`.\nAdditionally, each version has a helper function called `vectorial_psf_centered`\nand `scalar_psf_centered` respectively. The main difference is that the `_psf`\nfunctions accept a vector of Z positions `zv` (relative to coverslip) at which\nPSF is calculated. As such, the point source may or may not actually be in the\ncenter of the rendered volume. The `_psf_centered` variants, by contrast, do\n_not_ accecpt `zv`, but rather accept `nz` (the number of z planes) and `dz`\n(the z step size in microns), and always generates an output volume in which the\npoint source is positioned in the middle of the Z range, with planes equidistant\nfrom each other. All functions accept an argument `pz`, specifying the position\nof the point source relative to the coverslip. See additional keyword arguments\nbelow\n\n_Note, all output dimensions (`nx` and `nz`) should be odd._\n\n```python\nimport psfmodels as psfm\nimport matplotlib.pyplot as plt\nfrom matplotlib.colors import PowerNorm\n\n# generate centered psf with a point source at `pz` microns from coverslip\n# shape will be (127, 127, 127)\npsf = psfm.make_psf(127, 127, dxy=0.05, dz=0.05, pz=0)\nfig, (ax1, ax2) = plt.subplots(1, 2)\nax1.imshow(psf[nz//2], norm=PowerNorm(gamma=0.4))\nax2.imshow(psf[:, nx//2], norm=PowerNorm(gamma=0.4))\nplt.show()\n```\n\n![Image of PSF](fig.png)\n\n```python\n# instead of nz and dz, you can directly specify a vector of z positions\nimport numpy as np\n\n# generate 31 evenly spaced Z positions from -3 to 3 microns\npsf = psfm.make_psf(np.linspace(-3, 3, 31), nx=127)\npsf.shape  # (31, 127, 127)\n```\n\n**all** PSF functions accept the following parameters. Units should be provided\nin microns unless otherwise stated. Python API may change slightly in the\nfuture.  See function docstrings as well.\n\n```\nnx (int):       XY size of output PSF in pixels, must be odd.\ndxy (float):    pixel size in sample space (microns) [default: 0.05]\npz (float):     depth of point source relative to coverslip (in microns) [default: 0]\nti0 (float):    working distance of the objective (microns) [default: 150.0]\nni0 (float):    immersion medium refractive index, design value [default: 1.515]\nni (float):     immersion medium refractive index, experimental value [default: 1.515]\ntg0 (float):    coverslip thickness, design value (microns) [default: 170.0]\ntg (float):     coverslip thickness, experimental value (microns) [default: 170.0]\nng0 (float):    coverslip refractive index, design value [default: 1.515]\nng (float):     coverslip refractive index, experimental value [default: 1.515]\nns (float):     sample refractive index [default: 1.47]\nwvl (float):    emission wavelength (microns) [default: 0.6]\nNA (float):     numerical aperture [default: 1.4]\n```\n\n## Comparison with other models\n\nWhile these models are definitely slower than the one implemented in [Li et al\n(2017)](https://doi.org/10.1364/JOSAA.34.001029) and\n[MicroscPSF](https://github.com/MicroscPSF), there are some interesting\ndifferences between the scalar and vectorial approximations, particularly with\nhigher NA lenses, non-ideal sample refractive index, and increasing spherical\naberration with depth from the coverslip.\n\nFor an interactive comparison, see the [examples.ipynb](notebooks/examples.ipynb) Jupyter\nnotebook.\n\n## Lightsheet PSF utility function\n\nThe `psfmodels.tot_psf()` function provides a quick way to simulate the total\nsystem PSF (excitation x detection) as might be observed on a light sheet\nmicroscope (currently, only strictly orthogonal illumination and detection are\nsupported).  See the [lightsheet.ipynb](notebooks/lightsheet.ipynb) Jupyter notebook for\nexamples.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlambert03%2Fpsfmodels","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlambert03%2Fpsfmodels","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlambert03%2Fpsfmodels/lists"}