# leadE_desktop

**Repository Path**: elead_3/lead-e_desktop

## Basic Information

- **Project Name**: leadE_desktop
- **Description**: leeade的桌面端探索
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# leadE_desktop —— 参数化 3D CAD（C++ 核心 + Electron 桌面端）

> ⚠️ **项目状态：探索中（WIP）**
>
> 本项目目前仍处于早期探索与原型验证阶段，架构、接口和功能均可能调整，暂不建议用于生产环境。
>
> 按时间线规划，桌面端预计在 **2027 年 3 月** 正式推出（将在 Web 版本稳定之后启动）。

参数化 3D CAD 系统：2D 草图绘制 + 几何/尺寸约束求解 + 三维特征（拉伸/回转/倒圆/倒角）。

## 平台支持

本系统支持跨平台桌面输出：

| 平台 | 架构 | 状态 | 说明 |
|------|------|------|------|
| **macOS** | Apple Silicon (arm64) | ✅ 已支持 | M1/M2/M3/M4 等，专用打包脚本 |
| **macOS** | Intel (x86_64) | ✅ 已支持 | Intel 芯片 Mac，专用打包脚本 |
| **Windows** | x86_64 | ✅ 已支持 | CMake 编译 .dll + Electron 打包 |
| **鸿蒙 PC** | arm64/x86_64 | 📋 规划中 | 未来支持（NAPI 封装 C++ 核心 + ArkUI） |

> 三端共享同一份 C++ 核心（`native-core/`）和同一套 C ABI，桌面 UI 基于 Electron 跨平台一致。
> macOS 提供两个独立的架构版本，针对不同芯片优化，用户按机型选择对应版本。

### macOS 打包命令

仓库提供专用打包脚本（位于 `scripts/`）：

```bash
# 打包 Apple Silicon 版本（M1/M2/M3/M4 Mac）
./scripts/build-macos-apple-silicon.sh
# 产出：desktop/dist/leadE_desktop-apple-silicon.app

# 打包 Intel 版本（Intel 芯片 Mac）
./scripts/build-macos-intel.sh
# 产出：desktop/dist/leadE_desktop-intel.app

# 一次性打包两个架构版本
./scripts/build-macos-all.sh
```

脚本会自动完成：
1. 用 CMake 编译对应架构的 C++ 核心（`libcad_core.dylib`）
2. 构建 viewer3d 前端（Vue3 + Vite），产物放到 `desktop/viewer-dist/`
3. 安装 Electron 依赖，编译 TypeScript
4. 基于 Electron.app 模板组装 `.app`（dylib 和 viewer-dist 打入 Resources）
5. 配置 Info.plist + ad-hoc 签名

> **环境要求**：Node.js 18+（构建 viewer3d 前端需要）。脚本会通过 nvm 自动切换到合适的 Node 版本。

### Windows 打包命令

```bash
# 一键构建 Windows x86_64 版本（Git Bash 下运行）
./scripts/build-windows-x64.sh
# 产出：desktop/dist/win-unpacked/leadE_desktop.exe
```

**前置依赖（首次）**：
- Visual Studio 2022 Build Tools，安装时勾选 **"Desktop development with C++"** workload（含 MSVC + Windows SDK）
- CMake（`winget install Kitware.CMake`）
- Node.js 20+（推荐 22/24）
- Git Bash（安装 git for Windows 即附带）

脚本一次完成 6 个阶段，每个阶段都处理了 Windows 构建链中的已知坑（见脚本内注释）：
1. 编译 C++ 核心（MSVC + CMake → `cad_core.dll`，经 `native-core/build-win.cmd`）
2. 构建 Viewer（`viewer3d/frontend` 的 `build:project` → `desktop/viewer-dist/`）
3. 构建 cadgen（`pi_cadgen_cli` 的 `tsc` → `desktop/cadgen-dist/`，含依赖）
4. desktop 依赖（`npm install` + patch node-pty 的 Spectre 编译问题 + 创建 xterm `vendor/`）
5. 编译 TypeScript（`npm run build`）
6. electron-builder 打包（`afterPack.js` 钩子自动把 cadgen 的 `node_modules` 拷进产物）

产物含三个 tab：**Viewer**（3D 模型查看器）、**Editor**（参数化 CAD）、**TUI**（pi_cadgen_cli 自然语言建模终端）。

> **交叉编译**：在 macOS/Linux 上交叉编译 Windows 版本需 MinGW-w64（`brew install mingw-w64`），但 viewer/cadgen/TUI 的完整构建仅支持 Windows 原生环境（node-pty 需 MSVC）。

## 架构
```
┌─────────────────────────────────────────────────┐
│  Electron 桌面端（desktop/）                     │
│  UI（HTML/Canvas/Three.js） + 交互              │
├─────────────────────────────────────────────────┤
│  koffi FFI（Node.js 调 C ABI）                  │
├─────────────────────────────────────────────────┤
│  C ABI（native-core/include/cad/c_api.h）        │
│  extern "C" 接口，不透明句柄                     │
├─────────────────────────────────────────────────┤
│  C++ 核心（native-core/）                        │
│  几何图元 / 约束求解 / 参数化 / 三维特征         │
└─────────────────────────────────────────────────┘
```

## 目录结构
```
leadE_desktop/
├── native-core/              C++ 核心（几何内核）
│   ├── include/cad/          公共头文件
│   │   ├── geometry.h        Vec2 / Point / Line / Circle / Arc / Rect
│   │   ├── constraint.h      11 类约束
│   │   ├── sketch.h          Sketch 文档模型
│   │   ├── solver.h          约束求解器（投影梯度 + 高斯-牛顿）
│   │   ├── param.h           参数表（参数化驱动）
│   │   ├── feature.h         拉伸/回转/倒圆/倒角
│   │   └── c_api.h           C ABI（FFI 边界）
│   ├── src/                  实现
│   ├── tests/                GoogleTest 单元测试
│   └── examples/             C API 示例
│
└── desktop/                  Electron 桌面端
    ├── src/
    │   ├── main.ts           Electron 主进程（IPC）
    │   ├── preload.ts        安全桥接（contextBridge）
    │   ├── cad_binding.ts    koffi FFI 绑定（调 C ABI）
    │   ├── renderer.ts       渲染层（草图 Canvas + 特征 Three.js）
    │   ├── viewport3d.ts     Three.js 3D 视口
    │   └── renderer/         HTML + CSS
    └── package.json
```

## 功能

### 草图模式（2D）
- 绘制：点 / 直线 / 圆 / 矩形
- 约束：距离 / 水平 / 竖直 / 平行 / 垂直 / 半径
- 实时约束求解（投影梯度下降 + 高斯-牛顿两阶段算法）

### 特征模式（3D）
- 拉伸（Extrude）：草图轮廓沿 z 轴拉伸成实体
- 回转（Revolve）：草图绕 y 轴旋转生成回转体
- 倒圆（Fillet）：尖边圆角过渡
- 倒角（Chamfer）：尖边斜角过渡
- Three.js WebGL 渲染（实心面 + 光照 + 锐边线框，CAD 风格）
- 轨道相机（拖拽旋转 / 滚轮缩放）

## 构建

### 1. 编译 C++ 核心（产出 dylib）
```bash
cd native-core
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
cmake --build build -j --target cad_core_shared
```

### 2. 启动 Electron 桌面端
```bash
cd desktop
npm install
npm run build
npm start
```

## 核心算法

### 约束求解器
- 自由度 = 每个被约束 2D 点的 (x, y)
- 每个约束残差 r(p)，总能量 E = Σ r²
- 阶段 1：投影梯度下降（Armijo backtracking line search）粗调
- 阶段 2：高斯-牛顿法（带 LM 阻尼）精修，二次收敛
- 残差全部用线性形式（避免平方残差在解附近梯度消失）

### C ABI
`include/cad/c_api.h` 暴露纯 C 接口，是所有外部语言桥接的统一边界：
- 不透明句柄 `cad_Sketch*` / `cad_Mesh*`
- 内存所有权清晰（create / destroy 配对）
- 输出数组用 copy 模式（调用方分配 TypedArray，C++ 拷贝）