📽️ playNano

AFM Video Reader for .h5-jpk files and other high-speed AFM video formats

PyPI - Python Version

</div>

playNano is a Python tool for loading, filtering, visualising, and exporting time-series AFM data, such as high-speed AFM (HS-AFM) videos. It supports interactive playback, flexible processing pipelines, and provenance-aware analysis tracking, and export in multiple formats, including OME-TIFF, NPZ (NumPy zipped archive), HDF5 bundles, and animated GIFs.

playNano handles complete time-series datasets—such as high-speed AFM videos—as unified, time-aware stacks rather than separate frames. Every step in a processing or analysis pipeline is recorded for full reproducibility and provenance tracking.

Learn more about the motivation, design, and structure of playNano in the Introduction.

Files read:

.h5-jpk, .jpk, .asd, .spm

</div>

This project requires Python 3.10 - 3.12 and is in development. If you find any issues, please open an issue at: https://github.com/derollins/playNano/issues

Questions? Email: d.e.rollins@leeds.ac.uk

📘 Documentation

Full documentation: https://derollins.github.io/playNano/

📜 Changelog

✨ Features

📂 AFM time-series extraction — reads .h5-jpk, .asd, and folders of .jpk or .spm frames.
▶️ Interactive video viewer — PySide6-based GUI with playback, z-scale control, and export tools.
🪟 Processing pipeline — applies filters and masks with full provenance tracking.
📏 Analysis pipeline — runs detection, clustering, and tracking with reproducible outputs.
📩 Flexible exports — save to OME-TIFF, NPZ, HDF5, and annotated GIFs.
🔌 Extensible design — add your own filters or analysis modules as plugins.

📦 Installation and Dependencies

Python compatibility: 3.10 – 3.12

It is recommended to use a virtual environment such as conda to isolate the installation. There are instructions on how to do this in the docs: Installation

If you have Anaconda or miniconda installed, open the terminal (or Anaconda PowerShell Prompt on Windows) and create and activate a new virtual environment.

conda create -n playnano_env python=3.11 # Create a new virtual environment with Python 3.11
conda activate playnano_env  # Activate the virtual environment

The simplest way to install playNano is through PyPi using the command:

pip install playnano

More information on installation is available in the documentation: https://derollins.github.io/playNano/main/installation.html

For development setup see CONTRIBUTING.md.

🚀 Quickstart

Play a file (GUI):

playnano play ./tests/resources/sample_0.h5-jpk # This command opens example data if run in the project root

Replace the path with the location of your data (file for asd/h5-jpk or folder for spm/jpk) This opens an interactive window that can be used to view the videos and configure formatting for the display and GIF exports. Press the f key to flatten with default steps.

Batch process + make GIF:

playnano process ./tests/resources/sample_0.h5-jpk \
  --processing "remove_plane;gaussian_filter:sigma=1.0" \
  --export tif,npz --make-gif --output-folder ./results

See the full docs for the complete CLI reference, GUI guide, filters, YAML schemas, and examples.

📒 Notebooks

To access and use the Notebooks you need to clone the repository and install the required dependencies pip install -e .[notebooks] see the docs page for more details and full instructions: https://derollins.github.io/playNano/main/notebooks.html

Once installed use jupyter notebook to open jupyter notebook and navigate to the notebooks\ folder. These notebooks allow the user to experiment with using playNano programmatically and allows the user to test pipelines interactively and with rapid feedback on the parameters that may need adjusting in order to process a high-speed dataset.

🤝 Contributing

Contributions are welcome — bug reports, new features, processing plugins, and analysis modules. See CONTRIBUTING.md for development setup, code style requirements, and guidance on how to contribute analysis modules and processing plugins either directly or via the playNano-plugins repository.

🧩 Dependencies

This project requires the following Python packages:

numpy
pandas
h5py
Pillow
matplotlib
scipy
scikit-learn
scikit-image
python-dateutil
tifffile
pyyaml
PySide6 — for the GUI
AFMReader — for reading .jpk, .spm and .asd files

🔗 Related Software

These are some software packages that have helped and inspired this project:

Topostats

A general AFM image processing programme written in Python that batch processes AFM images. Topostats is able to flatten raw AFM images, mask objects and provides advanced analysis tools including U-net based masking.

AFMReader

Spun out of Topostats, AFMReader is Python library for loading a variety of AFM file formats. It opens each as a tuple containing a NumPy array and a float referring to the planar pixel to nanometer conversion factor. Within playNano this library is used to open the folder-based AFM video formats.

NanoLocz

A free MATLAB app with an interactive GUI that is able to load, process and analyse AFM images and high-speed AFM videos. Featuring mask analysis, particle detection and tracking, it also integrates Localization AFM (L-AFM).

NOW AVAILABLE: The masking, levelling and auto levelling routines rewritten in Python can be found here: Python-NanoLocz-Library. This project also contains playNano entry points so can be used directly when installed in the same environment as playNano.

📜 License

This project is licensed under the GNU General Public License v3.0 (GPLv3)

📖 Citing playNano

If you use playNano in academic work, please cite it as:

Rollins, D. (2025). playNano: AFM Video Reader and Analysis Toolkit. GitHub repository: https://github.com/derollins/playNano

<details> <summary>Show BibTeX</summary>

@misc{rollins2025playnano,
  author = {Rollins, D.},
  title  = {playNano: AFM Video Reader and Analysis Toolkit},
  year   = {2025},
  url    = {https://github.com/derollins/playNano}
}

</details>

AI Transparency Note

AI-based tools were used for limited typing/formatting assistance and for debugging, refactoring, and documentation suggestions. All code paths, algorithms, and final behaviour were reviewed and validated by the author.

Included Fonts

This project bundles the following fonts:

Steps Mono by Velvetyne Type Foundry, licensed under the SIL Open Font License 1.1.
Basic by Eben Sorkin, licensed under the SIL Open Font License 1.1.

Full license texts and attribution are provided in:

src/playnano/fonts/Steps-Mono/LICENCE.txt
src/playnano/fonts/Basic/LICENCE.txt

PlayNano

Install / Use

README