mono-pixel 0.1.0__tar.gz

mono_pixel-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.3
+Name: mono-pixel
+Version: 0.1.0
+Summary: a tool that converts your text and fonts into pixel img.
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# mono-pixel
+
+![mono-pixel logo](docs/mono-pixel-logo.png)
+
+mono-pixel is a small Python library and CLI for rendering high-contrast, "pixel"-style text
+images suitable for LED-like displays, e-paper, or retro-styled graphics. It provides utilities
+for loading fonts, calculating text layout, rendering text to an image, and exporting images
+with strict binarization.
+
+Features
+- Render text into fixed-size pixel canvases
+- Automatic font sizing to fit text into a target box
+- Strict binarization and monochrome export
+- Small, dependency-light implementation (Pillow + Typer)
+
+Quick start
+1. See the detailed usage guide in the `docs` directory: [Usage](docs/usage.md)
+2. From source you can run the CLI with:
+
+```
+uv run mono-pixel --help
+```
+
+License
+This project is available under the terms described in the `LICENSE.txt` file.
+

mono_pixel-0.1.0/README.md

@@ -0,0 +1,26 @@
+# mono-pixel
+
+![mono-pixel logo](docs/mono-pixel-logo.png)
+
+mono-pixel is a small Python library and CLI for rendering high-contrast, "pixel"-style text
+images suitable for LED-like displays, e-paper, or retro-styled graphics. It provides utilities
+for loading fonts, calculating text layout, rendering text to an image, and exporting images
+with strict binarization.
+
+Features
+- Render text into fixed-size pixel canvases
+- Automatic font sizing to fit text into a target box
+- Strict binarization and monochrome export
+- Small, dependency-light implementation (Pillow + Typer)
+
+Quick start
+1. See the detailed usage guide in the `docs` directory: [Usage](docs/usage.md)
+2. From source you can run the CLI with:
+
+```
+uv run mono-pixel --help
+```
+
+License
+This project is available under the terms described in the `LICENSE.txt` file.
+

mono_pixel-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "mono-pixel"
+version = "0.1.0"
+description = "a tool that converts your text and fonts into pixel img."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["pillow>=10.0.0", "typer>=0.12.0"]
+
+[project.scripts]
+mono-pixel = "mono_pixel.cli:cli"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.4.0",
+    "ruff>=0.14.5",
+    "ty>=0.0.25",
+    "pytest>=8.0.0",
+    "uv-build>=0.11.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12"]
+build-backend = "uv_build"
+
+## UV
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
+default = true
+
+## Type checker (ty)
+[tool.ty]
+
+[tool.ty.rules]
+all = "error"
+
+[tool.ty.analysis]
+respect-type-ignore-comments = true
+
+[tool.ty.terminal]
+output-format = "concise"
+
+
+## Linter and formatter (ruff)
+
+[tool.ruff]
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG001", # unused arguments in functions
+]
+
+[tool.ruff.format]
+docstring-code-format = true

mono_pixel-0.1.0/src/mono_pixel/__init__.py

@@ -0,0 +1,127 @@
+"""High-fidelity pixel text rendering engine."""
+
+from __future__ import annotations
+
+from PIL import Image
+
+from .exporter import save_image, strict_binarization
+from .font_loader import (
+    FontError,
+    FontNotFoundError,
+    InvalidFontError,
+    calculate_text_size,
+    load_font,
+    validate_font_file,
+)
+from .renderer import (
+    HorizontalAlign,
+    VerticalAlign,
+    calculate_auto_font_size,
+    create_canvas,
+    render_pixel_text,
+    render_text,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Exceptions
+    "FontError",
+    "FontNotFoundError",
+    "InvalidFontError",
+    # Enums
+    "HorizontalAlign",
+    "VerticalAlign",
+    # Font loader
+    "validate_font_file",
+    "load_font",
+    "calculate_text_size",
+    # Renderer
+    "create_canvas",
+    "calculate_auto_font_size",
+    "render_pixel_text",
+    "render_text",
+    # Exporter
+    "strict_binarization",
+    "save_image",
+    # High-level API
+    "generate_pixel_text",
+]
+
+
+def generate_pixel_text(
+    text: str,
+    font_path: str,
+    image_size: tuple[int, int],
+    font_size: int | None = None,
+    auto_fit: bool = False,
+    padding: int | tuple[int, int, int, int] = 16,
+    align: HorizontalAlign | str = HorizontalAlign.CENTER,
+    valign: VerticalAlign | str = VerticalAlign.MIDDLE,
+    bg_color: str | tuple[int, int, int] = "white",
+    fg_color: str | tuple[int, int, int] = "black",
+    output_path: str | None = None,
+    strict_binarize: bool = True,
+    binarization_threshold: int = 127,
+    dpi: tuple[int, int] = (72, 72),
+) -> Image.Image:
+    """Generate a pixel-style text image with a single high-level API.
+
+    Args:
+        text: Text to render.
+        font_path: Path to TTF/OTF font file.
+        image_size: Output image size as (width, height).
+        font_size: Manual font size in pixels; mutually exclusive with auto_fit.
+        auto_fit: Whether to auto-fit font size.
+        padding: Padding value or (top, right, bottom, left).
+        align: Horizontal alignment.
+        valign: Vertical alignment.
+        bg_color: Background color.
+        fg_color: Foreground (text) color.
+        output_path: Output PNG path. If None, image is not saved.
+        strict_binarize: Whether to strictly binarize output.
+        binarization_threshold: Binarization threshold.
+        dpi: Output DPI.
+
+    Returns:
+        Rendered PIL image object.
+
+    Raises:
+        ValueError: Invalid argument combination.
+        FontNotFoundError: Font file does not exist.
+        InvalidFontError: Font file is invalid.
+    """
+    if not text:
+        raise ValueError("Text cannot be empty")
+
+    if (font_size is None and not auto_fit) or (font_size is not None and auto_fit):
+        raise ValueError("Specify exactly one of font_size or auto_fit")
+
+    image = render_text(
+        text=text,
+        font_path=font_path,
+        image_size=image_size,
+        font_size=font_size,
+        auto_fit=auto_fit,
+        padding=padding,
+        align=align,
+        valign=valign,
+        bg_color=bg_color,
+        fg_color=fg_color,
+    )
+
+    if output_path is not None:
+        save_image(
+            image=image,
+            output_path=output_path,
+            strict_binarize=strict_binarize,
+            bg_color=bg_color,
+            fg_color=fg_color,
+            binarization_threshold=binarization_threshold,
+            dpi=dpi,
+            optimize=True,
+        )
+
+    return image