hand-writter/AGENTS.md

AGENTS.md — hand-writter

Руководство для агентов (и людей), работающих с репозиторием hand-writter.

О проекте

handwrite.py — CLI-утилита на Python, превращающая текст в картинку рукописного текста с поддержкой кириллицы (полный русский алфавит, включая Ё, щ, ъ, э, ю, я). Единственная зависимость — Pillow (PIL).

Ключевые особенности:

• Автоподбор рукописного шрифта из системы с проверкой покрытия кириллицы (без сторонних библиотек — только Pillow: рендер символа и сравнение с notdef-глифом). Приоритет: Marker Felt, затем Snell Roundhand, затем любой шрифт с кириллицей.
• Синие чернила по умолчанию (#1a3b8c) с имитацией письма ручкой: коррелированный дрейф «давления» (тёмные/светлые участки), полупрозрачные чернила, неровный край мазка.
• Выравнивание глифов — стандартное PIL text((x, line_top)) (через маску в _stamp_glyph). Все обычные буквы (а, о, н, б, й) стоят на одной baseline, буквы с нижними выносными (р, у, д, ц, щ) опускают хвосты ниже — строчная «р» ниже обычных букв, точки/запятые внизу, спецсимволы ($ ~ % @ …) — по дизайну шрифта. Не вводите ручное смещение «по ink_bottom» — оно ломает б/й/н и обрезает глифы.
• Перенос по словам + сохранение \n из входного файла/STDIN.
• Тетрадная «линейная» бумага (--lined), цвета чернил/бумаги/линий, синие палитры и градиенты оттенков.

Структура

hand-writter/
├── handwrite.py          # основной скрипт (точка входа)
├── requirements.txt      # Pillow>=9.0.0
├── run.sh                # обёртка-команды: init/upd/render/...
├── README.md             # пользовательская документация
├── AGENTS.md             # этот файл
└── examples/             # примеры вывода
    ├── blue_pen.png
    ├── blue_pen_lined.png
    ├── multiline.png
    └── sample_input.txt

Окружение и запуск

• Python 3.8+ (в run.sh предполагается python3.13; если его нет — отредактируйте PY в run.sh или используйте системный python3).
• Активация venv: source .venv/bin/activate (через ./run.sh init).
• Прямой запуск: python3 handwrite.py "Текст" -o out.png.
• Команды-обёртки: ./run.sh render "Текст" и др. (см. ниже).

Правила работы с кодом

1. Не добавляйте новых зависимостей без крайней необходимости. Скрипт намеренно зависит только от Pillow — это упрощает установку в изолированных средах. Любая новая зависимость должна быть обоснована и добавлена в requirements.txt.

2. Сохраняйте поддержку кириллицы. Любое изменение рендера/шрифтов должно проверяться на полном русском алфавите (см. CYRILLIC_TEST в handwrite.py). Не полагайтесь на «визуальную» проверку — шрифт может отрисовывать notdef для отсутствующих глифов; используйте _font_covers_cyrillic().

3. Выравнивание — стандартное PIL. В _stamp_glyph глиф рисуется маской с origin в канвасе и композируется так, чтобы совпадать с text((x, line_top)). НЕ прижимайте ink_bottom вручную к baseline и НЕ сдвигайте глифы по bbox — это ломает б/й (обрезает) и делает их «слишком низкими». Канвас берётся по абсолютным границам bbox (включая отрицательные bbox[0]/bbox[1] для Ё, р). Знаки препинания рисуются с jitter=0 (чёткие точки), но тем же выравниванием.

4. Сохраняйте переносы строк. wrap_text использует splitlines() — каждая строка входа становится отдельной строкой на картинке. Не «схлоптывайте» пустые строки без явного флага.

5. Не ломайте CLI-совместимость. Новые параметры добавляйте с значениями по умолчанию, не меняйте семантику существующих.

6. Внесение изменений: после правок проверяйте

   • python3 -c "import ast; ast.parse(open('handwrite.py').read())" — синтаксис;
   • запуск на кириллице с точками/запятыми и многострочным файлом;
   • что точки-знаки остаются в нижней зоне строки.

Команды (run.sh)

Команда	Описание
./run.sh init	Создать venv и установить зависимости
./run.sh upd	Обновить зависимости
./run.sh render "текст"	Рендер текста-аргумента → out/handwriting.png
./run.sh lined "текст"	Рендер на тетрадной бумаге
./run.sh big "текст"	Крупный шрифт (64pt) на тёплой бумаге
./run.sh calm "текст"	«Спокойный» почерк (jitter 0.3, seed 42)
./run.sh plain "текст"	Ровный текст (без дрожания/поворота строк)
./run.sh render-file file.txt	Рендер файла (с переносами строк)
./run.sh poetry file.txt	Многострочный файл → тетрадь, крупный шрифт → out/poetry.png
./run.sh render-stdin	Чтение из STDIN (echo "..." | ./run.sh render-stdin)
./run.sh list-fonts	Показать доступные рукописные шрифты с кириллицей
./run.sh examples	Перегенерировать примеры в examples/

Все команды рендера (render, lined, big, calm, plain, poetry, render-file, render-stdin) принимают доп. опции handwrite.py после --, например: ./run.sh render "Текст" -- --jitter 0.4 --seed 7 --lined.

Тестовые сценарии (обязательно прогонять при правках)

# кириллица с б/й/р, точками и спецсимволами (б/й на baseline, р ниже, точки внизу)
python3 handwrite.py "байты йогурт река. \$ ~ % @ # конец!" -o /tmp/t1.png

# многострочный файл (каждая строка файла → строка на картинке)
printf 'Строка 1.\nСтрока 2.\nСтрока 3.\n' > /tmp/m.txt
python3 handwrite.py -i /tmp/m.txt -o /tmp/t2.png --lined

# синий (по умолчанию) + тетрадь
python3 handwrite.py "Текст" --lined -o /tmp/t3.png

Чего не делать

• Не коммитьте .DS_Store, .venv/, временные *.png вне examples/.
• Не удаляйте examples/ — это демонстрация возможностей.
• Не «упрощайте» проверку глифов кириллицы до textbbox/ширины — это ненадёжно (узкие буквы, например «г», неотличимы от notdef по ширине).
• Цвет чернил по умолчанию — синий. Палитры/градиенты намеренно убраны (раньше были, но усложняли). Не возвращайте мульти-цвет без явной просьбы.