Metadata-Version: 2.4
Name: glyphloss
Version: 0.1.0
Summary: Composite loss function for neural glyph-image reconstruction.
Author-email: Simon Cozens <simon@simon-cozens.org>
Project-URL: Homepage, https://github.com/simoncozens/glyphloss
Project-URL: Repository, https://github.com/simoncozens/glyphloss
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.11.0
Provides-Extra: train
Requires-Dist: Pillow; extra == "train"
Requires-Dist: fonttools; extra == "train"
Requires-Dist: uharfbuzz; extra == "train"
Requires-Dist: tensorboard; extra == "train"
Requires-Dist: freetype-py; extra == "train"
Requires-Dist: numpy; extra == "train"
Requires-Dist: tqdm; extra == "train"
Dynamic: license-file

# Glyph Loss

A Torch loss function and module designed specifically for training neural networks to reconstruct glyph images rendered from font files.

This attempts to improve upon the standard L1/L2 pixel-wise loss by adding loss components specific to rendered glyph images. In particular:

* *Grey weighting*: The interesting part of glyph images is the edge of the glyph contours, not the background or the foreground. At the resolutions used in ML training (typically 128 pixels or less), the glyph edges are anti-aliased subpixels, and appear as grey pixels. The loss function weights these grey pixels considerably more heavily than the black/white pixels making up the bulk of the image.

* *Gradient loss*: The gradient loss component penalizes differences in the image gradients, which helps to preserve the sharpness of the glyph edges. This is similar to Sobel loss, but it decomposes the magnitude and direction of the gradients, and penalizes differences in both. This attempts to preserve fine details around terminals and the distinctions between rounded and sharp corners.

* *Frequency loss*: The frequency loss component penalizes differences in the frequency domain, which helps to preserve the spectral characteristics of the glyphs. This also attempts to prevent deliberately roughened edges in display fonts or sharp corners from becoming smoothed or blurred by the network.

## Installation

```bash
# Core loss (requires only PyTorch):
pip install glyphloss

# With training harness (adds font rendering & TensorBoard deps):
pip install "glyphloss[train]"
```

Requires Python ≥ 3.8.

## Using the loss function

Available as an `nn.Module` class and as a pre-instantiated default singleton:

```python
from glyphloss import GlyphReconstructionLoss, glyph_reconstruction_loss
```

The `nn.Module` version has the following parameters:

* `weight_epsilon` : floor weight for pure black/white pixels (keeps some gradient signal even outside the grey zone)
* `lambda_pixel` : weight for pixel loss term
* `lambda_mag` : weight for gradient magnitude term
* `lambda_dir` : weight for gradient direction term (cosine loss)
* `lambda_spectral` : weight for spectral loss term
* `patch_size` : spatial size of patches for spectral loss
* `patch_stride` : stride for patch extraction
* `dir_eps` : numerical floor in cosine denominator

## Testing/development

The Python package also includes a training harness with configurable loss functions and TensorBoard logging. To use it, install the package with the `[train]` extra dependencies, put some fonts into the `data/` directory, and run:

```bash
python -m glyphloss.train --data-dir data --epochs 50
```

## License

This projected is licensed under the Apache License 2.0. See the LICENSE file for details.
