C#基于TerraExplorer的三维GIS二次开发实战指南

简介TerraExplorer二次开发C#示例代码是一套面向GIS开发者和Skyline平台二次开发人员的轻量级示例工程围绕TerraExplorer SDK展示如何在C#中实现地图加载、图层控制、3D模型展示、数据集成等常见功能可帮助读者快速建立三维地球/GIS应用的开发框架缩短上手周期。压缩包共含21个文件核心包括cs源码、resx资源文件、sln解决方案以及用于测试功能的地图数据与场景文件文件类型涉及Shapefile系列shp/shx/dbf/prj/qix和fly场景文件整体仅42KB结构紧凑便于按模块对照学习。目前已有482人学习下载。通过学习该工程的代码组织读者可以获得一套清晰的C#项目结构掌握主窗体、资源文件和空间数据的调用关系了解官方常见API的基本用法并为后续扩展WMS/WFS网络服务、空间查询、自定义界面和多线程优化等高级开发打下基础。1. 从C#视角理解TerraExplorer的二次开发体系TerraExplorer是Skyline系列三维地理信息平台的核心模块它不是一个简单的三维浏览器而是一套完整的桌面端虚拟场景构建与展示工具。做二次开发时我接触最多的是它自带的ActiveX控件和一套庞大的COM类型库而C#恰恰是调用这套COM接口最顺手的语言之一。对这个标题涉及的场景我做一下明确定位如果你是做三维GIS项目需要把地形、影像、倾斜摄影、人工模型叠加到一个场景里还要在场景上实现飞行漫游、标签标注、属性查询、视点跳转等功能那么用C#基于TerraExplorer做二次开发是业内非常成熟的路线。这套开发模式适合三类人一是三维GIS项目的中级开发人员需要快速交付可交互的桌面端场景二是传统GIS开发者在转向三维展示时需要一套上手快的API三是做平台集成的人要把TerraExplorer场景嵌入到自己的C#系统中。为什么选C#而不是其他语言核心原因有两个。第一TerraExplorer的SDK通过COM对外暴露接口C#在Visual Studio中对COM组件的引用非常成熟能自动生成互操作程序集开发效率远高于C直接操作COM指针。第二TerraExplorer自带一套可视化控件可以直接嵌入WinForms窗体或WPF的WindowsFormsHost中这种控件嵌入的开发方式天然契合C#的桌面开发模型。不过我建议所有接触这个SDK的开发者先建立一个认知TerraExplorer的二次开发本质上是操作一棵场景树。这棵树叫Information Tree里面挂着图层、模型、标注、视点等各种对象。你用C#写代码绝大部分操作是在增删改查这棵树上的节点或者控制树根上的TerraExplorer对象去执行场景级别的动作。理解了这个模型后面碰到的接口命名、方法调用就都不难猜了。关键的一个版本问题是TerraExplorer从6.x升级到7.x之后API的变化比较大。如果你用的是TerraExplorer Pro 7.x或TerraExplorer Fusion 7.x建议以新接口为准很多老版本的接口已经被标记为废弃直接照搬旧代码会踩坑。后文的示例代码我会以7.x为主同时标注在不同版本下需要注意的差异点。2. 开发环境搭建与第一个C#连接示例2.1 环境准备清单搭建开发环境之前先把所有需要的软件和SDK列出来避免做到一半才发现少东西。TerraExplorer Pro 7.x64位版本许可模式选择试用或正式授权均可Visual Studio 2019/2022.NET Framework 4.7.2或更高版本TerraExplorer二次开发SDK安装后会在安装目录下提供TerraExplorerX.dll与相关头文件、示例工程一份基础地形数据或工程文件比如带影像和高程的MPT格式文件或者本地的3DML切片数据。安装完成之后在Visual Studio中新建一个WinForms项目。在解决方案资源管理器中右键引用→添加引用→浏览找到TerraExplorer安装目录下的TerraExplorerX.dll将它添加进来。添加后VS会自动生成对应的COM互操作程序集你在代码里就能直接使用TerraExplorerX这个命名空间下的类了。一个比较容易被忽略的细节TerraExplorerX.dll虽然文件名看起来像普通DLL但它实际是一个COM组件库不是纯托管程序集。所以如果是64位开发环境一定确保项目平台目标是x64否则运行时会出现未能加载文件或程序集的COM类未注册错误。2.2 启动场景并连接主控件下面是一个最小可跑的C#代码实现把TerraExplorer控件嵌入窗体并完成初始化using System; using System.Windows.Forms; using TerraExplorerX; namespace TerraExplorerDemo { public partial class MainForm : Form { private AxTerraExplorerX.AxTerraExplorer axTE; public MainForm() { InitializeComponent(); InitializeTerraExplorer(); } private void InitializeTerraExplorer() { // 创建ActiveX控件实例 axTE new AxTerraExplorerX.AxTerraExplorer(); axTE.Dock DockStyle.Fill; this.Controls.Add(axTE); // 获取顶层SGWorld对象这是所有API调用的入口 SGWorld64 sgworld axTE.SGWorld64; // 创建工作空间显示导航树、信息树并让场景开始渲染 axTE.CreateWindow(Handle.ToInt32()); } } }这段代码看起来简单但有两个关键点。一是SGWorld64这个对象它是TerraExplorer所有功能的根入口后续不管是加载图层、创建标注还是操作相机全部要通过它来调用。二是一个经验问题直接调用CreateWindow有时候窗口渲染不出来我碰上过几次原因是窗体还没完全加载就创建了窗口稳妥的做法是把初始化调用放在Shown事件中或者加上一行this.Activate()强制保持窗体焦点。注意如果是TerraExplorer 6.x及更早版本入口对象叫SGWorld7.x的64位版本叫SGWorld64。这个对象名不能混用我见过不少新手在这里编译报错后一脸茫然。3. 核心功能开发的常见场景与示例代码3.1 加载地形与影像数据TerraExplorer最基础的能力就是把地形高程和影像贴图叠加成三维场景。加载的方式有几种我按照便捷程度排列一下加载本地MPT工程文件整个工程的地形、图层、标注全都有往往就一句代码加载单个地形或影像文件需要用LoadLayer方法通过WMS或WMTS服务动态加载远程数据用LoadLayer传入服务URL即可。下面是加载MPT工程和直接加载图层的两个典型片段// 方式一加载MPT工程文件 string mptPath D:\Data\base.mpt; sgworld.Project.Open(mptPath); // 方式二直接加载地形/影像 string terrainFile D:\Data\Terrain.tif; sgworld.Project.LoadLayer(terrainFile, LayerType.TLT_TERRAIN); string imageFile D:\Data\Image.tif; sgworld.Project.LoadLayer(imageFile, LayerType.TLT_IMAGE);这里的LayerType枚举需要留意地形是TLT_TERRAIN影像贴图是TLT_IMAGE矢量是TLT_VECTOR栅格综合数据是TLT_RASTER。分类不对会导致数据加载到场景却看不到任何东西或者显示在错误的层级这种加载不出结果的问题一大半是图层枚举类型选错了。我自己常用的一个习惯是在加载前先用sgworld.Project.IsLayer(LayerType, path)判断一下文件是否可被识别提前过滤掉格式不合法的数据省得在场景里排查半天。3.2 添加三维模型与标注对象在地形之上加模型、加标注是日常开发中使用频率最高的操作。TerraExplorer里创建一个对象逻辑上分成三步先定义位置坐标再创建对象最后把对象挂到信息树上。// 创建一个三维模型实例 private void AddModel() { // 1. 定义位置经度、纬度、高度、高度模式 Position64 pos new Position64(); pos.X 116.391; pos.Y 39.907; pos.Altitude 100; pos.AltitudeType AltitudeTypeCode.ATC_TERRAIN_ABSOLUTE; // 2. 创建模型对象 string modelFile D:\Data\building.3ds; IModel model sgworld.Creator.CreateModel(pos, modelFile, BuildingModel); // 3. 将对象添加到信息树 sgworld.ProjectTree.AddItem(Models, model); }这段代码是人话版本实际开发时大部分时间都在调整Position64的参数。高度模式ATC_TERRAIN_ABSOLUTE表示高度取绝对海拔如果想让模型贴着地面自动起伏就改成ATC_TERRAIN_RELATIVE并设一个基准偏移值。创建文本标注也是类似套路IAnnotation ann sgworld.Creator.CreateAnnotation( pos, 这是一个测试标注, TestLabel, Color.Red ); sgworld.ProjectTree.AddItem(Labels, ann);注意CreateAnnotation的颜色参数用的是COM的OLE_COLOR类型如果你直接传入C#的System.Drawing.Color部分版本会隐式转换失败我这边的处理办法是用ColorTranslator.ToOle(Color.Red)显式转换一次稳定。3.3 场景交互与事件响应TerraExplorer的交互事件比如鼠标点击场景、选中对象、相机移动主要通过IEventDispatch接口来驱动。这个接口本质上是一个观察者模式你往里面挂一个委托用户在场景上的动作就会以事件形式回调到你的C#代码里。我在一个巡查项目中需要实现点击模型弹出属性面板的功能当时的做法是订阅鼠标点击事件IEventDispatch eventDispatch sgworld.EventDispatch; eventDispatch.OnLButtonDown new _IEventDispatchEvents_OnLButtonDownEventHandler(OnSceneClick); private void OnSceneClick(double x, double y) { // 将屏幕坐标转为地理坐标 Position64 pos sgworld.Window.ScreenToWorld(x, y); string layerId sgworld.Window.PickObject(x, y, PickType.PT_ANY, false, 0); if (!string.IsNullOrEmpty(layerId)) { // 从信息树拿到对象并读取属性 IInformationTree6 tree (IInformationTree6)sgworld.ProjectTree; string name tree.GetObjectName(layerId); Console.WriteLine(选中对象: name); } }这里有个真实的性能教训PickObject这个操作场景内部要做命中测试如果每帧都去调界面会非常卡。我一开始做了一个工具窗口实时显示鼠标所指的对象名结果鼠标一动就卡成一帧帧的幻灯片。后来改成鼠标停顿200毫秒后才执行拾取的方案流畅度彻底解决。凡是涉及事件回调里的高开销操作多想想是不是该延时触发这算是我在三维场景交互开发里最值得分享的经验之一。3.4 视点控制与飞行漫游视点控制是TerraExplorer开发里最容易出彩、也最难调的部分。它的逻辑是操作一个ICamera64对象通过设置经纬度、高度、方向角、俯仰角来定位相机再配合时间轴实现飞行效果。一个基础的跳转到指定位置的代码ICamera64 camera sgworld.Navigate.Camera64; Position64 cameraPos new Position64(); cameraPos.X 116.391; cameraPos.Y 39.907; cameraPos.Altitude 1500; cameraPos.Yaw 0; // 方向角0为正北 cameraPos.Pitch -45; // 俯仰角负数表示俯视 cameraPos.Roll 0; // 翻滚角通常保持0 camera.MoveTo(cameraPos, 1.5); // 第二个参数是飞行过渡时间单位秒飞行漫游其实就是通过camera.MoveTo在多个关键点之间连续运动。如果你想做平滑路径漫游需要自己维护一个关键点数组按时间逐个调用MoveTo。这里有一个很实用的经验飞行过渡时间不要设置得太短小于0.5秒时MoveTo经常会产生跳变看起来像闪现大于3秒又会让人等得不耐烦。我一般取1到2秒视觉最自然。4. 射线选择、坐标转换与性能优化的进阶实现4.1 屏幕坐标与地理坐标的互转三维场景里到处都要做坐标转换。鼠标点在屏幕上的某个像素你要知道它对应地球上的哪一点或者反过来把一个经纬度坐标算成屏幕位置去画动态标签。TerraExplorer提供了两套核心接口Window.ScreenToWorld和Window.WorldToScreen。严格来说ScreenToWorld的返回结果和拾取模式有关。你传进去的x, y是相对于控件客户区的屏幕坐标左上角为原点得到的Position64是基于地形表面的交点。如果要得到鼠标所指的模型表面的点不能直接使用ScreenToWorld而是要用拾取接口Window.PickPoint它会返回三维空间中的实际交点坐标。这个区别在做距离量测工具时尤其关键。如果你量测的是两座建筑之间的直线距离ScreenToWorld给出的地面投影点去算距离和PickPoint给出的模型表面点去算距离误差可能达到几十米。我自己在楼宇间距测量项目里吃过这个亏后来统一改成PickPoint才把精度拉到可接受范围。4.2 千万级三角网场景的性能优化做三维GIS的迟早会碰到性能问题。我经历过的几个真实场景数据量大概是倾斜摄影模型500GB左右、地表影像16TB、三维管线模型几十万个独立对象优化前在普通工作站上转一圈大概3到5秒优化后能压到1秒以内。先说最要紧的一条不要频繁调用COM接口。C#和COM之间要跨越托管与非托管的边界每次调用都有开销如果在一个循环里反复调用SGWorld下的接口性能会急剧下降。我见过有人用for循环逐个创建1000个标注对象结果耗时几十秒改成批量方式后执行时间降到了2秒以内。第二个优化点是利用TerraExplorer自带的多细节层次LOD机制。当你加载了体量很大的倾斜摄影或地形数据时不要试图一次性载入全部而是用官方的数据预处理工具把数据先切分成金字塔层级。TerraExplorer会根据相机距离自动选择加载哪个层级的瓦片这比你用代码去控制显隐最高效。第三个优化点是合理设置LoadPriority和缓存目录。每个图层在加载时都可以设置优先级实时需要的图层比如管线、道路优先级调高影像大图层优先级调低保证场景初始打开时最快呈现核心内容。缓存目录则建议放到一块独立的SSD上如果放到HDD上加载大数据量切片时会明显拖慢。4.3 多线程场景下的API调用约束很多人第一次用C#开发TerraExplorer会企图用BackgroundWorker或Task在后台线程去加载大数据量图层来避免界面卡死但这个念头要尽快打消。TerraExplorer的COM接口绝大多数组件不是线程安全的也就是说后台线程直接调用API轻则无效重则进程崩溃。我的常用方案是使用System.Windows.Forms.Timer或者Task.ContinueWith把耗时操作分片放到UI线程上执行。比如加载大量三维管线数据时可以每200毫秒处理一批对象中间穿插调用Application.DoEvents()让界面保持响应。这样虽然真实耗时没有减少但用户在感官上不会觉得程序卡死了。5. 实际项目中的常见问题与排查技巧我把自己和朋友们在TerraExplorer二次开发中真正踩过、查过、解决过的高频问题整理成了一张速查表希望能帮你缩短排查时间。问题现象可能原因解决方法启动时提示COM类未注册项目平台和TerraExplorer位数不一致确认项目目标平台为x64加载MPT工程后场景空白工程文件路径含中文或特殊字符将数据路径改为纯英文路径CreateModel报参数错误高度模式与所传坐标类型不匹配检查Position64的AltitudeType设置事件回调里执行卡顿回调内做了高开销操作改为延时触发或离线计算结果对象消失但信息树节点还在删除时未按对象类型调对应删除方法使用RemoveObject接口而非直接删树节点GetObjectName找不到节点ID对象ID在工程重新加载后失效重新获取对象引用后再访问多屏拼接时坐标偏移控件坐标系与屏幕坐标系混淆用控件坐标不用屏幕坐标上面这些每条都有说头但最有代表性的是数据路径的问题。TerraExplorer对非英文字符的支持一直不太稳定不是不能显示而是解析路径时会出现不可预期的错误。特别是中文路径下加载MPT工程经常出现图层丢失。我的规矩是项目涉及数据文件时全部拷贝到纯英文目录下文件名也用英文加数字给用户的安装包说明里也强调这一点。另外一个容易被坑到的问题是对象ID失效。TerraExplorer信息树上的每个对象都有一个唯一的字符串ID我们开发属性查询功能时常常把这个ID存在数据库里。但工程每次重新加载ID可能都会变化。如果你要把配置存到数据库建议不要直接存ID而是在程序启动时通过对象名称反向查找ID并做兜底处理。6. 开发中的几个实操经验与心得在多个三维GIS项目里摸爬滚打之后我最大的感受是TerraExplorer这套二次开发接口不算复杂它真正的门槛在于你要理解它底层的三个模型场景树模型、事件驱动模型和COM互操作模型。场景树模型告诉你要按层级管理对象事件驱动模型提醒你要把交互逻辑挂在正确的事件上COM互操作模型则决定了你写代码时需要考虑内存释放、线程调度和性能开销。建立起这三个模型认知之后绝大多数网上能搜到的功能示例你都能轻松看懂、快速改造成自己的业务模块。我个人的建议是拿到SDK之后先不要急着写功能代码把官方自带的示例工程完整跑一遍尤其是加载数据、创建对象、响应鼠标事件三个基础Demo。然后在这个骨架上一个一个叠加业务功能每叠加一个就实测一次别攒到最后一口气测试否则出了问题完全没法定位。另一个对实际项目帮助极大的技巧是多利用TerraExplorer自带的信息树导出功能把场景里的对象结构导出成XML用于检查数据加载情况。在排查为什么某个对象没显示的时候看看信息树里有没有对应节点能帮你快速区分数据没加载和数据加载了但渲染异常两个不同问题这两个问题排查路径完全不同。最后说一句关于学习的心里话这类专业GIS平台的二次开发资料远不如互联网框架那么丰富遇到问题第一时间应该看官方API文档和示例工程其次才是搜索引擎。多花时间把官方示例看明白比在网上找碎片信息效率高得多。本文还有配套的精品资源点击获取