lightcad git:20261015.6820988A

Immutable. This exact content never changes and is served at /api/v1/blob/94562d717712cbfb.

---
name: lightcad
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:
  - csharp
  - dotnet
  - cad
  - bim
  - 2d
  - 3d
  - dwg
  - plugin
  - architecture
---

> **项目地址：** <https://github.com/znlgis/lightcad1>
>
> **所属平台：** 飞扬集成设计平台（LightCAD，启道软件 Qidao Soft 开源）
>
> **许可证：** CC-BY-SA-4.0（见仓库 LICENSE）
>
> **中文教程：** <https://znlgis.github.io/cad/LightCAD/>（20 章，从架构到插件实战）
>
> **版本：** 仓库暂无公开 Release/Tag，以 master 分支为准（截至2026-10）

## 概述

LightCAD（飞扬集成设计平台）是一套基于 .NET 8 / C# 开发的开源建筑工程设计软件，目标是把二维设计、三维设计、BIM 设计、智能设计与协同设计融合为一体，为建筑设计行业提供 BIM 正向设计支撑能力。项目采用严格的分层架构（MathLib → Core → RenderUtils → Drawing → Runtime → UI），既可作为完整 CAD 平台使用，也可作为二次开发底座。核心特性：

- **完整 2D/3D 能力**：直线、圆弧、多段线、样条等二维图元；拉伸、旋转、放样、融合等参数化实体建模
- **多渲染后端**：Three.js4Net（WebGL）与 OpenTK（OpenGL）
- **DWG/DXF 兼容**：通过 ODA SDK 与内置 netDxf 处理 AutoCAD 文件格式，另支持 SketchUp 导入
- **插件体系**：基于 Weikio Plugin Framework 运行时加载；预置建筑（QdArch）、电气（QdElectric）、暖通（QdHvac）、结构（QdStruct）、给排水（QdWater）五大行业插件
- **视图构建**：正交投影、截面视图、详图生成

---

## 环境准备

### 前置条件

| 项 | 要求 |
|----|------|
| 操作系统 | Windows 10（1909+）/ Windows 11 64 位 |
| 开发工具 | Visual Studio 2022（17.5.5+，.NET 桌面开发工作负载）或 `dotnet` CLI |
| SDK | .NET 8 SDK |
| 硬件 | 8GB 内存起（推荐 16GB+），支持 OpenGL 3.3 的显卡 |

### 获取源码与编译（命令行方式）

```bash
# 仓库体积较大（含 DLL 与资源），建议浅克隆
git clone --depth 1 https://github.com/znlgis/lightcad1.git
cd lightcad1

# 还原与编译
dotnet restore LightCAD1.sln
dotnet build LightCAD1.sln --configuration Debug
```

### 运行（VS 或 CLI）

```bash
# VS：用 Visual Studio 打开 LightCAD1.sln，将 LightCAD.WinForm 设为启动项目，按 F5
# CLI：
dotnet run --project src/LightCAD.WinForm
```

**验证**：稳定编译后启动主窗口即成功；插件调试采用 VS「附加到进程」绑定 `lightcad` 进程（参见 FY_Layout 插件示例的做法）。

---

## 解决方案结构（关键项目）

| 项目 | 职责 |
|------|------|
| `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

### 图元实体（LightCAD.Core）

二维基本图元以 `Lc` 前缀命名，与 AutoCAD 习惯一致：

```csharp
using LightCAD.Core;

// 常见二维图元
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();       // 文字

// 元素加入文档模型空间
lcDocument.ModelSpace.Elements.Add(line);
```

实体目录还包括三维图元（`Elements/Element3d`）、实体建模（`Elements/Solid`）、标注（`Elements/Dim`、`Dim3`）、表格（`Table`）等（详见仓库 `src/LightCAD.Core/Elements/`）。

### 插件接口（LightCAD.Runtime）

插件入口实现 `ILcPlugin`，由 `PluginManager` 通过 Weikio Plugin Framework 加载：

```csharp
using LightCAD.Runtime;
using LightCAD.Core;

public class MyPlugin : ILcPlugin
{
    public static TabItem MyTab = new TabItem { Name = "MyMajor", Text = "我的专业" };

    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());
    }

    public void Completed()
    {
        AppRuntime.UISystem.AddInitTabItems(new[] { MyTab });   // 挂接 UI 菜单
    }

    public void OnInitializeDocRt(DocumentRuntime docRt) { }
    public void OnDisposeDocRt(DocumentRuntime docRt) { }
}
```

插件目录通过主程序旁的 `plugins.json`（`folders` 数组）配置，`PluginManager.LoadPlugins()` 扫描加载。

### 命令注册（CommandClass / CommandMethod）

```csharp
using LightCAD.Core;
using LightCAD.Runtime;

[CommandClass]
public class MyCmds
{
    [CommandMethod(Name = "MyCross", ShortCuts = "MCX")]
    public CommandResult DrawCross(IDocumentEditor docEditor, string[] args)
    {
        // 交互拾取与实体创建：参见 LightCAD.Drawing.Actions 中的 Action 基类
        // ...
        return CommandResult.Succ();
    }
}
```

命令行（命令行窗口 / 命令别名）与 AutoCAD 风格一致：`LINE`/`CIRCLE`/`PLINE`/`MOVE`/`COPY`/`MIRROR`/`TRIM` 等内置命令。

### DWG 导入导出

`LoadDwg` / `SaveDwg` 命令即为导入导出入口（`LightCAD.ImportAndExport`）：

```csharp
var lcDocument = DwgReader.Import(filePath);   // 读入 DWG → LcDocument
// 修改 lcDocument.ModelSpace.Elements 后
// 通过 SaveDwg 命令或导出器写回 DWG/DXF
```

---

## 端到端工作流

### 工作流一：从源码构建并运行平台

1. 安装 .NET 8 SDK 与 Visual Studio 2022（17.5.5+，.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）

1. 新建类库项目（`net8.0-windows`，与平台工程 TFM 保持一致），引用平台项目或 `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>

---

## 最佳实践

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/` 依赖完整

---

## 常见问题

| 问题 | 解决 |
|------|------|
| 编译报「找不到 ThreeJs4Net.dll / OpenTK.dll」 | 确认仓库 `src/Libs/` 下 DLL 完整（部分二进制依赖未随 Git 提供时需从发布包获取） |
| `The current .NET SDK does not support targeting .NET 8` | 安装 .NET 8 SDK（平台全部工程为 `net8.0` / `net8.0-windows` 目标） |
| WinForms 项目在非 Windows 上编译失败 | `net8.0-windows` 项目仅支持 Windows 编译与运行 |
| NuGet 还原失败（NU1301） | 检查网络或配置国内 NuGet 镜像源 |
| 插件不加载 | 检查 `plugins.json` 的 `folders` 配置、DLL 是否位于扫描目录、是否实现 `ILcPlugin` |
| 命令行输入命令无响应 | 确认平台已启动文档（文档未初始化时命令框架不执行） |
| DWG 打开异常 | 确认目标版本受 ODA 支持；必要时先用 ODA File Converter 转存 |

---

## 相关技能

- **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/znlgis/lightcad1>
- 中文教程（20 章）：<https://znlgis.github.io/cad/LightCAD/>
- 插件示例仓库：<https://github.com/znlgis/FY_Layout>
- 关键章节：第 3 章（分层架构）、第 15 章（插件系统与扩展开发）、第 16 章（命令与操作系统）