# Meme

**Repository Path**: al01/Meme

## Basic Information

- **Project Name**: Meme
- **Description**: 一些也许有用的表情包相关的小工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: SquareMaker
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python, Gradio, meme, tools, Webapp

## README

# ⬛ SquareMaker - 批量图片1:1正方形化工具

**SquareMaker** 是一个基于 Python 和 Gradio 构建的批量图片处理工具，专门用于将任意比例的非正方形图片批量调整为1:1正方形尺寸。支持智能背景填充和居中放置，确保图片内容不变形。
 
# Meme / SquareMaker

SquareMaker 是总项目「Meme」中的一个子模块（分支名称：`SquareMaker`），用于将任意比例图片批量转换为 1:1 正方形。提供简单的 Gradio 可视化界面与可编程的批处理 API，支持背景填充、透明背景、模糊背景与指定尺寸缩放等能力。

## 主要特性

- 批量正方形化：一次处理多张图片，输出统一的 1:1 尺寸
- 多种背景：纯色、透明、模糊背景，适配不同使用场景
- 两种模式：仅填充（pad）或缩放到指定尺寸（resize）
- 可控质量与格式：支持 `PNG`、`JPG`、`WEBP`，可设置质量（对 `JPG/WEBP` 生效）
- 并发处理：线程池并发，提升批量处理速度
- 打包下载：自动生成 `outputs/run_<timestamp>.zip`
- 自定义前缀：支持为输出文件名添加自定义前缀（如 `sq_`）

## 快速开始

```bash
# 安装依赖
pip install -r requirements.txt

# 启动可视化界面（Gradio）默认端口 8081
python main.py

# 指定端口（CLI）
python main.py --port 9000

# 或使用环境变量
# Windows PowerShell
$Env:MEME_PORT=9000; python main.py
# 或
$Env:PORT=9000; python main.py
```

启动后通过浏览器访问本地地址（控制台会显示链接）即可使用。界面包含图片选择、背景填充开关、模式选择、背景类型与颜色、输出格式与质量、并发等参数配置。

## 安装与运行脚本（推荐）

- 安装依赖（初始化环境）
  - Windows：在项目根目录执行 `setup.bat`
  - macOS/Linux：在项目根目录执行 `./setup.sh`
  - 作用：创建并激活本地 `.venv`，升级 `pip`，安装 `requirements.txt` 依赖

- 启动应用（仅运行）
  - Windows：执行 `run.bat`，可选端口参数，如 `run.bat 9000`
  - macOS/Linux：执行 `./run.sh`，可选端口参数，如 `./run.sh 9000`
  - 作用：激活 `.venv` 并运行 `main.py`；如未传入端口参数，使用默认端口或环境变量 `MEME_PORT`/`PORT`/`GRADIO_SERVER_PORT`

## 图形界面参数说明

- `背景填充（bg_fill）`：开启后在方形画布上填充背景并居中放置原图
- `模式（mode）`：
  - 仅填充：不缩放原图，方形画布边长为原图长边或指定值
  - 缩放到指定尺寸：按长边缩放到目标边长，保持比例，居中放置
- `背景类型（bg_type）`：`纯色`、`模糊`、`透明`
- `背景颜色（bg_color）`：16 进制颜色（如 `#FFFFFF`），透明背景时忽略
- `输出格式（out_fmt）`：`PNG`、`JPG`、`WEBP`
- `质量（quality）`：50–100，仅对 `JPG/WEBP` 生效
- `并发（concurrency）`：1–16，默认 4
- `文件名前缀（prefix）`：可选，为输出文件名添加统一前缀；无需手动输入下划线，系统会在非空前缀后自动追加 `_`

处理完成后，界面会展示预览，并提供打包下载链接（zip）。

## 作为库使用（批处理 API）

```python
from processing.batch_runner import process_images

paths = ["path/to/img1.jpg", "path/to/img2.png"]
results = process_images(
    paths=paths,
    mode="pad",              # 或 "resize"
    bg_fill=True,             # 开/关背景填充
    bg_type="solid",         # "solid" | "transparent" | "blur"
    bg_color=(255, 255, 255, 255),  # RGBA 或 RGB
    target_size=1024,         # 指定输出边长；为 None 时按输入长边
    out_dir="outputs/run_custom",
    out_fmt="PNG",           # PNG/JPG/WEBP
    quality=90,               # 仅对 JPG/WEBP 生效
    concurrency=4,
    prefix="sq",             # 可选，文件名前缀；无需包含下划线
)
print(results)  # 输出文件路径列表
```

核心图像操作位于 `processing/image_ops.py`：

- `to_square_pad(img, size)`：不缩放，居中贴到方形画布
- `to_square_resize(img, size)`：按长边缩放到目标边长后居中贴到方形画布
- `to_square_crop_center(img)`：中心裁剪为正方形
- `make_solid_bg(size, color)` / `make_transparent_bg(size)` / `make_blur_bg(img, size)`：生成不同类型背景

## 输出与命名规则

- 输出目录：`outputs/run_<timestamp>/`
- 打包路径：`outputs/run_<timestamp>.zip`
- 文件名：`<前缀><原名>_square.<ext>` 或 `<前缀><原名>_size<边长>.<ext>`（当指定了 `target_size`；前缀可为空）

## 配置项（默认值见 `config.py`）

- `DEFAULT_BACKGROUND_FILL = True`
- `DEFAULT_BACKGROUND_TYPE = "solid"`
- `DEFAULT_BACKGROUND_COLOR = "#FFFFFF"`
- `DEFAULT_OUTPUT_FORMAT = "PNG"`
- `DEFAULT_OUTPUT_QUALITY = 90`
- `DEFAULT_CONCURRENCY = 4`
- `DEFAULT_FILENAME_PREFIX = ""`
- `DEFAULT_PORT = 8081`

## 项目结构

- `main.py`：启动 Gradio 界面
- `ui/gradio_app.py`：界面布局与交互逻辑
- `processing/`：批量处理与图像操作
  - `batch_runner.py`：并发批处理、保存与命名
  - `image_ops.py`：方形化、裁剪、背景生成等函数
- `tests/test_image_ops.py`：核心图像函数的单元测试
- `config.py`：默认配置项
- `outputs/`：处理结果输出目录与打包文件
- `requirements.txt`：项目依赖

## 测试

```bash
python -m pytest -q
```

## 注意事项

- 透明背景建议使用 `PNG` 输出；`JPG` 不支持透明
- 质量参数仅对 `JPG/WEBP` 生效，`PNG` 无损
- 大图与高并发会增加内存占用，按需调整 `concurrency`
- 关闭背景填充（`bg_fill=False`）时，内部采用中心裁剪为正方形，再按输出格式选择透明或纯色方形画布居中贴合

—— 本模块隶属于总项目「Meme」，分支（子模块）名称为「SquareMaker」。