pnanolocz 📦

A Python library for AFM image flattening, background leveling, and edge detection, based on the MATLAB NanoLocz platform. Original NanoLocz MATLAB library is available here: https://github.com/George-R-Heath/NanoLocz-Matlab-Library

🔍 Key Features

• Versatile Leveling: Polynomial plane/line subtraction, median- and log‑based flattening.
• Automated Routines: Multi‑frame “routines” (plane‑line, iterative high/low, Otsu pipelines, etc.).
• Threshold & Edge Masks: Histogram, Otsu, Sobel‑based edges, skeletonization, change‑point line steps.
• 2D & 3D Support: Works on single images (H,W) or stacks (N,H,W).
• Batch‑Ready: Scriptable for high‑speed AFM (HS‑AFM) and localization AFM (LAFM) workflows.

📦 Installation

pip install pnanolocz

Or clone & install locally:

git clone https://github.com/derollins/Python-Nanolocz-Library.git
cd Python-Nanolocz-Library
pip install .

Requirements

This library requires Python 3.11 or newer and uses modern scientific Python packages to replace MATLAB functionality from the original NanoLocz platform:

• NumPy – Core numerical operations and array handling (replaces MATLAB’s matrix operations).
• SciPy – Polynomial fitting, signal processing, and optimization routines (similar to MATLAB’s polyfit, filter, etc.).
• scikit-image – Image processing tools for thresholding, edge detection, and morphological operations (analogous to MATLAB’s Image Processing Toolbox).
• Matplotlib – Visualization of AFM frames and masks (replaces MATLAB’s plotting functions).
• ruptures – Change-point detection for line-step analysis (provides advanced segmentation beyond MATLAB’s built-ins).
• sknw – Skeletonization and graph-based analysis for edge and structure detection.

These libraries allow the Python implementation to match or exceed MATLAB’s capabilities while remaining open-source and easily extensible for AFM workflows.

🚀 Quickstart

import numpy as np
from pnanolocz.level import apply_level
from pnanolocz.level_auto import apply_level_auto
from pnanolocz.thresholder import apply_thresholder
from pnanolocz.level_weighted import apply_weighted_level

# 1) Polynomial plane leveling
img = np.load("frame.npy")        # (H,W)
flat = apply_level(img, 2, 2, method="plane")

# 2) Region-weighted line leveling
frames = np.load("frames.npy")      # (N,H,W)
mask = thresholder(frames, method="threshold", limits=(1.5, 50))
levelled = apply_weighted_level(frames, 1, 0, method="line", mask=mask)

# 3) Automated multi‑frame pipeline
stack = np.load("stack.npy")      # (N,H,W)
out = apply_level_auto(stack, routine="multi-plane-otsu")

# 4) Otsu mask
mask = apply_thresholder(img, method="otsu", limits=None)

📖 Modules

• pnanolocz.level Core flattening / leveling (plane, line, median, smoothed, mean, log).

  Typical usage involves calling the apply_level() function with an image (2D) or image stack (3D) and specifying the desired method and polynomial orders. (see Quickstart above for an example)

  Available methods:

• pnanolocz.level_weighted Weighted-region flattening / leveling (plane, line, median and smoothed).

  Typical usage involves calling the apply_weighted_level() function with an image (2D) or image stack (3D) and specifying the desired method and polynomial orders. (see Quickstart above for an example)

  Available methods:

• pnanolocz.thresholder Intensity / edge detection: histogram, Otsu, auto edges, skeleton, step detection.

  Typical usage involves calling the apply_thresholder() function with an image (2D) or image stack (3D) and specifying the desired method and polynomial orders. (see Quickstart above for an example)

  Available thresholder functions:

• pnanolocz.level_auto Pre‑defined multi‑frame routines built from level + thresholder.

🔗 Links

• Homepage: GitHub Repository Explore the source code, documentation, and examples.
• Issue Tracker: https://github.com/derollins/Python-Nanolocz-Library/issues Use this to submit bug reports, feature requests, or ask questions.

📝 Citation

If you use this library, please cite:

Heath, G.R. et al. NanoLocz: Image analysis platform for AFM, high‑speed AFM and localization AFM. Small Methods 2024, 2301766. https://doi.org/10.1002/smtd.202301766

and

Rollins, D. E., & Heath, G. R. (2025). Python-NanoLocz-Library: A Python implementation of the NanoLocz AFM leveling and analysis tools. University of Leeds. https://github.com/derollins/Python-Nanolocz-Library

⚖️ License

Distributed under the terms of the GNU GPL v3.0.