Metadata-Version: 2.4
Name: smappy-smlm
Version: 0.5.1
Summary: Single-molecule localization fitting pipeline (Python port of the SMAP fast-simple workflow)
Author-email: Jonas Ries <ries@embl.de>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/ries-lab/SMAPpy
Project-URL: Source, https://github.com/ries-lab/SMAPpy
Keywords: SMLM,super-resolution,localization microscopy,PALM,STORM
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11.2
Requires-Dist: tifffile>=2022.7.28
Requires-Dist: h5py>=3.10
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: PySide6-Essentials>=6.6.1
Requires-Dist: pyqtgraph>=0.13.3
Requires-Dist: matplotlib>=3.7.3
Requires-Dist: ziamath>=0.13
Requires-Dist: imageio-ffmpeg>=0.4
Provides-Extra: image
Requires-Dist: pillow>=10.0; extra == "image"
Provides-Extra: movie
Provides-Extra: drift
Requires-Dist: matplotlib>=3.7.3; extra == "drift"
Provides-Extra: cuda
Requires-Dist: numba>=0.59; extra == "cuda"
Provides-Extra: gui
Provides-Extra: gpu
Requires-Dist: wgpu>=0.19; extra == "gpu"
Provides-Extra: tutorial
Requires-Dist: playwright>=1.40; extra == "tutorial"
Requires-Dist: piper-tts>=1.2; extra == "tutorial"
Provides-Extra: clusters
Requires-Dist: hdbscan>=0.8.44; extra == "clusters"
Provides-Extra: uipsf
Requires-Dist: torch>=2.4; extra == "uipsf"
Provides-Extra: test
Requires-Dist: pytest>=8.4; extra == "test"
Requires-Dist: pytest-timeout>=2.1; extra == "test"
Requires-Dist: pytest-xdist>=3.2; extra == "test"
Dynamic: license-file

# SMAPpy

SMAPpy is software for single-molecule localization microscopy (SMLM) in
Python. It takes raw camera frames to localizations and super-resolution
images, with a graphical interface, command-line tools and a Python API. It is
a Python port of [SMAP](https://github.com/jries/SMAP).

## Install

    pip install smappy-smlm

The GUI is included. Binary wheels are available for Python 3.12-3.14 on macOS,
Linux and Windows, so nothing needs to be compiled. The package is called
`smappy-smlm` on PyPI; in Python you `import smappy`.

**I need more help.** Never used a terminal or `pip`?
[Installing SMAPpy, step by step](docs/install-step-by-step.md) walks through
it on a Mac or Windows computer, from opening the terminal to starting the GUI,
and says what to ask an AI assistant that can do it for you.

With [uv](https://docs.astral.sh/uv/) you can install the GUI as a standalone
tool, or run it without installing:

    uv tool install smappy-smlm
    uvx --from smappy-smlm smappy-gui

To install from a checkout, which builds the C++ extensions (pip 21.3 or newer):

    git clone https://github.com/ries-lab/SMAPpy.git
    cd SMAPpy
    python -m venv .venv
    .venv/bin/python -m pip install -e .

## Update

Close SMAPpy first: on Windows, pip cannot replace the program files of a
running SMAPpy. Then, in the same environment you installed it into:

    pip install --upgrade smappy-smlm

`pip show smappy-smlm` tells you which version you have; the newest is on
[PyPI](https://pypi.org/project/smappy-smlm/). If you installed it with uv,
run `uv tool upgrade smappy-smlm` instead. In a checkout, run `git pull`, then
`.venv/bin/python -m pip install -e .` again, which rebuilds the C++
extensions.

SMAPpy itself looks for a newer version once a day when it starts and, if
there is one, says so at the bottom right of the control window. *Help → Check
for updates...* asks at any time. Its *Update and restart* closes SMAPpy,
installs the new version with pip (or uv) and starts SMAPpy again; *Copy
command* gives the command for your installation instead, and a checkout is
always updated by hand. The daily check is turned off in the *General* tab of
*Preferences...*.

## Start

    smappy-gui

or, to open a localization file directly:

    smappy-gui FILE.hdf5

Files can also be dropped onto either window: a localization file opens as
with *File → Open*; a short TIFF (50 frames or fewer) or a PNG is added as an
image layer, as with *File → Open image*; and a longer stack (TIFF, an NDTiff
folder, `*.sim.yaml`) becomes the *file* of the fitter on the Localize tab,
ready to fit.

From a checkout, activate the venv first or run `.venv/bin/smappy-gui`.

## Tutorials and documentation

**Tutorials.** [ries-lab.github.io/SMAPpy](https://ries-lab.github.io/SMAPpy/)
has short guided tours on simulated data you can follow along with. Start with
[SMAPpy in three minutes](https://ries-lab.github.io/SMAPpy/quickstart/).

**Help pages.** Every plugin and the main parts of the GUI have a help page.
It explains the theoretical background and every control. Open it with the
**?** in a plugin's or a Render-tab section's title bar, with F1 in any panel or
window, or from *Help → Plugin documentation*. The same pages are online at
[ries-lab.github.io/SMAPpy/help](https://ries-lab.github.io/SMAPpy/help/), and
`python -m smappy.docs -o DIR` writes them as a static website.

**Your own analysis.** When no plugin measures what you need, make one:
describe it to an AI assistant started in your plugin folder (*Plugins → Show
my plugin folder*), or start from the example with *Plugins → New plugin...*.
A file saved there appears under *Plugins → User*. The help page
[Your own plugins](https://ries-lab.github.io/SMAPpy/help/panels-your-own-plugins.html)
explains how.

**For developers.** [GUI.md](GUI.md) describes the architecture.
[docs/](docs/) holds design notes on the plugin system and individual
algorithms. [NOTES.md](NOTES.md) records design decisions and measurements.

## License

SMAPpy is released under the BSD 3-Clause license; see [LICENSE](LICENSE) and
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
