GoudanLabs/pinmap-to-pinlist
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
836ad20515a7314edb466c1ff994f8d9fbb84331
pinmap-to-pinlist/Code/docs/README.md

7.9 KiB
Raw Blame History

PinMAP → PinList 转换器

将 Excel 格式的 PinMAP 文件（方形封装引脚布局图）自动转换为 PinList 格式（引脚序号列表），消除手动抄录的低效与错误风险。

项目简介

在 IC 封装设计中，PinMAP 以方形/长方形矩阵形式展示引脚分布，而 PinList 则以线性列表形式提供引脚序号对照。本项目通过纯 Python 实现，自动完成从 PinMAP 到 PinList 的转换，支持 .xls 和 .xlsx 两种格式。

版本: v1.0.0
发布日期: 2026-05-25
运行平台: Windows（tkinter GUI）/ Linux（命令行回退）
技术栈: Python 标准库，零第三方依赖

功能特性

核心功能

功能 说明
PinMAP 解析 自动识别方形/长方形结构，沿四条边（左→下→右→上）逆时针提取引脚
数据验证 检测序号不连续、序号重复、PinName 缺失、A1 封装信息缺失
PinList 生成 A 列 PinName，B 列 Pin 序号，按序号递增排序
双格式支持 同时支持 .xls（BIFF8 引擎）和 .xlsx（OOXML 引擎）
双模式运行 GUI 文件选择对话框 + 命令行参数模式

验证规则

  • 序号连续性：Pin 序号必须为 1~N 连续整数，无间隔
  • 序号唯一性：每个 Pin 序号只能出现一次，无重复
  • PinName 完整性：缺失 PinName 的引脚自动标记为 "NC"（警告级别，不中断流程）
  • 结构完整性：方形区域至少 2×2，A1 单元格必须包含封装信息

技术栈

零第三方依赖

本项目完全使用 Python 标准库实现，不依赖任何第三方包。

模块 用途 标准库
xls_reader.py BIFF8 解析引擎（~19KB OLE2 解析） struct
xlsx_reader.py XLSX 读取引擎（ZIP + XML 解析） zipfile, xml.etree.ElementTree
xlsx_writer.py XLSX 写入引擎（OOXML 构建） zipfile, xml.etree.ElementTree
file_selector.py 文件选择对话框 tkinter.filedialog
pinmap_parser.py PinMAP 结构解析 纯 Python
validator.py 数据验证 collections.Counter
pinlist_generator.py PinList 生成 纯 Python

核心技术亮点

  • BIFF8 手动解析：从零实现 OLE2 复合文档 + BIFF8 记录流解析，支持 SST、LABELSST、NUMBER、FORMULA、RK、MULRK、LABEL 等记录类型
  • OOXML 手动构建：不使用 openpyxl/xlrd，纯手工构建 [Content_Types].xml、workbook.xml、sharedStrings.xml、sheet1.xml 等 OOXML 结构
  • 模块化架构：解析 → 验证 → 生成 → 输出，各模块职责清晰，接口契约明确

使用方式

前提条件

  • Python 3.6+（推荐 3.8+）
  • Windows 环境（GUI 模式需要 tkinter）
  • Linux/Mac 环境（仅命令行模式）

命令行模式

# 基本用法
python main.py input.xlsx

# 支持 .xls 格式
python main.py input.xls

# 输出文件自动命名为 input_PinList.xlsx

GUI 模式

# 不带参数运行，弹出文件选择对话框
python main.py

在对话框中选择 .xls 或 .xlsx 文件，点击"打开"即可开始转换。

输出示例

输入 PinMAP（方形封装）：

     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

输出 PinList：

     A         B
1  QFP-44
2  Pin1      1
3  Pin2      2
4  Pin3      3
5  Pin4      4
6  Pin5      5
7  Pin6      6

项目结构

pinmap-to-pinlist/
├── Code/
│   ├── src/
│   │   ├── main.py              # 主入口：流程编排
│   │   ├── file_selector.py     # 文件选择（GUI + 命令行回退）
│   │   ├── xls_reader.py        # XLS (BIFF8) 读取引擎
│   │   ├── xlsx_reader.py       # XLSX 读取引擎
│   │   ├── xlsx_writer.py       # XLSX 写入引擎
│   │   ├── pinmap_parser.py     # PinMAP 结构解析
│   │   ├── validator.py         # 数据验证
│   │   ├── pinlist_generator.py # PinList 生成
│   │   ├── models.py            # 数据模型
│   │   ├── utils.py             # 工具函数
│   │   └── test_pinmap.py       # 单元测试
│   └── docs/
│       ├── README.md            # 本文档
│       ├── QUICKSTART.md        # 快速入门指南
│       ├── RELEASE.md           # 版本发布说明
│       ├── architecture-design.md  # 架构设计文档
│       └── team.md              # 团队成员
├── Test/
│   ├── fixtures/                # 测试夹具
│   │   ├── sample_4x4.xlsx      # 标准 4×4 PinMAP
│   │   ├── sample_rect.xlsx     # 长方形 PinMAP
│   │   ├── error_gap.xlsx       # 序号不连续测试
│   │   ├── error_dup.xlsx       # 序号重复测试
│   │   ├── error_empty_a1.xlsx  # A1 为空测试
│   │   └── warning_missing.xlsx # PinName 缺失测试
│   └── test_report.md           # 测试报告
├── README.md                    # 项目根目录 README
├── CHANGELOG.md                 # 变更日志
└── .gitignore

测试情况

单元测试

运行 python test_pinmap.py（在 Code/src/ 目录下）：

测试用例 说明 状态
test_4x4_parse 4×4 方形 PinMAP 解析 ✅ 通过
test_4x4_validate 4×4 方形验证 ✅ 通过
test_missing_names_warning PinName 缺失警告 ✅ 通过
test_duplicate_numbers 序号重复检测 ✅ 通过
test_gap_in_numbers 序号不连续检测 ✅ 通过
test_empty_cells 空单元格处理 ✅ 通过
test_no_pins 无引脚数据检测 ✅ 通过
test_12pin_square 12 引脚方形解析 ✅ 通过

集成测试

测试用例 输入文件 说明 状态
TC001 sample_4x4.xlsx 标准 4×4 转换（8 Pin） ✅ 通过
TC002 sample_rect.xlsx 长方形转换（13 Pin） ✅ 通过
TC003 error_gap.xlsx 序号不连续检测 ✅ 通过
TC004 error_dup.xlsx 序号重复检测 ✅ 通过
TC005 warning_missing.xlsx PinName 缺失警告 ✅ 通过
TC006 error_empty_a1.xlsx A1 为空检测 ✅ 通过

结论：所有测试用例通过，无阻塞性问题。详见 Test/test_report.md。

解析算法说明

PinMAP 结构

PinMAP 以方形/长方形矩阵展示引脚分布：

        col A(0)   col B(1)   col C(2)   col D(3)
row 0   [A1=封装]
row 1   [1]        [2]        [3]        [4]          ← 上边 Pin 序号
row 2   [PinName]  [          ]          [PinName]    ← PinName 行
row 3   [PinName]  [          ]          [PinName]
row 4   [13]       [12]       [11]       [10]         ← 下边 Pin 序号

逆时针提取规则

引脚沿四条边逆时针提取：

  1. 左边：从上到下
  2. 下边：从左到右
  3. 右边：从下到上
  4. 上边：从右到左

角点单元格只计数一次（按单元格位置去重）。

PinList 输出规则

  • A1 单元格：封装信息（从 PinMAP 的 A1 复制）
  • A 列：PinName（缺失时自动设为 "NC"）
  • B 列：Pin 序号
  • 按 Pin 序号递增排序

错误处理

级别 类型 行为
[FATAL] 文件格式错误 / 结构错误 终止处理，显示错误信息
[ERROR] 数据验证错误（重复/不连续） 终止处理，显示详细错误
[WARN] PinName 缺失 提示警告，自动设为 "NC"，继续处理
[INFO] 解析进度信息 仅显示，不影响流程
[SUCCESS] 转换完成 显示输出文件路径和统计信息

许可证

内部项目

Reference in New Issue View Git Blame Copy Permalink