lightcad · diff
git:20260922.e0d0947 to git:20261014.e943c53
160 added, 172 removed. Audit B to A.
---
name: lightcad
- description: "Use when embedding lightweight 2D CAD features in web applications — basic drawing, layer management, snapping, DXF import. LightCAD: lightweight Web 2D CAD framework for browser-based drafting."
+ description: "Use when building or extending a desktop CAD/BIM application with the open-source FeiYang LightCAD platform — plugin development, custom elements, DWG/DXF I/O, 2D drafting and 3D/BIM modeling on C#/.NET. LightCAD: 飞扬集成设计平台, a C# CAD system integrating 2D design, 3D design, and BIM."
tags:
- - web
- - 2d
+ - csharp
+ - dotnet
- cad
- - dxf
- - typescript
- - drafting
+ - bim
+ - 2d
+ - 3d
+ - dwg
+ - plugin
+ - architecture
---
- > **项目地址：** 原仓库 `github.com/light-CAD/lightcad` 已404，请以 [znlgis.github.io](https://znlgis.github.io/cad/LightCAD/) 为准
+ > **项目地址：** <https://github.com/znlgis/lightcad1>
>
- > **官网/演示：** <https://lightcad.cn/>
+ > **所属平台：** 飞扬集成设计平台（LightCAD，启道软件 Qidao Soft 开源）
>
- > **许可证：** MIT / Apache-2.0（视仓库声明）
+ > **许可证：** CC-BY-SA-4.0（见仓库 LICENSE）
+ >
+ > **中文教程：** <https://znlgis.github.io/cad/LightCAD/>（20 章，从架构到插件实战）
+ >
+ > **版本：** 仓库暂无公开 Release/Tag，以 master 分支为准（截至2026-10）
## 概述
- LightCAD 主要特性：
-
- - **纯前端 CAD**：HTML5 Canvas / WebGL 渲染，无插件
- - **AutoCAD 风格命令行**：line / circle / pline / trim / mirror …
- - **DXF 互通**：导入导出 DXF（基于 dxf-parser/dxf-writer）
- - **图层 / 块 / 标注 / 文字**
- - **可嵌入**：iframe 或 Web Component
- - **二次开发 API**：JS/TS 对应实体、命令、事件、UI
+ LightCAD（飞扬集成设计平台）是一套基于 .NET 10 / C# 开发的开源建筑工程设计软件，目标是把二维设计、三维设计、BIM 设计、智能设计与协同设计融合为一体，为建筑设计行业提供 BIM 正向设计支撑能力。项目采用严格的分层架构（MathLib → Core → RenderUtils → Drawing → Runtime → UI），既可作为完整 CAD 平台使用，也可作为二次开发底座。核心特性：
- > 该项目处于活跃迭代阶段，下文以通用 Web CAD 二次开发为视角，如细节差异请以仓库 README 与 znlgis 教程为准。
+ - **完整 2D/3D 能力**：直线、圆弧、多段线、样条等二维图元；拉伸、旋转、放样、融合等参数化实体建模
+ - **多渲染后端**：Three.js4Net（WebGL）与 OpenTK（OpenGL）
+ - **DWG/DXF 兼容**：通过 ODA SDK 与内置 netDxf 处理 AutoCAD 文件格式，另支持 SketchUp 导入
+ - **插件体系**：基于 Weikio Plugin Framework 运行时加载；预置建筑（QdArch）、电气（QdElectric）、暖通（QdHvac）、结构（QdStruct）、给排水（QdWater）五大行业插件
+ - **视图构建**：正交投影、截面视图、详图生成
---
- ## 安装与试用
-
- ### 在线试用
-
- 直接打开 <https://lightcad.cn/> 体验。
+ ## 环境准备
- ### 嵌入 iframe
+ ### 前置条件
- ```html
- <iframe src="https://lightcad.cn/" style="width:100%;height:100vh;border:0"></iframe>
- ```
+ | 项 | 要求 |
+ |----|------|
+ | 操作系统 | Windows 10（1909+）/ Windows 11 64 位 |
+ | 开发工具 | Visual Studio 2026（.NET 桌面开发工作负载）或 `dotnet` CLI |
+ | SDK | .NET 10 SDK |
+ | 硬件 | 8GB 内存起（推荐 16GB+），支持 OpenGL 3.3 的显卡 |
- ---
+ ### 获取源码与编译（命令行方式）
- ## 嵌入到自有应用（SDK）
+ ```bash
+ # 仓库体积较大（含 DLL 与资源），建议浅克隆
+ git clone --depth 1 https://github.com/znlgis/lightcad1.git
+ cd lightcad1
- ```html
- <div id="cad" style="width:100%;height:100vh"></div>
- <script type="module">
- // ⚠ npm 仓库目前查无 @lightcad/sdk 包（404），请以 znlgis 文档 / 源码构建为准
- import { LightCAD } from '@lightcad/sdk';
+ # 还原与编译
+ dotnet restore LightCAD1.sln
+ dotnet build LightCAD1.sln --configuration Debug
+ ```
- const app = new LightCAD({
- container: '#cad',
- locale: 'zh-CN'
- });
- await app.init();
+ ### 运行（VS 或 CLI）
- // 直接执行命令
- app.exec('line 0,0 100,100');
- </script>
+ ```bash
+ # VS：用 Visual Studio 打开 LightCAD1.sln，将 LightCAD.WinForm 设为启动项目，按 F5
+ # CLI：
+ dotnet run --project src/LightCAD.WinForm
```
+ **验证**：稳定编译后启动主窗口即成功；插件调试采用 VS「附加到进程」绑定 `lightcad` 进程（参见 FY_Layout 插件示例的做法）。
+
---
- ## 命令行用法（与 AutoCAD 类似）
+ ## 解决方案结构（关键项目）
- | 命令 | 功能 | 示例 |
- |------|------|------|
- | `line` / `l` | 直线 | `line 0,0 100,0` |
- | `circle` / `c` | 圆 | `c 50,50 r 20` |
- | `pline` / `pl` | 多段线 | `pl 0,0 10,0 10,10` |
- | `arc` / `a` | 圆弧（3点 / 起-中-终） | `a 0,0 10,10 20,0` |
- | `rect` / `re` | 矩形 | `re 0,0 100,50` |
- | `text` | 文字 | `text 0,0 "Hello"` |
- | `dimlinear` | 线性标注 | |
- | `move/mv` | 平移 | |
- | `copy/cp` | 复制 | |
- | `mirror/mi` | 镜像 | |
- | `trim/tr` | 修剪 | |
- | `extend/ex` | 延伸 | |
- | `fillet/f` | 圆角 | `f 10` 后选两条线 |
- | `chamfer/cha` | 倒角 | |
+ | 项目 | 职责 |
+ |------|------|
+ | `LightCAD.MathLib` | 向量/矩阵、曲线数学、几何求交（`Vector2`/`Vector3` 等） |
+ | `LightCAD.Core` | 核心数据模型：`LcDocument`、图元实体（`LcElement`）、`ElementType`、元素空间 |
+ | `LightCAD.RenderUtils` | Three.js4Net 桥接、资源与事件、三维控件 |
+ | `LightCAD.Drawing` / `LightCAD.Drawing.Actions` | 视口、输入系统、捕捉、交互 Action（`IDocumentEditor`） |
+ | `LightCAD.Runtime` | 应用运行时：`ILcPlugin`、`PluginManager`、命令框架（`CommandClass`/`CommandMethod`） |
+ | `LightCAD.Model` / `LightCAD.UI.WinForm` / `LightCAD.WinForm` | 模型控件、UI 层与主程序入口 |
+ | `LightCAD.ImportAndExport` | DWG/DXF/SketchUp 导入导出 |
+ | `Plugins/` | 预编译行业插件（QdArch 等） |
+ | `netDxf`、`Libs/`、`ThirdParty/` | DXF 库源码、本地 DLL（ThreeJs4Net/OpenTK）、第三方源码 |
---
- ## 实体与图层（API）
+ ## 核心 API
- ```ts
- // 添加实体
- const id = app.add('LINE', { p1: [0,0], p2: [100,100] });
- app.add('CIRCLE', { center: [50,50], radius: 20, layer: 'WALL' });
+ ### 图元实体（LightCAD.Core）
- // 修改
- app.update(id, { color: '#ff0000', lineWeight: 0.3 });
+ 二维基本图元以 `Lc` 前缀命名，与 AutoCAD 习惯一致：
- // 查询
- const entities = app.query({ type: 'LINE', layer: 'WALL' });
+ ```csharp
+ using LightCAD.Core;
- // 删除
- app.remove(id);
+ // 常见二维图元
+ var line = new LcLine(); // 直线
+ var circle = new LcCircle(); // 圆
+ var arc = new LcArc(); // 圆弧
+ var pline = new LcPolyLine(); // 多段线
+ var ell = new LcEllipse(); // 椭圆
+ var hatch = new LcHatch(); // 填充
+ var text = new LcText(); // 文字
- // 图层
- app.layers.add('WALL', { color: '#0000ff', lineType: 'CONTINUOUS' });
- app.layers.setCurrent('WALL');
- app.layers.set('WALL', { visible: false });
+ // 元素加入文档模型空间
+ lcDocument.ModelSpace.Elements.Add(line);
```
- ---
-
- ## 块（Block）
+ 实体目录还包括三维图元（`Elements/Element3d`）、实体建模（`Elements/Solid`）、标注（`Elements/Dim`、`Dim3`）、表格（`Table`）等（详见仓库 `src/LightCAD.Core/Elements/`）。
- ```ts
- const blkId = app.blocks.create('CHAIR', {
- base: [0, 0],
- entities: [
- { type: 'CIRCLE', center: [0,0], radius: 5 },
- { type: 'LINE', p1: [-5,0], p2: [5,0] }
- ]
- });
+ ### 插件接口（LightCAD.Runtime）
- app.add('INSERT', { block: 'CHAIR', position: [10,10], rotation: 0, scale: 1 });
- ```
+ 插件入口实现 `ILcPlugin`，由 `PluginManager` 通过 Weikio Plugin Framework 加载：
- ---
+ ```csharp
+ using LightCAD.Runtime;
+ using LightCAD.Core;
- ## DXF 导入 / 导出
+ public class MyPlugin : ILcPlugin
+ {
+ public static TabItem MyTab = new TabItem { Name = "MyMajor", Text = "我的专业" };
- ```ts
- // 导入
- const dxfText = await fetch('/files/plan.dxf').then(r => r.text());
- app.io.importDXF(dxfText);
+ public void Loaded()
+ {
+ // 注册自定义元素类型（ElementType 需含唯一 Guid、Name、DispalyName 与 ClassType）
+ LcDocument.RegistElementTypes(MyElementType.All);
+ // 注册 2D/3D Action
+ LcDocument.ElementActions.Add(MyElementType.Device, new DeviceAction());
+ LcDocument.Element3dActions.Add(MyElementType.Device, new Device3dAction());
+ }
- // 导出
- const dxf = app.io.exportDXF();
- saveAs(new Blob([dxf]), 'out.dxf');
+ public void Completed()
+ {
+ AppRuntime.UISystem.AddInitTabItems(new[] { MyTab }); // 挂接 UI 菜单
+ }
- // 导出 SVG / PNG
- const svg = app.io.exportSVG();
- const png = await app.io.exportPNG({ width: 1920, height: 1080 });
+ public void OnInitializeDocRt(DocumentRuntime docRt) { }
+ public void OnDisposeDocRt(DocumentRuntime docRt) { }
+ }
```
- ---
-
- ## 事件
-
- ```ts
- app.on('selectionChanged', sel => console.log(sel.length, '已选'));
- app.on('commandStarted', name => console.log('命令', name));
- app.on('entityModified', e => console.log(e.id));
- app.on('mouseClick', e => console.log(e.world));
- ```
+ 插件目录通过主程序旁的 `plugins.json`（`folders` 数组）配置，`PluginManager.LoadPlugins()` 扫描加载。
- ---
+ ### 命令注册（CommandClass / CommandMethod）
- ## 自定义命令（插件）
+ ```csharp
+ using LightCAD.Core;
+ using LightCAD.Runtime;
- ```ts
- app.commands.register({
- name: 'mycross',
- handler: async (ctx) => {
- const p = await ctx.input.getPoint('选择中心点');
- ctx.app.add('LINE', { p1: [p.x-5, p.y], p2: [p.x+5, p.y] });
- ctx.app.add('LINE', { p1: [p.x, p.y-5], p2: [p.x, p.y+5] });
+ [CommandClass]
+ public class MyCmds
+ {
+ [CommandMethod(Name = "MyCross", ShortCuts = "MCX")]
+ public CommandResult DrawCross(IDocumentEditor docEditor, string[] args)
+ {
+ // 交互拾取与实体创建：参见 LightCAD.Drawing.Actions 中的 Action 基类
+ // ...
+ return CommandResult.Succ();
}
- });
- // 命令行：mycross
+ }
```
- ---
+ 命令行（命令行窗口 / 命令别名）与 AutoCAD 风格一致：`LINE`/`CIRCLE`/`PLINE`/`MOVE`/`COPY`/`MIRROR`/`TRIM` 等内置命令。
- ## 视图与导航
+ ### DWG 导入导出
- ```ts
- app.view.zoomExtents();
- app.view.zoomTo([0,0,100,100]);
- app.view.pan(10, 0);
- app.view.rotate(15);
+ `LoadDwg` / `SaveDwg` 命令即为导入导出入口（`LightCAD.ImportAndExport`）：
+
+ ```csharp
+ var lcDocument = DwgReader.Import(filePath); // 读入 DWG → LcDocument
+ // 修改 lcDocument.ModelSpace.Elements 后
+ // 通过 SaveDwg 命令或导出器写回 DWG/DXF
```
---
- ## 性能优化
+ ## 端到端工作流
- 1. **批量添加实体**用 `app.batch(() => { ... })` 包装，仅刷新一次
- 2. **大量绘制**关闭实时 OSNAP、网格
- 3. **DXF 导入大文件**用 Web Worker 解析后再注入
- 4. **样式复用**：定义图层与块，避免每个实体重复样式
- 5. **PNG 导出**注意分辨率与字体加载
+ ### 工作流一：从源码构建并运行平台
- ---
+ 1. 安装 .NET 10 SDK 与 VS2026（.NET 桌面开发工作负载）
+ 2. `git clone --depth 1 https://github.com/znlgis/lightcad1.git`
+ 3. `dotnet restore LightCAD1.sln` → `dotnet build LightCAD1.sln -c Debug`
+ 4. 启动 `LightCAD.WinForm`，在命令行窗口输入 `LINE` 画一条直线验证交互
+ 5. 用 `LoadDwg`/`SaveDwg` 打开与保存 DWG 图纸验证文件链路
- ## 常见问题
+ ### 工作流二：开发一个行业插件（元素 + 命令 + Action）
- | 问题 | 解决 |
- |------|------|
- | DWG 不支持 | 先用 ODA File Converter / LibreDWG 转 DXF |
- | 中文乱码 | DXF 文件编码为 UTF-8；字体配置 `Noto Sans CJK SC` |
- | 标注比例小 | 设置 `dimstyle.scale` |
- | 与业务集成 | 监听 `app.on('entityModified', ...)` 同步到后端 |
+ 1. 新建类库项目（`net10.0-windows`），引用平台项目或 `Libs/` 下的 SDK DLL（LightCAD.Core、LightCAD.Runtime、LightCAD.Drawing.Actions、LightCAD.MathLib 等）
+ 2. 定义 `ElementType` 静态集合（唯一 Guid、Name、`DispalyName`、`ClassType`），实体类继承 `LcElement`
+ 3. 实现 `ILcPlugin`：在 `Loaded()` 注册元素类型与 2D/3D Action，在 `Completed()` 挂接菜单 Tab
+ 4. 用 `[CommandClass]`/`[CommandMethod]` 编写用户命令，内部驱动 Action 完成交互绘制
+ 5. 编译后把 DLL 放入插件目录（或配置 `plugins.json` 的 `folders`），启动平台验证命令可执行
+ 6. VS 中以「附加到进程」调试 `lightcad` 进程；参考完整示例：<https://github.com/znlgis/FY_Layout>
---
- ## AI 使用建议
+ ## 最佳实践
- - **推荐工作流模式**：AI 助手应区分「在线使用」（用户直接操作 GUI）和「SDK 嵌入」（`LightCAD` 类实例化）。SDK 模式按「app.init() → app.exec(command) 或 app.add(entity) → app.io.exportDXF()」的流程操作。批量添加实体用 `app.batch(() => {...})` 包装。
- - **关键注意事项**：① DWG 不支持直接读写，需先用 ODA/LibreDWG 转 DXF；② DXF 文件编码保持 UTF-8，中文文字配置 `Noto Sans CJK SC` 字体；③ 大文件 DXF 导入建议用 Web Worker 解析；④ 标注比例通过 `dimstyle.scale` 设置。
- - **常用代码模式**：SDK 初始化：`new LightCAD({ container: '#cad', locale: 'zh-CN' })` → `app.init()` → `app.exec('line 0,0 100,100')`。自定义命令：`app.commands.register({ name, handler: async (ctx) => { const p = await ctx.input.getPoint('...'); ... } })`。
+ 1. **分层依赖**：业务代码只引用 `LightCAD.Core`/`LightCAD.MathLib`，UI 与交互逻辑放 Action 层，避免循环依赖
+ 2. **元素类型 GUID 稳定**：`ElementType.Guid` 是序列化标识，发布后不可更改；注意 SDK 属性拼写为 `DispalyName`
+ 3. **命令薄、Action 厚**：`[CommandMethod]` 只做参数解析与转发，交互逻辑放入 Action 类便于复用与调试
+ 4. **大仓库浅克隆**：仓库含大量 DLL/字体资源，开发机建议 `--depth 1`
+ 5. **渲染路径分离**：2D 显示与 3D 显示（ThreeJs4Net/OpenTK）分别验证，避免把 2D 交互问题误判为渲染问题
+ 6. **DWG 兼容性**：DWG 读写依赖 ODA 相关 DLL，分发插件时确认 `Libs/` 依赖完整
---
- ## 相关技能
+ ## 常见问题
- - **librecad** — 开源桌面 2D CAD，DXF 编辑：[../librecad/SKILL.md](../librecad/SKILL.md)
- - **qcad** — 2D CAD 软件，ECMAScript 脚本扩展：[../qcad/SKILL.md](../qcad/SKILL.md)
- - **chili3d** — Web 3D CAD，类似的前端架构模式：[../chili3d/SKILL.md](../chili3d/SKILL.md)
- - **astral3d** — Web 3D 可视化框架，可配合展示 LightCAD 模型：[../astral3d/SKILL.md](../astral3d/SKILL.md)
+ | 问题 | 解决 |
+ |------|------|
+ | 编译报「找不到 ThreeJs4Net.dll / OpenTK.dll」 | 确认仓库 `src/Libs/` 下 DLL 完整（部分二进制依赖未随 Git 提供时需从发布包获取） |
+ | `The current .NET SDK does not support targeting .NET 10` | 安装最新 .NET 10 SDK |
+ | WinForms 项目在非 Windows 上编译失败 | `net10.0-windows` 项目仅支持 Windows 编译与运行 |
+ | NuGet 还原失败（NU1301） | 检查网络或配置国内 NuGet 镜像源 |
+ | 插件不加载 | 检查 `plugins.json` 的 `folders` 配置、DLL 是否位于扫描目录、是否实现 `ILcPlugin` |
+ | 命令行输入命令无响应 | 确认平台已启动文档（文档未初始化时命令框架不执行） |
+ | DWG 打开异常 | 确认目标版本受 ODA 支持；必要时先用 ODA File Converter 转存 |
---
- ## 典型工作流
-
- ### 工作流一：嵌入业务系统作为在线绘图组件
-
- 1. iframe 嵌入，或从源码构建（⚠ npm 仓库暂无 `@lightcad/sdk` 包，勿直接 `pnpm install`）
- 2. 在页面中创建容器 `<div>`，实例化 `LightCAD` 并初始化
- 3. 注册自定义命令（如绘制特殊符号/标注）
- 4. 监听 `entityModified`/`selectionChanged` 事件同步数据到后端
- 5. 提供 DXF 导入/导出按钮，调用 `app.io.importDXF()`/`app.io.exportDXF()`
- 6. 可选：导出 SVG/PNG 用于报表或预览
-
- ### 工作流二：命令行驱动快速绘图
+ ## 相关技能
- 1. 初始化 LightCAD 实例后，通过 `app.exec()` 发送 AutoCAD 风格命令
- 2. `app.exec('line 0,0 100,100')` 绘制直线
- 3. `app.exec('circle 50,50 r 20')` 绘制圆
- 4. `app.exec('rect 0,0 100,50')` 绘制矩形
- 5. `app.io.exportDXF()` 导出为 DXF 文件
+ - **fy_layout** — 飞扬平台场地布置插件示例（完整的插件工程结构与 SDK 用法）：[../fy_layout/SKILL.md](../fy_layout/SKILL.md)
+ - **ifoxcad** — AutoCAD .NET 二次开发框架（对照参考另一种 .NET CAD 插件模式）：[../ifoxcad/SKILL.md](../ifoxcad/SKILL.md)
+ - **xbim** — .NET BIM/IFC 工具包（BIM 数据交换互补）：[../xbim/SKILL.md](../xbim/SKILL.md)
+ - **libredwg** — DWG/DXF 读写库（文件格式侧互补）：[../libredwg/SKILL.md](../libredwg/SKILL.md)
---
## 参考资源
- - 原仓库（已下线）：<https://github.com/light-CAD/lightcad>
- - 文档与示例：<https://lightcad.cn/docs>
- - 中文教程（znlgis）：<https://znlgis.github.io/cad/LightCAD/>
-
- > 该 SKILL 基于 Web CAD 通用模式整理，具体 API 命名以最新版本仓库为准。
+ - 仓库：<https://github.com/znlgis/lightcad1>
+ - 中文教程（20 章）：<https://znlgis.github.io/cad/LightCAD/>
+ - 插件示例仓库：<https://github.com/znlgis/FY_Layout>
+ - 关键章节：第 3 章（分层架构）、第 15 章（插件系统与扩展开发）、第 16 章（命令与操作系统）