spmkit 0.1.0__py3-none-any.whl

spmkit/core/analysis/profiles.py

@@ -0,0 +1,76 @@
+"""Perfiles de línea sobre imágenes SPM.
+
+Extrae el perfil de altura a lo largo de un segmento arbitrario usando
+interpolación bilineal, devolviendo distancia física vs altura.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from spmkit.core.models import SPMChannel
+
+
+@dataclass(frozen=True)
+class Profile:
+    """Perfil de línea: distancia (m) vs altura (unidad del canal)."""
+
+    distance: np.ndarray
+    height: np.ndarray
+    unit: str
+    distance_unit: str = "m"
+
+    def __len__(self) -> int:
+        return int(self.distance.size)
+
+
+def _bilinear(z: np.ndarray, r: np.ndarray, c: np.ndarray) -> np.ndarray:
+    """Muestreo bilineal de ``z`` en coordenadas fraccionarias (fila, col)."""
+    rows, cols = z.shape
+    r0 = np.clip(np.floor(r).astype(int), 0, rows - 1)
+    c0 = np.clip(np.floor(c).astype(int), 0, cols - 1)
+    r1 = np.clip(r0 + 1, 0, rows - 1)
+    c1 = np.clip(c0 + 1, 0, cols - 1)
+    dr = r - r0
+    dc = c - c0
+    top = z[r0, c0] * (1 - dc) + z[r0, c1] * dc
+    bot = z[r1, c0] * (1 - dc) + z[r1, c1] * dc
+    return top * (1 - dr) + bot * dr
+
+
+def line(
+    channel: SPMChannel,
+    p0: tuple[float, float],
+    p1: tuple[float, float],
+    n: int | None = None,
+) -> Profile:
+    """Extrae un perfil entre dos puntos en **coordenadas de píxel** ``(col, row)``.
+
+    Args:
+        channel: Canal de origen.
+        p0: Punto inicial ``(col, row)`` en píxeles.
+        p1: Punto final ``(col, row)`` en píxeles.
+        n: Número de muestras. Por defecto, la longitud del segmento en píxeles.
+
+    Returns:
+        Un :class:`Profile` con distancia física acumulada y altura.
+    """
+    z = np.asarray(channel.data, dtype=np.float64)
+    (x0, y0), (x1, y1) = p0, p1
+    seg_px = float(np.hypot(x1 - x0, y1 - y0))
+    if n is None:
+        n = max(2, int(round(seg_px)) + 1)
+
+    cols = np.linspace(x0, x1, n)
+    rows = np.linspace(y0, y1, n)
+    height = _bilinear(z, rows, cols)
+
+    # Distancia física: escala media de píxel ponderada por la dirección.
+    dx = (x1 - x0) * channel.pixel_size_x
+    dy = (y1 - y0) * channel.pixel_size_y
+    total = float(np.hypot(dx, dy))
+    distance = np.linspace(0.0, total, n)
+
+    return Profile(distance=distance, height=height, unit=channel.unit)

spmkit/core/analysis/roughness.py

@@ -0,0 +1,76 @@
+"""Parámetros de rugosidad superficial (ISO 25178 areal y ISO 4287 de perfil).
+
+Las funciones esperan datos **ya nivelados** (ver :mod:`spmkit.core.analysis.leveling`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+import numpy as np
+
+from spmkit.core.models import SPMChannel
+
+
+@dataclass(frozen=True)
+class RoughnessResult:
+    """Parámetros de rugosidad areal (ISO 25178).
+
+    Attributes:
+        Sa: Altura media aritmética (media de |z|).
+        Sq: Altura media cuadrática (RMS).
+        Sz: Altura máxima (pico-valle): ``Sp + |Sv|``.
+        Sp: Altura máxima de pico.
+        Sv: Profundidad máxima de valle.
+        Ssk: Asimetría (skewness) de la distribución de alturas.
+        Sku: Curtosis (kurtosis) de la distribución de alturas.
+        unit: Unidad de las magnitudes de altura.
+        n_points: Número de puntos usados.
+    """
+
+    Sa: float
+    Sq: float
+    Sz: float
+    Sp: float
+    Sv: float
+    Ssk: float
+    Sku: float
+    unit: str
+    n_points: int
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def statistics(channel: SPMChannel) -> RoughnessResult:
+    """Calcula los parámetros de rugosidad areal de un canal nivelado."""
+    z = np.asarray(channel.data, dtype=np.float64)
+    flat = z.ravel()
+    flat = flat[np.isfinite(flat)]
+    mean = flat.mean()
+    dev = flat - mean
+
+    sq = float(np.sqrt(np.mean(dev**2)))
+    sa = float(np.mean(np.abs(dev)))
+    sp = float(dev.max())
+    sv = float(dev.min())
+    sz = float(sp - sv)
+    # Momentos normalizados (con guardia para superficie plana)
+    if sq > 0:
+        ssk = float(np.mean(dev**3) / sq**3)
+        sku = float(np.mean(dev**4) / sq**4)
+    else:
+        ssk = 0.0
+        sku = 0.0
+
+    return RoughnessResult(
+        Sa=sa,
+        Sq=sq,
+        Sz=sz,
+        Sp=sp,
+        Sv=sv,
+        Ssk=ssk,
+        Sku=sku,
+        unit=channel.unit,
+        n_points=int(flat.size),
+    )

spmkit/core/batch.py

@@ -0,0 +1,110 @@
+"""Procesamiento por lotes de múltiples archivos SPM.
+
+Recorre una carpeta (o lista de archivos), aplica el pipeline de análisis a
+cada uno y devuelve una tabla resumen, ideal para procesar campañas completas
+de medidas del lab.
+"""
+
+from __future__ import annotations
+
+import csv as _csv
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from spmkit.core.analysis import kpfm, leveling, roughness
+from spmkit.core.io import load, supported_extensions
+
+
+@dataclass
+class BatchRow:
+    """Resumen de un archivo procesado."""
+
+    file: str
+    channel: str
+    ok: bool
+    Sa: float | None = None
+    Sq: float | None = None
+    Sz: float | None = None
+    cpd_mean: float | None = None
+    error: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "file": self.file,
+            "channel": self.channel,
+            "ok": self.ok,
+            "Sa": self.Sa,
+            "Sq": self.Sq,
+            "Sz": self.Sz,
+            "cpd_mean": self.cpd_mean,
+            "error": self.error,
+        }
+
+
+@dataclass
+class BatchResult:
+    """Resultado de un lote: filas + conteo de éxitos/errores."""
+
+    rows: list[BatchRow] = field(default_factory=list)
+
+    @property
+    def n_ok(self) -> int:
+        return sum(r.ok for r in self.rows)
+
+    @property
+    def n_failed(self) -> int:
+        return sum(not r.ok for r in self.rows)
+
+    def to_csv(self, path: str | Path) -> Path:
+        path = Path(path)
+        with path.open("w", newline="", encoding="utf-8") as fh:
+            writer = _csv.DictWriter(fh, fieldnames=list(BatchRow("", "", True).to_dict()))
+            writer.writeheader()
+            for row in self.rows:
+                writer.writerow(row.to_dict())
+        return path
+
+
+def find_files(folder: str | Path) -> list[Path]:
+    """Lista archivos SPM soportados en una carpeta (no recursivo)."""
+    folder = Path(folder)
+    exts = set(supported_extensions())
+    return sorted(p for p in folder.iterdir() if p.suffix.lower() in exts)
+
+
+def process(
+    files: Iterable[str | Path],
+    channel: str = "Z-Axis",
+    cpd_channel: str = "CPD",
+    level: str = "plane",
+) -> BatchResult:
+    """Analiza una colección de archivos y devuelve la tabla resumen."""
+    result = BatchResult()
+    for f in files:
+        f = Path(f)
+        try:
+            data = load(f)
+            ch = data[channel]
+            if level == "plane":
+                ch = leveling.plane_fit(ch)
+            elif level == "poly":
+                ch = leveling.polynomial(ch, order=2)
+            stats = roughness.statistics(ch)
+            cpd_mean = None
+            if cpd_channel in data.names:
+                cpd_mean = kpfm.statistics(data[cpd_channel]).mean
+            result.rows.append(
+                BatchRow(
+                    file=f.name,
+                    channel=channel,
+                    ok=True,
+                    Sa=stats.Sa,
+                    Sq=stats.Sq,
+                    Sz=stats.Sz,
+                    cpd_mean=cpd_mean,
+                )
+            )
+        except Exception as exc:  # noqa: BLE001 - registrar fallo y continuar
+            result.rows.append(BatchRow(file=f.name, channel=channel, ok=False, error=str(exc)))
+    return result

spmkit/core/export/__init__.py

@@ -0,0 +1,5 @@
+"""Exportación de datos y resultados a formatos abiertos."""
+
+from spmkit.core.export.writers import to_csv, to_hdf5, to_json
+
+__all__ = ["to_csv", "to_hdf5", "to_json"]

spmkit/core/export/writers.py

@@ -0,0 +1,90 @@
+"""Exportación de datos y resultados procesados a formatos abiertos.
+
+Soporta CSV y JSON (siempre disponibles) y HDF5 (requiere el extra
+``hdf5``). Las funciones aceptan tanto los dataclasses de resultados
+(``RoughnessResult``, ``CPDResult``, ``Profile``) como objetos
+:class:`SPMData` completos.
+"""
+
+from __future__ import annotations
+
+import csv as _csv
+import json as _json
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from spmkit.core.analysis.profiles import Profile
+from spmkit.core.models import SPMData
+
+
+def _to_serializable(obj: Any) -> Any:
+    """Convierte dataclasses / ndarrays a tipos JSON-serializables."""
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return {k: _to_serializable(v) for k, v in asdict(obj).items()}
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, np.generic):
+        return obj.item()
+    if isinstance(obj, dict):
+        return {k: _to_serializable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_to_serializable(v) for v in obj]
+    return obj
+
+
+def to_json(result: Any, path: str | Path) -> Path:
+    """Escribe cualquier resultado (dataclass/dict) a JSON."""
+    path = Path(path)
+    path.write_text(
+        _json.dumps(_to_serializable(result), indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return path
+
+
+def to_csv(result: Any, path: str | Path) -> Path:
+    """Escribe un resultado a CSV.
+
+    * Para :class:`Profile`: dos columnas ``distance,height``.
+    * Para dataclasses escalares (rugosidad, CPD): formato ``key,value``.
+    """
+    path = Path(path)
+    with path.open("w", newline="", encoding="utf-8") as fh:
+        writer = _csv.writer(fh)
+        if isinstance(result, Profile):
+            writer.writerow([f"distance[{result.distance_unit}]", f"height[{result.unit}]"])
+            for d, h in zip(result.distance, result.height, strict=True):
+                writer.writerow([d, h])
+        elif is_dataclass(result) and not isinstance(result, type):
+            writer.writerow(["key", "value"])
+            for key, value in asdict(result).items():
+                writer.writerow([key, value])
+        else:
+            raise TypeError(f"No sé exportar a CSV: {type(result).__name__}")
+    return path
+
+
+def to_hdf5(data: SPMData, path: str | Path) -> Path:
+    """Escribe un :class:`SPMData` completo a HDF5 (un dataset por canal)."""
+    try:
+        import h5py
+    except ImportError as exc:  # pragma: no cover - depende del entorno
+        raise ImportError(
+            "Exportar a HDF5 requiere h5py. Instala con: pip install 'spmkit[hdf5]'"
+        ) from exc
+
+    path = Path(path)
+    with h5py.File(path, "w") as f:
+        f.attrs["source_path"] = data.source_path
+        f.attrs["format"] = str(data.metadata.get("format", ""))
+        for i, ch in enumerate(data.channels):
+            dset = f.create_dataset(f"{ch.group}/{ch.name}_{i}", data=ch.data)
+            dset.attrs["name"] = ch.name
+            dset.attrs["unit"] = ch.unit
+            dset.attrs["x_range"] = ch.x_range
+            dset.attrs["y_range"] = ch.y_range
+            dset.attrs["direction"] = ch.direction
+    return path

spmkit/core/io/__init__.py

@@ -0,0 +1,8 @@
+"""Lectura de formatos SPM."""
+
+from spmkit.core.io.gwy import load_gwy, save_gwy
+from spmkit.core.io.nhf import load_nhf
+from spmkit.core.io.nid import load_nid
+from spmkit.core.io.registry import load, supported_extensions
+
+__all__ = ["load", "load_nid", "load_nhf", "load_gwy", "save_gwy", "supported_extensions"]

spmkit/core/io/gwy.py

@@ -0,0 +1,97 @@
+"""Interop con Gwyddion: lectura y escritura del formato ``.gwy``.
+
+Usa la librería pura-Python ``gwyfile`` (no requiere tener Gwyddion
+instalado), de modo que los archivos viajan sin fricción entre spmkit y el
+flujo de trabajo del lab en Gwyddion.
+
+Necesita el extra ``gwy`` (``pip install 'spmkit[gwy]'``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from spmkit.core.models import SPMChannel, SPMData
+
+_DIRECTIONS = ("forward", "backward")
+
+
+def _import_gwyfile():  # type: ignore[no-untyped-def]
+    try:
+        import gwyfile
+    except ImportError as exc:  # pragma: no cover - depende del entorno
+        raise ImportError(
+            "La interop .gwy requiere gwyfile. Instala con: pip install 'spmkit[gwy]'"
+        ) from exc
+    return gwyfile
+
+
+def _split_direction(title: str) -> tuple[str, str]:
+    """Separa ``'Z-Axis forward'`` → ``('Z-Axis', 'forward')``."""
+    for direction in _DIRECTIONS:
+        if title.endswith(direction):
+            return title[: -len(direction)].strip(), direction
+    return title, "forward"
+
+
+def load_gwy(path: str | Path) -> SPMData:
+    """Lee un archivo Gwyddion ``.gwy`` y devuelve un :class:`SPMData`."""
+    gwyfile = _import_gwyfile()
+    from gwyfile.util import get_datafields
+
+    path = Path(path)
+    container = gwyfile.load(str(path))
+    datafields = get_datafields(container)
+
+    channels: list[SPMChannel] = []
+    for title, df in datafields.items():
+        name, direction = _split_direction(title)
+        unit = getattr(getattr(df, "si_unit_z", None), "unitstr", "") or ""
+        channels.append(
+            SPMChannel(
+                name=name,
+                data=np.asarray(df.data, dtype=np.float64),
+                unit=unit,
+                x_range=float(df.xreal),
+                y_range=float(df.yreal),
+                direction=direction,
+                group=title,
+                metadata={"gwy_title": title},
+            )
+        )
+    if not channels:
+        raise ValueError(f"No se encontraron canales en el .gwy: {path}")
+    return SPMData(channels=tuple(channels), metadata={"format": "gwy"}, source_path=str(path))
+
+
+def save_gwy(data: SPMData, path: str | Path) -> Path:
+    """Escribe un :class:`SPMData` a ``.gwy`` (abrible directamente en Gwyddion)."""
+    _import_gwyfile()
+    from gwyfile.objects import GwyContainer, GwyDataField, GwySIUnit
+
+    path = Path(path)
+    container = GwyContainer()
+    seen: dict[str, int] = {}
+    for i, ch in enumerate(data.channels):
+        df = GwyDataField(
+            np.ascontiguousarray(ch.data, dtype=np.float64),
+            xreal=ch.x_range or 1.0,
+            yreal=ch.y_range or 1.0,
+            si_unit_xy=GwySIUnit(unitstr="m"),
+            si_unit_z=GwySIUnit(unitstr=ch.unit or ""),
+        )
+        container[f"/{i}/data"] = df
+        container[f"/{i}/data/title"] = _unique_title(f"{ch.name} {ch.direction}".strip(), seen)
+    container.tofile(str(path))
+    return path
+
+
+def _unique_title(title: str, seen: dict[str, int]) -> str:
+    """Garantiza títulos únicos (Gwyddion colapsa títulos repetidos)."""
+    if title not in seen:
+        seen[title] = 1
+        return title
+    seen[title] += 1
+    return f"{title} ({seen[title]})"

spmkit/core/io/nhf.py

@@ -0,0 +1,74 @@
+"""Parser del formato NanoSurf ``.nhf`` (nuevo, basado en HDF5).
+
+El formato ``.nhf`` es un contenedor HDF5. Esta implementación recorre el
+árbol HDF5 de forma genérica: cada *dataset* 2D se interpreta como un canal,
+tomando unidades/escala de los atributos cuando están disponibles.
+
+.. note::
+   Implementación inicial best-effort. Requiere validación contra archivos
+   ``.nhf`` reales del lab. Necesita el extra ``hdf5`` (``pip install
+   spmkit[hdf5]``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from spmkit.core.models import SPMChannel, SPMData
+
+
+def _attr(obj: Any, *keys: str, default: Any = None) -> Any:
+    """Devuelve el primer atributo presente entre ``keys``."""
+    for key in keys:
+        if key in obj.attrs:
+            val = obj.attrs[key]
+            if isinstance(val, bytes):
+                return val.decode("utf-8", "replace")
+            return val
+    return default
+
+
+def load_nhf(path: str | Path) -> SPMData:
+    """Lee un archivo NanoSurf ``.nhf`` (HDF5) y devuelve un :class:`SPMData`."""
+    try:
+        import h5py
+    except ImportError as exc:  # pragma: no cover - depende del entorno
+        raise ImportError(
+            "Leer .nhf requiere h5py. Instala con: pip install 'spmkit[hdf5]'"
+        ) from exc
+
+    path = Path(path)
+    channels: list[SPMChannel] = []
+
+    with h5py.File(path, "r") as f:
+
+        def visit(name: str, obj: Any) -> None:
+            if not isinstance(obj, h5py.Dataset):
+                return
+            if obj.ndim != 2:
+                return
+            data = np.asarray(obj[()], dtype=np.float64)
+            channels.append(
+                SPMChannel(
+                    name=_attr(obj, "name", "Name", default=name.split("/")[-1]),
+                    data=data,
+                    unit=_attr(obj, "unit", "Unit", "base_unit", default=""),
+                    x_range=float(_attr(obj, "x_range", "image_size_x", default=0.0)),
+                    y_range=float(_attr(obj, "y_range", "image_size_y", default=0.0)),
+                    direction=_attr(obj, "direction", default="forward"),
+                    group=name.rsplit("/", 1)[0],
+                    metadata={k: _attr(obj, k) for k in obj.attrs},
+                )
+            )
+
+        f.visititems(visit)
+        root_meta = {k: _attr(f, k) for k in f.attrs}
+
+    if not channels:
+        raise ValueError(f"No se encontraron canales 2D en el .nhf: {path}")
+
+    metadata = {"format": "nhf", "info": root_meta}
+    return SPMData(channels=tuple(channels), metadata=metadata, source_path=str(path))