Metadata-Version: 2.4
Name: spmkit
Version: 0.1.0
Summary: Analizador open-source de datos AFM/KPFM para microscopía de sonda de barrido (SPM)
Project-URL: Homepage, https://github.com/kegouro/spmkit
Project-URL: Repository, https://github.com/kegouro/spmkit
Project-URL: Issues, https://github.com/kegouro/spmkit/issues
Author: Tomás Corrales
Author-email: José Labarca <joselabarcabaeza11@hotmail.com>
Maintainer: SPM Lab UTFSM
License: MIT
License-File: LICENSE
Keywords: afm,kpfm,microscopy,nanosurf,nid,roughness,spm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: cmcrameri>=1.7; extra == 'all'
Requires-Dist: gwyfile>=0.3; extra == 'all'
Requires-Dist: h5py>=3.8; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: matplotlib-scalebar>=0.8; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: nsfopen>=2.2; extra == 'all'
Requires-Dist: pyqt6>=6.6; extra == 'all'
Requires-Dist: pyqtgraph>=0.13; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: gui
Requires-Dist: cmcrameri>=1.7; extra == 'gui'
Requires-Dist: matplotlib-scalebar>=0.8; extra == 'gui'
Requires-Dist: matplotlib>=3.8; extra == 'gui'
Requires-Dist: pyqt6>=6.6; extra == 'gui'
Requires-Dist: pyqtgraph>=0.13; extra == 'gui'
Provides-Extra: gwy
Requires-Dist: gwyfile>=0.3; extra == 'gwy'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.8; extra == 'hdf5'
Provides-Extra: nanosurf
Requires-Dist: nsfopen>=2.2; extra == 'nanosurf'
Provides-Extra: report
Requires-Dist: cmcrameri>=1.7; extra == 'report'
Requires-Dist: jinja2>=3.1; extra == 'report'
Requires-Dist: matplotlib-scalebar>=0.8; extra == 'report'
Requires-Dist: matplotlib>=3.8; extra == 'report'
Provides-Extra: test-gui
Requires-Dist: pytest-qt>=4.4; extra == 'test-gui'
Provides-Extra: viz
Requires-Dist: cmcrameri>=1.7; extra == 'viz'
Requires-Dist: matplotlib-scalebar>=0.8; extra == 'viz'
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Description-Content-Type: text/markdown

# spmkit

[![CI](https://github.com/kegouro/spmkit/actions/workflows/ci.yml/badge.svg)](https://github.com/kegouro/spmkit/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/spmkit.svg)](https://pypi.org/project/spmkit/)
[![Python](https://img.shields.io/pypi/pyversions/spmkit.svg)](https://pypi.org/project/spmkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![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)

Analizador **open-source** de datos de microscopía de sonda de barrido (SPM),
con foco en **AFM** y **KPFM**. Desarrollado en el **SPM Lab de la UTFSM**.

Lee formatos NanoSurf (`.nid`, `.nhf`) y Gwyddion (`.gwy`), calcula rugosidad,
perfiles de línea, KPFM (CPD / función de trabajo) y nanomecánica, y exporta a
formatos abiertos (CSV, HDF5, JSON, figuras). Incluye CLI y una GUI científica
(PyQt6 + pyqtgraph).

![spmkit GUI](docs/images/screenshot_viewer.png)

> _Captura con datos sintéticos de ejemplo._

## Tabla de contenidos

- [Capacidades](#capacidades) · [Instalación](#instalación) · [Uso rápido](#uso-rápido)
- [Formatos](#formatos-soportados) · [Arquitectura](#arquitectura) ·
  [Validación científica](docs/VALIDATION.md) · [Desarrollo](#desarrollo) ·
  [Contribuir](CONTRIBUTING.md) · [Citación](#citación)

## Arquitectura

Separación estricta en tres capas. CLI y GUI **solo** usan la API pública del
`core`; nunca tocan parsers ni implementan análisis.

```
┌───────────────┐     ┌───────────────┐
│   cli/        │     │   gui/        │   ← capas de presentación
│ (typer+rich)  │     │ (PyQt6+pg)    │
└───────┬───────┘     └───────┬───────┘
        │   importan funciones del core   │
        └───────────────┬─────────────────┘
                        ▼
        ┌───────────────────────────────┐
        │            core/              │   ← puro Python, sin UI
        │  io · models · analysis · export │
        └───────────────────────────────┘
                        ▲
        .nid / .nhf  ───┘  (archivos del instrumento)
```

## Instalación

```bash
# Recomendado: con uv
uv pip install spmkit            # núcleo + CLI
uv pip install "spmkit[gui]"     # + interfaz gráfica (PyQt6, incluye viz)
uv pip install "spmkit[viz]"     # + figuras de publicación (matplotlib, colormaps, scale bar)
uv pip install "spmkit[gwy]"     # + interop Gwyddion (.gwy)
uv pip install "spmkit[hdf5]"    # + lectura/exportación HDF5
uv pip install "spmkit[report]"  # + reportes HTML/PDF
uv pip install "spmkit[nanosurf]"# + lector .nhf validado (NSFopen)
uv pip install "spmkit[all]"     # todo

# Desarrollo (desde el repo)
uv pip install -e ".[dev,gui,hdf5,gwy,report]"
pre-commit install
```

> También funciona con `pip` clásico (`pip install spmkit`). El build backend es
> `hatchling`, moderno y compatible.

## Uso rápido

### CLI

```bash
spmkit info scan.nid                          # metadatos y canales
spmkit roughness scan.nid -c Z-Axis           # rugosidad (ISO 25178)
spmkit analyze scan.nid -o ./results/         # pipeline completo → CSV+JSON
spmkit nanomech spec.nid --tip-radius 10e-9   # ajuste Hertz → módulo de Young
spmkit batch ./carpeta/ -o resumen.csv        # procesa una carpeta completa
spmkit figure scan.nid -o fig.svg --colormap batlow   # figura de publicación
spmkit convert scan.nid scan.gwy              # convierte a Gwyddion (.gwy)
spmkit gui                                     # interfaz gráfica
```

### Como librería

```python
from spmkit import load
from spmkit.core.analysis import leveling, roughness, profiles, kpfm

data = load("scan.nid")
print(data.names)                       # ['Z-Axis', 'CPD', 'Amplitude', ...]

ch    = data["Z-Axis"]
flat  = leveling.plane_fit(ch)          # corrige inclinación
stats = roughness.statistics(flat)      # Sa, Sq, Sz, Ssk, Sku
print(stats.Sq, stats.unit)

line  = profiles.line(flat, (0, 0), (100, 100))   # perfil de línea
cpd   = kpfm.statistics(data["CPD"], tip_work_function=5.0)
```

## Capacidades

- **Lectura**: NanoSurf `.nid` (validado), `.nhf` (HDF5) y Gwyddion `.gwy`.
- **Análisis**: rugosidad ISO 25178, nivelación, perfiles, KPFM (CPD/función de
  trabajo) y **nanomecánica** (curvas fuerza-distancia, Hertz/Sneddon → módulo
  de Young, punto de contacto, adhesión).
- **Interop Gwyddion**: lee/escribe `.gwy` (pure-Python) y abre el archivo en
  Gwyddion con un clic.
- **Figuras de publicación**: editor WYSIWYG (título, ejes, colormaps
  científicos, barra de escala, anotaciones arrastrables) → PNG/SVG/PDF.
- **Quality of life**: procesamiento por lotes, reportes HTML/PDF, archivos
  recientes, drag & drop, tema claro/oscuro.

## Formatos soportados

| Formato | Extensión | Estado |
|---------|-----------|--------|
| NanoSurf clásico | `.nid` | ✅ Lectura completa (validado) |
| NanoSurf HDF5 | `.nhf` | 🧪 Experimental (`[hdf5]` o `[nanosurf]`) |
| Gwyddion | `.gwy` | ✅ Lectura y escritura (`[gwy]`) |
| Exportación | `.csv`, `.json`, `.h5`, `.png/.svg/.pdf` | ✅ |

## Desarrollo

```bash
pytest                  # tests + cobertura
ruff check src tests    # lint
black src tests         # formato
mypy src                # tipos
```

## Citación

Si usas spmkit en tu investigación, cítalo según [`CITATION.cff`](CITATION.cff).

## Licencia

MIT © 2026 SPM Lab UTFSM — Prof. Tomás Corrales, José Labarca.
