docs: 完善项目文档和使用说明

- 更新README.md,补充GUI特性说明和参数配置文档
- 新增使用说明目录,包含完整的操作手册和界面截图
- 优化generate_template.py,支持自定义模板输出路径
- 改进GUI界面布局,优化文件上传和模板导出功能
- 添加系统参数配置说明(电压、功率因数等)
This commit is contained in:
dmy
2026-01-05 23:30:29 +08:00
parent c6168afd1d
commit b924f75add
10 changed files with 208 additions and 36 deletions

View File

@@ -4,15 +4,15 @@
## 🌟 主要功能
- 🖥️ **交互式 Web 界面**:基于 NiceGUI 开发,支持文件上传、实时日志、方案对比和可视化
- 🖥️ **原生桌面体验**:支持 Native 模式运行,提供类似本地应用的流畅体验(基于 NiceGUI & PyWebview
- 🌊 **多种布局生成**:内置模拟数据生成器,支持规则网格和随机分布布局。
- 🔌 **先进设计算法**
- **MST (Minimum Spanning Tree)**:无容量约束基准方案。
- **Capacitated Sweep (Base)**:基础扇区扫描分组。
- **Rotational Sweep**:全局最优起始角度旋转扫描优化。
- **Esau-Williams**:经典启发式算法,在距离与容量间寻找最优平衡。
- ⚙️ **灵活参数配置**:支持通过 Excel 自定义系统电压、功率因数及详细电缆规格。
- 📊 **智能方案对比**:自动运行三大场景(标准方案、含可选电缆方案、限制最大截面方案)并对比结果。
- 📋 **数据校验与保障**:严格校验输入数据的有序性及电缆配置规则。
- 📁 **多格式导出**
- 自动生成 CAD 图纸 (`.dxf`),按电缆规格分层并着色。
- 导出详细的 Excel 对比报告及单方案电缆清册。
@@ -23,19 +23,24 @@
本项目使用 `uv``pip` 管理环境。推荐安装依赖:
```bash
pip install numpy pandas matplotlib scikit-learn scipy networkx ezdxf nicegui openpyxl
pip install numpy pandas matplotlib scikit-learn scipy networkx ezdxf nicegui openpyxl pywebview
```
*注:`pywebview` 用于支持原生窗口模式。*
## 🚀 使用方法
### 1. 启动图形化界面 (推荐)
运行以下命令启动 Web 界面,程序将自动在浏览器中打开
运行以下命令启动应用,程序将自动弹出独立窗口
```bash
python gui.py
```
*注:程序默认监听 8080 端口,若被占用将自动尝试后续可用端口。*
**GUI 特性:**
- **模板导出**:点击界面上的 "导出 Excel 模板" 按钮可获取标准输入格式文件。
- **参数概览**:上传文件后自动解析并显示系统参数及电缆规格。
- **交互式分析**:点击结果表格中的行,可实时查看对应方案的拓扑图。
### 2. 命令行模式
@@ -45,7 +50,7 @@ python main.py --excel your_data.xlsx
## 📝 输入数据规范 (Excel)
为了确保计算结果的准确性,输入 Excel 文件应包含以下两个 Sheet
为了确保计算结果的准确性,输入 Excel 文件应包含以下 Sheet(推荐使用 GUI 导出模板)
### 1. Coordinates (坐标)
| Type | ID | X | Y | Power | PlatformHeight |
@@ -61,6 +66,14 @@ python main.py --excel your_data.xlsx
- `Optional` 列标记为 'Y' 的电缆最多只能有一条。
- 若存在可选电缆,它必须是列表中截面最大的一条。
### 3. Parameters (参数) [可选]
可自定义系统级参数,若不提供则使用默认值。
| Parameter | Value | 说明 |
|-----------|-------|------|
| Voltage (kV) | 66 | 系统电压,支持 `Voltage``System Voltage`。若 key 包含 `kV` 则自动 *1000。 |
| Power Factor | 0.95 | 功率因数 (0-1)。 |
## 📈 场景说明 (Scenarios)
1. **Scenario 1 (Standard)**:仅使用非可选(标准)电缆进行优化。