AFM Video Reader for .h5-jpk files and other high-speed AFM video formats
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
This project requires Python 3.10 or newer 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
Full documentation: https://derollins.github.io/playNano/
- 📂 AFM time-series extraction — reads
.h5-jpk,.asd, and folders of.jpkor.spmframes. ▶️ 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.
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 environmentThe simpliest way to install playNano is through PyPi using the command:
pip install playnanoAlternatively clone the repository from GitHub into a new folder:
git clone https://github.com/derollins/playNano.git
cd playNanoThen install in editable mode:
pip install -e .Key dependencies (install via pip install -e .): numpy, h5py, Pillow, matplotlib, scipy, scikit-learn, python-dateutil, tifffile, AFMReader.
More information on installation is available in the documentation: https://derollins.github.io/playNano/main/installation.html
Play a file (GUI):
playnano play ./tests/resources/sample_0.h5-jpk # This command opens example data if run in the project rootReplace 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 ./resultsSee the full docs for the complete CLI reference, GUI guide, filters, YAML schemas, and examples.
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.
-
Make sure the input file includes valid metadata like line_rate, or GIF generation may fail.
-
If --channel is incorrect or missing from the file, you’ll receive an error.
-
For .h5-jpk, .asd and other multi-frame formats, a single file is loaded. For formats like .jpk or .spm, provide a folder containing the frame files.
This project requires the following Python packages:
numpyh5pyPillowmatplotlibopencv-pythonscipyscikit-learnpython-dateutiltifffileAFMReader— for reading.jpk,.spmand.asdfiles
These are some software packages that have helped and inspired this project:
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.
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.
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).
This project is licensed under the GNU General Public License v3.0 (GPLv3)
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
Show BibTeX
@misc{rollins2025playnano,
author = {Rollins, D.},
title = {playNano: AFM Video Reader and Analysis Toolkit},
year = {2025},
url = {https://github.com/derollins/playNano}
}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.txtsrc/playnano/fonts/Basic/LICENCE.txt