# QR-ASCII-QR

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

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](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 文件格式不支持