# Perfect Pixel Local Studio

> 基于 `theamusing/perfectPixel` 扩展的本地像素图生成、背景处理与图集切片工具。

![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

## 项目截图

### Local Studio 首页

![Perfect Pixel Local Studio Screenshot](./assets/local-studio-screenshot.png)

这个界面就是当前仓库主打的本地工作流：上传图片、设置输出尺寸、一键生成、导出并切片，以及下载最终结果都可以在浏览器里完成。

### 核心算法流程示意

![Perfect Pixel Process](./assets/process.png)

## 项目简介

这个仓库在上游 `perfectPixel` 自动网格检测与像素对齐算法的基础上，扩展成了一个更适合日常使用的本地工作台：

- 在浏览器里本地上传图片并生成像素图
- 支持手动尺寸和自动识别尺寸两种模式
- 支持保留背景色，或把背景转成透明
- 支持先识别有效内容范围，再压缩到目标尺寸
- 支持把整张结果图继续送入“导出并切片”流程
- 支持自动识别图集中的小图，统一导出并打包 ZIP

如果你要做头像像素化、小图素材整理、游戏贴图切片，或者把 AI 生成的像素风图片整理成真正可用的像素资源，这个仓库更偏向“开箱即用的本地工具”。

## 主要功能

### 1. 像素图生成

- 自动识别像素网格
- 手动指定输出尺寸，如 `16x16`、`32x32`、`64x64`
- 可选择 `center` / `majority` / `median` 采样方式
- 可调细化强度 `refine_intensity`

### 2. 背景与有效范围处理

- 可保留原背景色输出
- 可将背景转为透明
- 可先识别有效图片范围，再压缩到目标尺寸

### 3. 导出并切片

- 支持将生成结果继续自动切片
- 支持原图切片和像素结果切片两种导出模式
- 支持统一切片尺寸
- 支持自动识别图集中的小图并导出 ZIP

### 4. 本地网页工作流

- Quick Flow 快速生成区
- 完整参数区
- 图集切片区
- 透明背景处理工作区

## 快速开始

### 安装依赖

```bash
pip install -e ".[web]"
```

### 启动本地网站

```bash
python local_web.py
```

然后打开：

```text
http://127.0.0.1:5000
```

## 推荐使用流程

### 普通图片转像素图

1. 上传图片
2. 选择输出模式
3. 如果需要，开启“先识别有效范围，再压缩到目标尺寸”
4. 选择是否把背景转透明
5. 点击生成
6. 下载 PNG，或继续送去切片

### 图集自动切片

1. 上传整张图集
2. 选择“自动识别”
3. 选择导出类型：
   - 原图切片
   - 像素结果
4. 如果是像素结果，设置单张输出尺寸
5. 导出 ZIP

## Python 核心算法调用

除了本地网页工作流，这个仓库仍然保留了上游核心算法的 Python 调用方式。

```python
import cv2
from perfect_pixel import get_perfect_pixel

bgr = cv2.imread("images/avatar.png", cv2.IMREAD_COLOR)
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)

width, height, output = get_perfect_pixel(rgb)
```

如果你只想把它当成算法库来集成，也可以直接使用 `src/perfect_pixel/` 下的实现。

## 项目结构

```text
src/perfect_pixel/          核心像素算法
web/templates/              本地网页模板
web/static/                 前端脚本与样式
tools/texture_atlas_slicer.py  图集切片与导出逻辑
local_web.py                本地 Flask 入口
images/                     示例图片
assets/                     README 资源图
```

## 与上游项目的关系

这个仓库不是从零开始重写的原创算法仓库，而是基于上游项目做的功能扩展版本。

### 上游项目信息

- 上游项目：[`theamusing/perfectPixel`](https://github.com/theamusing/perfectPixel)
- 原作者：`theAmusing`
- 作者邮箱：`amusingyyy@gmail.com`
- 上游项目主页：[`https://github.com/theamusing/perfectPixel`](https://github.com/theamusing/perfectPixel)
- 上游演示页：[`https://github.com/theamusing/perfectPixel_webdemo`](https://github.com/theamusing/perfectPixel_webdemo)

### 本仓库在上游基础上的扩展

- 增加本地 Web Studio
- 增加快速生成区
- 增加背景透明与有效范围压缩工作流
- 增加图集自动识别切片与 ZIP 导出
- 增加透明背景处理工作区

## 致谢

感谢上游作者 `theAmusing` 开源 `perfectPixel` 项目，并提供核心算法思路与实现基础。  
如果你也觉得这个项目有帮助，建议同时关注原项目：

- [`theamusing/perfectPixel`](https://github.com/theamusing/perfectPixel)

## License

本仓库遵循 `MIT License` 发布，并保留对上游项目的署名与许可说明。

详见：

- [`LICENSE`](./LICENSE)
