pixelkid

Превращает любое фото в пиксель-арт одной функцией — и в цветную PDF-раскраску по номерам. Сделано для мастер-классов по Python (возраст 11–17).

from pixelkid import pixelate

pixelate("photo.jpg", pixel_size=12, colors=16, save_as="art.png")

Установка

pip install pixelkid

Нужен Python 3.8+. Вместе с pixelkid автоматически установятся Pillow, NumPy и reportlab.

Функция pixelate

pixelate(image, pixel_size=12, colors=32, save_as=None, upscale=True)

Возвращает картинку Pillow (PIL.Image.Image), поэтому её можно показать (.show()), сохранить (.save(...)) или обработать дальше.

Ошибки. Если pixel_size меньше 2 или colors вне диапазона 2–256, функция выбросит ValueError.

Функция coloring_pdf

coloring_pdf(image, save_as="coloring.pdf", cells=32, colors=12, title="Пиксель-раскраска")

Делает цветной PDF «раскраска по номерам» (A4) в стиле МАСТЕРСАМ.

• Страница 1 — раскраска: клетки с номерами, палитра «номер · цвет · RGB», строка для имени.
• Страница 2 — ответ: как выглядит готовая картинка.

Возвращает палитру — список цветов (r, g, b). Цвет с номером 1 — первый в списке (самый частый на картинке).

Примеры

from pixelkid import pixelate, coloring_pdf

# 1. Просто показать результат
pixelate("cat.jpg").show()

# 2. Очень крупные пиксели и всего 4 цвета
pixelate("cat.jpg", pixel_size=30, colors=4, save_as="cat_8bit.png")

# 3. Пять версий одного фото
for size in (4, 8, 16, 24, 32):
    pixelate("cat.jpg", pixel_size=size, save_as=f"cat_{size}.png")

# 4. Раскраска по номерам для печати
coloring_pdf("cat.jpg", save_as="cat_coloring.pdf", cells=24, colors=8)

# 5. Маленькая «сетка» для своих игр и раскрасок
grid = pixelate("cat.jpg", pixel_size=16, upscale=False)
print(grid.size)   # например, (48, 48): можно перебрать каждую клеточку

Как это работает

1. Уменьшаем фото до «рабочей» копии: на каждую будущую клетку приходится до 6 × 6 точек.
2. Подбираем палитру из colors цветов методом k-means в цветовом пространстве Lab — в нём расстояние между цветами похоже на то, как их различает глаз. Начинаем с самых непохожих цветов, поэтому в палитре нет почти одинаковых оттенков.
3. Голосуем: каждая клетка получает цвет, которого больше всего среди её точек, — границы чёткие, без «размытой каши». Редкие цвета (ствол, глаза, мелкие детали) получают небольшой бонус, чтобы тонкие линии не пропадали.
4. Увеличиваем обратно методом NEAREST — он просто копирует цвет и не размывает границы.

Результат всегда одинаковый для одной и той же картинки, и в нём ровно colors цветов (если на фото их хватает).

На слайдах мастер-класса показан простой вариант из трёх шагов (resize → quantize → NEAREST) — его легко объяснить. Библиотека делает то же, только умнее.

Версии

• 0.3.0 — новый подбор цветов: k-means в Lab + голосование в клетках. Картинки сочнее, цвета палитры различимы, меньше одиночных клеток, тонкие линии сохраняются.
• 0.2.0 — coloring_pdf(): цветная PDF-раскраска по номерам.
• 0.1.0 — pixelate().

Разработка

pip install -e .[dev]    # или: pip install -e . pytest
pytest
python -m build          # собрать пакет в папку dist/

Лицензия

MIT. Шрифт Inter в папке fonts — SIL Open Font License 1.1 (fonts/OFL.txt).