🚀 Su.Revit.HelixToolkit.SharpDX 使用说明文档

🌐 项目地址

GitHub: https://github.com/ViewSuSu/Su.Revit.HelixToolkit.SharpDX
Gitee: https://gitee.com/SususuChang/su.-revit.-helix-toolkit.-sharp-dx

🎬 演示动画

---

📦 安装方式

通过 NuGet 安装（推荐）

# Package Manager
Install-Package Su.Revit.HelixToolkit.SharpDX

# .NET CLI
dotnet add package Su.Revit.HelixToolkit.SharpDX

包引用 (csproj)

<PackageReference Include="Su.Revit.HelixToolkit.SharpDX" Version="1.0.0" />

---

📖 简介

Su.Revit.HelixToolkit.SharpDX 是一个专为 Revit 插件开发设计的高性能 3D 可视化工具库。基于 HelixToolkit.Wpf.SharpDX 开发，提供了简单易用的 API 来在 Revit 插件中创建功能丰富的 3D 视图窗口。

核心特性:

• 🚀 高性能渲染: 对 Solid 三角面进行了索引优化，能够承载海量三角面数据的 Solid 模型
• 🎯 完整交互: 支持鼠标悬停高亮、点击选择、多选、旋转、缩放、平移等完整交互功能
• 📐 坐标系适配: 自动处理 Revit 与 Helix 坐标系转换，无缝集成
• 🎨 材质系统: 支持 Revit 原生材质、自定义颜色、贴图材质等多种渲染方式
• ⚡ 内存优化: 高效的几何数据管理和内存释放机制

---

🎯 快速开始

⚡ 基本使用

// 1. 📦 初始化构建器
var builder = HelixViewport3DBuilder.Init(
    revitDocument, 
    geometryObjects, 
    new Viewport3DXOptions()
);

// 2. 🖥️ 获取 3D 视口控件
Viewport3DX viewport = builder.Viewport;

// 3. 📝 将 viewport 添加到你的 WPF 窗口中

🔥 完整示例

// 准备要显示的几何对象
var geometryObjects = new List<GeometryObjectOptions>
{
    // 添加你的几何对象...
};

// 🎨 配置视口选项
var visualOptions = new Viewport3DXOptions
{
    BackgroundColor = System.Windows.Media.Colors.LightGray,
    FXAALevel = 4 // 抗锯齿等级
};

// 🏗️ 创建构建器
var builder = HelixViewport3DBuilder.Init(
    document, 
    geometryObjects, 
    visualOptions
);

// 📐 设置相机视图
builder.SetCamera(revitView);

// ✨ 启用交互功能
builder.SetHoverHighlightEnabled(true)
       .SetClickHighlightEnabled(true);

---

🎮 交互功能

🖱️ 鼠标操作

操作	功能	图标
🖱️ 中键双击	缩放至视图范围	🔍
🖱️ 中键拖动	平移视图	👐
🖱️ Shift + 右键	旋转视角	🔄
🖱️ 鼠标悬停	半透明高亮显示	👆
🖱️ 左键点击	选中模型	✅
🖱️ Ctrl + 点击	多选模型	📋

🎨 高亮功能

// 🌈 设置高亮颜色
builder.SetHighlightColor(Colors.Red, 0.8f);  // 红色高亮

// 💫 启用闪烁效果
builder.SetHighlightBlinking(true, 100);  // 100ms 闪烁间隔

// 🔧 程序化高亮特定对象
builder.HighlightGeometryObject(specificGeometry);

---

📊 视图控制

🎥 相机设置

// 方法1: 使用 Revit 视图
builder.SetCamera(revitView);

// 方法2: 自定义相机
builder.SetCamera(
    new XYZ(0, 0, 10),     // 📍 相机位置
    new XYZ(0, 0, -1),     // 👀 观察方向
    new XYZ(0, 1, 0)       // ⬆️ 上方向
);

🧭 导航控件

• ✅ 视图立方体: 显示在右上角，点击快速切换视角
• ✅ 自动缩放: 载入时自动调整到合适视图范围
• ✅ 抗锯齿: 可配置的图形质量设置

---

🛠️ 高级功能

📡 事件监听

// 👂 监听模型选中事件
builder.OnModelSelected += (sender, args) => 
{
    var selectedModel = args.SelectedModel;
    var geometryObject = args.GeometryObject;
    var hitPoint = args.HitPoint;
    
    // 🎯 处理选中逻辑
    Console.WriteLine($"选中了模型: {geometryObject}");
};

// 👂 监听取消选中事件
builder.OnModelDeselected += (sender, args) => 
{
    // 🗑️ 清除选中状态
};

🔍 选择管理

// 📋 获取当前选中的模型
var selectedModels = builder.GetSelectedModels();

// 📋 获取当前选中的几何对象
var selectedGeometry = builder.GetSelectedGeometryObjects();

// 🧹 清除所有选择
builder.ClearHighlight();

---

⚙️ 配置选项

🎨 视觉配置

var options = new Viewport3DXOptions
{
    BackgroundColor = Colors.Black,      // 🎨 背景颜色
    FXAALevel = 8,                       // 🔍 抗锯齿等级 (0-8)
    EnableRenderFrustum = true          // 🎯 视锥体裁剪
};

🔧 功能开关

// 启用/禁用悬停高亮
builder.SetHoverHighlightEnabled(true);

// 启用/禁用点击高亮  
builder.SetClickHighlightEnabled(true);

---

🎨 GeometryObjectOptions 使用指南

📝 基本配置

GeometryObjectOptions 用于配置几何对象的渲染方式：

使用 Revit 材质

var options = new GeometryObjectOptions(
    geometryObject,    // 📐 Revit 几何对象
    revitMaterial      // 🎨 Revit 材质（可选）
);

使用自定义颜色

var options = new GeometryObjectOptions(
    geometryObject,           // 📐 Revit 几何对象
    Colors.Blue,              // 🔵 自定义颜色
    0.8f                      // 💧 透明度 (0-1)
);

使用贴图材质

var options = new GeometryObjectOptions(
    geometryObject,           // 📐 Revit 几何对象
    textureStream,            // 🖼️ 贴图流
    Colors.White,             // ⚪ 自发光颜色
    1.0f                      // 💧 透明度
);

⚙️ 渲染参数配置

var options = new GeometryObjectOptions(geometryObject, material)
{
    LevelOfDetail = 0.8,                              // 🎯 细节等级 (0-1)
    MinAngleInTriangle = 0,                           // 📐 三角面最小角度
    MinExternalAngleBetweenTriangles = Math.PI / 4,   // 📏 相邻面最小外角
    IsDrawSolidEdges = true,                          // 📏 绘制轮廓线
    SolidEdgeThickness = 2f,                          // 🖊️ 轮廓线粗细
    SolidEdgeSmoothness = 10f                         // ✨ 轮廓线平滑度
};

🔧 参数说明

参数	说明	默认值	影响
LevelOfDetail	渲染细节等级	0.5	值越高网格越密集，精度越高但性能消耗越大
MinAngleInTriangle	三角面最小夹角	0	控制网格生成时的平滑度
MinExternalAngleBetweenTriangles	相邻三角面最小外角	2π	判断曲面平滑过渡程度
IsDrawSolidEdges	是否绘制轮廓线	true	显示边界线条
SolidEdgeThickness	轮廓线粗细	2f	线条的像素宽度
SolidEdgeSmoothness	轮廓线平滑度	10f	数值越大边缘越平滑

---

💡 使用技巧

🚀 性能优化

• ✅ 使用 EnableSwapChainRendering 提升渲染性能
• ✅ 合理设置 FXAALevel 平衡画质和性能
• ✅ 及时调用 Clear() 释放资源
• ✅ 根据需求调整 LevelOfDetail，避免不必要的细节
• ✅ 利用 Solid 三角面索引优化处理海量数据

🎯 最佳实践

1. 📱 响应式设计: 视口会自动适应容器大小
2. 🔄 实时更新: 支持动态添加/移除几何对象
3. 🎮 用户友好: 提供直观的鼠标交互反馈
4. 🎨 视觉一致: 保持与 Revit 相似的视觉风格
5. ⚡ 性能平衡: 根据场景复杂度调整渲染参数
6. 💾 内存管理: 及时清理不再使用的几何对象

🔄 场景管理

// 🧹 清空场景
builder.Clear();

// 📦 重新添加对象
builder.Add(newGeometryObjects);

// 🎯 重置相机
builder.SetCamera(newView);

---

❓ 常见问题

❓ 如何更改高亮颜色？

builder.SetHighlightColor(Colors.Blue, 0.7f);  // 🔵 蓝色高亮

❓ 如何禁用所有交互？

builder.SetHoverHighlightEnabled(false)
       .SetClickHighlightEnabled(false);

❓ 如何获取点击位置的世界坐标？

builder.OnModelSelected += (sender, args) => 
{
    var worldPosition = args.HitPoint;  // 🌍 世界坐标
};

❓ 如何优化复杂模型的性能？

var options = new GeometryObjectOptions(geometryObject, material)
{
    LevelOfDetail = 0.3,      // 🎯 降低细节等级
    IsDrawSolidEdges = false  // 📏 禁用轮廓线绘制
};

❓ 如何处理材质透明度？

// 方法1: 使用颜色透明度
var options = new GeometryObjectOptions(geometryObject, Colors.Red, 0.5f);

// 方法2: 使用 Revit 材质的透明度
var material = document.GetElement(materialId) as Autodesk.Revit.DB.Material;
var options = new GeometryObjectOptions(geometryObject, material);

❓ 如何处理海量三角面的 Solid 模型？

// 库已内置三角面索引优化，自动处理海量数据
// 只需正常创建 GeometryObjectOptions 即可
var options = new GeometryObjectOptions(largeSolidModel, material);

---

📞 技术支持

如果在使用过程中遇到问题，请检查：

• ✅ Revit 文档对象是否正确传递
• ✅ 几何对象集合是否包含有效数据
• ✅ 视口控件是否正确添加到 WPF 可视化树
• ✅ 事件处理程序是否正确注册和注销
• ✅ 渲染参数是否在合理范围内
• ✅ 内存使用是否正常，及时调用 Clear() 释放资源

📚 更多资源

• 📖 完整源代码: 请访问上面的 GitHub 或 Gitee 仓库
• 💡 功能建议: 欢迎提交 Pull Request 或功能建议
• 📋 更新日志: 查看仓库的 Release 页面获取最新版本信息

---

🎉 开始使用 Su.Revit.HelixToolkit.SharpDX 创建出色的 3D 可视化体验吧！