PySMLFM 1.0.0

Description:

PySMLFM 1.0.0

Single Molecule Light Field Microscopy Reconstruction (PySMLFM)








A Python solution inspired by MATLAB scripts in
hexSMLFM project.

This 3D reconstruction code accompanies the preprint titled
"High-density volumetric super-resolution microscopy".
In brief, 2D localisation data (x,y) captured using a (square or hexagonal)
fourier light field microscope are turned into 3D localisations (x,y,z).
It does this by first assigning (x,y) to (x,y,u,v) space and using microscope
parameters to calculate z position via parallax. For more information, see:
R. R. Sims, et al. Optica, 2020, 7, 1065.

Getting Started
Although this project is pure Python, one of its optional features talks to
ImageJ/Fiji via PyImageJ
wrapper and uses PeakFit from GDSC SMLM2
plugin. That basically defines main requirements as well as restrictions for
this project.
If you don't plan to use PeakFit directly from this project, feel free to
configure your Python environment in a way you are used to. You can still
follow the instruction below, just skip installation of PyImageJ and OpenJDK.
Following instructions assume you don't have Python installed yet and focuses to
Windows platform only.
Initial Setup
Initial setup follows PyImageJ instructions.
PyImageJ should be installed using Conda +
Mamba.
You can also pip install pyimagej, but will then need to install
OpenJDK and
Maven manually.


Install Miniforge3
to get whole Python environment. When asked how to install, select Just me,
because All users option would only complicate system-wide installation.
If you really need to share the installation with other users, select
location everybody can access and manually copy there also a Start menu
shortcut to Miniforge prompt created by installer for you only.


Run Miniforge Prompt from Start menu. It opens in your home folder by default
(e.g. C:\Users\Me).


Create new isolated virtual environment for this project (with name MyEnv)
to not clutter dependencies with your existing or new projects:
(base) C:\Users\Me> mamba create -n MyEnv -c conda-forge python=3.8 pyimagej openjdk=8

This command will install PyImageJ with OpenJDK 8 in new virt. env. using
Python 3.8 (the minimal Python version required).
If you don't want PyImageJ, remove last two package names from the command
to get clean environment.
Adjust Python version if needed.

Note:
If you have an AMD processor and experience low performance compared to
similar Intel CPU, installing an alternative BLAS library could help.
For example, to initialize new environment with BLIS library run:
(base) C:\Users\Me> mamba create -n MyEnv -c conda-forge python=3.8 pyimagej openjdk=8 blas=*=blis




Whenever you want to use MyEnv environment, activate it first:
(base) C:\Users\Me> mamba activate MyEnv



Ensure conda-forge is the first update channel:
(MyEnv) C:\Users\Me> conda config --add channels conda-forge
(MyEnv) C:\Users\Me> conda config --set channel_priority strict



Download Fiji from official source,
unpack it, run ImageJ-win64.exe and install 'GDSC SMLM2' plugin via
Help‑>Update... menu.


Install PySMLFM
Install either stable release or development version as shown below.
Latest Stable Release

Install the package from Python Package Index (PyPI):
(MyEnv) C:\Users\Me> pip install PySMLFM



Latest Development Version

Get the ZIP archive with sources from GitHub (PySMLFM-main.zip).
Install the package from source archive extracted e.g. in your home folder
(C:\Users\Me\PySMLFM-main):
(MyEnv) C:\Users\Me> cd PySMLFM-main
(MyEnv) C:\Users\Me\PySMLFM-main> pip install .



Execution
There are two ways how to run an application installed by this project -
by running a Python command from Miniforge Prompt or via installed .exe
helper script.
Via Python Command
Run the command line application:
(MyEnv) C:\Users\Me> python -m smlfm_cli

or the GUI application:
(MyEnv) C:\Users\Me> python -m smlfm_gui

Via Helper Script
During the installation is created a helper script that simplifies the execution
of the application. It is a self-extracting ZIP file that executes similar
command as above but uses for it the python.exe from the virt. env. where it
was created from. Because of that, the EXE helper works only on the that
computer and cannot be shared with anyone else, but it can be copied anywhere on
your computer.
Simply run it with:
(MyEnv) C:\Users\Me> smlfm-cli

or:
(MyEnv) C:\Users\Me> smlfm-gui

Notice the dash in the command name, it is not an underscore.
Usage
If you already tried running the CLI application, you saw an error message.
It is because the CLI application requires one or two options as input.
Configuration
The type of the input option is detected automatically from given file extension:

A configuration with .json file extension.
It contains all possible parameters for the localisation process, output
location, graphs to show, etc. If not specified, a default configuration file
is used. As a starting point, make your own copy and modify the parameters
accordingly. See
C:\Users\Me\miniforge\envs\MyEnv\Lib\site-packages\smlfm\data\default-config.json.
A 2D localisations with .csv or .xls file extension.
If not specified on command line, the path to the file must be set in the
configuration file under csv_file key.
By default the CSV is expected in the format generated by PeakFit plugin
in ImageJ/Fiji. A few other formats are supported, namely Thunderstorm and
Picasso. Adjust the configuration file key csv_format where the value is
all in upper-case.

For example, run the application with customized configuration and data, all
stored C:\MyExperiment folder:
(MyEnv) C:\MyExperiment> python -m smlfm_cli my-config.json my-localisations.csv

For quick access to the EXE helper script without opening command prompt you can
create a shortcut on the desktop or in your experiment folder.
Open the path with smlfm-cli.exe in File Explorer (by default it is in
C:\Users\Me\miniforge\envs\MyEnv\Scripts\ ), drag the EXE file with
mouse and drop it on the desktop or target folder while holding the Alt key.
The shortcut has working directory set by default to the folder with the EXE file.
It is recommended changing it to a location where you want the results to be
stored. Right-click on the shortcut, select Properties and modify 'Start in:'
box accordingly. Also don't forget to add the input options at the end of the
command in the 'Target:' box. Now you can double-click the shortcut anytime
you want to re-run the 3D localisation.
Processing
With valid configuration the 2D localisation data is loaded from CSV file and
every localisation point is assigned to the nearest lens from micro-lens array.
With default configuration the localisations and lens centres are shown in form
of 2D graph. The user can visually check the alignment. To continue, the graph
window must be closed and then the user must either confirm the alignment or
abort the process to adjust the configuration to fix the alignment. Simply
follow the instructions in the command prompt window.
Based on the amount of input localisations and computer performance, the
processing can take from a few seconds to minutes or even hours. The command
prompt window prints a message about the progress every 1000 frames processed.
Results
If everything completed successfully, three graphs with results are shown and
the results are stored in the disk. In the current working directory
(e.g. C:\MyExperiment) is created a subdirectory for every execution.
The subdirectory name starts with 3D Fitting prefix followed by a timestamp
and a CSV filename used.
Each folder contains JSON configuration file used (config.json), calculated
3D localisations (locs3D.csv), an output for
ViSP viewer (ViSP.3d) and
a Python script (figures.pyw) that reconstructs exactly the results graphs at
any time later without a need to start the processing from beginning.
To open the saved figures run a command that takes relative path to it like this
(quote the path with spaces):
(MyEnv) C:\MyExperiment> python "3D Fitting - 20240213-203318 - my-localisations.csv/figures.pyw"

When you use python command like above, the prompt will be blocked until all
graphs are closed. To open the figures without blocking the prompt use pythonw
instead.
Screenshots
Main Window

Optics Settings Dialog

Micro Lens Array Layout

Filtered Localisations

3D Reconstruction