210 lines
6.0 KiB
Markdown
210 lines
6.0 KiB
Markdown
# QR-ASCII-QR
|
||
|
||
一个强大且灵活的二维码生成工具，能够创建独特的"字符二维码"——在传统二维码的基础上叠加自定义字符，既保持完整的扫描功能，又具有独特的视觉效果。
|
||
|
||
[](https://python.org)
|
||
[](LICENSE)
|
||
|
||
## ✨ 主要特色
|
||
|
||
### 🎯 多种渲染模式
|
||
- **纯黑块模式 (solid)**: 传统的黑白二维码
|
||
- **纯文字模式 (text)**: 仅使用字符构成的二维码（定位点保持黑块）
|
||
- **组合模式 (combined)**: 黑色背景上叠加字符，视觉效果最佳
|
||
|
||
### 🔧 强大的自定义功能
|
||
- **自定义字符集**: 支持数字、字母、汉字等任意字符组合
|
||
- **多种输出格式**: PNG 位图和 SVG 矢量图
|
||
- **字体自定义**: 支持 TrueType 字体文件
|
||
- **Logo 嵌入**: 可在二维码中心添加 Logo（PNG 模式）
|
||
- **高纠错级别**: 默认 H 级（30% 容错），确保可扫描性
|
||
|
||
### 🚀 批量生成
|
||
- **三合一模式**: 一次命令生成三种不同风格的二维码
|
||
- **智能定位点处理**: 自动识别并优化定位点区域的显示效果
|
||
|
||
## 📦 安装
|
||
|
||
### 环境要求
|
||
- Python 3.7 或更高版本
|
||
- 支持 Windows、macOS、Linux
|
||
|
||
### 快速安装
|
||
```bash
|
||
# 2. 创建虚拟环境（推荐）
|
||
python -m venv venv
|
||
|
||
# 3. 激活虚拟环境
|
||
# Windows:
|
||
venv\Scripts\activate
|
||
# macOS/Linux:
|
||
source venv/bin/activate
|
||
|
||
# 4. 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 依赖包说明
|
||
- `qrcode>=7.4.2`: 二维码生成核心库
|
||
- `pillow>=10.0.0`: 图像处理库，用于 PNG 渲染
|
||
- `svgwrite>=1.4.3`: SVG 文件生成库
|
||
|
||
## 🎮 快速开始
|
||
|
||
### 基础使用
|
||
```bash
|
||
# 只生成字符二维码
|
||
python main.py -d "网站URL" -o "文件名" -c "hash值" --text-only
|
||
|
||
# 生成三种二维码
|
||
python main.py -d "网站URL" -o "文件名" -c "hash值" --three-types
|
||
|
||
|
||
### 高级使用
|
||
```bash
|
||
# 使用自定义字体和 Logo
|
||
python main.py -d "Branded QR" -o branded.png \
|
||
--font ./SIMHEI.TTF \
|
||
--logo ./logo.png \
|
||
-s 30
|
||
|
||
# 指定纠错级别
|
||
python main.py -d "High Error Correction" -o high_ec.png -e H
|
||
|
||
# 大尺寸二维码
|
||
python main.py -d "Large QR" -o large.png -s 50
|
||
```
|
||
|
||
## 📖 详细参数说明
|
||
|
||
### 命令行参数
|
||
|
||
| 参数 | 长格式 | 必需 | 默认值 | 说明 |
|
||
|------|--------|------|--------|------|
|
||
| `-d` | `--data` | ✅ | - | 要编码的数据（文本、URL、任意字符串） |
|
||
| `-o` | `--out` | ✅ | - | 输出文件路径，支持 .png 和 .svg 扩展名 |
|
||
| `-s` | `--cell-size` | ❌ | 20 | 单元格像素大小（仅 PNG 有效） |
|
||
| `-c` | `--charset` | ❌ | `0-9A-Z` | 用作填充的字符集合 |
|
||
| `-e` | `--ec-level` | ❌ | H | 纠错级别：L(7%) / M(15%) / Q(25%) / H(30%) |
|
||
| | `--font` | ❌ | 自动检测 | TrueType 字体文件路径（仅 PNG 有效） |
|
||
| | `--logo` | ❌ | - | Logo 图片路径（仅 PNG 有效） |
|
||
| | `--svg` | ❌ | false | 强制输出 SVG 格式 |
|
||
| | `--three-types` | ❌ | false | 生成三种渲染模式的二维码 |
|
||
|
||
|
||
|
||
## 🔧 API 使用
|
||
|
||
### 基本 API
|
||
```python
|
||
from qr_ascii_qr import generate_qr_image, generate_qr_svg
|
||
|
||
# 生成 PNG 图片
|
||
img = generate_qr_image(
|
||
data="Hello API",
|
||
cell_size=25,
|
||
charset="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
|
||
ec_level="H"
|
||
)
|
||
img.show() # 显示图片
|
||
img.save("api_example.png") # 保存图片
|
||
|
||
# 生成 SVG 文件
|
||
svg_path = generate_qr_svg(
|
||
data="SVG Example",
|
||
out_path="api_example.svg",
|
||
cell_size=20,
|
||
charset="★☆♦♣♠♥♪♫"
|
||
)
|
||
```
|
||
|
||
### 高级 API
|
||
```python
|
||
from qr_ascii_qr import generate_matrix, render_to_png, render_to_svg
|
||
|
||
# 生成矩阵
|
||
matrix = generate_matrix("Advanced Usage", ec_level="H")
|
||
|
||
# 渲染为 PNG（支持多种模式）
|
||
render_to_png(
|
||
matrix=matrix,
|
||
out_path="advanced.png",
|
||
cell_size=30,
|
||
charset="0123456789ABCDEF",
|
||
font_path="./fonts/custom.ttf",
|
||
logo_path="./logo.png",
|
||
render_mode="combined" # 'solid', 'text', 'combined'
|
||
)
|
||
|
||
# 渲染为 SVG
|
||
render_to_svg(
|
||
matrix=matrix,
|
||
out_path="advanced.svg",
|
||
cell_size=25,
|
||
charset="♠♣♥♦",
|
||
font_family="Arial"
|
||
)
|
||
```
|
||
|
||
## 🎨 渲染模式详解
|
||
|
||
### 1. 纯黑块模式 (solid)
|
||
传统的黑白二维码，与标准二维码完全一致。
|
||
|
||
### 2. 纯文字模式 (text)
|
||
- 定位点区域：保持黑色方块（确保扫描识别）
|
||
- 数据区域：使用指定字符替代黑色方块
|
||
- 背景：白色
|
||
- 适用场景：需要清晰可读字符的场合
|
||
|
||
### 3. 组合模式 (combined)
|
||
- 保持原有黑色方块
|
||
- 在黑色背景上叠加字符
|
||
- 字符颜色：黑色（在实际应用中可以调整为其他颜色）
|
||
- 视觉效果：最佳的艺术效果与扫描性能平衡
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
qr_ascii_qr/
|
||
├── qr_ascii_qr/ # 核心包
|
||
│ ├── __init__.py # 包导出接口
|
||
│ └── generator.py # 二维码生成核心逻辑
|
||
├── main.py # 命令行入口
|
||
├── requirements.txt # 项目依赖
|
||
├── SIMHEI.TTF # 默认中文字体
|
||
├── logo.png # 示例 Logo
|
||
├── README.md # 项目文档
|
||
└── venv/ # 虚拟环境（安装后生成）
|
||
```
|
||
|
||
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 常见问题
|
||
|
||
**Q: 生成的二维码无法扫描？**
|
||
A: 检查以下几点：
|
||
- 确保使用足够高的纠错级别（推荐 H 级）
|
||
- 验证单元格大小是否足够大（建议 ≥ 20 像素）
|
||
- 在组合模式下，确保字符颜色与背景有足够对比度
|
||
|
||
**Q: 字符显示不正确或乱码？**
|
||
A:
|
||
- 确保使用支持目标字符的字体文件
|
||
- 检查字符集编码是否正确（推荐使用 UTF-8）
|
||
- 验证字体文件路径是否正确
|
||
|
||
**Q: 程序运行缓慢？**
|
||
A:
|
||
- 减小单元格大小以降低图片分辨率
|
||
- 简化字符集，减少复杂字符的使用
|
||
- 考虑使用 SVG 格式替代大尺寸 PNG
|
||
|
||
### 错误代码
|
||
- `FileNotFoundError`: 字体文件或 Logo 文件路径错误
|
||
- `UnicodeError`: 字符集包含不支持的字符
|
||
- `PIL.UnidentifiedImageError`: Logo 文件格式不支持
|
||
|