Navisworks API开发指南

我们未开办一个专门的Navisworks API中文博客，但Navisworks API 已经火了很多年。在我们和客户交流中得知，越来越多的项目在使用Navisworks，无论建筑设计，工程施工，或是机械制造，也有着越来越多的开发需求。借本博客发一篇文章仅供参考。

*****************************************************

这是一篇迟到的文章：）大家知道，Navisworks API已经火了很多年。而这几年也成长了很多开发高手。在我们和客户交流中得知，越来越多的项目在使用Navisworks，无论建筑设计，工程施工，或是机械制造。也有着越来越多的开发需求。是时候有一篇文档了，算是一个小结，也是对刚进行Navisworks开发的小伙伴们一个参考。

Navisworks产品

 

产品能力

任何API都是用来对产品能力的拓展，有必要先了解Navisworks产品能做什么？需要明确的是，Navisworks是模型管理软件，而非设计软件。换句话讲，设计软件解决的是模型创建的任务，而模型是否满足施工要求，有无问题，模型的信息如何与下游（进度，施工方，监理方，供应商等等）对接，则需要管理软件。如果您从事BIM行业，一定知道，工程管理有着越来越多领域要进行超量规模的模型检查，多工作的协调；需要施工前的项目，进度和角色管理, 要在更短的时间内形成最终方案。同时处于下游的现场施工也要求越来越高的质量保证，安全检查，要求和设计模型的紧密关联，实时状态跟踪，对全项目设备的调试，移交以减少费用，优化流程，和及时投入运营。而Navisworks就扮演了这个角色，实现诸多方面的模型审查和管理，将模型和现实的工作流紧密结合。 Navisworks虽然是为建筑施工行业而诞生，但其实它没有很强的行业性。任何行业的都可以用得到。 

具体点看，Navisworks具备的几个大方面能力

• 模型聚合：工程各个环节可能用的是不同的设计软件，文件格式相当的丰富。当做模型管理时，需要将它们都堆到一起，例如，水暖电要和建筑本身进行问题排查，设备模型也放到建筑中管理查看。因此面临的首要问题是，能把不同格式模型聚合起来。Navisworks提供了多达60几种的文件格式解释器，能够打开这些文件，获取其中的模型和数据。可以说，BIM里能用到的文件格式都一应俱全。

• 模型查看： 由于工程设计，建筑，基础设施等领域的模型体量都很大，加之模型聚合，如何能高效的进行模型查看和浏览，是一个突出的问题。而Navisworks底层的特殊算法，让这个困难得到了很好的解决。当然，模型越大，自然速度递减，但Navisworks实时漫游引擎在这方面有着独到的处理，让用户体验保持最佳。

• 全方位项目审阅：Navisworks有着通常情况下几乎所有的项目审阅功能：属性查看，模型树，注释，超链接，红线标记，测量，场景动画，对象动画等等。

• 丰富的施工管理： 施工中我们需要知道工程的进度安排，今天修什么，明天修什么，项目老大们得掌握到总体的数据。而Navisworks的工程进度管理绝对强劲。除了常规的创建计划任务，还能打开流行的进度管理文档。先进的甘特图让进度的状态清晰可见。 

• 碰撞检测：前面提到，模型管理里的一项重要任务是问题的排查，其中一项是模型的构件直接有无干涉碰撞。有碰撞了，实际施工也没办法构造出来。利用Navisworks的碰撞检测，您可以直观的看到碰撞的位置，参与碰撞的对象，得到漂亮的报表，并获知它们来自哪些设计方，反馈给设计方做修改。

• 算量：业界经常说的3D模型，4D管理（工程进度），5D就是算量。Navisworks能自动提取出Revit或DWF文件中对象的相关信息，并提供多种算量模板，能让对象，尺寸，材料，价格都信息关联起来。也支持其他格式文件的算量管理。

• 数据库链接： DataTool工具可以获取外部数据源的信息，和对象（构件）做对应，将外部的信息作为附加属性显示在属性面板里。简答的几句SQL语句就可以实现。

文件格式

Navisworks可以打开很多文件格式，一般称为源CAD文件。Navisworks也有自己的文件格式： 

• nwc：当打开源CAD文件产生的临时缓冲文件。和源文件在同一目录，比源文件小很多。Navisworks的模型管理其实就是基于这个文件做的。可能您已明白为何它实时漫游能力很强，因为首先对文件数据做了特殊处理。
• nwd : 它是源CAD文件的快照，包含几何信息和Navisworks特有数据。文件很小，压缩近80%。它是所谓的发布格式。即，您的合作伙伴只需要这个文件就能看到模型和相关数据，而不再要源CAD文件。
• nwf：只是和源文件关联，不包含几何信息。包含Navisworks特有的数据。文件更小。可以理解为它类似于AutoCAD的Xref技术，主文件只是引用了其它文件，并没有合并在一起。所以，当要查看时，需要nwf和引用文件一起打包过去。

产品类型

• Autodesk Navisworks Freedom：这是免费的产品。主要用来浏览模型和查看属性。不过它只能打开 nwd 和 dwf文件。而且不支持API
• Autodesk Navisworks Manage： 这是最完全功能的产品，包括碰撞检测,  时间进度, 材质, 动画，基本功能…可以打开nwc, nwd和nwf。
• Autodesk NavisWorks Simulate：和Manage相比，Simulate基本只缺少碰撞检测。当然，价格相应也便宜些。 

产品学习资料和资讯

• 产品在线帮助：这就是产品帮助文档。按照功能类别进行
• AU全球 和AU中国: AU （Autodesk University）聚集了Autodesk的解决方案和最新资讯。有着大量的教程，成功故事，行业动态，案例分享等等。按Navisworks类别就能查找到。当然。AU全球基本都是英文的。如果您想听咱们的母语，就在AU中国检索。
• Lee的博客： 这是我们产品支持专家开办的，现在多个同事一起在忙活，博客关注的是Autodesk 建筑领域解决方案的动态，包括Revit，Navisworks
• Navisworks 论坛： 如在这篇博文提到的，鼓励大家不仅仅是查看博客，帮助文档，也能经常到论坛上溜达，发发帖，多交流，找方案，因为全球用户都在相互帮助。

Navisworks API开发

曾看到过程序员需要具备的几个素质，其中有一条是自我学习，专研帮助文档和资料的能力。因此，本文不做具体的开发介绍，而是说说大概的学习路径和相关资料。

API的基本能力

在熟悉产品的基础上，建议看看这个教程，其中介绍了API的基本能力，对您和业务逻辑结合可能会有所启发
Navisworks API助力产品功能拓展 （注：本教程发布到AU中国，但AU中国最近有些故障。待恢复后再附上链接）


简短的讲，主要有以下方面：
1. 文档：打开，聚合，导出为其它格式等
2. 模型：模型结构；对象颜色，透明度，位置操作；对象信息属性；对象查找和定位，选择集集合等
3. 视点：相机，保存视点等
4. 工程进度：进度任务，安排，自定义任务源
5. 碰撞检测：检测任务，碰撞结果，报表
6. 算量：对象信息链接，算量报表
7. 自定义图形
8. 用户界面：Ribbon，面板，独立界面程序
9. 大量的事件以帮助实现一些工作流
10. 创建自定义模型*
11. 加载自定义文件格式*


* 参见【API类型】章节

API类型

Navisworks 提供了.NET, COM和NwCreate 三种API。而通常我们说Navisworks API其实指的只是COM或.NET，因为NwCreate的功能比较特殊。待我一一道来：

• COM API: 这是很早很早以前就提供的接口。COM有多老基本它就有多老了。它能完成大部分产品里有的功能。
• .NET API: 这是2011版本开始提供的。用来逐渐取代COM API。但并不是简单的把COM 功能搬过来，而是从底层写起，并且，增加了很多COM没有的功能。

      .NET API诞生后，我们只在.NET里增加新功能，COM API只做维护。还有零星的一点COM功能.NET暂时没有暴露，但可以通过COM Interop去访问之。换句话讲，您可以 在.NET API里调用到COM的能力。下面这个表格是两种API的大致对比，以作参考。.

API 能力

COM

.NET

模型聚合

√

√

模型基本信息访问

√

√

模型结构树

√

√

对象属性访问

√ 但API结构繁琐

√ API结构清晰

对象查找

√ 但API结构繁琐

√ API结构清晰

LINQ查找

×

√

对象用户自定义属性添加和修改

√

×, 但可以通过COM Interop使用

自动化API

√

√

材质和渲染

× 2015之前有Presenter API，2015后去除

×

工程进度管理和操作

×

√

导入外部工程进度

×

√

碰撞检测

√  功能有限

√  功能完备

浏览模式

√

√

注释

×

√

算量

×

√

文档数据库

×

√

控件

√  ActiveX控件

√  .NET 控件

访问和添加超链接

√

×, 但可以通过COM Interop使用

访问和添加快速属性

√

×, 但可以通过COM Interop使用

剖面

√  功能很有限

×, 但可以通过COM Interop使用

全局选项

×  部分可通过注册表操作

×  部分可通过注册表操作

用户交互

×

√  目前仅插件支持

临时图形

×

√

支持WPF

×

√

Ribbon

×

√

面板

×

√

视点操作

√

√

相机操作

√ 功能有限

√ 功能完备

属性集操作

√

√

场景动画

×可部分利用保存视点

× 可部分利用保存视点

对象动画

×可部分利用对象位置变换

×  可部分利用对象位置变换

对象颜色

√

√

对象透明度

√

√

对象位置变换

√

√

添加自定义模型*

×

×

加载自定义文件*

×

×

• NwCreate: 用来创建模型的 --- 或许您会问，前面不是提到，Navisworks不是设计软件？嗯，是的，Navisworks本身不能创建模型，只是聚合已有的模型。而通常的API能力如上面的表格，都是对模型的审阅和管理。NwCreate是一个C++库，让开发者能

1. 自行从零开始，创建模型场景，生成模型，并存为nwd文件。类似于一个OpenGL程序，在自己的画布里绘制出自己的模型。
2. 或者，能做一种插件，解释特定的文件格式。Navisworks能打开60多种文件格式，但要是有些格式很特别，而您又知道怎么解释其中的数据，那可以利用NwCreate写个插件，当打开特定格式文件时，插件获取文件数据，按照要求绘制相应的模型。也就是说让您能做自己的文件解释器。

           总之，NwCreate是为开发者而生，创建模型所用。但它也不能在现有的模型上再添加模型，只是从零开始构建一个新模型文档。 

所以，我们说普通意义上的Navisworks API指的是COM或.NET。有时，您的程序也会和 NwCreate结合。例如：不能在现有的模型上再添加模型，那用NwCreate创建出模型，再聚合到主模型也是一个思路。

要了解这三种API，可参考这篇课程（当时的网络不太给力，图像和音效有点欠佳）。如果只使用.NET进行开发，可只看这个视频 。

API的访问方式

• 插件（Plugin）：很常规的形式，集成到Navisworks Simulate或Manage里，拓展其能力。COM也有插件，但太难用了，而且样式很少。建议不要浪费时间琢磨。直接上.NET的插件。
• 控件（Control）：也就是提供了查看器，可以嵌入到您的独立程序里。无论COM或.NET的控件底层都用到了Navisworks的显示引擎，所以模型漫游操作性能和产品是一样的。COM的叫做ActiveX控件，细节和用法上也比较绕，这里有篇博文详述。
• 自动化程序（Automation）：能开启Navisworks进程，执行自定义操作。一般是进行批处理工作，比如把很多源CAD文件批量的导出为nwd，或批量修改，丢给计划任务，头天晚上跑，第二天拿结果。虽然.NET和COM都有这种方式，但还是建议大家直接上.NET。

看到用的比较多的访问方式是控件，将控件集成到业务流中，例如BIM的工程管理环节。 

Navisworks SDK

以前版本在Navisworks Simulate或Manage安装后，在很醒目的位置： <安装路径>/api/。 从2013开始，SDK做成单独的安装包，可以从开发者中心（全球）下载。安装后也是放在Navisworks的安装路径下。这里面有帮助文档，例子。按照API类型分为COM，.NET，NwCreate（包括Nwcreate的头文件与库文件）。

• .NET: 先看看NET\documentation\NET API.chm里的Developer Guide. 这个章节介绍API访问方式如何编写代码，以及对应的例子。这个chm也包含了对象手册，用法介绍。例子都分类了，相信您能找到自己最关心的。
• COM: 个人推荐先看看COM综述COM Interface.pdf，再跑一下最简单的ActiveX例子：\api\COM\examples\ActiveX\ActiveXSimpleExample。经常用的帮助文档是NavisWorksCOM.chm。偷偷说，这个文档写的很简单，不过大多数通过方法参数名就能猜到大概的用法，实在不行上我们的AEC全球博客，那里有好些例子。
• NwCreate: 可以先看nwcreate\docs\NWCreate.chm，不过推荐看看这篇博文, 或许能让您更容易上手。 

 

API学习资料和资讯

• AEC全球博客： 如果Navisworks API开发不知道这个博客，我们就会郁闷坏了：）这里汇集了大量的文章，基本您开发初、中期阶段用得到的功能都有涉及。
• Navisworks API 论坛：经过多年的运行，已经聚集了很多讨论和解决方案。全球开发者在积极分享自己的经验。
• AU全球 和AU中国: 类似产品，上面也有API相关的教程
• 开发者中心（全球）Navisworks：有最新SDK 和基本内容教程。
• 开发者中心（中国）： 中国一些活动通知和培训教程。
• 几个中文的视频教程
  • .NET API入门教程
  • 插件教程1 
  • 插件教程2 
  • .NET控件程序

常见问题

问：选用什么API？

答：COM API已经很老，而且我们不再添加新功能。另外，，目前的IE10， IE11对ActiveX控件都支持得不好。注意，不是Navisworks ActiveX本身的问题，是微软不再关照ActiveX这种方式。所以，请考虑使用.NET API，.NET控件。

问：可以不装Navisworks Simulate或Manage就能使用API么？

答： 不行

问： Navisworks Freedom支持API么?
答： 不支持

问：使用Navisworks 的Redistributable ActiveX Control，遇到‘license error’的错误，是什么意思?

答：那是因为您访问的API在Redistributable ActiveX Control上没有开放。此种control基本只是模型查看器，以及保存视点转换。全API功能，则需要用Integrated ActiveX control，意味着您需要安装Navisworks Simulate或Manage。见此博客查看详情。

问：能否客户端不安装 Navisworks，就能使用到全API功能的ActiveX Control?  

答：目前没有任何方法，也没有任何政策能打包全API功能的ActiveX control。客户端必须安装Navisworks Simulate或Manage

问：可以修改Navisworks 原属性么?
答：目前不行


问： 可以在现有的模型里删除对象么?
答： 不行。

问： 可以在现有的模型里增加对象么?
答： 不行。可以考虑NwCreate创建好模型然后聚合。当然也可以是其它设计软件的文件再聚合。

问： .NET控件的程序能访问到Timeliner，和Clash Detective么?
答：目前不能。只能用插件能访问到。


问: .NET 控件有鼠标和键盘事件么?
答：虽然.NET控件是继承自标准的.NET，但目前没有暴露鼠标和键盘事件。只能利用选择集变化事件做事。


问：控件能嵌入到网页么?
答： ActiveX控件可以。看这篇博文Web Server with Navisworks ActiveX Control。NET控件可以通过XBAP技术封装。抱歉暂时没有写相关博客。


这次写到这里。我们会持续更新。如果您知道还有其它的资源，以及您自己的经验，请不吝分享。我们将会更新该博文，谢谢！