Metadata-Version: 2.4
Name: mcfonts
Version: 0.9.1.1
Summary: A library for exporting, manipulating, and working with Minecraft fonts
Keywords: minecraft,fonts,minecraft fonts,font exporting,minecraft opentype,minecraft font,minecraft export font,mc font,mc fonts,mcfonts
Author: WhoAteMyButter
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Text Processing :: Fonts
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
License-File: LICENSE.txt
Requires-Dist: fontTools >= 4.35.0
Requires-Dist: Pillow >= 9.3.0
Requires-Dist: tinyunicodeblock >= 1.1.0
Requires-Dist: bitarray >= 3.2.0
Requires-Dist: Sphinx >= 5.3.0 ; extra == "docs"
Requires-Dist: sphinx-autoapi >= 3.6.0 ; extra == "docs"
Requires-Dist: sphinxext-opengraph >= 0.8.2 ; extra == "docs"
Requires-Dist: sphinx-immaterial >= 0.11.8 ; extra == "docs"
Requires-Dist: astroid >= 3 ; extra == "docs"
Project-URL: Changelog, https://gitlab.com/whoatemybutter/mcfonts/-/blob/master/CHANGELOG.md
Project-URL: Documentation, https://mcfonts.readthedocs.io
Project-URL: Issues, https://gitlab.com/whoatemybutter/mcfonts/-/issues
Project-URL: Source, https://gitlab.com/whoatemybutter/mcfonts
Provides-Extra: docs

<p align="center">
<img src="assets/logo.png" width="480" alt="mcfonts"/>

<br>

<a href="https://github.com/astral-sh/ruff">
  <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
</a>

<a href="https://pylint.pycqa.org/en/latest/">
  <img src="https://img.shields.io/badge/pylint-9.62/10-ffbf48" alt="Pylint">
</a>

<a href="https://spdx.org/licenses/MIT.html">
  <img src="https://img.shields.io/badge/license-MIT--NOAI-a51931" alt="License">
</a>

<a href="https://pypi.org/project/mcfonts/">
  <img src="https://img.shields.io/pypi/v/mcfonts" alt="PyPI">
</a>

<a href="https://gitlab.com/whoatemybutter/mcfonts/-/pipelines?scope=all&page=1">
  <img src="https://img.shields.io/gitlab/pipeline-status/whoatemybutter%2Fmcfonts?branch=master" alt="Master pipeline status">
</a>

</p>

**mcfonts** is a modern, intuitive, and Pythonic library for working with *Minecraft: Java Edition* fonts.

It is designed to be easy to modify and extend new providers, glyphs, font loaders, and more.
mcfonts is ergonomic, fully typed, and documented.

```python
from pathlib import Path
from mcfonts.font import PrioritySortOrder, MinecraftFont
from mcfonts.glyph.bitmap import BitmapGlyph
from mcfonts.provider.import_all import import_all
from mcfonts.serde.minecraft import load_font_from_path
from PIL.Image import Image, merge

# Required to load providers, which are dynamic modules
import_all()

font: MinecraftFont = load_font_from_path(Path("assets/minecraft/font/default.json"))
print(font)  # -> MinecraftFont(3 providers => 1,205 characters)
print(len(font))  # Number of providers
for provider in font.get_providers(PrioritySortOrder.DESCENDING):
    for character, glyph in provider.items():
        # Providers can be treated like dictionaries
        print(glyph.show())
        if character > 0xFF:
            del provider[character]
        elif isinstance(glyph, BitmapGlyph):
            image: Image = glyph.get_image()
            r, g, b, a = image.split()
            # ALl BitmapGlyph images are in RGBA
            r = r.point(lambda i: i * 1.5)
            g = g.point(lambda i: i * 0.4)
            b = b.point(lambda i: i * 0.3)
            provider[character] = BitmapGlyph(merge("RGBA", (r, g, b, a)))
```

> ⚠️ mcfonts is in beta. The API may change drastically at any time; read the changelog carefully.

---

## Table of contents

- [Installation](#installation)
- [Features](#features)
- [Documentation](#documentation)
- [Changelog](#changelog)
- [License](#license)
- [External links](#external-links)

---

## Installation

`mcfonts` requires **Python 3.12+** and is available via PyPI:

```shell
python -m pip install mcfonts
```

For generating documentation:

```shell
python -m pip install mcfonts[docs]
```

### "externally-managed-environment"

This error occurs on some Linux distributions, such as Fedora 38 and Ubuntu 23.04.
It can be solved by either:

1. Using
   a [virtual environment (venv)](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment).
2. Using [pipx](https://github.com/pypa/pipx).
3. Bypassing it.

### Dependencies

* [fontTools](https://pypi.org/project/fontTools/): for exporting to OpenType
* [Pillow](https://pypi.org/project/Pillow/): for processing font textures
* [tinyunicodeblock](https://pypi.org/project/tinyunicodeblock/): for font coverage summaries

Optional dependencies under `docs`:

* [sphinx](https://pypi.org/project/sphinx/): for generating documentation
* [sphinx-autoapi](https://pypi.org/project/sphinx-autoapi/): for generating code documentation
* [sphinxext-opengraph](https://pypi.org/project/sphinxext-opengraph/): for meta tags
* [sphinx-immaterial](https://pypi.org/project/sphinx-immaterial/): for documentation theme

---

## Features

* Supports `bitmap`, `space`, `unihex`, `ttf`, `reference`, `legacy_unicode` providers
* Loads and saves fonts
* Creates fonts from scratch
* Lean memory usage
* Extensible, modular, and open (heavily interface-based)
* Fully documented and tested
* Pythonic API

---

### Loading

Currently, mcfonts only supports loading Minecraft: Java Edition fonts:

```python
from pathlib import Path
from mcfonts.font import MinecraftFont
from mcfonts.provider.import_all import import_all
from mcfonts.serde.minecraft import load_font_from_path

import_all()
font: MinecraftFont = load_font_from_path(Path("assets/minecraft/font/default.json"))
```

### Saving

mcfonts supports saving to any number of formats.
Currently, 4 are implemented:

* OpenType
* YAFF
* Unihex
* Minecraft

For example, for **OpenType**:

```python
from pathlib import Path
from fontTools.ttLib.ttFont import TTFont
from mcfonts.font import MinecraftFont
from mcfonts.serde.opentype import MetadataOptions
from mcfonts.serde.opentype import save_font as opentype_save_font

ttf: TTFont = opentype_save_font(
    MinecraftFont(),
    MetadataOptions(name="My cool font", include_credits=True, author="me", license="OFL")
)
```

Approximate performance:

|             |  OpenType |     Unihex |       YAFF |  Minecraft |
|-------------|----------:|-----------:|-----------:|-----------:|
| 1 chars     |    0.9 ms |   0.033 ms |   0.004 ms |   0.28  ms |
| 10 chars    |    1.0 ms |   0.075 ms |   0.06  ms |   0.457 ms |
| 100 chars   |   65.5 ms |   1.42  ms |   2.4   ms |   2.8   ms |
| 1000 chars  |  435.8 ms |  14.5   ms |  31.    ms |  34.    ms |
| 10000 chars | 1330.0 ms | 154.    ms | 260.    ms | 280.    ms |

*Complexity tends to be linear with respect to the number of providers. Each provider has its own complexity.*
*OpenType is the most expensive due to contour tracing.*

---

## Documentation

Documentation for `mcfonts` is available at https://mcfonts.readthedocs.io.

### Building locally

You can build the documentation yourself:

```shell
git clone https://gitlab.com/whoatemybutter/mcfonts.git
cd mcfonts
python -m pip install .
cd mcfonts/docs
sphinx-build . _build
```

> If you have make, you can also use the included Makefile as a shortcut: `make html`

The result index will be at `_build/html/index.html`.

---

## Changelog

The changelog is at [CHANGELOG.md](CHANGELOG.md).

---

## License

`mcfonts` is licensed under a **modified version** of the
[MIT license](https://spdx.org/licenses/MIT.html) known as **MIT NO-AI**.

In addition to the standard MIT terms, it also stipulates:
> In addition, the following restrictions apply:
> 1. The Software and any modifications made to it may not be used for the purpose of training or improving machine
     learning algorithms,
     including but not limited to artificial intelligence, natural language processing,
     or data mining. This condition applies to any derivatives, modifications, or updates based on the Software code.
     Any usage of the Software in an AI-training dataset is considered a breach of this License.
> 2. The Software may not be included in any dataset used for training or improving machine learning algorithms,
     including but not limited to artificial intelligence, natural language processing, or data mining.

Fonts created with this tool are under **no explicit license**; you can license them in any way you want.
This includes under a paid license.

## External links

* [Font - Minecraft Wiki](https://minecraft.wiki/w/Font)
* [OpenType specification](https://docs.microsoft.com/en-us/typography/opentype/spec/)
* [FontForge](https://fontforge.org/)

---

**mcfonts is not affiliated, endorsed, created, supported, or an official product by Mojang Studios in any way.**

