Metadata-Version: 2.4
Name: pixelkid
Version: 0.3.0
Summary: Превращает фото в пиксель-арт и PDF-раскраску по номерам. Сделано для мастер-классов по Python.
License: MIT
Keywords: pixel art,image,pillow,coloring,pdf,education,kids
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Multimedia :: Graphics
Classifier: Intended Audience :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.1
Requires-Dist: numpy>=1.21
Requires-Dist: reportlab<5,>=4.0; python_version < "3.10"
Requires-Dist: reportlab>=4.0; python_version >= "3.10"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# pixelkid

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

```python
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`

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

| Параметр | Что это | По умолчанию |
|---|---|---|
| `image` | Путь к файлу (`"photo.jpg"`) или картинка Pillow (`Image`) | — |
| `pixel_size` | Размер «большого пикселя» в обычных пикселях, от 2. Чем больше — тем крупнее квадраты | `12` |
| `colors` | Сколько цветов оставить, от 2 до 256 | `32` |
| `save_as` | Куда сохранить результат. Если не указать — файл не создаётся | `None` |
| `upscale` | `True` — картинка исходного размера с крупными пикселями. `False` — маленькая картинка, где 1 точка = 1 большой пиксель | `True` |

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

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

## Функция `coloring_pdf`

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

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

| Параметр | Что это | По умолчанию |
|---|---|---|
| `image` | Путь к файлу или картинка Pillow | — |
| `save_as` | Куда сохранить PDF | `"coloring.pdf"` |
| `cells` | Сколько клеток в ширину, от 4 до 60 | `32` |
| `colors` | Сколько цветов в палитре, от 2 до 24 | `12` |
| `title` | Заголовок на листе | `"Пиксель-раскраска"` |

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

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

## Примеры

```python
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` цветов (если на фото их хватает).

![Было и стало](https://raw.githubusercontent.com/Artem-Kornilov-pro/PixelArt/main/docs/img/algorithm.png)

> На слайдах мастер-класса показан простой вариант из трёх шагов (`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`).
