Metadata-Version: 2.4
Name: playnano
Version: 0.4.0.post1
Summary: Python toolkit for processing, analysing and visualising high-speed AFM (Atomic Force Microscopy) video data.
Project-URL: Homepage, https://github.com/derollins/playNano
Project-URL: Documentation, https://derollins.github.io/playNano
Project-URL: Issues, https://github.com/derollins/playNano/issues
Project-URL: Changelog, https://github.com/derollins/playNano/blob/main/CHANGELOG.md
Author-email: "Daniel E. Rollins" <d.e.rollins@leeds.ac.uk>
License: GPL-3.0-or-later
License-File: COPYING
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,visualization
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.10
Requires-Dist: afmreader
Requires-Dist: h5py
Requires-Dist: matplotlib
Requires-Dist: numpy>=1.23
Requires-Dist: opencv-python-headless
Requires-Dist: pandas
Requires-Dist: pillow
Requires-Dist: pyside6>=6.5
Requires-Dist: python-dateutil>=2.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: tifffile
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: jsonschema; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-qt; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: sphinx-autoapi; extra == 'docs'
Requires-Dist: sphinx-multiversion; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Requires-Dist: sphinx<9; extra == 'docs'
Requires-Dist: sphinxcontrib-programoutput; extra == 'docs'
Provides-Extra: notebooks
Requires-Dist: jupyter; extra == 'notebooks'
Description-Content-Type: text/markdown

<!-- markdownlint-disable MD033 -->
# 📽️ playNano

## AFM processing and analysis platform for high-speed AFM videos and time-series

<div align="center">

[![GitHub release](https://img.shields.io/github/v/release/derollins/playNano?color=green)](https://github.com/derollins/playNano/releases)
[![PyPI version](https://img.shields.io/pypi/v/playNano?color=blue)](https://pypi.org/project/playNano/)
[![PyPI downloads](https://img.shields.io/pypi/dm/playNano?color=blue)](https://pypi.org/project/playNano/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue?logo=github)](https://derollins.github.io/playNano/)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/playNano)
[![License](https://img.shields.io/badge/license-GPLv3-blue)](LICENSE)
![CI](https://github.com/derollins/playNano/actions/workflows/pre-commit.yaml/badge.svg)
[![Tests](https://github.com/derollins/playNano/actions/workflows/test.yaml/badge.svg)](https://github.com/derollins/playNano/actions/workflows/test.yaml)
[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Code style: flake8](https://img.shields.io/badge/code%20style-flake8-456789.svg)](https://github.com/psf/flake8)
[![codecov](https://codecov.io/github/derollins/playNano/graph/badge.svg?token=NEV1OC12AV)](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 videos and GIFs.

The **playNano** package 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`, `.aris`**

</div>

This project requires Python 3.10 - 3.13 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 `.aris` files, 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 data to OME-TIFF, NPZ, HDF5, and annotated videos as GIF, MP4, AVI or a folder
  of PNG files.
- 🎨 **Optimised colormaps** — new perceptually uniform colourmaps for clear and artifact free visualisation, alongside
  traditional AFM colour maps and `matplotlib` defaults.
- 🔌 **Extensible design** — add your own filters or analysis modules as plugins.

---

## 📦 Installation and Dependencies

**Python compatibility:** 3.10 – 3.13

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 simplest way to install **playNano** is through PyPi using the command:

```bash
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](CONTRIBUTING.md).

## 🚀 Quickstart

**Play a file (GUI):**

<!-- markdownlint-disable MD013 -->
<p align="center">
  <img src="https://github.com/derollins/playNano/raw/main/docs/images/GUI_window.png" alt="playNano GUI main window" width="400" />
</p>
<!-- markdownlint-enable MD013 -->

```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, annotations and
colormaps, for the display and animated exports.

Press the **f** key or press **Apply Filters** to level the data 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 --draw-ts --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.

## 🎨 Optimised Colormaps

**playNano** features new perceptually linear colormaps designed to eliminate the "black plateau" and "banding" found in
traditional AFM visualisation. The default, `afm_brown`, uses monotonically increasing luminance to resolve fine substrate
detail and ensure visual stability in HS-AFM videos, preventing the "flicker" artifacts caused by non-linear lightness
discontinuities, while retaining the classic orange-brown AFM character. The package also includes `playnano_gold`, a
monotone-lightness high-contrast colormap spanning the full luminance range (L* 0–100) for complex, feature-rich samples,
and `classic_afm`, a non-linear map replicating the common brown AFM colormap for continuity with existing workflows.

<!-- markdownlint-disable MD013 -->
<p align="center">
  <img src="https://raw.githubusercontent.com/derollins/playNano/main/docs/images/native_colormaps.png" alt="playNano native colormaps" width="400" />
</p>
<!-- markdownlint-enable MD013 -->

All three colormaps are registered globally on import as `matplotlib` cmaps, making them available across the entire
toolkit and in your own scripts alongside built-in options such as `afmhot` and `viridis`.

## 📒 Notebooks

<!-- markdownlint-disable MD013 -->
<p align="center">
  <img src="https://github.com/derollins/playNano/raw/main/docs/images/notebook_capture.png" alt="playNano demonstration notebook" width="400" />
</p>
<!-- markdownlint-enable MD013 -->

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.

## 🤝 Contributing

Contributions are welcome — bug reports, new features, processing plugins, and analysis modules.
See [CONTRIBUTING.md](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](https://github.com/derollins/playNano-plugins) repository.

## 🔗 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).

NOW AVAILABLE: The masking, levelling and auto levelling routines rewritten in Python can be found
here: [Python-NanoLocz-Library](https://github.com/derollins/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)](https://www.gnu.org/licenses/gpl-3.0.html)

## 📖 Citing playNano

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

> Rollins, D. E. (2026). *playNano: AFM Video Processing and Analysis Toolkit.*
> GitHub repository: <https://github.com/derollins/playNano>

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

```bibtex
@misc{rollins2026playnano,
  author = {Rollins, D. E.},
  title  = {playNano: AFM Video Processing and Analysis Toolkit},
  year   = {2026},
  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](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/resources/fonts/Steps-Mono/LICENSE.txt`
- `src/playnano/resources/fonts/basic/LICENSE.txt`
