katsuji 0.1.1__tar.gz

katsuji-0.1.1/.github/workflows/check.yml

@@ -0,0 +1,13 @@
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv sync --locked
+      - run: make check

katsuji-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,19 @@
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv sync --locked
+      - name: Publish
+        run: make publish
+        env:
+          HATCH_INDEX_AUTH: ${{ secrets.HATCH_INDEX_AUTH }}
+          HATCH_INDEX_USER: ${{ secrets.HATCH_INDEX_USER }}
+          VERSION: ${{ github.ref_name }}

katsuji-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+dist/

katsuji-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel Peralta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

katsuji-0.1.1/Makefile

@@ -0,0 +1,19 @@
+.PHONY: check tests format publish
+
+check:
+	uv run ruff format --check .
+	uv run ruff check .
+	uv run mypy
+	uv run pytest -q --cov=katsuji --cov-report=term-missing --cov-fail-under=95
+
+# The pre-push hook runs `make tests`.
+tests: check
+
+format:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+publish: check
+	rm -rf dist
+	uv build
+	HATCH_INDEX_USER=$(HATCH_INDEX_USER) HATCH_INDEX_AUTH=$(HATCH_INDEX_AUTH) uvx hatch publish

katsuji-0.1.1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: katsuji
+Version: v0.1.1
+Summary: Variable-width font tooling for a816 SNES projects: fonts, kerning, tiles, static text
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: a816>=1.1.0a44
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10
+Description-Content-Type: text/markdown
+
+# katsuji
+
+活字, movable type. Variable-width font tooling for [a816](https://github.com/manz/a816) SNES projects.
+
+## Build a project's fonts and strings
+
+`katsuji.toml` at the project root:
+
+```toml
+[fonts.dialog]
+png = "fonts/vwf.png"
+cell = [8, 16]
+table = "text/ff4fr.tbl"
+output = "assets/font.dat"
+widths = { "0xFF" = 3, "0xA0" = -1 }     # negative trims, positive sets
+kerning-candidates = ["Ta", "Te", "va"]  # tested for collision kerning
+kerning = { "tt" = 2 }                   # hand-tuned: pixels tighter
+
+[fonts.menu]
+png = "fonts/8x8vwf.png"
+cell = [8, 8]
+table = "text/ff4_menus.tbl"
+output = "assets/menu_font.dat"
+constants = "assets/menu_font.i"         # a816 constants describing the file
+
+[strings.items]
+font = "menu"
+file = "text/items.txt"                  # one string per line (or `texts = [...]`)
+bpp = 2
+ink = 3
+paper = 1
+blob = "assets/items_vwf.dat"            # tiles, no string across a bank edge
+index = "assets/items_vwf.idx"           # 4 bytes per string: offset lo16, bank, tiles
+```
+
+```
+katsuji build            # writes every output, paths relative to katsuji.toml
+katsuji banner "Tarot" --table text/ff4fr.tbl --font assets/font.dat
+```
+
+## Library
+
+- `Atlas`: a font drawn as a PNG grid of cells.
+- `find_kerning` / `pair_kerning`: pair kerning by collision (one diagonal touch, never side by side).
+- `VwfFont`: the font file the a816 VWF runtime reads (1bpp rows + width per glyph, kerning pairs, height).
+- `render` / `measure`: text set at build time exactly as the runtime sets it.
+- `Wrapper`: word wrap by pixel width, the game's control codes as data.
+- `Window` / `WindowBuilder`: fill text windows; a game's script rules drive them.
+- `encode_tiles` / `colourize`: SNES 2bpp / 4bpp planar tiles.
+- `text_tiles` / `pack_runs`: static strings pre-rendered to a bank-safe blob.
+
+Grown from ff4's tooling: its five fonts rebuild byte for byte, its wrapping and dialog goldens pass.
+
+```
+uv sync
+make check
+```

katsuji-0.1.1/README.md

@@ -0,0 +1,57 @@
+# katsuji
+
+活字, movable type. Variable-width font tooling for [a816](https://github.com/manz/a816) SNES projects.
+
+## Build a project's fonts and strings
+
+`katsuji.toml` at the project root:
+
+```toml
+[fonts.dialog]
+png = "fonts/vwf.png"
+cell = [8, 16]
+table = "text/ff4fr.tbl"
+output = "assets/font.dat"
+widths = { "0xFF" = 3, "0xA0" = -1 }     # negative trims, positive sets
+kerning-candidates = ["Ta", "Te", "va"]  # tested for collision kerning
+kerning = { "tt" = 2 }                   # hand-tuned: pixels tighter
+
+[fonts.menu]
+png = "fonts/8x8vwf.png"
+cell = [8, 8]
+table = "text/ff4_menus.tbl"
+output = "assets/menu_font.dat"
+constants = "assets/menu_font.i"         # a816 constants describing the file
+
+[strings.items]
+font = "menu"
+file = "text/items.txt"                  # one string per line (or `texts = [...]`)
+bpp = 2
+ink = 3
+paper = 1
+blob = "assets/items_vwf.dat"            # tiles, no string across a bank edge
+index = "assets/items_vwf.idx"           # 4 bytes per string: offset lo16, bank, tiles
+```
+
+```
+katsuji build            # writes every output, paths relative to katsuji.toml
+katsuji banner "Tarot" --table text/ff4fr.tbl --font assets/font.dat
+```
+
+## Library
+
+- `Atlas`: a font drawn as a PNG grid of cells.
+- `find_kerning` / `pair_kerning`: pair kerning by collision (one diagonal touch, never side by side).
+- `VwfFont`: the font file the a816 VWF runtime reads (1bpp rows + width per glyph, kerning pairs, height).
+- `render` / `measure`: text set at build time exactly as the runtime sets it.
+- `Wrapper`: word wrap by pixel width, the game's control codes as data.
+- `Window` / `WindowBuilder`: fill text windows; a game's script rules drive them.
+- `encode_tiles` / `colourize`: SNES 2bpp / 4bpp planar tiles.
+- `text_tiles` / `pack_runs`: static strings pre-rendered to a bank-safe blob.
+
+Grown from ff4's tooling: its five fonts rebuild byte for byte, its wrapping and dialog goldens pass.
+
+```
+uv sync
+make check
+```

katsuji-0.1.1/hatch_version.py

@@ -0,0 +1,15 @@
+"""Build-time version source for hatchling.
+
+Reads the `VERSION` env var when set (the release pipeline injects the tag),
+otherwise falls back to a dev placeholder so local builds work without it.
+"""
+
+from __future__ import annotations
+
+import os
+
+DEV_VERSION = "0.0.0.dev0"
+
+
+def get_version() -> str:
+    return os.environ.get("VERSION") or DEV_VERSION

katsuji-0.1.1/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "katsuji"
+dynamic = ["version"]
+description = "Variable-width font tooling for a816 SNES projects: fonts, kerning, tiles, static text"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+dependencies = [
+    "numpy>=1.26",
+    "pillow>=10",
+    "a816>=1.1.0a44",
+]
+
+[project.scripts]
+katsuji = "katsuji.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.16",
+    "mypy>=1.13",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "code"
+path = "hatch_version.py"
+expression = "get_version()"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katsuji"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+# ff4's dialog goldens, copied verbatim: their expected strings are long lines.
+"tests/test_dialog_ff4.py" = ["E501"]
+
+[tool.mypy]
+strict = true
+packages = ["katsuji", "tests"]
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = ["script", "script.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

katsuji-0.1.1/src/katsuji/__init__.py

@@ -0,0 +1,23 @@
+"""Variable-width font tooling for a816 SNES projects."""
+
+from katsuji.atlas import Atlas
+from katsuji.formats import VwfFont
+from katsuji.kerning import find_kerning, pair_kerning
+from katsuji.render import measure, render
+from katsuji.tiles import TileOrder, colourize, encode_tiles
+from katsuji.wrap import Controls, Fixed, Wrapper
+
+__all__ = [
+    "Atlas",
+    "Controls",
+    "Fixed",
+    "TileOrder",
+    "VwfFont",
+    "Wrapper",
+    "colourize",
+    "encode_tiles",
+    "find_kerning",
+    "measure",
+    "pair_kerning",
+    "render",
+]

katsuji-0.1.1/src/katsuji/atlas.py

@@ -0,0 +1,90 @@
+"""A font drawn as a PNG grid of fixed-size cells, one glyph per cell."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+from PIL import Image
+
+Pixels = NDArray[np.uint8]
+"""A 2D array of 0 (paper) and 1 (ink), indexed `[row, column]`."""
+
+
+@dataclass(frozen=True)
+class Atlas:
+    """Glyph cells laid out left to right, top to bottom.
+
+    `grid` atlases separate cells with a 1-pixel line (and start with one), so
+    a cell sits at `index * (size + 1) + 1`. Any non-zero pixel is ink.
+    """
+
+    pixels: Pixels
+    cell_width: int = 8
+    cell_height: int = 16
+    grid: bool = False
+
+    @classmethod
+    def open(cls, path: str | Path, cell_width: int = 8, cell_height: int = 16, grid: bool = False) -> Atlas:
+        image = np.array(Image.open(path))
+        if image.ndim == 3:
+            image = image[..., 0]
+        return cls((image != 0).astype(np.uint8), cell_width, cell_height, grid)
+
+    @property
+    def columns(self) -> int:
+        """Cells per row of the atlas."""
+        stride = self.cell_width + 1 if self.grid else self.cell_width
+        return int(self.pixels.shape[1] - (1 if self.grid else 0)) // stride
+
+    @property
+    def rows(self) -> int:
+        stride = self.cell_height + 1 if self.grid else self.cell_height
+        return int(self.pixels.shape[0] - (1 if self.grid else 0)) // stride
+
+    def __len__(self) -> int:
+        return self.columns * self.rows
+
+    def glyph(self, index: int) -> Pixels:
+        """The cell of glyph `index`, `cell_height` x `cell_width`."""
+        row, column = divmod(index, self.columns)
+        if self.grid:
+            x = column * (self.cell_width + 1) + 1
+            y = row * (self.cell_height + 1) + 1
+        else:
+            x = column * self.cell_width
+            y = row * self.cell_height
+        return self.pixels[y : y + self.cell_height, x : x + self.cell_width]
+
+    def ink_width(self, index: int) -> int:
+        """Columns up to and including the rightmost ink pixel (0 for a blank cell)."""
+        return ink_width(self.glyph(index))
+
+    def without_grid(self) -> Pixels:
+        """The atlas with its grid lines removed: cells packed edge to edge."""
+        lines = [
+            np.concatenate([self.glyph(row * self.columns + column) for column in range(self.columns)], axis=1)
+            for row in range(self.rows)
+        ]
+        return np.concatenate(lines, axis=0)
+
+
+def ink_width(glyph: Pixels) -> int:
+    """Columns up to and including the rightmost ink pixel of `glyph`."""
+    columns = np.flatnonzero(glyph.any(axis=0))
+    return int(columns[-1]) + 1 if columns.size else 0
+
+
+def ink_rows(glyph: Pixels) -> tuple[int, int]:
+    """First and last rows holding ink; the whole height for a blank glyph."""
+    rows = np.flatnonzero(glyph.any(axis=1))
+    if not rows.size:
+        return 0, glyph.shape[0] - 1
+    return int(rows[0]), int(rows[-1])
+
+
+def save_png(pixels: Pixels, path: str | Path) -> None:
+    """Write 0/1 pixels as a black-on-white PNG."""
+    Image.fromarray(np.where(pixels != 0, 0, 255).astype(np.uint8)).save(path, format="PNG")

katsuji-0.1.1/src/katsuji/banner.py

@@ -0,0 +1,59 @@
+"""Banners: text set with katsuji fonts, shown in the terminal or saved as a PNG.
+
+A preview of what the runtime will draw, font switches included. Each run of
+text between font switches is set with its font and the runs are joined edge
+to edge, as ff4's banner did.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Sequence
+
+import numpy as np
+
+from katsuji.atlas import Pixels
+from katsuji.formats import VwfFont
+from katsuji.render import render
+from katsuji.wrap import Controls
+
+
+def runs(codes: bytes, controls: Controls) -> list[tuple[int, list[int]]]:
+    """`codes` split at font switches into `(font, glyph codes)`; fixed codes are skipped."""
+    out: list[tuple[int, list[int]]] = []
+    font = 0
+    current: list[int] = []
+    index = 0
+    while index < len(codes):
+        code = codes[index]
+        if code == controls.font_switch and index + 1 < len(codes):
+            if current:
+                out.append((font, current))
+                current = []
+            index += 1
+            font = codes[index]
+        elif code in controls.fixed:
+            index += controls.fixed[code].arguments
+        else:
+            current.append(code)
+        index += 1
+    if current:
+        out.append((font, current))
+    return out
+
+
+def banner(fonts: Sequence[VwfFont], codes: bytes, controls: Controls, kerning: bool = True) -> Pixels:
+    """The pixels of `codes`, each run set with its font."""
+    pieces = []
+    for font_index, glyphs in runs(codes, controls):
+        font = fonts[font_index] if kerning else dataclasses.replace(fonts[font_index], kerning={})
+        pieces.append(render(font, glyphs))
+    if not pieces:
+        return np.zeros((0, 0), dtype=np.uint8)
+    height = max(piece.shape[0] for piece in pieces)
+    return np.concatenate([np.pad(piece, ((0, height - piece.shape[0]), (0, 0))) for piece in pieces], axis=1)
+
+
+def to_blocks(pixels: Pixels) -> str:
+    """Two full blocks per ink pixel, two spaces per paper pixel."""
+    return "\n".join("".join("██" if value else "  " for value in row) for row in pixels)

katsuji-0.1.1/src/katsuji/build.py

@@ -0,0 +1,97 @@
+"""Build everything a `katsuji.toml` describes: font files, string blobs, constants."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from script import Table
+
+from katsuji.atlas import Atlas
+from katsuji.config import Config, ConfigError, FontConfig, StringsConfig
+from katsuji.formats import VwfFont
+from katsuji.kerning import find_kerning
+from katsuji.strings import index_entry, pack_runs, text_tiles
+
+
+def build(config: Config) -> list[Path]:
+    """Write every output of `config`; returns the paths written."""
+    written: list[Path] = []
+    fonts = {name: _build_font(font, written) for name, font in config.fonts.items()}
+    for strings in config.strings.values():
+        _build_strings(strings, fonts[strings.font], config.fonts[strings.font], written)
+    return written
+
+
+def _table(path: Path | None, where: str) -> Table:
+    if path is None:
+        raise ConfigError(f"[{where}] needs a `table` to encode its text")
+    return Table(str(path))
+
+
+def _pair(table: Table, text: str, where: str) -> tuple[int, int]:
+    codes = table.to_bytes(text)
+    if len(codes) != 2:
+        raise ConfigError(f"[{where}] kerning pair {text!r} encodes to {len(codes)} codes, not 2")
+    return codes[0], codes[1]
+
+
+def _build_font(config: FontConfig, written: list[Path]) -> VwfFont:
+    where = f"fonts.{config.name}"
+    atlas = Atlas.open(config.png, config.cell_width, config.cell_height, config.grid)
+    kerning: dict[tuple[int, int], int] = {}
+    if config.kerning_candidates or config.kerning:
+        table = _table(config.table, where)
+        candidates = (table.to_bytes(text) for text in config.kerning_candidates)
+        pairs = [(codes[0], codes[1]) for codes in candidates if len(codes) == 2]
+        kerning = find_kerning(atlas, pairs, config.default_kerning)
+        for text, pixels in config.kerning.items():
+            kerning[_pair(table, text, where)] = pixels
+    font = VwfFont.from_atlas(atlas, config.widths, kerning)
+    _write(config.output, font.encode(), written)
+    if config.constants:
+        prefix = config.name.upper()
+        _write_constants(
+            config.constants,
+            {
+                f"{prefix}_FONT_HEIGHT": font.height,
+                f"{prefix}_FONT_GLYPH_SIZE": font.height + 1,
+                f"{prefix}_FONT_KERNING_PAIRS": len(font.kerning),
+            },
+            written,
+        )
+    return font
+
+
+def _build_strings(config: StringsConfig, font: VwfFont, font_config: FontConfig, written: list[Path]) -> None:
+    where = f"strings.{config.name}"
+    table = _table(config.table or font_config.table, where)
+    runs: list[bytes] = []
+    counts: list[int] = []
+    for text in config.texts:
+        tiles, columns = text_tiles(
+            font, table.to_bytes(text), config.bpp, config.ink, config.paper, config.gap, config.max_tiles
+        )
+        runs.append(tiles)
+        counts.append(columns)
+    blob, offsets = pack_runs(runs, config.bank_size)
+    _write(config.blob, blob, written)
+    _write(config.index, b"".join(index_entry(o, n) for o, n in zip(offsets, counts, strict=True)), written)
+    if config.constants:
+        prefix = config.name.upper()
+        _write_constants(
+            config.constants,
+            {f"{prefix}_COUNT": len(config.texts), f"{prefix}_MAX_TILES": max(counts, default=0)},
+            written,
+        )
+
+
+def _write(path: Path, data: bytes, written: list[Path]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    written.append(path)
+
+
+def _write_constants(path: Path, constants: dict[str, int], written: list[Path]) -> None:
+    lines = ['"""Generated by katsuji build; do not edit."""', ""]
+    lines += [f"{name} = {value:#x}" if value > 9 else f"{name} = {value}" for name, value in constants.items()]
+    _write(path, ("\n".join(lines) + "\n").encode(), written)

katsuji-0.1.1/src/katsuji/cli.py

@@ -0,0 +1,67 @@
+"""`katsuji` command line."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from script import Table
+
+from katsuji.atlas import save_png
+from katsuji.banner import banner, to_blocks
+from katsuji.build import build
+from katsuji.config import ConfigError, load
+from katsuji.formats import VwfFont
+from katsuji.wrap import Controls
+
+
+def _code(value: str) -> int:
+    return int(value, 0)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="katsuji", description="Variable-width font tooling for a816 projects.")
+    commands = parser.add_subparsers(dest="command", required=True)
+    show = commands.add_parser("banner", help="show text set with katsuji fonts")
+    show.add_argument("text")
+    show.add_argument("--table", required=True, type=Path, help="text table (.tbl) encoding TEXT")
+    show.add_argument(
+        "--font", required=True, action="append", type=Path, dest="fonts", help="font file; repeat for font switches"
+    )
+    show.add_argument("--font-switch", type=_code, help="code switching font, followed by the font index (ff4: 0xFE)")
+    show.add_argument("--no-kerning", action="store_true", help="ignore the fonts' kerning pairs")
+    show.add_argument("--png", type=Path, help="save the banner as a PNG instead of printing it")
+    make = commands.add_parser("build", help="build the fonts and strings a katsuji.toml describes")
+    make.add_argument("config", nargs="?", type=Path, default=Path("katsuji.toml"))
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "build":
+        return _build(args.config)
+    fonts = [VwfFont.decode(path.read_bytes()) for path in args.fonts]
+    codes = Table(str(args.table)).to_bytes(args.text)
+    pixels = banner(fonts, codes, Controls(font_switch=args.font_switch), kerning=not args.no_kerning)
+    if args.png:
+        save_png(pixels, args.png)
+    else:
+        print(to_blocks(pixels))
+        print(f"width: {pixels.shape[1]}", file=sys.stderr)
+    return 0
+
+
+def _build(path: Path) -> int:
+    try:
+        for written in build(load(path)):
+            print(written)
+    except ConfigError as error:
+        print(f"katsuji: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())