自动分析 PCB 的 Gerber 文件（RS-274X），一键生成用于承托 / 焊接 / 返修 PCB 的治具 3D 模型，并提供 Web 端 3D 预览、2D 工程视图与多格式导出。
治具（Fixture）是一种带 PCB 沉腔与定位销的托盘，把 PCB 稳稳托住，方便焊接、测试、返修或批量周转。本工具根据板厚、外形、安装孔、连接器位置自动计算沉腔与各类固定结构，省去手工建模。
演示地址：zhiju.x-smt.cn
- 功能特性
- 快速开始
- 双 Web 服务器
- 使用流程
- 多板（多份 Gerber）支持
- 治具设计规则
- 参数配置（config.json）
- Web API 说明
- 部署指南
- 后端模块说明
- 前端说明
- 目录结构
- 辅助脚本
- 常见问题
- 许可
- Gerber 解析：解析 RS-274X 各层（顶层/底层线路、阻焊、锡膏、钻孔、外形等），提取板外形、焊盘、过孔、安装孔。
- 智能轮廓提取：优先使用外形层（
.gko/.gm1等）；缺失时由所有层几何联合 + 闭运算推导，支持不规则外形。 - 安装孔识别：优先解析压缩包内的 Excellon 钻孔文件（
.drl/.txt/.xln）提取孔位与孔径；无钻孔文件时回退到阻焊/铜层的圆形开窗，匹配 M2/M2.5/M3/M4/M5 标准孔径，自动排针阵列过滤。 - FPC 软板支撑：检测细间距等距共线焊盘阵列且靠板边者，在治具对应位置保留支撑平台，辅助焊接。
- 边缘连接器避让：自动检测超出板外形的连接器/元件，在对应边额外留空并把超界器件并入沉腔挖出避让槽。
- 治具建模：生成含沉腔、承托台阶、定位销、取板凹口、四角磁体、对立面固定的实体模型（trimesh + manifold3d 布尔运算）。
- 3D 预览：Web 端 Three.js 渲染，支持旋转/缩放/平移、线框模式、PCB 示意显示、分体展开演示。
- 2D 工程视图：实时生成上/前/后/左/右五向 SVG 视图，可独立开关。
- 多格式导出：STL / OBJ / PLY / GLB / 3MF / OFF，支持整体与分体两半分别导出。
- 多板支持：压缩包内含多份 Gerber 时，以选项页（Tab）方式分别展示，切换同步左侧分析结果。
- 在线参数配置：浏览器内直接修改全部参数，保存后即时生效。
- 热重载：uvicorn
--reload监视app/与static/，改代码即生效，无需重启。
- Python ≥ 3.10
- （可选）PHP ≥ 8.0 + php-curl（使用 PHP 作为 Web 服务器时）
- （可选）7-Zip / UnRAR（解压 7z/rar 格式压缩包）
# 1. 克隆仓库
git clone <repository-url>
cd zhiju
# 2. 创建虚拟环境并安装依赖
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
# 3. 启动（默认端口 8300，热重载）
.venv\Scripts\python.exe run.py
# 或指定端口
.venv\Scripts\python.exe run.py 9000浏览器打开 http://127.0.0.1:8300 即可使用。
# 1. 先启动 Python 计算后端（端口 8300）
python run.py &
# 2. 启动 PHP 内置服务器（端口 8080）
php -S 127.0.0.1:8080 -t . index.php浏览器打开 http://127.0.0.1:8080。
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python run.py本项目同时支持 Python 和 PHP 作为独立的 Web 服务器，你可以根据部署环境自由选择，前端会自动适配 API 调用方式，无需手动配置。
┌──────────────────────────────────────────────────┐
│ 浏览器 │
│ http://127.0.0.1:8300 │
└──────────┬───────────────────────┬────────────────┘
│ │
┌─────▼─────┐ ┌─────▼─────┐
│ Python │ │ PHP │
│ FastAPI │ │ 内置服务器 │
│ (run.py) │ │ (index.php)│
└─────┬─────┘ └─────┬─────┘
│ │
│ 静态文件 + API │ 静态文件 + 代理 API
│ 全部由 Python 处理 │ PHP 处理路由，转发到 Python
│ │
┌─────▼───────────────────────▼─────┐
│ Python 计算引擎 │
│ (Gerber 解析 / 治具建模 / 导出) │
└───────────────────────────────────┘
两种模式的功能完全相同，API 行为一致，前端自动检测并适配。选择最适合你现有技术栈的模式即可。
FastAPI 直接托管静态文件并提供 API，零额外依赖。启动方式见 快速开始。
PHP 作为前端控制器，负责静态文件服务和 API 路由转发，所有计算仍由 Python 后端完成。适合已有 nginx+PHP 环境的用户。启动方式见 快速开始 > 方式二。
前端 main.js 会自动检测当前 Web 服务器类型并适配 API 调用路径：
| 检测方式 | Web 服务器 | API 路径格式 | 示例 |
|---|---|---|---|
| 默认（无标记） | Python | RESTful 路径 | /api/upload、/api/model/abc.stl |
window.__ZHIJU_MODE__="php" |
PHP | 查询参数 | /index.php?_act=upload、/index.php?_act=model&id=abc |
PHP 模式标记由
index.php在输出首页 HTML 时自动注入，无需手动配置。
| 从 → 到 | 操作 |
|---|---|
| Python → PHP | 1. 安装 PHP + php-curl；2. 启动 Python 后端 python run.py &；3. 启动 PHP php -S 127.0.0.1:8080 -t . index.php；4. 浏览器访问 http://127.0.0.1:8080 |
| PHP → Python | 直接使用 python run.py 启动，浏览器访问 http://127.0.0.1:8300 |
- 上传 Gerber：点击「上传 Gerber 压缩包(zip)」选择本地 zip；或点击「使用 testgerber 测试数据」直接体验。
- 上传进度：上传与解析过程中，视图区中央显示醒目进度条（XHR 实时进度），完成自动消失。
- 查看结果：
- 左侧「分析结果」显示板尺寸、外形方式、安装孔、FPC 区、边缘避让、文件清单（默认收起，点击展开）。
- 中间 3D 视图可旋转/缩放/平移；勾选「线框模式」「显示 PCB 示意」「分体展开演示」调整显示。
- 「2D 视图开关」以流布局排布，勾选对应视图即叠加相应 SVG 工程图。
- 配置参数：右侧常驻「参数面板」按分组在线设置；点击「保存并重新生成」即按最新参数对当前任务动态重生成（无需重新上传），同时写回
config.json作用于后续生成。 - 导出模型：左侧「3D 导出」列出 STL/OBJ/PLY/GLB/3MF/OFF，点击下载；若启用分体，可分别下载两半。
多份 Gerber 时，3D 视图上方出现选项页（Tab），切换 Tab 会同步刷新左侧的板信息与该板的 3D / 2D 视图。
压缩包解压后按如下规则自动分组，每组生成一块治具：
| 压缩包内布局 | 分组规则 | 板名 |
|---|---|---|
| 扁平布局（所有层文件在根目录） | 按文件名主干（stem）分组，同名不同后缀的层归为一块 | 文件名主干 |
| 嵌套布局（各板在独立子目录） | 以第一级子目录名为板名，目录内全部文件归该板 | 子目录名 |
以下默认值均可在 config.json 调整：
| 项 | 默认值 | 说明 |
|---|---|---|
| PCB 板厚 | 1.6 mm | 2 层板标准；沉腔深度 = 板厚，PCB 顶面与治具顶面齐平 |
| 外形间隙 | 单边 0.5 mm（公差 ±0.1） | PCB 与治具内壁间隙 |
| 治具边距 | 13 mm | 治具四周壁到 PCB 边的距离，固定治具长宽 |
| 承托台阶 | 宽 1 mm | 轮廓内缩 1mm 的内凹承托环 |
| 腔体深度 | 15 mm | 内腔最低面距治具顶面 1.5cm |
| 治具总高 | 20 mm | |
| 定位销间隙 | 单边 0.05 mm | 销径 = 孔径 − 2×0.05 |
| 防呆 | 一圆一方 | 第 2 个定位销为方销，保证方向唯一 |
| 取板凹口 | 半圆柱长槽 | 4 种方案可选，自动放在没有磁体的立面 |
| 安装孔识别 | M2/M2.5/M3/M4/M5 | 按标准螺丝过孔直径匹配 |
| FPC 检测 | 间距≤1mm、≥6 脚、距边≤8mm | 检出后在其正下方生成支撑平台 |
| 四角磁体 | D10×5.5 mm | 圆磁体嵌入六角沉孔防转 |
| 对立面固定 | 左右各 2 个磁体 | 竖直居中或上下分置 |
所有设计参数集中在此文件，亦可在网页「右侧参数面板」在线编辑。主要节：
| 节 | 关键字段 | 说明 |
|---|---|---|
units |
mm |
单位 |
pcb |
thickness / clearance_per_side |
板厚、外形单边间隙 |
fixture |
edge_margin / total_height / cavity_depth / notch |
边距、总高、腔深、取板凹口 |
corner_magnets |
diameter / depth / enable |
四角磁体 |
side_fix |
mode / faces / count_per_side |
对立面固定 |
edge_clearance |
extra / probe / enable |
边缘连接器避让 |
split |
enable / axis / preview_gap |
分体 |
pins |
fit_clearance_per_side / anti_fool |
定位销配合参数与防呆 |
mounting_holes |
screw_standards_mm |
安装孔标准与过滤 |
fpc |
enable / min_pads / max_pitch |
FPC 检测阈值 |
outline |
merge_gap / simplify |
外形合并间隙与简化 |
基础地址 http://127.0.0.1:8300（端口可配置）。
以下路径为 Python 直出模式下的 RESTful 格式。使用 PHP 作为 Web 服务器时，API 通过
index.php?_act=xxx&...查询参数调用，功能完全一致。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/upload |
上传 Gerber zip → 解析+建模 |
| POST | /api/demo |
使用内置 testgerber 测试数据生成 |
| GET | /api/result/{job_id} |
获取某任务的完整分析 + 治具元数据（JSON） |
| GET | /api/model/{job_id}.stl |
获取治具 3D 预览模型（STL） |
| GET | /api/part/{job_id}/{which}.stl |
分体两半预览（which=a|b） |
| GET | /api/export/{job_id}.{fmt} |
导出整体模型，fmt ∈ stl/obj/ply/glb/3mf/off |
| GET | /api/export_part/{job_id}/{which}.{fmt} |
导出分体某半 |
| POST | /api/split/{job_id} |
按需分体 |
| GET | /api/views/{job_id}/{view}.svg |
2D 工程视图，view ∈ top/front/back/left/right |
| GET | /api/config |
获取当前参数配置 |
| PUT | /api/config |
覆盖保存参数配置 |
| POST | /api/regenerate/{job_id} |
按当前参数对已有任务动态重新生成 |
| GET | /api/brand |
返回品牌信息 |
| DELETE | /api/cleanup |
清空 tmp/models、tmp/uploads 下全部任务数据 |
典型响应（单板 /api/upload）
{
"id": "a1b2c3d4e5f6",
"multi": false,
"name": "PCB",
"analysis": { "board_size": [50.0, 40.0], "holes": [...], "fpc_zones": [], ... },
"fixture": { "fixture_size": [70.0, 60.0, 20.0], "fixture_bounds": [...], ... },
"formats": ["stl", "obj", "ply", "glb", "3mf", "off"],
"has_parts": false
}# Python 作为 Web 服务器（最简单）
python run.py
# 浏览器打开 http://127.0.0.1:8300以下两种方案任选其一：
Python FastAPI 直接提供服务，通过 nginx 反向代理：
location /zhiju/ {
proxy_pass http://127.0.0.1:8300/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 300s;
client_max_body_size 100m;
}启动 Python 服务：
scripts/zhiju-ctl.sh start
# 或 systemctl start zhiju# PHP 文件通过 FastCGI 处理
location ~ ^/zhiju/.*\.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME /path/to/zhiju/index.php;
include fastcgi_params;
fastcgi_read_timeout 300s;
}
# 前端路由全部交给 index.php
location /zhiju/ {
alias /path/to/zhiju/;
index index.php;
try_files $uri $uri/ /zhiju/index.php?$uri;
client_max_body_size 100m;
}启动服务：
# 1. 启动 Python 计算后端
python run.py &
# 2. 启动 PHP-FPM
systemctl start php8.3-fpm
# 3. 重载 nginx
nginx -t && systemctl reload nginx# 安装服务
sudo cp scripts/zhiju.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now zhiju
# 管理
systemctl status zhiju
systemctl restart zhiju
journalctl -u zhiju -fapp/ 下为 FastAPI 后端，各模块职责：
| 文件 | 职责 |
|---|---|
server.py |
Web 服务入口，定义全部 API 路由；负责 zip 解压、多板分组、逐板建模、结果落盘、按需分体 |
gerber_parser.py |
解析 RS-274X Gerber 指令，转换为几何图元 |
board_analyzer.py |
板分析：轮廓提取、安装孔识别、FPC 检测、边缘避让探测 |
fixture_builder.py |
治具几何建模：生成含沉腔/销/避让的实体；多格式导出；分体 |
views2d.py |
由治具几何生成五向 2D 工程视图 SVG |
__init__.py |
包标识 |
处理流水线：zip 解压 → _group_boards 分组 → 每块 analyze() → build_fixture() → _finalize_result()
static/ 为纯静态前端（无需构建，直接由 Web 服务器托管）：
| 文件 | 说明 |
|---|---|
index.html |
页面结构：顶栏、左侧信息面板、中部 3D/2D 舞台、右侧参数面板、上传进度遮罩 |
style.css |
全部样式 |
main.js |
交互逻辑：XHR 上传进度、结果渲染、多板 Tab、2D 视图叠加、3D 显示切换、参数配置、自动检测 PHP/Python 模式并适配 API 路径 |
vendor/ |
本地 Three.js 模块，离线可用 |
前端通过 fetch/XHR 调用上述 API；3D 预览用 Three.js 的
STLLoader加载模型。前端自动检测 Web 服务器类型（PHP 标记注入），无需手动切换 API 路径。
zhiju/
├── app/ 后端（解析/分析/建模/视图/服务）
│ ├── __init__.py
│ ├── gerber_parser.py Gerber 解析
│ ├── board_analyzer.py 板分析（轮廓/安装孔/FPC/避让）
│ ├── fixture_builder.py 治具建模与导出/分体
│ ├── views2d.py 2D 工程视图 SVG
│ └── server.py Web 服务与 API 路由
├── static/ 前端（Three.js 3D 预览，vendor 本地化）
│ ├── index.html
│ ├── main.js
│ ├── style.css
│ └── vendor/ three.module.js 等
├── scripts/ 运维脚本（启动/停止/安装）
│ ├── install.sh Ubuntu 一键安装
│ ├── zhiju-ctl.sh Linux 服务管理
│ ├── zhiju-ctl.ps1 Windows 服务管理
│ ├── zhiju-ctl.bat Windows 批处理包装器
│ ├── zhiju.service systemd 服务单元
│ ├── zhiju-start.ps1 Windows 启动
│ ├── zhiju-stop.ps1 Windows 停止
│ └── zhiju-status.ps1 Windows 状态
├── testgerber/ 测试用 Gerber 数据
├── config.json 全部可调参数（带注释）
├── clean.py 清除临时产物的辅助脚本
├── run.py 启动入口（Python Web 服务器，热重载）
├── run_cli.py CLI 后端（供 PHP Web 服务器通过 proc_open 调用）
├── index.php PHP Web 服务器入口（可选）
├── nginx-zhiju.conf Nginx 配置模板（双方案示例）
├── .htaccess Apache URL 重写（PHP 模式用）
├── requirements.txt Python 依赖
├── LICENSE AGPL-3.0 + 商业许可（英文）
├── LICENSE.zh-CN.md AGPL-3.0 + 商业许可（中文）
└── tmp/ 运行产物（models/uploads 任务数据）
run.py：Python Web 服务器入口。python run.py [port]，默认 8300，启用--reload热重载。run_cli.py：CLI 后端，供 PHP Web 服务器通过proc_open+ JSON stdin/stdout 调用（PHP 模式的替代方案，更轻量）。clean.py：清理tmp下的生成数据。python clean.py # 仅清 models/uploads 内容与 *.log python clean.py --all # 额外清除 tmp 下其他临时产物 python clean.py --yes # 跳过确认
scripts/zhiju-ctl.sh：Linux 服务管理（start/stop/restart/status）。scripts/zhiju-ctl.ps1：Windows 服务管理（同上）。
Q：上传后提示"处理失败 / 422"？
A：确认压缩包为有效 zip 且内含 Gerber 文件（至少含一个非钻孔层）。错误详情写入 tmp/upload_err.log。
Q：多板没有分成多个 Tab？
A：检查压缩包内布局——扁平布局需各层文件共享文件名主干；嵌套布局需把每块板的文件放入独立子目录。
Q：改了 config.json 但没生效？
A：网页「参数面板」点「保存并重新生成」会即时写回文件并对当前任务重生成；若直接改文件，下次上传/测数据或点「保存并重新生成」即生效。
Q：3D 视图空白/不显示？
A：检查浏览器是否加载本地 vendor/three.module.js；服务需正常提供 /static/。模型加载依赖 /api/model/{job_id}.stl 存在。
Q：如何离线部署？
A：前端 Three.js 已本地化（static/vendor/），后端纯 Python 依赖，安装 requirements.txt 后即可在内网运行，无需访问外网。
Q：Python 和 PHP 两种 Web 服务器有什么区别？
A：功能完全相同。Python 模式更简单，零额外依赖；PHP 模式适合已有 nginx+PHP 环境的用户。前端会自动适配，无需手动配置。详见 双 Web 服务器。
本项目采用 AGPL-3.0 + 商业许可 双许可证模式：
- 个人 / 学术 / 研究：在 AGPL-3.0 条款下完全免费使用、修改和分发。
- 商业使用：AGPL-3.0 要求公开全部源码（包括网络服务的修改版本），如需闭源商业使用，请获取单独的商业许可。
详见：
- LICENSE — 英文原版
- LICENSE.zh-CN.md — 中文参考译文 + 商业许可声明
- 3D 几何：
trimesh/manifold3d - 2D 几何：
shapely - Web 框架：
FastAPI+uvicorn - 前端渲染：
Three.js