QR-ASCII-QR

一个强大且灵活的二维码生成工具，能够创建独特的"字符二维码"——在传统二维码的基础上叠加自定义字符，既保持完整的扫描功能，又具有独特的视觉效果。

✨ 主要特色

🎯 多种渲染模式

• 纯黑块模式 (solid): 传统的黑白二维码
• 纯文字模式 (text): 仅使用字符构成的二维码（定位点保持黑块）
• 组合模式 (combined): 黑色背景上叠加字符，视觉效果最佳

🔧 强大的自定义功能

• 自定义字符集: 支持数字、字母、汉字等任意字符组合
• 多种输出格式: PNG 位图和 SVG 矢量图
• 字体自定义: 支持 TrueType 字体文件
• Logo 嵌入: 可在二维码中心添加 Logo（PNG 模式）
• 高纠错级别: 默认 H 级（30% 容错），确保可扫描性

🚀 批量生成

• 三合一模式: 一次命令生成三种不同风格的二维码
• 智能定位点处理: 自动识别并优化定位点区域的显示效果

📦 安装

环境要求

• Python 3.10 或更高版本
• 支持 Windows、macOS、Linux

快速安装

# 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 文件生成库

🎮 快速开始

基础使用

# 只生成字符二维码
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

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

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 文件格式不支持