<!-- markdownlint-disable MD033 -->
# 📽️ playNano
**AFM Video Reader for `.h5-jpk` files and other high-speed AFM video formats**
<div align="center">
[](https://github.com/derollins/playNano/releases)
[](https://github.com/derollins/playNano/releases)
[](https://pypi.org/project/playNano/)
[](https://pypi.org/project/playNano/)
[](https://derollins.github.io/playNano/)
[](LICENSE)
[](https://github.com/derollins/playNano/actions/workflows/test.yaml)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](https://github.com/psf/flake8)
[](https://codecov.io/github/derollins/playNano)
</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](https://derollins.github.io/playNano/main/introduction.html).
**Files read:**
<div align="center">
**`.h5-jpk`, `.jpk`, `.asd`, `.spm`**
</div>
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>
## 📘 Documentation
Full documentation: <https://derollins.github.io/playNano/>
📜 [Changelog](https://derollins.github.io/playNano/main/changelog.html)
---
## ✨ 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](https://derollins.github.io/playNano/main/installation.html)
If you have [Anaconda](https://anaconda.org/) or [miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install)
installed, open the terminal (or Anaconda PowerShell Prompt on Windows) and create and activate
a new virtual environment.
```bash
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 simpliest way to install **playNano** is through PyPi using the command:
```bash
pip install playnano
```
Alternatively clone the repository from GitHub into a new folder:
```bash
git clone https://github.com/derollins/playNano.git
cd playNano
```
Then install in editable mode:
```bash
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>
## 🚀 Quickstart
**Play a file (GUI):**
<p align="center">
<img src="docs/images/GUI_window.png" alt="playNano GUI main window" width="400" />
</p>
```bash
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:**
```bash
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](https://derollins.github.io/playNano/main/cli.html),
[GUI guide](https://derollins.github.io/playNano/main/gui.html), filters, YAML schemas, and examples.
## Notebooks
<p align="center">
<img src="docs/images/notebook_capture.png" alt="playNano demonstration notebook" width="400" />
</p>
To access and use the [Notebooks](https://derollins.github.io/playNano/main/notebooks.html) 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.
## ⚠️ Notes
- 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.
## 🧩 Dependencies
This project requires the following Python packages:
- `numpy`
- `h5py`
- `Pillow`
- `matplotlib`
- `opencv-python`
- `scipy`
- `scikit-learn`
- `python-dateutil`
- `tifffile`
- [`AFMReader`](https://github.com/AFM-SPM/AFMReader) — for reading `.jpk`, `.spm` and `.asd` files
## 🤝 Related Software
These are some software packages that have helped and inspired this project:
### [Topostats](https://github.com/AFM-SPM/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](https://github.com/AFM-SPM/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](https://github.com/George-R-Heath/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)](https://www.nature.com/articles/s41586-021-03551-x).
## 📜 License
This project is licensed under the [GNU General Public License v3.0 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.html)
## 📖 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>
```bibtex
@misc{rollins2025playnano,
author = {Rollins, D.},
title = {playNano: AFM Video Reader and Analysis Toolkit},
year = {2025},
url = {https://github.com/derollins/playNano}
}
```
</details>
## Included Fonts
This project bundles the following fonts:
- **Steps Mono** by [Velvetyne Type Foundry](https://velvetyne.fr/fonts/steps-mono/),
licensed under the SIL Open Font License 1.1.
- **Basic** by [Eben Sorkin](https://github.com/EbenSorkin),
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`
Raw data
{
"_id": null,
"home_page": null,
"name": "playnano",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "AFM, FAIR data, HS-AFM, SPM, atomic force microscopy, biomolecular imaging, biophysics, clustering, data analysis, feature detection, flattening filters, high-speed AFM, image processing, image segmentation, materials science, microscopy data, nanometrology, nanoscopy, nanotechnology, open science, particle tracking, reproducible research, scanning probe microscopy, scientific computing, scientific visualization, surface analysis, time-series analysis, video analysis, video processing",
"author": null,
"author_email": "\"D. E. Rollins\" <d.e.rollins@leeds.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/70/dc/913cadae2036912f34f5b5cc264b3d0a37b9ee947cc86b21d5b71a4113a4/playnano-0.2.1.tar.gz",
"platform": null,
"description": "<!-- markdownlint-disable MD033 -->\n# \ud83d\udcfd\ufe0f playNano\n\n**AFM Video Reader for `.h5-jpk` files and other high-speed AFM video formats**\n\n<div align=\"center\">\n\n[](https://github.com/derollins/playNano/releases)\n[](https://github.com/derollins/playNano/releases)\n[](https://pypi.org/project/playNano/)\n[](https://pypi.org/project/playNano/)\n[](https://derollins.github.io/playNano/)\n\n[](LICENSE)\n\n[](https://github.com/derollins/playNano/actions/workflows/test.yaml)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n[](https://github.com/psf/flake8)\n[](https://codecov.io/github/derollins/playNano)\n\n</div>\n\n**playNano** is a Python tool for loading, filtering, visualising, and exporting time-series AFM data,\nsuch as high-speed AFM (HS-AFM) videos. It supports interactive playback, flexible processing pipelines,\nand provenance-aware analysis tracking, and export in multiple formats, including OME-TIFF, NPZ (NumPy zipped archive),\nHDF5 bundles, and animated GIFs.\n\n**playNano** handles complete time-series datasets\u2014such as high-speed AFM videos\u2014as unified, time-aware stacks rather\nthan separate frames. Every step in a processing or analysis pipeline is recorded for full reproducibility and\nprovenance tracking.\n\nLearn more about the motivation, design, and structure of playNano in the [Introduction](https://derollins.github.io/playNano/main/introduction.html).\n\n**Files read:**\n<div align=\"center\">\n\n**`.h5-jpk`, `.jpk`, `.asd`, `.spm`**\n\n</div>\n\nThis project requires Python 3.10 or newer and is in development. If you find any issues, please open an issue at:\n<https://github.com/derollins/playNano/issues>\n\nQuestions? Email: <d.e.rollins@leeds.ac.uk>\n\n## \ud83d\udcd8 Documentation\n\nFull documentation: <https://derollins.github.io/playNano/>\n\n\ud83d\udcdc [Changelog](https://derollins.github.io/playNano/main/changelog.html)\n\n---\n\n## \u2728 Features\n\n- \ud83d\udcc2 **AFM time-series extraction** \u2014 reads `.h5-jpk`, `.asd`, and folders of `.jpk` or `.spm` frames.\n- \u25b6\ufe0f **Interactive video viewer** \u2014 PySide6-based GUI with playback, z-scale control, and export tools.\n- \ud83e\ude9f **Processing pipeline** \u2014 applies filters and masks with full provenance tracking.\n- \ud83d\udccf **Analysis pipeline** \u2014 runs detection, clustering, and tracking with reproducible outputs.\n- \ud83d\udce9 **Flexible exports** \u2014 save to OME-TIFF, NPZ, HDF5, and annotated GIFs.\n- \ud83d\udd0c **Extensible design** \u2014 add your own filters or analysis modules as plugins.\n\n---\n\n## \ud83d\udce6 Installation and Dependencies\n\n**Python compatibility:** 3.10 \u2013 3.12\n\nIt is recommended to use a virtual environment such as conda to isolate the installation. There\nare instructions on how to do this in the docs: [Installation](https://derollins.github.io/playNano/main/installation.html)\n\nIf you have [Anaconda](https://anaconda.org/) or [miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install)\ninstalled, open the terminal (or Anaconda PowerShell Prompt on Windows) and create and activate\na new virtual environment.\n\n ```bash\n conda create -n playnano_env python=3.11 # Create a new virtual environment with Python 3.11\n conda activate playnano_env # Activate the virtual environment\n ```\n\nThe simpliest way to install **playNano** is through PyPi using the command:\n\n```bash\npip install playnano\n```\n\nAlternatively clone the repository from GitHub into a new folder:\n\n```bash\ngit clone https://github.com/derollins/playNano.git\ncd playNano\n```\n\nThen install in editable mode:\n\n```bash\npip install -e .\n```\n\nKey dependencies (install via pip install -e .): numpy, h5py, Pillow, matplotlib,\nscipy, scikit-learn, python-dateutil, tifffile, AFMReader.\n\nMore information on installation is available in the documentation: <https://derollins.github.io/playNano/main/installation.html>\n\n## \ud83d\ude80 Quickstart\n\n**Play a file (GUI):**\n\n<p align=\"center\">\n <img src=\"docs/images/GUI_window.png\" alt=\"playNano GUI main window\" width=\"400\" />\n</p>\n\n```bash\nplaynano play ./tests/resources/sample_0.h5-jpk # This command opens example data if run in the project root\n```\n\nReplace the path with the location of your data (file for asd/h5-jpk or folder for spm/jpk)\nThis opens an interactive window that can be used to view the videos and configure\nformatting for the display and GIF exports.\nPress the **f** key to flatten with default steps.\n\n**Batch process + make GIF:**\n\n```bash\nplaynano process ./tests/resources/sample_0.h5-jpk \\\n --processing \"remove_plane;gaussian_filter:sigma=1.0\" \\\n --export tif,npz --make-gif --output-folder ./results\n```\n\nSee the full docs for the complete [CLI reference](https://derollins.github.io/playNano/main/cli.html),\n[GUI guide](https://derollins.github.io/playNano/main/gui.html), filters, YAML schemas, and examples.\n\n## Notebooks\n\n<p align=\"center\">\n <img src=\"docs/images/notebook_capture.png\" alt=\"playNano demonstration notebook\" width=\"400\" />\n</p>\n\nTo access and use the [Notebooks](https://derollins.github.io/playNano/main/notebooks.html) you need to clone the\nrepository and install the required dependencies `pip install -e .[notebooks]' see the docs page for more\ndetails and full instructions: <https://derollins.github.io/playNano/main/notebooks.html>\n\nOnce installed use `jupyter notebook` to open jupyter notebook and navigate to the notebooks\\ folder. These\nnotebooks allow the user to experiment with using **playNano** programmatically and allows the user to test\npipelines interactively and with rapid feedback on the parameters that may need adjusting in order to process\na high-speed dataset.\n\n## \u26a0\ufe0f Notes\n\n- Make sure the input file includes valid metadata like line_rate, or GIF generation may fail.\n\n- If --channel is incorrect or missing from the file, you\u2019ll receive an error.\n\n- For .h5-jpk, .asd and other multi-frame formats, a single file is loaded. For formats like .jpk or .spm, provide a\n folder containing the frame files.\n\n## \ud83e\udde9 Dependencies\n\nThis project requires the following Python packages:\n\n- `numpy`\n- `h5py`\n- `Pillow`\n- `matplotlib`\n- `opencv-python`\n- `scipy`\n- `scikit-learn`\n- `python-dateutil`\n- `tifffile`\n- [`AFMReader`](https://github.com/AFM-SPM/AFMReader) \u2014 for reading `.jpk`, `.spm` and `.asd` files\n\n## \ud83e\udd1d Related Software\n\nThese are some software packages that have helped and inspired this project:\n\n### [Topostats](https://github.com/AFM-SPM/TopoStats)\n\nA general AFM image processing programme written in Python that batch processes AFM images.\nTopostats is able to flatten raw AFM images, mask objects and provides advanced analysis tools\nincluding U-net based masking.\n\n### [AFMReader](https://github.com/AFM-SPM/AFMReader)\n\nSpun out of Topostats, AFMReader is Python library for loading a variety of AFM file formats. It opens\neach as a tuple containing a NumPy array and a float referring to the planar pixel to nanometer conversion\nfactor. Within playNano this library is used to open the folder-based AFM video formats.\n\n### [NanoLocz](https://github.com/George-R-Heath/NanoLocz)\n\nA free MATLAB app with an interactive GUI that is able to load, process and analyse AFM images and\nhigh-speed AFM videos. Featuring mask analysis, particle detection and tracking, it also\nintegrates Localization AFM [(L-AFM)](https://www.nature.com/articles/s41586-021-03551-x).\n\n## \ud83d\udcdc License\n\nThis project is licensed under the [GNU General Public License v3.0 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.html)\n\n## \ud83d\udcd6 Citing playNano\n\nIf you use **playNano** in academic work, please cite it as:\n\n> Rollins, D. (2025). *playNano: AFM Video Reader and Analysis Toolkit.*\n> GitHub repository: <https://github.com/derollins/playNano>\n\n<details>\n<summary>Show BibTeX</summary>\n\n```bibtex\n@misc{rollins2025playnano,\n author = {Rollins, D.},\n title = {playNano: AFM Video Reader and Analysis Toolkit},\n year = {2025},\n url = {https://github.com/derollins/playNano}\n}\n```\n\n</details>\n\n## Included Fonts\n\nThis project bundles the following fonts:\n\n- **Steps Mono** by [Velvetyne Type Foundry](https://velvetyne.fr/fonts/steps-mono/),\n licensed under the SIL Open Font License 1.1.\n\n- **Basic** by [Eben Sorkin](https://github.com/EbenSorkin),\n licensed under the SIL Open Font License 1.1.\n\nFull license texts and attribution are provided in:\n\n- `src/playnano/fonts/Steps-Mono/LICENCE.txt`\n- `src/playnano/fonts/Basic/LICENCE.txt`\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Python toolkit for processing and visualising high-speed AFM (Atomic Force Microscopy) video data.",
"version": "0.2.1",
"project_urls": {
"Changelog": "https://github.com/derollins/playNano/blob/main/CHANGELOG.md",
"Documentation": "https://derollins.github.io/playNano",
"Homepage": "https://github.com/derollins/playNano",
"Issues": "https://github.com/derollins/playNano/issues"
},
"split_keywords": [
"afm",
" fair data",
" hs-afm",
" spm",
" atomic force microscopy",
" biomolecular imaging",
" biophysics",
" clustering",
" data analysis",
" feature detection",
" flattening filters",
" high-speed afm",
" image processing",
" image segmentation",
" materials science",
" microscopy data",
" nanometrology",
" nanoscopy",
" nanotechnology",
" open science",
" particle tracking",
" reproducible research",
" scanning probe microscopy",
" scientific computing",
" scientific visualization",
" surface analysis",
" time-series analysis",
" video analysis",
" video processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c05cd017548c8f42b74766c00297cec7b331d62eebad3e38cc14a52dfe6667de",
"md5": "e9c44de1577197e31b7f1db364db10ad",
"sha256": "410ed1b2d322579a1882bf5755cad6badb699f535f6e70b317ce947f95cda47e"
},
"downloads": -1,
"filename": "playnano-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9c44de1577197e31b7f1db364db10ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 215821,
"upload_time": "2025-10-30T00:10:21",
"upload_time_iso_8601": "2025-10-30T00:10:21.846068Z",
"url": "https://files.pythonhosted.org/packages/c0/5c/d017548c8f42b74766c00297cec7b331d62eebad3e38cc14a52dfe6667de/playnano-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70dc913cadae2036912f34f5b5cc264b3d0a37b9ee947cc86b21d5b71a4113a4",
"md5": "7396e1a52a76cf10f9055af743a75981",
"sha256": "55f7105b3b419447b665222c4ed9fc669800ac31df5cb13cc9094a61d7e5ff1e"
},
"downloads": -1,
"filename": "playnano-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "7396e1a52a76cf10f9055af743a75981",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 179378,
"upload_time": "2025-10-30T00:10:23",
"upload_time_iso_8601": "2025-10-30T00:10:23.508980Z",
"url": "https://files.pythonhosted.org/packages/70/dc/913cadae2036912f34f5b5cc264b3d0a37b9ee947cc86b21d5b71a4113a4/playnano-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 00:10:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "derollins",
"github_project": "playNano",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "playnano"
}
JSON
