Metadata-Version: 2.4
Name: py-easy-image
Version: 1.0.1
Summary: Python 图像处理工具包，提供简单易用的图像处理功能，包括 HTML 转图像和图片文本绘制等操作。
Home-page: https://gitee.com/guolei19850528/py_easy_image
Author: guolei
Author-email: 174000902@qq.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: imgkit
Requires-Dist: Pillow
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# py_easy_image

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

## 功能特性

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

## 安装

### 使用 pip 安装

```bash
pip install py_easy_image
```

### 从源码安装

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

## 依赖

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

## 快速开始

### HTML 转图像

```python
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}")
```

### 图片文本绘制

```python
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 转图像高级选项

```python
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}")
```

### 图片文本绘制高级选项

```python
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 测试文件
```

## 测试

运行测试：

```bash
# 运行 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](https://pypi.org/project/imgkit/) - HTML 转图像库
- [Pillow](https://pillow.readthedocs.io/) - Python 图像处理库
- [wkhtmltoimage](https://wkhtmltopdf.org/) - HTML 转图像工具
