GoudanLabs/pinmap-to-pinlist
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

feat: PinMAP转PinList v1.2.0 - 新增PinList转PinMAP反向转换功能

Browse Source
This commit is contained in:
Agent
2026-05-28 01:53:51 +08:00
parent 853f10a73b
commit 3228c1a2e6
18 changed files with 3781 additions and 977 deletions
Download Patch File Download Diff File Expand all files Collapse all files

342
Code/docs/QUICKSTART.md
View File

@@ -1,6 +1,6 @@
# 快速入门指南
本文档帮助你快速上手 PinMAP → PinList 转换器。
本文档帮助你快速上手 PinMAP ↔ PinList 双向转换器。
---
@@ -46,36 +46,57 @@ cd pinmap-to-pinlist/Code/src/
### 第二步：运行转换
#### 方式一：GUI 模式（推荐）
#### 方式一：交互式模式（推荐）
```bash
python main.py
```
弹出文件选择对话框，选择 `.xls` 或 `.xlsx` 文件即可。
运行后显示方向选择菜单，选择 1 或 2：
```
请选择转换方向:
1 — PinMAP → PinList
2 — PinList → PinMAP
请输入选项 (1/2): _
```
#### 方式二：命令行模式
```bash
python main.py /path/to/your/input.xlsx
# PinMAP → PinList（直接指定文件）
python main.py /path/to/your/PinMAP.xlsx
# PinList → PinMAP（命令行模式默认走 MAP→List 方向）
# 如需 List→MAP，请使用交互式模式
```
### 第三步：查看输出
转换完成后，在当前目录生成 `{原文件名}_PinList.xlsx`：
转换完成后，在当前目录生成输出文件：
```
输入: QFP44_PinMAP.xlsx
输出: QFP44_PinMAP_PinList.xlsx
PinMAP → PinList: QFP44_PinMAP.xlsx → QFP44_PinMAP_PinList.xlsx
PinList → PinMAP: QFN20_PinList.xlsx → QFN20_PinList_PinMAP.xlsx
```
---
## 使用示例
## 方向一：PinMAP → PinList
### 示例 1：标准方形 PinMAP
将方形封装引脚布局图转换为线性引脚列表。
**输入文件** `QFP44.xlsx`：
### 操作步骤
1. 运行 `python main.py`，选择方向 **1**
2. 选择 PinMAP 文件（`.xls` 或 `.xlsx`）
3. 等待转换完成
4. 查看输出的 `_PinList.xlsx` 文件
### 使用示例
**输入文件** `QFP44.xlsx`（6×6 方形封装，8 个引脚）：
```
A B C D E F
@@ -88,7 +109,7 @@ python main.py /path/to/your/input.xlsx
7 3 4
```
**运行命令**：
**运行**：
```bash
python main.py QFP44.xlsx
@@ -97,12 +118,20 @@ 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
[SUCCESS] 转换完成！
输出文件: QFP44_PinList.xlsx
封装信息: QFP-44
Pin数量: 8
```
**输出文件内容**：
@@ -118,62 +147,7 @@ python main.py QFP44.xlsx
7 Pin6 6
```
### 示例 2：长方形 PinMAP
**输入文件** `LQFP100.xlsx`（13 个引脚的长方形封装）
```bash
python main.py LQFP100.xlsx
```
**输出**：
```
[INFO] 解析完成: 长方形结构，共 13 个Pin
[INFO] 封装信息: LQFP-100
[SUCCESS] 转换完成！输出文件: LQFP100_PinList.xlsx
- 封装信息: LQFP-100
- Pin数量: 13
```
### 示例 3：处理警告
当 PinMAP 中部分引脚缺少 PinName 时：
```
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44
[WARN] 发现 3 个警告:
- 检测到 3 个引脚缺少 PinName: 缺失引脚序号: [2, 3, 4]，将默认为 NC
[SUCCESS] 转换完成！输出文件: QFP44_PinList.xlsx
- 封装信息: QFP-44
- Pin数量: 8
```
缺失 PinName 的引脚在输出中自动标记为 "NC"。
### 示例 4：处理错误
当 PinMAP 存在数据错误时：
```
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44
[ERROR] 发现 1 个错误:
- Pin序号不连续: 缺失的序号: [3]
转换终止，请修正PinMAP文件后重试。
```
---
## PinMAP 文件规范
### 格式要求
### PinMAP 文件规范
| 要求 | 说明 |
|------|------|
@@ -192,7 +166,204 @@ python main.py LQFP100.xlsx
上边：序号在 (min_row, c)，PinName 在 (min_row+1, c)
```
### 支持的输入格式
---
## 方向二：PinList → PinMAP
将线性引脚列表转换为方形封装引脚布局图。
### 操作步骤
1. 运行 `python main.py`，选择方向 **2**
2. 选择 PinList 文件（`.xls` 或 `.xlsx`）
3. **输入 PinMAP 行数**（至少 2）
4. **输入 PinMAP 列数**（至少 2）
5. 等待转换完成
6. 查看输出的 `_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`，然后根据需要调整行和列的比例。
### 模板文件说明
PinList → PinMAP 转换时，程序会自动尝试从输入文件所在目录读取模板样式：
- **模板来源**：程序会尝试解析与输入文件同名的 `.xlsx` 模板文件中的样式信息
- **提取内容**：字体（名称、大小、粗体、斜体、颜色）、填充、边框、列宽、行高
- **优雅降级**：如果模板不存在或解析失败，程序会自动使用默认样式，不影响转换流程
### 使用示例
**输入文件** `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
```
**运行**：
```bash
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）
```bash
python main.py QFP44.xlsx
```
**输出** `QFP44_PinList.xlsx`（A 列 PinName，B 列序号）
### 示例 2：长方形 PinMAP（MAP→List）
**输入** `LQFP100.xlsx`（长方形，13 Pin）
```bash
python main.py LQFP100.xlsx
```
**输出** `LQFP100_PinList.xlsx`
### 示例 3：标准 PinList（List→MAP）
**输入** `QFN20_PinList.xlsx`（20 Pin）
```bash
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文件或网格尺寸后重试。
```
---
## 支持的格式
### 输入格式
| 格式 | 扩展名 | 支持情况 |
|------|--------|----------|
@@ -233,7 +404,7 @@ python main.py input.xlsx
### Q3: 提示 "A1 单元格为空，缺少封装信息"
**原因**：PinMAP 文件的 A1 单元格为空。
**原因**：文件的 A1 单元格为空。
**解决**：在 Excel 中打开文件，在 A1 单元格填入封装信息（如 "QFP-44"），保存后重新转换。
@@ -241,21 +412,29 @@ python main.py input.xlsx
**原因**：Pin 序号存在间隔（如 1, 2, 4, 5，缺少 3）。
**解决**：检查 PinMAP 文件，补全缺失的引脚序号。
**解决**：检查文件，补全缺失的引脚序号。
### Q5: 提示 "Pin序号重复"
**原因**：同一个 Pin 序号出现了多次。
**解决**：检查 PinMAP 文件，修正重复的序号。
**解决**：检查文件，修正重复的序号。
### Q6: 警告 "检测到 N 个引脚缺少 PinName"
### Q6: 提示 "Pin数量与网格周长不匹配"
**原因**：PinList 的引脚数与输入的 rows×cols 网格周长不一致。
**解决**：
- 检查引脚数量是否正确
- 或调整网格尺寸，使 `2×rows + 2×cols − 4 = 引脚数`
### Q7: 警告 "检测到 N 个引脚缺少 PinName"
**说明**：这是警告而非错误，转换会继续进行。缺失的 PinName 会自动设为 "NC"。
**解决**（可选）：在 Excel 中补全缺失的 PinName，重新转换。
### Q7: Linux 下没有弹出文件选择对话框
### Q8: Linux 下没有弹出文件选择对话框
**说明**：Linux 无头环境（无显示器）不支持 tkinter GUI。
@@ -269,26 +448,31 @@ python main.py /path/to/input.xlsx
sudo apt install python3-tk
```
### Q8: 输出文件打不开
### Q9: 输出文件打不开
**可能原因**：Excel 版本过旧（2003 及以下不支持 .xlsx）。
**解决**：使用 Excel 2007+ 或 WPS Office 打开输出文件。
### Q9: 支持多大的 PinMAP？
### Q10: 支持多大的 PinMAP？
**回答**：当前实现适合 < 1000 引脚的场景。典型 IC 封装引脚数在 8~200 之间，完全满足需求。
### Q10: 能否批量转换多个文件？
### Q11: 能否批量转换多个文件？
**回答**：当前版本一次处理一个文件。如需批量转换，可使用 shell 脚本：
```bash
# PinMAP → PinList
for f in *.xlsx; do
python main.py "$f"
done
```
### Q12: 命令行模式下如何执行 PinList → PinMAP？
**回答**：命令行模式下直接传入文件参数默认走 PinMAP → PinList 方向。如需执行 PinList → PinMAP，请使用交互式模式（不带参数运行），选择方向 2。
---
## 测试验证