blys 0.1.0__py3-none-any.whl

blys/__init__.py

@@ -0,0 +1,10 @@
+"""blys package.
+
+Utilities for loading fonts, building PyTorch datasets, rendering glyph rasters,
+and running repeatable training loops for font-focused ML tasks.
+"""
+
+from .utils import TrainingLoop
+from .googlefonts import GoogleFonts
+
+__all__ = ["TrainingLoop", "GoogleFonts"]

blys/dataset.py

@@ -0,0 +1,318 @@
+"""Dataset construction helpers for font ML tasks.
+
+This module provides train/test splitting at the family level and dataset/sampler
+utilities that emit either codepoint-level items or glyph-index-level items.
+"""
+
+from collections import defaultdict
+import math
+import random
+from typing import Callable, Optional, Sequence, Set
+
+import torch
+import uharfbuzz as hb
+from glyphsets import GlyphSet, unicodes_per_glyphset
+from sklearn.model_selection import train_test_split
+from torch.utils.data import BatchSampler, DataLoader
+from torch.utils.data import Dataset as TorchDataset
+
+from blys.googlefonts import GoogleFonts
+
+LATIN_CORE = [x for x in GlyphSet("GF_Latin_Core").get_characters() if x != 32]
+# Skip combining characters
+LATIN_CORE = [x for x in LATIN_CORE if not (0x0300 <= x <= 0x036F)]
+
+kernel_glyphs = unicodes_per_glyphset("GF_Latin_Kernel")
+assert kernel_glyphs is not None
+LATIN_KERNEL = [x for x in kernel_glyphs if x != 32]
+# Skip combining characters
+LATIN_KERNEL = [x for x in LATIN_KERNEL if not (0x0300 <= x <= 0x036F)]
+
+
+def _hb_font_for_face(face):
+    """Construct a HarfBuzz Font object for a face."""
+    return getattr(hb, "Font")(face)
+
+
+class DatasetMaker:
+    """Create train/test splits and loaders over glyph rendering items."""
+
+    def __init__(
+        self,
+        repo_url: str,
+        batch_size: int,
+        having: Optional[Set[int]] = None,
+        target_codepoints: Optional[Set[int]] = None,
+        canary_size: Optional[int] = None,
+        image_size: int = 128,
+        split_seed: int = 1234,
+    ):
+        self.target_codepoints = set(target_codepoints) if target_codepoints else None
+        having_filter: Optional[Set[int]] = None
+        if having is not None:
+            having_filter = set(having)
+        if self.target_codepoints is not None:
+            having_filter = (
+                set(self.target_codepoints)
+                if having_filter is None
+                else having_filter | self.target_codepoints
+            )
+
+        self.googlefonts = GoogleFonts(repo_url, having=having_filter)
+        self.batch_size = batch_size
+        self.image_size = image_size
+        self.split_seed = split_seed
+        # Keep data-order randomization reproducible without forcing fixed batches.
+        self._train_loader_generator = torch.Generator()
+        self._train_loader_generator.manual_seed(self.split_seed + 1)
+        self._test_loader_generator = torch.Generator()
+        self._test_loader_generator.manual_seed(self.split_seed + 2)
+
+        # Test chars are a random split from GF Latin Core.
+        _, self.test_latincore_chars = train_test_split(
+            LATIN_CORE,
+            random_state=self.split_seed,
+        )
+
+        if canary_size is not None:
+            fonts = self.googlefonts.fonts[:canary_size]
+        else:
+            fonts = self.googlefonts.fonts
+
+        self.train_fonts, self.test_fonts = self._split_fonts_by_family(
+            fonts,
+            split_seed=self.split_seed,
+        )
+        print("Train fonts:", len(self.train_fonts))
+        print("Test fonts:", len(self.test_fonts))
+
+    @staticmethod
+    def _split_fonts_by_family(fonts, *, split_seed: int):
+        """Split fonts into train/test by family to avoid cross-style leakage."""
+        if len(fonts) < 2:
+            return list(fonts), []
+
+        family_to_fonts = defaultdict(list)
+        for font in fonts:
+            family_to_fonts[font.family].append(font)
+
+        families = sorted(family_to_fonts.keys())
+        if len(families) < 2:
+            # If only one family is available, keep current behaviour and avoid empty train.
+            return list(fonts), []
+
+        train_families, test_families = train_test_split(
+            families,
+            random_state=split_seed,
+        )
+
+        train_family_set = set(train_families)
+        test_family_set = set(test_families)
+
+        train_fonts = [
+            font for family in train_family_set for font in family_to_fonts[family]
+        ]
+        test_fonts = [
+            font for family in test_family_set for font in family_to_fonts[family]
+        ]
+        return train_fonts, test_fonts
+
+    def train_set(self):
+        """Return the training dataset for this maker.
+
+        Subclasses can override this to emit task-specific item structures.
+        """
+        return Dataset(
+            self.train_fonts, codepoint_filter_fn=self.train_codepoint_filter
+        )
+
+    def test_set(self):
+        """Return the test/validation dataset for this maker."""
+        return Dataset(self.test_fonts, codepoint_filter_fn=self.test_codepoint_filter)
+
+    def train_codepoint_filter(self, font_codepoints: Set[int]) -> Set[int]:
+        """Filter a font's codepoints for training.
+
+        By default this excludes the held-out Latin Core split, unless
+        ``target_codepoints`` was provided, in which case only those are kept.
+        """
+        if self.target_codepoints is not None:
+            return set(font_codepoints) & self.target_codepoints
+        return set(font_codepoints) - set(self.test_latincore_chars)
+
+    def test_codepoint_filter(self, font_codepoints: Set[int]) -> Set[int]:
+        """Filter a font's codepoints for testing.
+
+        By default this keeps only the held-out Latin Core split, unless
+        ``target_codepoints`` was provided, in which case only those are kept.
+        """
+        if self.target_codepoints is not None:
+            return set(font_codepoints) & self.target_codepoints
+        return set(font_codepoints) & set(self.test_latincore_chars)
+
+    def train_loader(self):
+        """Build the shuffled training ``DataLoader`` with deterministic RNG."""
+        return DataLoader(
+            self.train_set(),
+            batch_size=self.batch_size,
+            shuffle=True,
+            generator=self._train_loader_generator,
+            drop_last=True,
+            collate_fn=self.collate_fn,
+        )
+
+    def test_loader(self):
+        """Build the shuffled test ``DataLoader`` with deterministic RNG."""
+        return DataLoader(
+            self.test_set(),
+            batch_size=self.batch_size,
+            shuffle=True,
+            generator=self._test_loader_generator,
+            drop_last=True,
+            collate_fn=self.collate_fn,
+        )
+
+    def collate_fn(self, batch):
+        """Collate a batch into model inputs/targets.
+
+        Must be implemented by subclasses that know the task-specific tensor
+        layout and metadata packing.
+        """
+        raise NotImplementedError("Base DatasetMaker does not implement collate_fn")
+
+
+class Dataset(TorchDataset):
+    """Dataset over (font, char) pairs for codepoint-level tasks.
+
+    Returns items of the form {"font": font, "char": char} where char is a Unicode
+    codepoint integer. The dataset is filtered by the provided codepoint_filter_fn,
+    which takes the set of codepoints available in a font and returns the subset to
+    include in the dataset.
+    """
+
+    def __init__(self, fonts, codepoint_filter_fn: Callable[[Set[int]], Set[int]]):
+        """Initialize a codepoint-level dataset over the provided fonts."""
+        self.fonts = fonts
+        self.codepoint_filter_fn = codepoint_filter_fn
+        self.order = []
+        for font in self.fonts:
+            chars = self.codepoint_filter_fn(set(font.codepoints))
+            for char in chars:
+                # Skip empty glyphs; they can destabilize training targets.
+                if font.has_non_empty_codepoint(char):
+                    self.order.append((font, char))
+
+    def __len__(self):
+        """Return number of (font, codepoint) items."""
+        return len(self.order)
+
+    def __getitem__(self, idx):
+        """Return one sample dictionary containing ``char`` and ``font``."""
+        font, char = self.order[idx]
+        return {
+            "char": char,
+            "font": font,
+        }
+
+
+class AllGidsDataset(TorchDataset):
+    """Dataset over all GIDs in the font, used for glyph-level tasks.
+
+    Returns items of the form {"font": font, "gid": gid} where gid is a glyph index. The
+    dataset includes all GIDs for which the font has a non-empty outline, regardless of
+    codepoint coverage.
+    """
+
+    def __init__(self, fonts):
+        """Initialize a glyph-index dataset over all non-empty outlines."""
+        self.fonts = fonts
+        self.order = []
+        for font in self.fonts:
+            for gid in range(1, font.hb_face.glyph_count):
+                # Skip empty glyphs; they can destabilize training targets.
+                if font.has_non_empty_gid(gid):
+                    self.order.append((font, gid))
+
+    def __len__(self):
+        """Return number of (font, gid) items."""
+        return len(self.order)
+
+    def __getitem__(self, idx):
+        """Return one sample dictionary containing ``gid`` and ``font``."""
+        font, gid = self.order[idx]
+        return {
+            "gid": gid,
+            "font": font,
+        }
+
+
+class ClassBalancedBatchSampler(BatchSampler):
+    """Batch sampler that balances font classes within each emitted batch."""
+
+    def __init__(
+        self,
+        order: Sequence[tuple],
+        *,
+        batch_size: int,
+        drop_last: bool,
+    ) -> None:
+        if batch_size <= 0:
+            raise ValueError(f"batch_size must be positive, got {batch_size}")
+        if len(order) == 0:
+            raise ValueError("Cannot build class-balanced sampler for empty dataset")
+
+        self.batch_size = batch_size
+        self.drop_last = drop_last
+        self.dataset_size = len(order)
+
+        class_to_indices: dict[str, list[int]] = {}
+        for idx, (font, _char) in enumerate(order):
+            cls = font.classification()
+            class_to_indices.setdefault(cls, []).append(idx)
+
+        if not class_to_indices:
+            raise ValueError("No classes found for class-balanced sampling")
+
+        self.class_to_indices = class_to_indices
+        self.classes = sorted(class_to_indices.keys())
+
+    def __len__(self) -> int:
+        """Return the number of batches emitted per epoch-like pass."""
+        if self.drop_last:
+            return self.dataset_size // self.batch_size
+        return math.ceil(self.dataset_size / self.batch_size)
+
+    def __iter__(self):
+        """Yield index batches with near-uniform class presence per batch."""
+        num_classes = len(self.classes)
+        num_batches = len(self)
+
+        class_cursor = random.randrange(num_classes)
+
+        for _ in range(num_batches):
+            batch_indices: list[int] = []
+
+            if num_classes <= self.batch_size:
+                base = self.batch_size // num_classes
+                remainder = self.batch_size % num_classes
+                class_order = self.classes[:]
+                random.shuffle(class_order)
+
+                for cls in class_order:
+                    indices = self.class_to_indices[cls]
+                    for _ in range(base):
+                        batch_indices.append(random.choice(indices))
+
+                for cls in class_order[:remainder]:
+                    batch_indices.append(random.choice(self.class_to_indices[cls]))
+            else:
+                selected_classes = [
+                    self.classes[(class_cursor + i) % num_classes]
+                    for i in range(self.batch_size)
+                ]
+                class_cursor = (class_cursor + self.batch_size) % num_classes
+                for cls in selected_classes:
+                    batch_indices.append(random.choice(self.class_to_indices[cls]))
+
+            random.shuffle(batch_indices)
+            yield batch_indices

blys/font.py

@@ -0,0 +1,110 @@
+"""Font abstractions shared by Google Fonts-backed and standalone fonts."""
+
+from functools import cached_property
+import itertools
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+import uharfbuzz as hb
+
+import numpy as np
+
+from fontTools.ttLib import TTFont
+from blys.render import render_gid
+
+
+class Font:
+    """A font, whether standalone or from the Google Fonts repository. This is an abstract base class that defines the interface for fonts, and provides some common functionality. The concrete implementations are GoogleFont and StandaloneFont."""
+
+    hb_face: hb.Face
+    path: Path
+
+    def render_char(
+        self, char: int, size: int = 64, axis_position: Optional[List[float]] = None
+    ) -> np.ndarray:
+        """Render one Unicode codepoint as a CHW float image.
+
+        Returns an all-ones fallback image if shaping or rasterization fails.
+        """
+        try:
+            gid = hb.Font(self.hb_face).get_nominal_glyph(char)
+            return self.render_gid(gid, size, axis_position=axis_position)
+        except Exception:
+            return np.ones((3, size, size), dtype=np.float32)
+
+    def render_gid(
+        self, gid: int, size: int = 64, axis_position: Optional[List[float]] = None
+    ) -> np.ndarray:
+        """Render one glyph index (GID) as a CHW float image.
+
+        Returns an all-ones fallback image if rasterization fails.
+        """
+        try:
+            axis_tuple = tuple(axis_position) if axis_position is not None else None
+            return render_gid(self.path, gid, size, axis_position=axis_tuple)
+        except Exception:
+            return np.ones((3, size, size), dtype=np.float32)
+
+    @cached_property
+    def codepoints(self) -> Set[int]:
+        """Unicode codepoints present in this font."""
+        return set(self.hb_face.unicodes)
+
+    def has_codepoint(self, char: int) -> bool:
+        """Return whether this font contains a glyph for ``char``."""
+        return char in self.codepoints
+
+    def description(self) -> str:
+        """Empty description — no metadata available for standalone fonts."""
+        return ""
+
+    def tags(self) -> Dict[str, float]:
+        """Empty tags — no metadata available for standalone fonts."""
+        return {}
+
+    def classification(self) -> str:
+        """Coarse style classification used for bucketed training metrics."""
+        return "UNKNOWN"
+
+    def sample_axis_positions(self, splits: int = 5) -> List[List[float]]:
+        """Sample variable-axis user-space coordinates.
+
+        If the font is not variable, returns ``[[]]``. Otherwise this returns
+        a list containing the default ``[]`` plus a Cartesian-product grid of up
+        to the first five fvar axes, each split into ``splits`` values.
+        """
+        if "fvar" not in self.hb_face.table_tags:
+            return [[]]
+        # Slow path
+        ttfont = TTFont(self.path)
+        axes = {
+            ix: np.linspace(axis.minValue, axis.maxValue, splits).tolist()
+            for ix, axis in enumerate(ttfont["fvar"].axes[0:5])
+            # Use first five axes to stop things like Amstelvar dominating the dataset
+        }
+        # Take Cartesian product, convert each set of coordinates to list in order
+        tags = axes.keys()
+        instances = itertools.product(*axes.values())
+        instances = [[instance[ix] for ix in tags] for instance in instances]
+        return [[]] + instances
+
+    def has_non_empty_codepoint(self, codepoint: int) -> bool:
+        """Return True if the font has a non-empty outline for codepoint."""
+        if not self.has_codepoint(codepoint):
+            return False
+        if not hasattr(self, "hb_face"):
+            # Test doubles and lightweight mocks may not expose HarfBuzz handles.
+            return True
+        hb_font = hb.Font(self.hb_face)  # type: ignore
+        gid = hb_font.get_nominal_glyph(codepoint)
+        return self.has_non_empty_gid(gid)
+
+    def has_non_empty_gid(self, gid: int) -> bool:
+        """Return True if the font has a non-empty outline for the given gid."""
+        if not hasattr(self, "hb_face"):
+            # Test doubles and lightweight mocks may not expose HarfBuzz handles.
+            return True
+        hb_font = hb.Font(self.hb_face)  # type: ignore
+        extents = hb_font.get_glyph_extents(gid)
+        if extents is None:
+            return False
+        return not all(x == 0 for x in extents)