py_easy_image

Python 图像处理工具包，提供简单易用的图像处理功能，包括 HTML 转图像和图片文本绘制等操作。

功能特性

• HTML 转图像：支持将 HTML 字符串、URL 和文件转换为图像
• 图片文本绘制：支持在图片上绘制多个文本，自定义位置、字体、颜色等
• 目录自动创建：自动创建输出目录，避免路径错误
• 错误处理：提供简单的错误处理机制
• 类型提示：完整的类型注解，提供良好的 IDE 支持

安装

使用 pip 安装

pip install py_easy_image

从源码安装

git clone https://gitee.com/guolei19850528/py_easy_image.git
cd py_easy_image
pip install -e .

依赖

• imgkit
• Pillow
• wkhtmltoimage (imgkit 依赖，需要单独安装)

快速开始

HTML 转图像

from py_easy_image.imgkit import from_string, from_url, from_file

# 从 HTML 字符串转换
output_path = from_string(
    string="<h1>Hello, World!</h1>",
    output_path="./output/from_string.png"
)
print(f"转换结果: {output_path}")

# 从 URL 转换
output_path = from_url(
    url="https://example.com",
    output_path="./output/from_url.png"
)
print(f"转换结果: {output_path}")

# 从 HTML 文件转换
output_path = from_file(
    file="./input/sample.html",
    output_path="./output/from_file.png"
)
print(f"转换结果: {output_path}")

图片文本绘制

from py_easy_image.pillow import draw_texts
from PIL import ImageFont

# 准备字体
font = ImageFont.truetype("./runtime/input/draw_texts/SourceHanSansSC-Normal-2.otf", 36)

# 绘制文本
output_path = draw_texts(
    image_file_path="./runtime/input/draw_texts/horizontal.png",
    image_file_save_kwargs={
        "fp": "./runtime/output/drawn_image.png"
    },
    texts=[
        {
            "xy": (100, 100),
            "text": "Hello, World!",
            "font": font,
            "fill": "#000000"
        },
        {
            "xy": (100, 150),
            "text": "Python 图像处理",
            "font": font,
            "fill": "#ff0000"
        }
    ]
)
print(f"绘制结果: {output_path}")

API 文档

imgkit 模块

函数

from_string(**kwargs)

将 HTML 字符串转换为图像

• 参数:
  • string: HTML 字符串内容（必需）
  • output_path: 输出图像文件路径（可选）
  • css: CSS 样式字符串或文件路径（可选）
  • options: 配置选项字典，如格式、质量等（可选）
• 返回:
  • str or None: 成功时返回输出图像路径，失败时返回 None

from_url(**kwargs)

将网页 URL 转换为图像

• 参数:
  • url: 网页 URL 地址（必需）
  • output_path: 输出图像文件路径（可选）
  • css: CSS 样式字符串或文件路径（可选）
  • options: 配置选项字典，如格式、质量等（可选）
• 返回:
  • str or None: 成功时返回输出图像路径，失败时返回 None

from_file(**kwargs)

将 HTML 文件转换为图像

• 参数:
  • file: HTML 文件路径（必需）
  • output_path: 输出图像文件路径（可选）
  • css: CSS 样式字符串或文件路径（可选）
  • options: 配置选项字典，如格式、质量等（可选）
• 返回:
  • str or None: 成功时返回输出图像路径，失败时返回 None

pillow 模块

函数

draw_texts(image_file_path="", image_file_save_kwargs=dict(), texts=[])

在图片上绘制多个文本，并保存结果图片

• 参数:
  • image_file_path: 原始图片文件路径（必需）
  • image_file_save_kwargs: 图片保存参数，至少应包含'fp'键指定保存路径
  • texts: 要绘制的文本列表，每个元素是一个字典，包含 ImageDraw.text() 方法所需的参数
• 返回:
  • str: 保存的图片文件路径

高级用法

HTML 转图像高级选项

from py_easy_image.imgkit import from_string

# 自定义选项
options = {
    'format': 'png',
    'quality': 90,
    'width': 1024,
    'height': 768
}

# 转换 HTML 字符串
output_path = from_string(
    string="<h1>Hello, World!</h1>",
    output_path="./output/custom_options.png",
    options=options
)
print(f"转换结果: {output_path}")

图片文本绘制高级选项

from py_easy_image.pillow import draw_texts
from PIL import ImageFont

# 准备不同字体和颜色
font1 = ImageFont.truetype("./runtime/input/draw_texts/SourceHanSansSC-Normal-2.otf", 36)
font2 = ImageFont.truetype("./runtime/input/draw_texts/SourceHanSansSC-Normal-2.otf", 24)

# 绘制多个文本
output_path = draw_texts(
    image_file_path="./runtime/input/draw_texts/horizontal.png",
    image_file_save_kwargs={
        "fp": "./runtime/output/advanced_drawn.png",
        "quality": 95
    },
    texts=[
        {
            "xy": (100, 100),
            "text": "标题文本",
            "font": font1,
            "fill": "#000000"
        },
        {
            "xy": (100, 150),
            "text": "副标题文本",
            "font": font2,
            "fill": "#666666"
        },
        {
            "xy": (100, 200),
            "text": "普通文本",
            "font": font2,
            "fill": "#999999"
        }
    ]
)
print(f"绘制结果: {output_path}")

项目结构

py_easy_image/
├── py_easy_image/              # 主包目录
│   ├── __init__.py            # 包初始化文件
│   ├── imgkit.py              # HTML 转图像模块
│   └── pillow.py              # 图片文本绘制模块
├── runtime/                   # 运行时目录
│   ├── input/                 # 输入文件目录
│   │   └── draw_texts/        # 文本绘制相关资源
│   └── output/                # 输出文件目录
├── README.md                  # 项目文档
├── setup.py                   # 安装配置
├── requirements.txt           # 依赖列表
├── LICENSE                    # 许可证文件
├── deploy.sh                  # 部署脚本
├── .gitignore                 # Git 忽略文件
├── test_imgkit.py             # imgkit 测试文件
└── test_pillow.py             # pillow 测试文件

测试

运行测试：

# 运行 imgkit 测试
python test_imgkit.py

# 运行 pillow 测试
python test_pillow.py

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

• 作者：guolei
• 邮箱：174000902@qq.com
• 项目地址：https://gitee.com/guolei19850528/py_easy_image

致谢

• imgkit - HTML 转图像库
• Pillow - Python 图像处理库
• wkhtmltoimage - HTML 转图像工具