基于Civil 3D的排水管网辅助建模二次开发

毕 晨 李在钟

(林同棪国际工程咨询(中国)有限公司，重庆 401121)

引言

随着BIM技术在国内的快速发展及应用，越来越多的土木工程项目采用了Autodesk Civil 3D平台进行设计、建模[1-3]。Civil 3D软件中集成的管网模块，提供了一系列功能，可用于市政排水管网的建模、修改及分析等[4]； 在Civil 3D平台下，排水管网能够非常方便地与市政道路、隧道、强弱电管网等专业协同设计，多专业间数据可共享，极大提升了项目设计效率和设计精度[5]。

然而，由于Civil 3D是一款面向多专业的设计软件，且功能主要偏向于场地处理和路线设计等，软件功能难以完全覆盖到各个附属专业的建模需求； 就管网模块而言，Civil 3D没有面向国内市政排水管网设计场景和设计习惯进行深度优化，部分功能缺失或不完善，导致排水设计人员的建模效率低，推广正向设计需付出较高的代价。

为提高Civil 3D市政排水管网设计的效率，须对软件的管网设计模块进行二次开发，提高软件的易用性，为排水正向设计的推广做好铺垫。

同样作为BIM软件，Revit二次开发技术在国内已经得到了广泛的研究与应用[6-8]； 相比之下，Civil 3D二次开发技术在工程中的应用案例较少，且主要集中在场地、路线领域[9-11]，至于其管网模块二次开发的研究与应用，则较为鲜见。故本研究亦希望通过对一系列具体功能的二次开发，来探讨Civil 3D重力管网模块二次开发的主要流程和若干技术细节。

1 二次开发流程

本研究基于Civil 3D的.NET API(.NET Application Programming Interface，即.NET框架下的应用程序编程接口)，它为Civil 3D的二次开发提供了一系列功能接口，能实现绝大部分的软件操作； 本研究使用C#编程语言进行二次开发，二次开发环境见表1。本研究的开发流程如下所述。

表1 二次开发环境

1.1 新建开发项目

打开Visual Studio 2017软件，新建名称为“CivilNetworkTools”的项目，编程语言选择visual C#，项目类型选择“类库(.NET Framework)”，项目框架选择“.NET Framework 4.7.2”。

1.2 添加外部引用

进行二次开发前，应根据开发的需要，向项目中添加程序必要的引用。本二次开发项目需要的引用包括AutoCAD和Civil 3D的.NET API库和COM(Component Object Model，组件对象模型)API库[12]、定制AutoCAD功能区选项卡界面的库等。

(1).NET API库

引用Civil 3D安装目录下的acdbmgd.dll、acmgd.dll、accoremgd.dll、AecBaseMgd.dll以及AeccDbMgd.dll等库文件，上述文件是进行Civil 3D二次开发最基础的库文件。

(2)COM API库

引用Civil 3D安装目录下的Autodesk.AutoCAD.Interop.dll、Autodesk.AutoCAD.Interop.Common.dll、Autodesk.AECC.Interop.UiPipe.dll以及Autodesk.AECC.Interop.Pipe.dll等库文件； Civil 3D官方推荐使用.NET API，然而.NET API并未涵盖所有Civil 3D功能，因此开发过程中可能会使用到仅在COM API中开放的功能。

(3)用户界面相关的库

引用Civil 3D安装目录下的AcWindows.dll、AdWindows.dll等库文件，用于为二次开发的功能定制AutoCAD功能区界面。

1.3 程序的编写与生成

在项目中新建若干C#类文件，于各个文件起始部分引入所需的命名空间，而后进行编程； 完成预期功能后，使用Visual Studio“生成解决方案”功能以生成最终程序文件，而后于项目文件目录下，获取最终生成的目标文件。根据先前设置，本项目生成了动态链接库(dll)文件。

1.4 程序的加载

启动Civil 3D软件，键入加载.NET程序集命令“netload”，加载先前生成的dll文件； 加载成功后，键入二次开发的“NetworkToolsRibbonTab”命令，加载程序的图形用户界面(GUI)，供用户调用二次开发功能。用户界面采用了AutoCAD的功能区(Ribbon)选项卡界面，如图1所示； 功能区是当下众多CAD二次开发软件的界面选择，相比于传统菜单栏、工具栏，它具有流程清晰、分类明确、界面美观等优点[13]。

图1 二次开发用户图形界面

2 管网.NET API类接口概述

利用.NET API二次开发时，最常用到的类显然是管网相关类以及管网零件族相关类接口，如管网类Network、结构类(含检查井)Structure、管道类Pipe以及零件族类PartFamily和零件尺寸类PartSize等[14]，它们之间的层级逻辑关系如图2所示。

图2 管网对象层级关系图

通过当前活动文档(ActiveDocument)的GetPipeNetworkIds()方法，可获取图形中所有管网(Network)的Id集合(ObjectIdCollection)，从而获取所有管网实例； 类似地，通过单个管网可获取该管网的所有结构(Structure)和管道(Pipe)； 通过单个结构和管道，即可获取或设置他们各自的属性(如图2中提及的名称、位置、坐标等属性)。二次开发大部分的功能即是通过上述层级关系，对管网、结构以及管道的数据进行读写。

此外，通过当前活动文档，亦可直接获取图形中所有样式(Styles)，其中包括管网零件列表的集合(PartsListSet)； 通过单个零件列表(PartsList)，可以获取该列表所有零件族(PartFamily)，而单个零件族下又有不同的尺寸(PartSize)实例。二次开发中关于获取或设置管网零件类型的功能即是通过上述层级关系实现的。

3 排水管网辅助建模功能的二次开发

3.1 预期开发功能

表2 二次开发功能一览

根据项目中使用Civil 3D软件进行排水管网设计的体会和经验，本研究整理了建模过程中耗时较多的操作，并据此确定了需要二次开发的具体功能，主要包括管网图元的参数化创建、排水管网平纵的几何参数及非几何参数批量修改、排水管网图元快速查找以及管网数据转换等功能。表2为本研究确定的二次开发功能。

3.2 功能实现过程

面对待开发的一系列功能，应当理清各个功能的逻辑思路，再利用合适的API逐一进行实现。对于某一功能而言，首先要分析其对应实际设计中的某一系列建模操作，而后将其抽象为流程图，再根据流程图进行具体的编程设计，最终实现预期功能。以下试举几个典型实例，说明本研究的功能实现过程。

(1)实例一：“布置雨水口”功能

建模时，布置雨水口的实际操作大致分为三步：①选定要连接雨水口的检查井;②选定布置雨水口的道路边线;③根据检查井及边线的几何关系，布置雨水口和连接管； 将其抽象为流程图，则如图3所示； 根据流程图步骤进行编程，其代码框架如图4所示(连接管参数选用工程中最常用的参数，即管径d300、坡度i=0.003、起点覆土1.0m； 雨水口地面高程参考道路曲面对应高程)。通过该功能，可批量布置雨水口及其连接管。

图3 “布置雨水口”功能流程图

图4 “布置雨水口”功能代码框架

实现本功能时，对检查井Structure类的坐标属性Position进行了读写，本研究中凡是涉及检查井空间位置的功能，均需对该属性进行读写； 类似地，管道Pipe类的起终点坐标属性StartPoint、EndPoint以及GetPointAtParam(double paramInterval)方法，可用于读写管道空间位置。

(2)实例二：“修改管高”功能

修改模型几何信息——管道高程时，其实际操作亦大致分为三步：①于纵断面选定要修改高程的连续管段;②确定要调整的高程;③根据调整高程，依次修改管道及检查井的内底高程； 将其抽象为流程图，则如图5所示； 根据流程图步骤进行编程，其代码框架如图6所示。通过该功能，可快捷高效地调整连续管段的高程。

图5 “修改管高”功能流程图

图6 “修改管高”功能代码框架

实现本功能时，利用了管网Network类的静态方法Network.FindShortestNetworkPath(ObjectId startPartId，ObjectId endPartId，ref double minLength)来获取同一管网中两检查井间的最短路径零件集合； 该方法在本研究中发挥了极其重要的作用，相当一部分二次开发功能的实现，均需要调用该方法，来获取两检查井之间的零件集合(如“定覆土”、“移动管网”、“修改管坡”、“选择管段”等功能)。

(3)实例三：“修改井参考曲面”功能

修改模型非几何信息——参考曲面时，其实际操作亦可归结为三步：①选定要参考的目标曲面;②选定要修改参考曲面的检查井;③将选定井的参考曲面修改为目标曲面； 其流程图和代码框架分别如图7和图8所示。通过该功能，可以批量修改检查井的参考曲面，从而在道路曲面发生调整等情况下，能够将检查井快速地参考到最新曲面上，完成井面标高的更新。

图7 “修改井参考曲面”功能流程图

图8 “修改井参考曲面”功能代码框架

此外，如1.2节所述，二次开发过程中，不可避免地使用到了COM API。例如，.NET API中，Structure或Pipe的Name属性(即检查井或管道的名称)，是只读的，不能修改[14]，而COM API中提供了对该属性的修改功能，本研究开发的“修改井编号”及“修改井编号前缀”等功能，均涉及到对检查井名称的修改，故需要调用COM API来实现。

当需要调用COM API时，应将.NET对象转换为COM对象，可利用COM API中文档(AeccDocument)对象的HandleToObject(string Handle)或ObjectIdToObject(long ObjectId)方法，通过.NET对象的唯一标记(句柄或ObjectId)，来获取对应的COM对象[12]。

4 工程实例应用

以重庆市某市政道路排水工程为例，来验证二次开发功能集对Civil 3D排水管网建模效率的提升。

通过二次开发的功能，将先前流程繁琐(如修改连续管段的高程、坡度或井编号等操作)或机械重复(如批量修改检查井参考曲面或管道、检查井族类型等操作)的操作进行优化、整合，设计人员仅负责输入关键参数，由计算机依照输入自动执行； 通过二次开发的功能，亦能方便地进行模型的查找，在模型元素较多的情况下，实现元素的快速定位(如平纵模型的相互查找以及由编号查找检查井等操作)。与先前相比，排水管网建模流程实现了化繁为简，显著提升了排水管网建模及修改的效率、减轻了设计人员的工作量，需要额外花费的时间仅为族和图形模板的建立。选取本文描述的三种操作，比较了常规操作和二次开发功能的工作效率(基于1km排水管道工作量)，如图9所示，得到的结果支持本文的结论。

图9 常规操作与二次开发功能效率对比

此外，由于参数化的设计模式，使得模型准确度相较先前得到提升，可更精准进行三维模型的展示与数据分析。图10及图11分别为Civil 3D中管网模型的三维查看视图以及管网模型导入到Infraworks软件中进行的精细化展示。

图10 Civil 3D中管网三维模型

图11 Infraworks中管网三维模型

5 总结

本研究基于.NET API，二次开发了一系列扩展功能，用以优化Civil 3D排水管网建模流程； 经实际工程验证，管网建模效率在二次开发功能的辅助下，实现了显著的提升。

此外，建模过程中，仍存在着诸多有待优化的操作流程，例如检查井的自动选型、管道开挖量的自动计算等，在后续研究中将针对这些问题进行探讨。

Civil 3D软件不仅为重力管网的三维建模提供了坚实可靠的基础框架和数据结构，而且还提供了高度开放的.NET API，这使得用户可根据公司或项目的具体需求，针对重力管网模块进行二次开发，实现更多自定义的高效功能。随着二次开发技术的不断推广，Civil 3D针对各个专业的建模流程将会越来越完善，各专业间的协同设计将会越来越便利，Civil 3D平台将会激发出更大的潜力，在市政道路及其附属工程BIM设计中发挥更多的作用。