v0.3.0 — Automatic text wrapping, overflow protection, and a full CLI manual

What's new

Text now adapts itself instead of being silently clipped, mixed CJK/Latin lines no longer collapse into a row of boxes, and the project finally has a reference manual.

Automatic line wrapping

Subtitle, footnote (-d) and eyebrow (-e) lines wrap to the text area when they are too wide, so long copy no longer runs off the canvas and gets cut.

• CJK characters and full-width punctuation break per character, so Chinese wraps without spaces.
• Latin text breaks on spaces; a single word wider than the text area (long URL, hash) is hard-split by character as a last resort.
• Wrapping happens inside each line you pass: -s repeated still means separate paragraphs.
• On by default. --no-wrap (CLI) or "layout": {"wrap": false} (JSONC) restores the old single-line behaviour.

Overflow protection

When the wrapped block is still taller than the available height, the subtitle and footnote font sizes step down proportionally, re-wrapping as they go, with a floor of 9px. Only if it still does not fit does pixellogo print a warning and continue:

pixellogo: warning: content is 810px tall but only 656px is available; font size is already at 9px, the rest will be clipped

The exit code stays 0, so batch runs are not interrupted. Measured ceilings on a clean canvas (title 3–4 characters, subtitle only):

Canvas	Lines that still fit
poster	~30
square	~20
card	~16
slide	~13
banner	~8

--badge is a solid box, so it is not wrapped; it shrinks its font size instead when it would exceed the content width.

Missing glyphs no longer take the whole line down

The bundled ArkPixel-zh-hans.ttf covers 18,648 of the 20,902 basic CJK ideographs (89.2%), and a few common characters are genuinely absent (「即」U+5373, 「然」U+7136, 「餐」U+9910). The old font picker gave up on the entire line when no single font covered it and fell back to the Latin font, which turned every CJK character on that line into a tofu box.

Now the line keeps the font that covers the most characters, and the characters that no font can draw are named on stderr:

pixellogo: warning: font ArkPixel-zh-hans.ttf has no glyph for 即; those characters will render as boxes

Both the warning and the font choice are also reported by --dry-run, so you can check before rendering. Pass --font-title / --font-sub / --font-body with any pixel TTF to cover a missing glyph.

Documentation

• docs/architecture.md — annotated three-level file tree, layer-by-layer module responsibilities, render data flow, and the constraints the architecture imposes (in Chinese).
• docs/cli-guide.md — a full command-line manual: guided quick start, every flag, JSONC configs and batch mode, scripting and exit codes, plus a dedicated chapter on limits (characters per line, line ceilings, glyph coverage) and a troubleshooting table (in Chinese).

Both are linked from the table of contents and the new "Documentation" section of the English and Chinese READMEs.

Packaging fix

v0.2.0 wheels accidentally shipped a retired font (ArkPixel12pxProportional.ttf), because setuptools packaged from a stale build/lib snapshot. Release builds now start from a clean build/, so the wheel contains exactly the four fonts listed in the docs.

Upgrade notes

• Output changes only where text used to be clipped. All 40 gallery samples produce byte-identical geometry; no images were regenerated.
• Wrapping is on by default: if you depend on a single overflowing line, add --no-wrap.
• layout.wrap is a new config key; the JSON Schema has been updated to match.
• "uppercase": "false" (a string) is now correctly treated as off instead of on.

Install

pipx install git+https://github.com/sogeisetsu/pixel-logo-toolkit.git
# or
pip install git+https://github.com/sogeisetsu/pixel-logo-toolkit.git

Or grab an asset below: pip install pixellogo-0.3.0-py3-none-any.whl, or unpack the portable zip and run pixellogo.cmd / ./pixellogo.sh with no install at all. Python 3.9+, Pillow for rendering.

Tests

160 unit tests pass on Python 3.12 locally, and CI covers 3.9 / 3.10 / 3.11 / 3.12.

Full changelog: v0.2.0...v0.3.0

v0.2.0 — First release: bilingual CLI, English-first docs

pixellogo 0.2.0 is the first tagged release: a command line tool that turns a title, a few subtitle lines and a footnote into real 8-bit / retro-terminal pixel art — PNG and SVG from the same geometry, five canvases, ten palettes, and mixed Latin / Chinese / Japanese / Korean text without missing glyphs.

Highlights

• Real pixels, not a filter. Text is rasterized into a binary mask and merged per row into integer-coordinate rectangles. Every edge stays a whole block at any zoom: no anti-aliasing, no gradients, no feathering.
• One geometry, two formats. PNG and SVG are produced from the same Scene, so they match pixel for pixel. The SVG is self-contained and needs no font files.
• Five canvases. poster 1080×1440, card 1440×1080, banner 1280×640, slide 1920×1080, square 1080×1080, each with its own layout strategy.
• Ten palettes. From retro terminal to paper journal; every preset passes a WCAG contrast check (--list presets prints the ratio).
• CJK-ready. A Chinese pixel font ships in the box, so mixed Latin/Chinese lines keep one stroke weight; Traditional Chinese, Japanese and Korean download on demand.
• Bilingual CLI. Help page, option tables, font status, warnings and errors in English or Simplified Chinese — automatic from the terminal locale, or forced with --ui-lang.
• No browser dependency. Pure Python and Pillow rasterization; runs on servers and in CI.
• Reusable configuration. JSONC files with comments and trailing commas, dot-path overrides, batch mode, and a --dry-run snapshot of the merged result.

New in 0.2.0

Bilingual command line

All terminal output now exists in English and Simplified Chinese: the help page, --list modes|presets|fonts, fonts status, warnings, and every error message (including argparse's own argument errors).

• Automatic: LC_ALL → LC_MESSAGES → LANG → LANGUAGE → Windows UI language → English. C / POSIX count as English.
• Explicit: --ui-lang auto|en|zh for a single run, or PIXELLOGO_UI_LANG as a persistent default. Precedence is flag > environment > locale.
• --ui-lang (CLI wording) is independent of --lang (glyph variant used for the image): --ui-lang en --lang ja gives an English interface with Japanese glyphs.

English-first documentation

• README.md is now English and is the default entry point.
• README.zh-CN.md holds the Chinese version; the two are cross-linked.
• pyproject.toml metadata and the GitHub repository description are in English.

Packaging and robustness

• Built distribution: wheel, source distribution, and a portable zip (see the asset table below).
• Missing Pillow no longer breaks the query commands: if Pillow is absent, --version, --help, --list and fonts still work, and rendering exits with code 2 plus an instruction to install it.

Install

From this release:

pipx install pixellogo-0.2.0-py3-none-any.whl
# or
pip install pixellogo-0.2.0-py3-none-any.whl

From source at this tag:

pipx install git+https://github.com/sogeisetsu/pixel-logo-toolkit.git@v0.2.0

Release assets

File	What it is
pixellogo-0.2.0-py3-none-any.whl	Wheel. pip install this for a normal install; it adds the pixellogo command and bundles the five fonts, license texts and JSON schema.
pixellogo-0.2.0.tar.gz	Source distribution (sdist), for packagers or pip install from source.
pixellogo-0.2.0-portable.zip	No installation needed. Unpack and run pixellogo.cmd (Windows) or ./pixellogo.sh (macOS / Linux). Contains the package, fonts, licenses, both READMEs and RUNNING.txt.

GitHub also generates "Source code (zip)" and "Source code (tar.gz)" archives for every release. Those are raw repository snapshots and contain no built package — use the assets above if you just want to install and run the tool.

Quick start

# One cover image, both formats, into out/
pixellogo -t "REA" -s "REVERSE ENGINEER" -d "One CLI for agents"

# A 16:9 slide cover in the cyber palette with a grid texture
pixellogo -t "PIXEL" -m slide -p cyber --bg-pattern grid

# Inspect what is available
pixellogo --list modes
pixellogo --list presets
pixellogo fonts

Running pixellogo with no arguments prints the help page; --help, -h and pixellogo help are equivalent.

Command line at a glance

Flag	Effect
-t, --title	Main title (required)
-s, --subtitle / -d, --desc	Subtitle and footnote lines, one flag per line
-m, --mode	poster / card / banner / slide / square
-p, --preset	One of the ten palettes
--bg --fg --primary --accent --shadow-color	Single-color overrides
-f, --format	png / svg / both (default both)
-o, --out	Output file or directory
-c, --config / --set	JSONC config and dot-path overrides
--ui-lang	CLI output language: auto / en / zh
--lang	Glyph variant: zh-hans / zh-hant / ja / ko
--json / --dry-run / --open	Machine-readable output / merged config / open the result

Exit codes: 0 success, 2 invalid arguments or configuration.

Python API

from pixellogo import render, make_image, make_scene, to_svg_text

paths = render(title="REA", mode="banner", preset="cyber", format="png", out="out/")
image = make_image(title="REA", mode="square", scale=1)
scene = make_scene(title="REA", mode="poster")
svg = to_svg_text(title="REA", mode="slide")

Keyword names match the JSONC config keys exactly, so anything valid in a config file is valid here.

Requirements

• Python 3.9 or newer
• Pillow 9.0 or newer (only runtime dependency)

Testing

• 143 unit and integration tests (PYTHONPATH=src python -m unittest discover -s tests).
• CI runs the suite on Python 3.9, 3.10, 3.11 and 3.12, plus a job that renders real images on Linux.

Known limitations

• The background must be a solid color; image backgrounds are excluded by design. Use --bg-pattern for graph paper, dots or scanlines.
• docs/gallery.md, docs/design.md and docs/style-spec.md are currently Chinese only.
• The GitHub social preview image has to be uploaded manually (Settings → Social preview); a banner render at 1280×640 is the right size.

Changelog

Work merged up to this release, in order: repository restructure, CJK font support, render core (mask → rectangles), canvas modes and layout, JSONC configuration, output formats, CI tests, typography, semantic mode names, ten presets, help page, Python API, background patterns, multilingual fonts, documentation, command gallery, bilingual CLI, and the Pillow-optional startup fix.

Full Changelog: https://github.com/sogeisetsu/pixel-logo-toolkit/commits/v0.2.0