captix 1.0.0__py3-none-any.whl

captix/__init__.py

@@ -0,0 +1,62 @@
+"""captix: Python port of the R captcha package."""
+from __future__ import annotations
+
+from .captcha import Captcha, read_captcha
+from .annotate import annotate
+from .dataset import (
+    CaptchaDataset,
+    DEFAULT_VOCAB,
+    transform_image,
+    encode_label,
+    decode_indices,
+    pad_collate,
+)
+from .model import CRNN
+from .fit import fit_model, FitHistory
+from .decrypt import decrypt
+from .load import save_model, load_model, available_models, download_model
+from .data import download_dataset, available_datasets
+from .metrics import sequence_accuracy
+from .download import (
+    DownloadError,
+    available_sources,
+    download_captchas,
+)
+from .hub import (
+    DEFAULT_REPO_ID,
+    from_pretrained,
+    push_to_hub,
+    save_pretrained,
+)
+
+__all__ = [
+    "Captcha",
+    "read_captcha",
+    "annotate",
+    "CaptchaDataset",
+    "DEFAULT_VOCAB",
+    "transform_image",
+    "encode_label",
+    "decode_indices",
+    "pad_collate",
+    "CRNN",
+    "fit_model",
+    "FitHistory",
+    "decrypt",
+    "save_model",
+    "load_model",
+    "available_models",
+    "download_model",
+    "download_dataset",
+    "available_datasets",
+    "sequence_accuracy",
+    "download_captchas",
+    "available_sources",
+    "DownloadError",
+    "from_pretrained",
+    "save_pretrained",
+    "push_to_hub",
+    "DEFAULT_REPO_ID",
+]
+
+__version__ = "1.0.0"

captix/annotate.py

@@ -0,0 +1,70 @@
+"""Manual / batch annotation of captcha files."""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Callable, List, Optional, Sequence, Union
+
+PathLike = Union[str, Path]
+
+
+def _annotate_one(
+    file: Path,
+    label: str,
+    out_dir: Optional[Path],
+    rm_old: bool,
+) -> Path:
+    target_dir = out_dir if out_dir is not None else file.parent
+    target_dir.mkdir(parents=True, exist_ok=True)
+    new_name = f"{file.stem}_{label}{file.suffix}"
+    new_path = target_dir / new_name
+    if rm_old and out_dir is None:
+        file.rename(new_path)
+    else:
+        shutil.copy2(file, new_path)
+        if rm_old:
+            file.unlink()
+    return new_path
+
+
+def annotate(
+    files: Union[PathLike, Sequence[PathLike]],
+    labels: Optional[Sequence[str]] = None,
+    path: Optional[PathLike] = None,
+    rm_old: bool = False,
+    prompt: Optional[Callable[[Path], str]] = None,
+) -> List[Path]:
+    """Annotate captcha files by appending `_<label>` to the filename.
+
+    Parameters
+    ----------
+    files: file path or list of file paths.
+    labels: list of labels matching `files`. If None, `prompt` is called
+        for each file to obtain the label interactively.
+    path: optional output directory. Defaults to the file's directory.
+    rm_old: if True, remove the original file after annotation.
+    prompt: callable taking the file Path and returning a label string.
+        Defaults to interactive `input()`.
+    """
+    if isinstance(files, (str, Path)):
+        file_list = [Path(files)]
+    else:
+        file_list = [Path(f) for f in files]
+
+    out_dir = Path(path) if path is not None else None
+
+    if labels is None:
+        if prompt is None:
+            def prompt(f: Path) -> str:  # type: ignore[misc]
+                return input(f"Label for {f.name}: ").strip()
+        labels = [prompt(f) for f in file_list]
+    else:
+        if len(labels) != len(file_list):
+            raise ValueError(
+                f"labels length ({len(labels)}) must match files length ({len(file_list)})"
+            )
+
+    return [
+        _annotate_one(f, lab, out_dir, rm_old)
+        for f, lab in zip(file_list, labels)
+    ]

captix/captcha.py

@@ -0,0 +1,111 @@
+"""Captcha container class and read_captcha function."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Union
+
+from PIL import Image
+
+PathLike = Union[str, Path]
+
+_LABEL_RE = re.compile(r"(?<=_)[0-9a-zA-Z]+")
+
+
+def _extract_label(path: Path) -> Optional[str]:
+    stem = path.stem
+    m = _LABEL_RE.search(stem)
+    return m.group(0) if m else None
+
+
+@dataclass
+class Captcha:
+    """Container for one or more captcha images.
+
+    Mirrors the R `captcha` S3 object: a list with `img`, `lab`, `path`.
+    """
+
+    images: List[Image.Image] = field(default_factory=list)
+    labels: List[Optional[str]] = field(default_factory=list)
+    paths: List[Path] = field(default_factory=list)
+
+    def __len__(self) -> int:
+        return len(self.images)
+
+    def __getitem__(self, idx) -> "Captcha":
+        if isinstance(idx, int):
+            return Captcha(
+                images=[self.images[idx]],
+                labels=[self.labels[idx]],
+                paths=[self.paths[idx]],
+            )
+        if isinstance(idx, slice):
+            return Captcha(
+                images=self.images[idx],
+                labels=self.labels[idx],
+                paths=self.paths[idx],
+            )
+        if isinstance(idx, (list, tuple)):
+            return Captcha(
+                images=[self.images[i] for i in idx],
+                labels=[self.labels[i] for i in idx],
+                paths=[self.paths[i] for i in idx],
+            )
+        raise TypeError(f"Unsupported index type: {type(idx)}")
+
+    def __repr__(self) -> str:
+        return f"Captcha(n={len(self)})"
+
+    def plot(self, cols: int = 4, max_rows: int = 25):
+        """Display captcha images in a grid using matplotlib."""
+        import matplotlib.pyplot as plt
+
+        n = min(len(self), cols * max_rows)
+        rows = (n + cols - 1) // cols
+        fig, axes = plt.subplots(rows, cols, figsize=(cols * 2, rows * 1.2))
+        if rows == 1 and cols == 1:
+            axes = [[axes]]
+        elif rows == 1:
+            axes = [axes]
+        elif cols == 1:
+            axes = [[a] for a in axes]
+        for i in range(rows * cols):
+            r, c = divmod(i, cols)
+            ax = axes[r][c]
+            ax.axis("off")
+            if i < n:
+                ax.imshow(self.images[i])
+                if self.labels[i]:
+                    ax.set_title(self.labels[i], fontsize=8)
+        fig.tight_layout()
+        return fig
+
+
+def read_captcha(
+    files: Union[PathLike, Sequence[PathLike]],
+    lab_in_path: bool = False,
+) -> Captcha:
+    """Read one or more captcha image files into a Captcha object.
+
+    Parameters
+    ----------
+    files: path or sequence of paths
+    lab_in_path: extract label from filename (after the first underscore).
+    """
+    if isinstance(files, (str, Path)):
+        paths: List[Path] = [Path(files)]
+    else:
+        paths = [Path(f) for f in files]
+
+    images: List[Image.Image] = []
+    labels: List[Optional[str]] = []
+    for p in paths:
+        if not p.exists():
+            raise FileNotFoundError(p)
+        img = Image.open(p)
+        img.load()
+        images.append(img)
+        labels.append(_extract_label(p) if lab_in_path else None)
+
+    return Captcha(images=images, labels=labels, paths=paths)

captix/data.py

@@ -0,0 +1,65 @@
+"""Download and unzip the labeled captcha datasets from the R package releases."""
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+from typing import List, Union
+
+PathLike = Union[str, Path]
+
+DATASET_NAMES: List[str] = [
+    "cadesp", "esaj", "jucesp", "rfb", "sei",
+    "tjmg", "tjpe", "tjrs", "trf5", "trt",
+]
+
+DATASET_REPO_BASE = "https://github.com/decryptr/captcha/releases/download/data"
+
+
+def available_datasets() -> List[str]:
+    """List of dataset names published in the R captcha release."""
+    return list(DATASET_NAMES)
+
+
+def download_dataset(
+    name: str,
+    dest_dir: PathLike,
+    extract: bool = True,
+    force: bool = False,
+) -> Path:
+    """Download (and optionally unzip) one of the R captcha datasets.
+
+    Returns the path to the extracted directory (or the .zip if `extract=False`).
+    """
+    import requests
+    from tqdm import tqdm
+
+    if name not in DATASET_NAMES:
+        raise ValueError(f"Unknown dataset {name!r}. Choose one of {DATASET_NAMES}.")
+    dest_dir = Path(dest_dir)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    zip_path = dest_dir / f"{name}.zip"
+    out_dir = dest_dir / name
+
+    if not zip_path.exists() or force:
+        url = f"{DATASET_REPO_BASE}/{name}.zip"
+        with requests.get(url, stream=True, timeout=300) as r:
+            r.raise_for_status()
+            total = int(r.headers.get("content-length", 0))
+            with open(zip_path, "wb") as f, tqdm(
+                total=total, unit="B", unit_scale=True, desc=name
+            ) as bar:
+                for chunk in r.iter_content(chunk_size=1 << 20):
+                    if chunk:
+                        f.write(chunk)
+                        bar.update(len(chunk))
+
+    if not extract:
+        return zip_path
+
+    if not out_dir.exists() or force:
+        out_dir.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(zip_path) as zf:
+            zf.extractall(out_dir)
+
+    return out_dir

captix/dataset.py

@@ -0,0 +1,207 @@
+"""Dataset, transforms and label encoding for captix.
+
+The model uses CTC loss, so labels are encoded as integer sequences with a
+reserved blank index 0. The default vocabulary is the full alphanumeric set
+``0-9a-zA-Z`` (62 classes), giving 63 logits including blank.
+"""
+from __future__ import annotations
+
+import re
+import string
+from pathlib import Path
+from typing import List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+import torch
+from PIL import Image
+from torch.utils.data import Dataset
+from torchvision import transforms as T
+
+PathLike = Union[str, Path]
+
+# Default vocabulary: digits + lowercase + uppercase
+DEFAULT_VOCAB: List[str] = list(string.digits + string.ascii_lowercase + string.ascii_uppercase)
+
+# Index 0 is reserved as the CTC blank
+BLANK_INDEX = 0
+
+_LABEL_RE = re.compile(r"(?<=_)[0-9a-zA-Z]+")
+
+
+def _build_char_to_idx(vocab: Sequence[str]) -> dict:
+    return {ch: i + 1 for i, ch in enumerate(vocab)}  # +1 to skip blank
+
+
+def encode_label(label: str, vocab: Sequence[str] = DEFAULT_VOCAB) -> torch.Tensor:
+    """Encode a string label into a 1D LongTensor of vocab indices (no blanks)."""
+    c2i = _build_char_to_idx(vocab)
+    try:
+        return torch.tensor([c2i[c] for c in label], dtype=torch.long)
+    except KeyError as e:
+        raise ValueError(f"Character {e!s} not in vocabulary") from None
+
+
+def decode_indices(
+    indices: Sequence[int],
+    vocab: Sequence[str] = DEFAULT_VOCAB,
+    collapse: bool = True,
+) -> str:
+    """Decode a CTC index sequence to a string.
+
+    If `collapse` is True, applies CTC collapse (remove repeats then blanks).
+    """
+    out_chars: List[str] = []
+    prev = -1
+    for i in indices:
+        i = int(i)
+        if collapse:
+            if i == prev:
+                continue
+            prev = i
+        if i == BLANK_INDEX:
+            continue
+        out_chars.append(vocab[i - 1])
+    return "".join(out_chars)
+
+
+def _flatten_transparency(img: Image.Image) -> Image.Image:
+    """If ``img`` has an alpha channel, composite it onto a solid background
+    whose luminance contrasts with the average color of the visible pixels,
+    then return an RGB image. Otherwise return ``img.convert('RGB')``.
+
+    PIL's default ``convert('RGB')`` drops alpha by pasting onto black — so a
+    captcha drawn as black glyphs on a transparent PNG (TJPE, some PJe
+    installs) collapses to an all-black image and the model sees nothing.
+    Picking the background as the tonal inverse of the mean visible color
+    recovers the contrast regardless of whether the glyphs are dark or light.
+    """
+    has_alpha = img.mode in ("RGBA", "LA") or (
+        img.mode == "P" and "transparency" in img.info
+    )
+    if not has_alpha:
+        return img.convert("RGB")
+    rgba = img.convert("RGBA")
+    arr = np.asarray(rgba)
+    visible = arr[..., 3] > 0
+    if visible.any():
+        mean_lum = float(arr[..., :3][visible].mean())
+    else:
+        mean_lum = 0.0
+    bg_value = 255 if mean_lum < 128 else 0
+    bg = Image.new("RGB", rgba.size, (bg_value, bg_value, bg_value))
+    bg.paste(rgba, mask=rgba.split()[-1])
+    return bg
+
+
+def transform_image(
+    files: Union[PathLike, Sequence[PathLike], Image.Image, Sequence[Image.Image]],
+    height: int = 32,
+    max_width: Optional[int] = None,
+) -> torch.Tensor:
+    """Load and resize image(s) to a fixed height, preserving aspect ratio.
+
+    Returns a 4D tensor (B, 3, H, W). When passing a batch with different widths,
+    images are padded to the maximum width in the batch (or `max_width` if given).
+    """
+    if isinstance(files, (str, Path, Image.Image)):
+        files_list = [files]
+    else:
+        files_list = list(files)
+
+    to_tensor = T.ToTensor()
+    tensors: List[torch.Tensor] = []
+    for f in files_list:
+        if isinstance(f, Image.Image):
+            img = _flatten_transparency(f)
+        else:
+            img = _flatten_transparency(Image.open(f))
+        w, h = img.size
+        new_w = max(1, int(round(w * (height / h))))
+        img = img.resize((new_w, height), Image.BILINEAR)
+        tensors.append(to_tensor(img))
+
+    target_w = max_width if max_width is not None else max(t.shape[-1] for t in tensors)
+    padded = []
+    for t in tensors:
+        if t.shape[-1] < target_w:
+            pad = torch.zeros(3, height, target_w - t.shape[-1])
+            t = torch.cat([t, pad], dim=-1)
+        elif t.shape[-1] > target_w:
+            t = t[..., :target_w]
+        padded.append(t)
+    return torch.stack(padded, dim=0)
+
+
+def _list_files(root: Path) -> List[Path]:
+    exts = {".png", ".jpg", ".jpeg", ".bmp", ".gif", ".tiff", ".webp"}
+    return sorted(p for p in root.rglob("*") if p.is_file() and p.suffix.lower() in exts)
+
+
+def _label_from_path(p: Path) -> Optional[str]:
+    m = _LABEL_RE.search(p.stem)
+    return m.group(0) if m else None
+
+
+class CaptchaDataset(Dataset):
+    """Dataset of labeled captcha images.
+
+    Files must follow the pattern ``<id>_<label>.<ext>``. Labels can have
+    different lengths (CTC handles variable-length sequences).
+    """
+
+    def __init__(
+        self,
+        root: PathLike,
+        vocab: Sequence[str] = DEFAULT_VOCAB,
+        height: int = 32,
+        case_sensitive: bool = True,
+    ):
+        self.root = Path(root)
+        if not self.root.is_dir():
+            raise NotADirectoryError(self.root)
+        self.height = height
+        self.vocab = list(vocab)
+        self.case_sensitive = case_sensitive
+        self.files: List[Path] = []
+        self.labels: List[str] = []
+        for f in _list_files(self.root):
+            lab = _label_from_path(f)
+            if lab is None:
+                continue
+            if not case_sensitive:
+                lab = lab.lower()
+            self.files.append(f)
+            self.labels.append(lab)
+        if not self.files:
+            raise ValueError(f"No labeled captcha files found in {self.root}")
+
+    def __len__(self) -> int:
+        return len(self.files)
+
+    def __getitem__(self, idx: int) -> Tuple[torch.Tensor, torch.Tensor]:
+        img_t = transform_image(self.files[idx], height=self.height)[0]  # (3, H, W)
+        target = encode_label(self.labels[idx], self.vocab)
+        return img_t, target
+
+
+def pad_collate(
+    batch: Sequence[Tuple[torch.Tensor, torch.Tensor]],
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Collate function: pads images to the max width and stacks targets.
+
+    Returns
+    -------
+    images: (B, 3, H, W_max)
+    targets: 1D tensor concatenating all label sequences
+    target_lengths: (B,) lengths for CTC loss
+    """
+    images = [b[0] for b in batch]
+    targets = [b[1] for b in batch]
+    H = images[0].shape[1]
+    W_max = max(im.shape[-1] for im in images)
+    out = torch.zeros(len(images), 3, H, W_max)
+    for i, im in enumerate(images):
+        out[i, :, :, : im.shape[-1]] = im
+    target_lengths = torch.tensor([len(t) for t in targets], dtype=torch.long)
+    targets_cat = torch.cat(targets) if targets else torch.zeros(0, dtype=torch.long)
+    return out, targets_cat, target_lengths