12 KiB
快速入门指南
本文档帮助你快速上手 PinMAP ↔ PinList 双向转换器。
环境要求
系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 7+ / Linux / macOS |
| Python | 3.6+（推荐 3.8+） |
| 内存 | ≥ 64MB（实际使用 < 20MB） |
| 磁盘 | ≥ 1MB |
依赖项
零第三方依赖 — 仅需 Python 标准库。
# 检查 Python 版本
python --version
# 输出示例: Python 3.12.3
GUI 支持（可选）
- Windows: tkinter 内置，开箱即用
- Linux: 需要
python3-tk包（sudo apt install python3-tk） - macOS: tkinter 内置
无 GUI 环境时自动回退到命令行模式，不影响核心功能。
快速开始
第一步：获取项目
# 进入项目目录
cd pinmap-to-pinlist/Code/src/
第二步：运行转换
方式一：交互式模式（推荐）
python main.py
运行后显示方向选择菜单，选择 1 或 2：
请选择转换方向:
1 — PinMAP → PinList
2 — PinList → PinMAP
请输入选项 (1/2): _
方式二：命令行模式
# PinMAP → PinList（直接指定文件）
python main.py /path/to/your/PinMAP.xlsx
# PinList → PinMAP（命令行模式默认走 MAP→List 方向）
# 如需 List→MAP，请使用交互式模式
第三步：查看输出
转换完成后，在当前目录生成输出文件：
PinMAP → PinList: QFP44_PinMAP.xlsx → QFP44_PinMAP_PinList.xlsx
PinList → PinMAP: QFN20_PinList.xlsx → QFN20_PinList_PinMAP.xlsx
方向一：PinMAP → PinList
将方形封装引脚布局图转换为线性引脚列表。
操作步骤
- 运行
python main.py，选择方向 1 - 选择 PinMAP 文件（
.xls或.xlsx） - 等待转换完成
- 查看输出的
_PinList.xlsx文件
使用示例
输入文件 QFP44.xlsx（6×6 方形封装，8 个引脚）：
A B C D E F
1 QFP-44
2 Pin6 6
3 Pin5 5
4 1 Pin1
5 2 Pin2
6 Pin3 Pin4
7 3 4
运行：
python main.py QFP44.xlsx
输出：
[INFO] 正在读取文件: QFP44.xlsx
[INFO] 文件读取完成，共 16 个非空单元格
[INFO] 正在解析 PinMAP 结构...
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44
[INFO] 正在验证数据...
[INFO] 验证通过
[INFO] 正在生成 PinList...
[INFO] 正在写入输出文件: QFP44_PinList.xlsx
[SUCCESS] 转换完成！
输出文件: QFP44_PinList.xlsx
封装信息: QFP-44
Pin数量: 8
输出文件内容：
A B
1 QFP-44
2 Pin1 1
3 Pin2 2
4 Pin3 3
5 Pin4 4
6 Pin5 5
7 Pin6 6
PinMAP 文件规范
| 要求 | 说明 |
|---|---|
| A1 单元格 | 必须包含封装信息（如 "QFP-44"） |
| 方形区域 | 至少 2×2，引脚沿四条边分布 |
| 引脚序号 | 1-based 整数，从 1 到 N 连续 |
| 排序方向 | 左上角为 1 脚，逆时针排列 |
| PinName 位置 | 在序号单元格的"内侧相邻"位置 |
四边 PinName 位置
左边：序号在 (r, min_col)，PinName 在 (r, min_col+1)
下边：序号在 (max_row, c)，PinName 在 (max_row-1, c)
右边：序号在 (r, max_col)，PinName 在 (r, max_col-1)
上边：序号在 (min_row, c)，PinName 在 (min_row+1, c)
方向二：PinList → PinMAP
将线性引脚列表转换为方形封装引脚布局图。
操作步骤
- 运行
python main.py，选择方向 2 - 选择 PinList 文件（
.xls或.xlsx） - 输入 PinMAP 行数（至少 2）
- 输入 PinMAP 列数（至少 2）
- 等待转换完成
- 查看输出的
_PinMAP.xlsx文件
尺寸输入说明
PinMAP 的引脚分布在四条边上，总引脚数由网格尺寸决定：
总引脚数 = 2 × 行数 + 2 × 列数 − 4
常见封装尺寸参考：
| 封装类型 | 引脚数 | 推荐行数 | 推荐列数 |
|---|---|---|---|
| QFP-8 | 8 | 4 | 4 |
| QFP-16 | 16 | 6 | 6 |
| QFP-20 | 20 | 6 | 6 |
| QFP-24 | 24 | 8 | 6 |
| QFP-32 | 32 | 10 | 8 |
| QFP-44 | 44 | 12 | 10 |
| QFP-64 | 64 | 16 | 16 |
| QFP-100 | 100 | 26 | 26 |
提示：如果不确定尺寸，可以先用公式反推：
行数 + 列数 = (引脚数 + 4) / 2，然后根据需要调整行和列的比例。
模板文件说明（v1.5.0）
从 v1.5.0 开始，两个方向的转换使用各自独立的模板文件：
| 转换方向 | 模板文件 | 查找位置 |
|---|---|---|
| MAP→List | BallList-Template.xlsx |
项目根目录 → 当前工作目录 |
| List→MAP | BallMAP-Template.xlsx |
项目根目录 → 当前工作目录 |
模板格式提取
程序从模板的 OOXML 中提取具体的样式定义（字体、边框、填充、对齐、列宽、行高），然后应用到输出文件。这种方式确保即使模板结构复杂也能正确提取关键样式属性。
优雅降级
- 模板文件不存在 → 使用硬编码默认样式（Calibri 11pt、thin 边框、居中）
- 模板解析失败（损坏/格式异常）→ 优雅回退到默认样式
- 模板中某些样式属性缺失 → 仅应用可用属性，其余保持默认
使用示例
输入文件 QFN20_PinList.xlsx（20 个引脚）：
A B
1 QFN-20
2 VCC 1
3 GND 2
4 IO0 3
5 IO1 4
6 IO2 5
7 IO3 6
8 IO4 7
9 IO5 8
10 IO6 9
11 IO7 10
12 NC 11
13 NC 12
14 NC 13
15 NC 14
16 NC 15
17 NC 16
18 NC 17
19 NC 18
20 NC 19
21 NC 20
运行：
python main.py
# 选择方向: 2 (PinList → PinMAP)
# 选择文件: QFN20_PinList.xlsx
# 输入行数: 6
# 输入列数: 6
输出：
[INFO] PinMAP 尺寸: 6 行 × 6 列
[INFO] 正在解析 PinList 文件: QFN20_PinList.xlsx
[INFO] 解析完成: 封装信息 'QFN-20', 共 20 个引脚
[INFO] 正在验证数据...
[INFO] 验证通过
[INFO] 正在生成 PinMAP 并写入: QFN20_PinList_PinMAP.xlsx
[SUCCESS] 转换完成！
输出文件: QFN20_PinList_PinMAP.xlsx
封装信息: QFN-20
PinMAP 尺寸: 6×6
Pin数量: 20
输出文件内容（6×6 网格，20 个引脚）：
A B C D E F
1 QFN-20 IO8 IO7
2 1 VCC IO6 IO5
3 2 GND IO4 IO3
4 3 IO0 IO2 IO1
5 4 IO1 NC NC
6 20 19 18 17 16
布局规则
引脚按逆时针分配到四条边（左上角为 1 脚）：
左边: 从上到下（rows 个引脚）
下边: 从左到右（cols − 1 个引脚）
右边: 从下到上（rows − 2 个引脚）
上边: 从右到左（cols − 1 个引脚）
PinName 与序号的相对位置：
左边：Name 在序号右侧
下边：Name 在序号上方
右边：Name 在序号左侧
上边：Name 在序号下方
使用示例汇总
示例 1：标准方形 PinMAP（MAP→List）
输入 QFP44.xlsx（6×6，8 Pin）
python main.py QFP44.xlsx
输出 QFP44_PinList.xlsx（A 列 PinName，B 列序号）
示例 2：长方形 PinMAP（MAP→List）
输入 LQFP100.xlsx（长方形，13 Pin）
python main.py LQFP100.xlsx
输出 LQFP100_PinList.xlsx
示例 3：标准 PinList（List→MAP）
输入 QFN20_PinList.xlsx（20 Pin）
python main.py
# 选择 2，输入 6×6
输出 QFN20_PinList_PinMAP.xlsx（6×6 方形）
示例 4：处理警告
当 PinMAP 中部分引脚缺少 PinName 时：
[WARN] 发现 3 个警告:
- 检测到 3 个引脚缺少 PinName: 缺失引脚序号: [2, 3, 4]，将默认为 NC
[SUCCESS] 转换完成！
缺失 PinName 的引脚在输出中自动标记为 "NC"。
示例 5：处理错误
当 PinList 引脚数与网格尺寸不匹配时：
[ERROR] 验证未通过，发现 1 个错误:
- Pin数量与网格周长不匹配: 网格 6×6 需要 20 个引脚，但 PinList 有 24 个
转换终止，请修正PinList文件或网格尺寸后重试。
支持的格式
输入格式
| 格式 | 扩展名 | 支持情况 |
|---|---|---|
| Excel 97-2003 | .xls |
✅ 支持（BIFF8 引擎） |
| Excel 2007+ | .xlsx |
✅ 支持（OOXML 引擎） |
输出格式
| 格式 | 扩展名 | 说明 |
|---|---|---|
| Excel 2007+ | .xlsx |
唯一输出格式 |
常见问题
Q1: 运行时提示 "未选择文件，退出"
原因：在 GUI 模式下点击了"取消"，或在无 GUI 环境下未提供命令行参数。
解决：
# 提供命令行参数
python main.py input.xlsx
Q2: 提示 "文件读取失败"
可能原因：
- 文件路径不存在
- 文件格式不是有效的 Excel 文件
- 文件已损坏
解决：
- 检查文件路径是否正确
- 确认文件可以用 Excel 正常打开
- 尝试用 Excel 重新保存文件
Q3: 提示 "A1 单元格为空，缺少封装信息"
原因：文件的 A1 单元格为空。
解决：在 Excel 中打开文件，在 A1 单元格填入封装信息（如 "QFP-44"），保存后重新转换。
Q4: 提示 "Pin序号不连续"
原因：Pin 序号存在间隔（如 1, 2, 4, 5，缺少 3）。
解决：检查文件，补全缺失的引脚序号。
Q5: 提示 "Pin序号重复"
原因：同一个 Pin 序号出现了多次。
解决：检查文件，修正重复的序号。
Q6: 提示 "Pin数量与网格周长不匹配"
原因：PinList 的引脚数与输入的 rows×cols 网格周长不一致。
解决：
- 检查引脚数量是否正确
- 或调整网格尺寸，使
2×rows + 2×cols − 4 = 引脚数
Q7: 警告 "检测到 N 个引脚缺少 PinName"
说明：这是警告而非错误，转换会继续进行。缺失的 PinName 会自动设为 "NC"。
解决（可选）：在 Excel 中补全缺失的 PinName，重新转换。
Q8: Linux 下没有弹出文件选择对话框
说明：Linux 无头环境（无显示器）不支持 tkinter GUI。
解决：使用命令行模式：
python main.py /path/to/input.xlsx
如需 GUI，安装 tkinter：
sudo apt install python3-tk
Q9: 输出文件打不开
可能原因：Excel 版本过旧（2003 及以下不支持 .xlsx）。
解决：使用 Excel 2007+ 或 WPS Office 打开输出文件。
Q10: 支持多大的 PinMAP？
回答：当前实现适合 < 1000 引脚的场景。典型 IC 封装引脚数在 8~200 之间，完全满足需求。
Q11: 能否批量转换多个文件？
回答：当前版本一次处理一个文件。如需批量转换，可使用 shell 脚本：
# PinMAP → PinList
for f in *.xlsx; do
python main.py "$f"
done
Q12: 命令行模式下如何执行 PinList → PinMAP？
回答：命令行模式下直接传入文件参数默认走 PinMAP → PinList 方向。如需执行 PinList → PinMAP，请使用交互式模式（不带参数运行），选择方向 2。
测试验证
运行内置单元测试：
cd Code/src/
python test_pinmap.py
预期输出：
✓ test_4x4_parse passed
✓ test_4x4_validate passed
✓ test_missing_names_warning passed
✓ test_duplicate_numbers passed
✓ test_gap_in_numbers passed
✓ test_empty_cells passed
✓ test_no_pins passed
✓ test_12pin_square passed
✅ All tests passed!