pad-train 1.0.0__py3-none-any.whl

pad_train/__init__.py

@@ -0,0 +1,51 @@
+"""k-NN presentation attack detection trained on real or synthetic attack samples.
+
+Typical use::
+
+    import pad_train
+
+    pad_train.settings.data_root = "/path/to/data"   # optional
+    results = pad_train.evaluate(extractors=["fourier", "haralick"])   # pandas.DataFrame
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from pad_train.config import DatasetConfig, DataSource, Settings, settings
+from pad_train.data import PadData, download_data, load_data
+from pad_train.evaluation import cross_validate, evaluate, evaluate_dataset
+from pad_train.features import (
+    FeatureExtractor,
+    available_extractors,
+    get_extractor,
+    make_fourier_extractor,
+    register_dataset_extractor,
+    register_extractor,
+)
+from pad_train.metrics import PadMetrics, pad_metrics
+
+try:
+    __version__: str = version("pad_train")
+except PackageNotFoundError:  # running from a source tree without installation
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DataSource",
+    "DatasetConfig",
+    "FeatureExtractor",
+    "PadData",
+    "PadMetrics",
+    "Settings",
+    "__version__",
+    "available_extractors",
+    "cross_validate",
+    "download_data",
+    "evaluate",
+    "evaluate_dataset",
+    "get_extractor",
+    "load_data",
+    "make_fourier_extractor",
+    "pad_metrics",
+    "register_dataset_extractor",
+    "register_extractor",
+    "settings",
+]

pad_train/cli.py

@@ -0,0 +1,66 @@
+"""Command line interface: ``pad-train download`` and ``pad-train evaluate``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from collections.abc import Sequence
+from pathlib import Path
+
+from pad_train.config import settings
+from pad_train.data import download_data
+from pad_train.evaluation import PROTOCOLS, evaluate
+from pad_train.features import available_extractors
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Create the argument parser."""
+    parser = argparse.ArgumentParser(prog="pad-train", description=__doc__)
+    parser.add_argument(
+        "--data-root", type=Path, help=f"data directory (default: {settings.data_root})"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    commands.add_parser("download", help="fetch all datasets that are not on disk yet")
+
+    run = commands.add_parser("evaluate", help="run the evaluation and print the result table")
+    run.add_argument("--datasets", nargs="+", choices=list(settings.datasets), help="default: all")
+    run.add_argument("--extractors", nargs="+", default=["fourier"], choices=available_extractors())
+    run.add_argument(
+        "--synthetic", nargs="+", choices=list(settings.synthetic_sources), help="default: all"
+    )
+    run.add_argument("--protocols", nargs="+", default=list(PROTOCOLS), choices=PROTOCOLS)
+    run.add_argument("--n-neighbors", type=int, help="k of the k-NN (default: per dataset)")
+    run.add_argument("--per-fold", action="store_true", help="report every fold, not the mean")
+    run.add_argument("--no-download", action="store_true", help="fail if data is missing")
+    run.add_argument("--output", type=Path, help="also write the table to this CSV file")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the command line interface."""
+    args = _build_parser().parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    if args.data_root is not None:
+        settings.data_root = args.data_root
+
+    if args.command == "download":
+        download_data()
+        return
+
+    results = evaluate(
+        datasets=args.datasets,
+        extractors=args.extractors,
+        synthetic=args.synthetic,
+        protocols=args.protocols,
+        n_neighbors=args.n_neighbors,
+        per_fold=args.per_fold,
+        download=not args.no_download,
+    )
+    print(results.to_string(index=False, float_format="{:.4f}".format))
+    if args.output is not None:
+        results.to_csv(args.output, index=False)
+
+
+if __name__ == "__main__":
+    main()

pad_train/config.py

@@ -0,0 +1,172 @@
+"""Central configuration: where the data lives and how the datasets are laid out.
+
+Everything is plain Python. To change a value, mutate the module-level
+:data:`settings` object before calling into the package::
+
+    from pathlib import Path
+    from pad_train import settings
+
+    settings.data_root = Path("/mnt/datasets/finger_vein")
+
+The data root can also be set through the ``PAD_TRAIN_DATA_ROOT`` environment
+variable, which is read once at import time.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+#: Environment variable overriding the default data root.
+DATA_ROOT_ENV_VAR: str = "PAD_TRAIN_DATA_ROOT"
+
+
+@dataclass
+class DataSource:
+    """A directory of samples, optionally backed by a downloadable zip archive.
+
+    Attributes:
+        name: Short identifier, used in logs and in the result table.
+        path: Directory holding the per-dataset folders. Relative paths are
+            resolved against :attr:`Settings.data_root`.
+        url: Zip archive to fetch when ``path`` does not exist. ``None`` marks a
+            purely local source (e.g. samples produced by your own code).
+        archive_root: Folder inside the archive that holds the per-dataset
+            folders. ``None`` if they sit at the top level of the archive.
+    """
+
+    name: str
+    path: Path
+    url: str | None = None
+    archive_root: str | None = None
+
+
+@dataclass
+class DatasetConfig:
+    """Layout and classifier settings of one finger vein dataset.
+
+    Attributes:
+        name: Dataset identifier (``"PLUS"``, ``"IDIAP"``, ``"SCUT"``).
+        real_dir: Dataset folder inside the real/spoof source.
+        synthetic_dir: Dataset folder inside a synthetic source.
+        subsets: Sub-folders of ``real_dir`` that each contain a ``real`` and a
+            ``spoof`` folder. ``("",)`` means they sit directly in ``real_dir``.
+        n_neighbors: ``k`` of the k-NN classifier.
+        pair_by_filename: Real and spoof captures of the same finger share a
+            file name, so bona fide samples can be matched to their attack
+            sample one-to-one. If ``False`` the matching is done per subject.
+        fourier_thirds: Thirds of the Fourier magnitude spectrum used by the
+            ``fourier`` extractor for this dataset: 1 = low, 2 = middle,
+            3 = high frequencies. Change them in :func:`_default_datasets`.
+    """
+
+    name: str
+    real_dir: str
+    synthetic_dir: str
+    subsets: tuple[str, ...] = ("",)
+    n_neighbors: int = 1
+    pair_by_filename: bool = False
+    fourier_thirds: tuple[int, ...] = (1, 2, 3)
+
+
+def _default_data_root() -> Path:
+    """Return the data root from the environment, falling back to ``./data``."""
+    return Path(os.environ.get(DATA_ROOT_ENV_VAR, "data")).expanduser()
+
+
+def _default_synthetic_sources() -> dict[str, DataSource]:
+    """Return the two diffusion-based synthetic attack sources."""
+    return {
+        "AE_Res": DataSource(
+            name="AE_Res",
+            path=Path("AE_Res-diff"),
+            url="https://cosy.sbg.ac.at/~uhl/AE_Res-diff.zip",
+        ),
+        "VAE": DataSource(
+            name="VAE",
+            path=Path("VAE-diff"),
+            url="https://cosy.sbg.ac.at/~uhl/VAE-diff.zip",
+        ),
+    }
+
+
+def _default_datasets() -> dict[str, DatasetConfig]:
+    """Return the layout of the three supported datasets."""
+    return {
+        "PLUS": DatasetConfig(
+            name="PLUS",
+            real_dir="PLUS",
+            synthetic_dir="PLUS_matched",
+            n_neighbors=6,
+            pair_by_filename=True,
+            fourier_thirds=(1, 2, 3),
+        ),
+        "IDIAP": DatasetConfig(
+            name="IDIAP",
+            real_dir="IDIAP/full",
+            synthetic_dir="IDIAP",
+            # ``test`` is unlabelled in the archive and therefore unusable.
+            subsets=("train", "dev"),
+            pair_by_filename=True,
+            fourier_thirds=(1, 2),
+        ),
+        "SCUT": DatasetConfig(
+            name="SCUT",
+            real_dir="SCUT/full",
+            synthetic_dir="SCUT",
+            subsets=("train", "dev", "test"),
+            fourier_thirds=(1,),
+        ),
+    }
+
+
+@dataclass
+class Settings:
+    """All tunable values of the package.
+
+    Attributes:
+        data_root: Base directory for every relative :attr:`DataSource.path`.
+        real_source: Source of the bona fide (type 1) and real attack (type 2)
+            samples.
+        synthetic_sources: Sources of synthetic attack (type 3) samples, keyed
+            by name. Add an entry to evaluate another generator.
+        synthetic_attack_subdir: Folder below a synthetic dataset folder that
+            holds the attack samples.
+        datasets: Supported datasets, keyed by name.
+        n_folds: Number of subject-disjoint cross-validation folds.
+        random_state: Seed for every random choice (synthetic sub-sampling).
+    """
+
+    data_root: Path = field(default_factory=_default_data_root)
+    real_source: DataSource = field(
+        default_factory=lambda: DataSource(
+            name="real",
+            path=Path("Data_FV_Spoofing_WS2025_26"),
+            url="https://www.cosy.sbg.ac.at/~uhl/Data_FV_Spoofing_WS2025_26.zip",
+            archive_root="Data_FV_Spoofing_WS2025_26",
+        )
+    )
+    synthetic_sources: dict[str, DataSource] = field(default_factory=_default_synthetic_sources)
+    synthetic_attack_subdir: str = "spoof/samples"
+    datasets: dict[str, DatasetConfig] = field(default_factory=_default_datasets)
+    n_folds: int = 5
+    random_state: int = 42
+
+    def resolve(self, source: DataSource) -> Path:
+        """Return the absolute-or-root-relative directory of ``source``."""
+        path = Path(source.path).expanduser()
+        return path if path.is_absolute() else Path(self.data_root).expanduser() / path
+
+    def synthetic_folder(self, source: str, dataset: str) -> Path:
+        """Return the folder holding the attack samples of ``dataset`` in ``source``."""
+        root = self.resolve(self.synthetic_sources[source])
+        return root / self.datasets[dataset].synthetic_dir / self.synthetic_attack_subdir
+
+    def sources(self) -> list[DataSource]:
+        """Return every configured source, the real one first."""
+        return [self.real_source, *self.synthetic_sources.values()]
+
+
+#: Package-wide default settings. Mutate this object to reconfigure the package.
+settings: Settings = Settings()

pad_train/data.py

@@ -0,0 +1,205 @@
+"""Dataset download and loading."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import tempfile
+import urllib.request
+import zipfile
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+from PIL import Image as PILImage
+
+from pad_train.config import DataSource, Settings, settings
+
+logger = logging.getLogger(__name__)
+
+#: A grayscale image as a 2-D ``uint8`` array.
+Image = NDArray[np.uint8]
+
+#: File suffixes (lower case) that are read as images.
+IMAGE_SUFFIXES: frozenset[str] = frozenset({".png", ".bmp", ".jpg", ".jpeg"})
+
+#: Bytes read per chunk while downloading.
+_CHUNK_SIZE: int = 1 << 20
+
+
+@dataclass
+class PadData:
+    """All samples of one dataset, ready for evaluation.
+
+    The bona fide and attack sets are balanced: only bona fide samples with a
+    matching real attack sample are kept (and vice versa).
+
+    Attributes:
+        dataset: Dataset name.
+        real: Bona fide (type 1) images.
+        real_subjects: Subject id of every bona fide image.
+        spoof: Real presentation attack (type 2) images.
+        spoof_subjects: Subject id of every attack image.
+        synthetic: Synthetic attack (type 3) images, keyed by source name. They
+            carry no subject identity.
+    """
+
+    dataset: str
+    real: list[Image]
+    real_subjects: NDArray[np.str_]
+    spoof: list[Image]
+    spoof_subjects: NDArray[np.str_]
+    synthetic: dict[str, list[Image]] = field(default_factory=dict)
+
+
+def _download(url: str, target: Path) -> None:
+    """Stream ``url`` to ``target``, going through a ``.part`` file."""
+    partial = target.with_name(target.name + ".part")
+    logger.info("Downloading %s", url)
+    with urllib.request.urlopen(url) as response, partial.open("wb") as out:
+        total = int(response.headers.get("Content-Length") or 0)
+        done, next_report = 0, 0.1
+        while chunk := response.read(_CHUNK_SIZE):
+            out.write(chunk)
+            done += len(chunk)
+            if total and done / total >= next_report:
+                logger.info("  %3.0f %% of %.0f MB", 100 * done / total, total / 1e6)
+                next_report += 0.1
+    partial.replace(target)
+
+
+def _extract(archive: Path, target: Path, archive_root: str | None) -> None:
+    """Extract ``archive`` so that ``archive_root`` (or its top level) becomes ``target``.
+
+    Extraction happens in a temporary sibling directory which is moved into
+    place at the end, so an existing ``target`` is always complete.
+    """
+    logger.info("Extracting %s", archive.name)
+    with tempfile.TemporaryDirectory(dir=target.parent, prefix=f".{target.name}-") as tmp:
+        staging = Path(tmp) / "content"
+        with zipfile.ZipFile(archive) as zip_file:
+            zip_file.extractall(staging)
+        payload = staging / archive_root if archive_root else staging
+        if not payload.is_dir():
+            raise FileNotFoundError(f"'{archive_root}' not found in {archive.name}")
+        shutil.move(payload, target)
+
+
+def ensure_source(
+    source: DataSource, download: bool = True, config: Settings | None = None
+) -> Path:
+    """Return the directory of ``source``, fetching it first if it is missing.
+
+    Args:
+        source: The data source to locate.
+        download: Download and extract the archive if the directory is missing.
+        config: Settings to use instead of the package-wide ones.
+
+    Returns:
+        The existing directory of the source.
+
+    Raises:
+        FileNotFoundError: The directory is missing and could not be fetched.
+    """
+    config = config or settings
+    path = config.resolve(source)
+    if path.is_dir():
+        return path
+    if not download or source.url is None:
+        raise FileNotFoundError(
+            f"Data source '{source.name}' not found at {path}. "
+            "Run `pad-train download` or call load_data(download=True)."
+        )
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    archive = path.parent / Path(source.url).name
+    if not archive.is_file():
+        _download(source.url, archive)
+    _extract(archive, path, source.archive_root)
+    archive.unlink()
+    return path
+
+
+def download_data(config: Settings | None = None) -> None:
+    """Fetch every configured data source that is not on disk yet."""
+    config = config or settings
+    for source in config.sources():
+        if source.url is not None:
+            logger.info("%s -> %s", source.name, ensure_source(source, config=config))
+
+
+def image_files(folder: Path) -> list[Path]:
+    """Return all image files below ``folder`` in a stable order."""
+    return sorted(p for p in folder.rglob("*") if p.suffix.lower() in IMAGE_SUFFIXES)
+
+
+def read_image(path: Path) -> Image:
+    """Read an image file as a grayscale array."""
+    with PILImage.open(path) as image:
+        return np.asarray(image.convert("L"), dtype=np.uint8)
+
+
+def load_data(
+    dataset: str,
+    synthetic: Sequence[str] | None = None,
+    download: bool = True,
+    config: Settings | None = None,
+) -> PadData:
+    """Load one dataset, downloading the underlying archives when necessary.
+
+    Args:
+        dataset: Dataset name, a key of :attr:`Settings.datasets`.
+        synthetic: Names of the synthetic sources to load. ``None`` loads all
+            configured ones, an empty sequence loads none.
+        download: Fetch missing sources. If ``False`` a missing source raises.
+        config: Settings to use instead of the package-wide ones.
+
+    Returns:
+        The balanced bona fide / attack samples plus the synthetic samples.
+
+    Raises:
+        KeyError: Unknown dataset or synthetic source name.
+        FileNotFoundError: A source is missing (and ``download`` is ``False``),
+            or it contains no samples for this dataset.
+    """
+    config = config or settings
+    layout = config.datasets[dataset]
+    real_root = ensure_source(config.real_source, download, config) / layout.real_dir
+
+    # Subject = name of the folder a capture lives in; key = what makes a bona
+    # fide sample and an attack sample "belong together".
+    files: dict[str, list[Path]] = {"real": [], "spoof": []}
+    for subset in layout.subsets:
+        for kind, found in files.items():
+            found.extend(image_files(real_root / subset / kind))
+
+    def key(path: Path) -> tuple[str, ...]:
+        subject = path.parent.name
+        return (subject, path.name) if layout.pair_by_filename else (subject,)
+
+    # Balanced sets: drop everything without a counterpart in the other class.
+    common = {key(p) for p in files["real"]} & {key(p) for p in files["spoof"]}
+    real_files = [p for p in files["real"] if key(p) in common]
+    spoof_files = [p for p in files["spoof"] if key(p) in common]
+    if not real_files:
+        raise FileNotFoundError(f"No matching real/spoof samples for {dataset} in {real_root}")
+
+    names = list(config.synthetic_sources) if synthetic is None else list(synthetic)
+    synthetic_images: dict[str, list[Image]] = {}
+    for name in names:
+        ensure_source(config.synthetic_sources[name], download, config)
+        folder = config.synthetic_folder(name, dataset)
+        synthetic_images[name] = [read_image(p) for p in image_files(folder)]
+        if not synthetic_images[name]:
+            raise FileNotFoundError(f"No synthetic samples for {dataset} in {folder}")
+
+    return PadData(
+        dataset=dataset,
+        real=[read_image(p) for p in real_files],
+        real_subjects=np.array([p.parent.name for p in real_files]),
+        spoof=[read_image(p) for p in spoof_files],
+        spoof_subjects=np.array([p.parent.name for p in spoof_files]),
+        synthetic=synthetic_images,
+    )