# SHOCK FEATHER

**Repository Path**: caraba/shock-feather

## Basic Information

- **Project Name**: SHOCK FEATHER
- **Description**: SHOCK FEATHER交互式PCB物料管理系统
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SHOCK FEATHER 交互式PCB物料管理系统

> 由大帅实验室使用 TRAE IDE 创建 | AGPL 3.0 许可

---

## 目录

- [功能特性](#功能特性)
- [系统要求](#系统要求)
- [安装与运行](#安装与运行)
  - [直接运行 EXE](#直接运行-exe)
  - [开发模式运行](#开发模式运行)
- [使用指南](#使用指南)
  - [打开 Gerber 文件](#打开-gerber-文件)
  - [BOM 文件管理](#bom-文件管理)
  - [图层切换](#图层切换)
  - [同时显示模式](#同时显示模式)
  - [焊接对料](#焊接对料)
  - [扫码入库](#扫码入库)
  - [查找本地物料](#查找本地物料)
- [技术架构](#技术架构)
- [项目结构](#项目结构)
- [命令行参数](#命令行参数)
- [许可证](#许可证)

---

## 功能特性

### 🎯 核心功能

- **Gerber 可视化**: 支持打开 Gerber ZIP 压缩包，自动解析并显示 PCB 图形
- **BOM 管理**: 支持 CSV/Excel BOM 文件加载、解析和显示
- **坐标匹配**: 加载坐标文件后，可通过 Designator 在 Gerber 中定位器件
- **双图层显示**: 支持同时显示顶层和底层，自适应布局（左右/上下排列）
- **器件标记**: 点击 BOM 列表或扫码匹配时，在 Gerber 中自动标记对应器件位置

### 🔧 焊接对料

- **扫码匹配**: 通过 USB 摄像头扫描二维码，自动匹配 BOM 中的物料
- **多种匹配模式**: 精确匹配、型号匹配、模糊匹配、手动匹配
- **匹配状态标记**: 不同匹配类型用不同颜色标记（深绿/浅绿/蓝色）
- **导出对料信息**: 导出包含匹配状态和颜色标记的 Excel 文件
- **自动加载 BOM**: 打开焊接对料时自动加载已加载的 BOM 文件

### 📦 物料管理

- **扫码入库**: 扫描物料二维码，记录入库信息到本地数据库
- **库存统计**: 实时显示库存数量和状态
- **本地物料查找**: 在本地数据库中搜索物料信息

### ⚙️ 视图控制

- **图层切换**: 支持顶层、底层、全部图层三种视图
- **同时显示**: 一键切换到顶层+底层双视图模式
- **自适应布局**: 根据窗口大小自动调整双视图排列方式
- **适应窗口**: 一键缩放至窗口大小
- **重置布局**: 恢复默认视图

---

## 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 10 / Windows 11 |
| Python | 3.11+ (开发模式) |
| gerbv | 需安装用于 Gerber → SVG 转换 |
| 摄像头 | USB 摄像头（用于扫码功能） |

### gerbv 安装

1. 下载 gerbv Windows 版本
2. 默认安装路径: `C:\Program Files\gerbv\gerbv.exe`
3. 如安装在其他路径，可通过 `--gerbv-exe` 参数指定

---

## 安装与运行

### 直接运行 EXE

1. 进入 `release/dist/` 目录
2. 双击 `ShockFeather.exe` 启动程序

> **注意**: EXE 文件为单文件打包，首次启动时会将资源解压到临时目录，启动时间可能稍长。

### 开发模式运行

```bash
# 克隆项目
git clone <repository-url>
cd shock_feather

# 安装依赖
pip install PyQt5 numpy opencv-python openpyxl zxing-cpp

# 运行程序
python main.py

# 命令行分析模式
python main.py --analyze /path/to/gerber.zip
```

---

## 使用指南

### 打开 Gerber 文件

1. 点击菜单栏 **文件 → 打开 Gerber 文件**
2. 选择 Gerber ZIP 压缩包
3. 程序会自动解压并分析文件
4. 如缺少 BOM 或坐标文件，会弹出选择对话框

### BOM 文件管理

- **加载 BOM**: 打开 Gerber 时自动检测，或手动选择 BOM 文件
- **显示 BOM**: 加载后左侧面板显示 BOM 列表（包含 Comment、Quantity、Footprint、Designator 等）
- **点击定位**: 点击 BOM 列表中的记录，右侧 Gerber 中会标记对应器件位置

### 图层切换

- **顶层**: 仅显示顶层 Gerber
- **底层**: 仅显示底层 Gerber（自动镜像）
- **全部图层**: 显示所有图层合并视图
- **同时显示**: 同时显示顶层和底层，自适应布局

### 同时显示模式

- 默认打开 Gerber 时为"同时显示"模式
- 两个视图根据窗口大小自动排列：
  - **宽窗口**: 左右排列
  - **窄窗口**: 上下排列
- 点击任意视图的工具栏按钮会同步更新两个视图

### 焊接对料

1. 点击工具栏 **焊接对料** 按钮或菜单
2. 自动加载已打开的 BOM 文件
3. **扫码匹配**: 扫描物料二维码自动匹配
4. **手动匹配**: 在左侧列表中选择物料进行匹配
5. **标记显示**: 匹配成功后，Gerber 中会标记对应器件位置
6. **导出**: 点击"导出对料信息"按钮导出 Excel 文件

### 扫码入库

1. 点击工具栏 **扫码入库** 按钮
2. 扫描物料二维码，自动填充型号、编码、数量
3. 修改数量后点击"确认入库"
4. 数据保存到本地数据库

### 查找本地物料

1. 点击工具栏 **查找本地物料** 按钮
2. 在搜索框中输入物料型号或编码
3. 双击搜索结果可查看详情

---

## 技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                      ShockFeather                           │
│  ┌──────────────┐    ┌──────────────────────────────────┐  │
│  │   菜单栏      │    │            工具栏                 │  │
│  └──────────────┘    └──────────────────────────────────┘  │
│                                                             │
│  ┌──────────────┐    ┌──────────────────────────────────┐  │
│  │   BOM列表     │    │        SVG 视图区域               │  │
│  │  (QSplitter) │    │  ┌─────────┐  ┌─────────┐        │  │
│  │              │    │  │  顶层视图 │  │  底层视图 │       │  │
│  │              │    │  │ (QStacked│  │  Widget)│       │  │
│  └──────────────┘    │  └─────────┘  └─────────┘        │  │
│                      └──────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                    状态栏                             │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### 核心模块

| 模块 | 功能 |
|------|------|
| `svg_viewer.py` | 主窗口、SVG 渲染、图层管理、标记绘制 |
| `camera_qr.py` | 摄像头管理、二维码识别、焊接对料、扫码入库 |
| `bom.py` | BOM 文件解析、数据模型 |
| `pickplace.py` | 坐标文件解析、Designator 匹配 |
| `gerber_size.py` | Gerber 尺寸分析、ZIP 解压、中文文件名修复 |
| `gerber_to_svg.py` | Gerber → SVG 转换（调用 gerbv） |
| `coordinate_mapper.py` | 坐标映射、Gerber 坐标到 SVG 坐标转换 |
| `storage_db.py` | 本地数据库管理、物料库存 |
| `icons.py` | 自定义 SVG 图标渲染 |

### 关键技术

- **PyQt5**: GUI 框架，支持 QGraphicsView、QSplitter、QWebEngineView
- **gerbv**: Gerber 文件解析和 SVG 转换
- **OpenCV**: 摄像头访问、二维码识别、图像增强
- **zxing-cpp**: 增强二维码识别能力
- **openpyxl**: Excel 文件读写（BOM 导入、对料信息导出）
- **PyInstaller**: 打包为单文件 EXE

---

## 项目结构

```
shock_feather/
├── main.py                    # 主程序入口
├── main.bat                   # 启动脚本
├── lcbom.csv                  # 本地物料数据库
├── core/                      # 核心模块
│   ├── __init__.py
│   ├── app_icon.png           # 应用图标
│   ├── bom.py                 # BOM 解析
│   ├── camera_qr.py           # 摄像头与二维码
│   ├── coordinate_mapper.py   # 坐标映射
│   ├── gerber_size.py         # Gerber 尺寸分析
│   ├── gerber_to_svg.py       # Gerber → SVG
│   ├── icons.py               # SVG 图标
│   ├── pickplace.py           # 坐标文件解析
│   ├── settings_dialog.py     # 设置对话框
│   ├── shock_feather.jpg      # 关于窗口图标
│   ├── storage_db.py          # 数据库管理
│   └── svg_viewer.py          # 主窗口
├── 1.demo_files/              # 示例文件
├── .trae/specs/               # 规格文档
└── release/                   # 发布版本
    ├── core/                  # 代码副本
    ├── main.py                # 入口副本
    ├── ShockFeather.spec      # PyInstaller 配置
    └── dist/                  # 打包输出
        └── ShockFeather.exe   # 可执行文件
```

---

## 命令行参数

```bash
python main.py [OPTIONS] [target]

位置参数:
  target              Gerber ZIP 文件或目录

选项:
  --analyze           仅在命令行打印尺寸分析结果（不启动 GUI）
  --gerbv-exe PATH    gerbv 可执行文件路径（默认: C:\Program Files\gerbv\gerber_viewer.exe）
  --dpi INT           SVG 输出 DPI（默认: 600）
  --ibom PATH         自动加载 IBOM HTML 文件路径
```

### 示例

```bash
# 启动 GUI
python main.py

# 命令行分析 Gerber ZIP
python main.py --analyze Gerber_PCB_2026-06-21.zip

# 指定 gerbv 路径
python main.py --gerbv-exe "D:\gerbv\gerbv.exe"

# 自动加载 IBOM
python main.py --ibom lcibom.html
```

---

## 许可证

本项目采用 **AGPL 3.0** 开源许可证。

```
SHOCK FEATHER 交互式PCB物料管理系统
Copyright (C) 2026 大帅实验室

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
```

---

## 关于

- **项目名称**: SHOCK FEATHER 交互式PCB物料管理系统
- **开发团队**: 大帅实验室
- **开发工具**: TRAE IDE
- **许可证**: AGPL 3.0

---

*由大帅实验室使用 TRAE IDE 创建*