TerraExplorer二次开发C#示例：COM互操作与三维GIS场景落地

简介：面向地理信息与三维可视化开发者的 TerraExplorer C# 二次开发示例资源，基于 Skyline 平台，旨在帮助需要快速掌握 TerraExplorer SDK 集成、地图控件操作、数据接入与三维场景构建的入门及进阶用户。包内共 21 个文件，压缩后约 42KB，涵盖 6 个 C# 源码文件、解决方案与工程文件、界面资源文件，以及用于测试的 Shapefile 空间数据和 TerraExplorer 场景文件（fly、shv），结构紧凑，便于对照学习。已有 483 人学习下载。借助这套示例代码，可以梳理 C# 中 TerraExplorer 的窗体交互、图层加载、3D 模型放置与空间查询等实现思路，也能直接复用其中地图对象与事件处理的写法，减少从零查阅文档的弯路；同时示例中涉及的 SDK 调用方式、事件驱动逻辑和多种数据格式加载方法，对理解 GIS 二次开发的项目组织与调试流程同样有参考价值。

1. TerraExplorer二次开发C#示例代码：先搞清楚它能帮你干哪些活

手里拿一个三维场景需求，比如数字孪生园区、管网巡检、地质灾害可视化，许多 C# 工程师的第一反应是自研渲染或接 Unity/WebGL。但当你需要在三天内把真实地形、影像叠加和 3DML 模型摆进一个 Windows 客户端时，TerraExplorer二次开发C#示例代码是一条省很多事的路。TerraExplorer 是 Skyline 的三维 GIS 底座，提供 COM 层 API，C# 通过互操作就能驱动它：打开 fly 工程、加图层、放模型、绑鼠标事件。这篇文章写给两类人：一类是从没碰过 C# COM 互操作的新手，照着环境搭建和第一段示例就能跑起来；另一类是已经在项目里被 API 版本、坐标、许可折磨过的熟手，可以直接跳到避坑章节对号入座。

2. 二次开发的底层逻辑：COM互操作与TerraExplorerX程序集

2.1 为什么C#二次开发绕不开COM：TerraExplorer的API血缘

TerraExplorer 的 SDK 从骨子里是 C++/COM 写的，后来才为脚本化二次开发提供了顶层入口。C# 调用 COM 组件这件事，准确叫法是“互操作”（Interop）：Visual Studio 添加 COM 引用时，会自动生成 Interop.TerraExplorerX.dll，把 COM 接口翻译成托管接口。理解这一点很重要——你不是在写一个插件塞进 TerraExplorer 里做扩展，而是在写一个“遥控器”去操控已经能跑起来的三维 GIS 进程。

这和 Creo二次开发、NX二次开发、CATIA二次开发那类 CAD 插件的路径完全不同。CAD 类的常见模式是编译出 DLL 挂进主进程，主进程加载你的代码，API 是进程内对象模型；TerraExplorer 更像一个独立程序加 COM 自动化接口，你的 C# 程序通过 ProgID 创建它的对象，再发号施令。很多做过 C# 上位机的同行，第一次拿这个 SDK 会习惯性地找托管 DLL 直接 new，结果发现程序集里全是接口定义没有实现类，就是这个心智模型没转过来。

C# 能拿到的入口主要有两个：一个是 ActiveX 控件 TE3DWindow，可以直接拖进 WinForms，界面交互都在里面；另一个是 SGWorld 对象，这是 TerraExplorer Pro 的脚本 API 演化来的，JavaScript、Python、C# 都能用。实际项目里，后台批量生成工程、数据预处理、自动化测试，我基本都用 SGWorld 进程外模式，因为不需要总挂一个可见窗口；交互展示场景才用控件模式。

2.2 进程内与进程外两种模式：选错后面全白干

进程内模式最舒服的地方是能够做完整的三维交互：点击选对象、拖拽漫游、框选查询，这些在指挥大屏和园区管理场景里几乎都是刚需。代价是它要求你的 WinForms 跑在 STA 线程，控件创建和释放都有讲究，主线程一旦被狠操作卡住，三维窗口就掉帧甚至白屏。进程外模式则干净得多：C# 程序通过 COM 启动 TerraExplorer 主程序，批量打开工程、创建模型、保存退出，全程不需要人盯着。画面验证可以靠主程序自带的渲染窗口，也可以截屏。

选型没有对错，只有合不合适。如果目标是做看板类产品，TE3DWindow 嵌入更讨喜；如果目标是把客户给的二维管网表变成三维场景数据，SGWorld 批处理模式能让你的交付路径短三分之一。我的习惯是先用进程外把数据流程跑通，再决定要不要把这套逻辑接到 UI 控件里，避免一开始就陷入控件生命周期和线程问题。

3. 环境搭建与引用：从Visual Studio到COM组件

3.1 开发机准备：TerraExplorer Pro和SDK缺一不可

先说结论：开发机上最好装完整版 TerraExplorer Pro，不要只装运行库。原因很简单，SGWorld 和 TE3DWindow 的 COM 注册信息由完整安装写入，缺了主程序，你的 Visual Studio 根本找不到类型库，后面所有代码都无从谈起。

版本和位数是第一个隐性门槛。TerraExplorer 的 COM 组件有 32 位和 64 位两种形态，安装时选哪个，你的 C# 工程就必须匹配哪个。最稳妥的做法是装 64 位 SDK，项目平台目标锁 x64，同时关闭“首选 32 位”。Visual Studio 默认启用了“首选 32 位”，哪怕你显式写了 x64，这个开关也会把程序跑成 32 位进程，COM 调用直接报类未注册。先跑一句代码确认进程位数：

Console.WriteLine("当前进程位数: " + Environment.Is64BitProcess); Console.WriteLine("操作系统位数: " + Environment.Is64BitOperatingSystem);

如果第一行输出 False，说明项目配置有问题，先修配置再往下写。框架方面，老老实实用 .NET Framework 4.7.2 或更高版本。.NET Core/5+ 也能做 COM 互操作，但要自己处理 ComWrappers，还要为生命周期管理额外写代码，对 TerraExplorer 这种老牌 COM 组件不划算。我做这类项目默认开一个 .NET Framework 的 WinForms 或控制台工程，省事得多。

注意：TerraExplorer 的版本差异比想象中大。某些版本里 SGWorld 的 ProgID 带版本号，某些不带。以安装后注册表HKEY_CLASSES_ROOT里实际存在的 ProgID 为准，不要背死一个字符串。

3.2 在Visual Studio里添加COM引用，生成Interop.TerraExplorerX.dll

项目右键，添加引用，COM 选项卡里找到 TerraExplorerX 类型库（名称通常类似 TerraExplorerX 1.0 Type Library），确定后 Visual Studio 会自动生成互操作程序集。这一步会在你的 bin 目录里出现 Interop.TerraExplorerX.dll，里面就是接口定义。选中这个引用，在属性面板里把“嵌入互操作类型”设为 False，不然你可能会因为程序集版本错位遇到稀奇古怪的加载错误。

代码里直接using TerraExplorerX就可以访问接口了。但有一个习惯我强烈建议保留：实例化对象时别用new TerraExplorerX.SGWorld()，改用 ProgID 动态创建。理由很简单，TerraExplorer 的主版本升级后，命名空间和 coclass 名称可能会变，编译期写死会让你升级 SDK 时改一地代码。用 ProgID 加一层反射，至少能让你把“版本问题”控制在配置层：

using System; using System.Runtime.InteropServices; class TeEntry { public static object CreateSgWorld() { // 老版本用 Skyline.SGWorld，新版本可能用 TerraExplorerX.SGWorld Type t = Type.GetTypeFromProgID("Skyline.SGWorld") ?? Type.GetTypeFromProgID("TerraExplorerX.SGWorld"); if (t == null) { throw new COMException("TerraExplorer SDK 未注册，请检查安装"); } return Activator.CreateInstance(t); } }

这段代码里我用了两个候选 ProgID，先后尝试。实际部署时可以在配置文件里写死你机器上验证通过的那个，正式项目里我更倾向把它做成配置项，而不是在代码里俩都试。Activator.CreateInstance 会触发 COM 对象的类工厂调用，失败时抛 COMException，后续的 HResult 能帮你定位问题。

3.3 三步验证许可证，别等运行时才报License not found

许可证问题是我见过翻车率最高的启动阶段问题。TerraExplorer 的授权常见形态是加密锁和软授权，两者都会在 COM 对象初次初始化时校验。不少人写完整套代码，一按 F5 才发现初始化失败，排查半天找不到原因。我一般先把许可证验证做成一个独立的启动自检，三步走：

第一步，手动启动一次安装好的 TerraExplorer Pro，确认界面能正常打开，这一步能排除加密锁驱动、服务没启动等环境问题。第二步，用你的 C# 工程里那段动态创建代码实例化 SGWorld，并触发一个最简单的属性读取，让 COM 底层完成完整初始化。第三步，捕获 COMException 并打印 HResult 和 Message，留存日志。

using System; using System.Runtime.InteropServices; class Program { static void Main() { try { object obj = TeEntry.CreateSgWorld(); if (obj == null) { Console.WriteLine("SDK 未注册，请先安装 TerraExplorer Pro/SDK"); return; } // 触发一次底层初始化，让许可错误尽早暴露 dynamic sgWorld = obj; string version = sgWorld.Version; Console.WriteLine("TerraExplorer 版本: " + version); } catch (COMException ex) { Console.WriteLine($"0x{ex.HResult:X8}: {ex.Message}"); // 0x80040154 类未注册 // 0x8007007E 依赖 DLL 缺失 // 消息里带 license / dongle / HASP 是许可问题 } catch (Exception ex) { Console.WriteLine(ex.Message); } } }

这里用dynamic是因为我们从反射拿到的对象类型不确定，直接编译期调用接口方法需要强转成某个具体接口，而版本一变接口名就可能对不上，用 dynamic 至少能跑起来。正式项目里我建议在验证完具体版本后，补一个强类型封装层，把 dynamic 限制在这个入口处，别满代码飞。

4. 跑通第一个示例：加载地形和3DML模型

4.1 实例化SGWorld并打开一个fly工程

飞行工程文件（.fly）是 TerraExplorer 的项目文件，地形、影像、模型图层都挂在里面。二次开发的第一步不是创建工程，而是打开一个已经存在的 fly 工程，因为 TerraExplorer 的地球场景需要加载全球地形缓存，空工程也能跑，但加载速度、视角定位都会让你怀疑人生。先用 Pro 主程序建一个带基础地形和影像的工程，保存成 base.fly，开发时反复用。

下面是打开工程的最小代码。注意我把 SGWorld 实例存成了类字段，这是 COM 生命周期管理的关键，局部变量容易被 GC 提前回收，回收后事件不回、对象失效，问题表现非常隐蔽。

using System; using TerraExplorerX; class SceneBuilder { private SGWorld _sg; private IProject _proj; public bool OpenScene(string flyPath) { // 用 ProgID 创建 SGWorld，避免编译期锁死具体版本 object obj = TeEntry.CreateSgWorld(); if (obj == null) return false; _sg = (SGWorld)obj; _proj = _sg.Project; // 打开工程失败时返回 false，不一定抛异常 bool ok = _proj.Open(flyPath, "", true); if (!ok) { Console.WriteLine("打开工程失败，检查路径或许可"); } return ok; } }

参数说明：Open的第一个参数是 fly 文件全路径，支持相对路径，但批处理脚本里我只会用绝对路径；第二个参数传空字符串表示使用默认覆盖策略；第三个参数传true表示只读打开，防止脚本误改原始工程。只读模式在调试阶段非常有用，跑挂了也不担心把原工程弄脏。

4.2 创建图层组：先给场景一个归类的骨架

很多示例代码急着加模型，模型全堆在信息树根节点上，后期做显隐、导出、按业务分类筛选时根本没法收拾。TerraExplorer 的信息树是场景的骨架，分组（Group）既是结构节点也是图层容器。我习惯在建任何模型之前先按业务域建好分组。

// 在信息树根节点下创建一个分组 IGroup group = _proj.CreateGroup("业务模型"); Console.WriteLine("分组ID: " + group.ID);

CreateGroup默认挂在根节点下，也可以在第二个参数指定父分组 ID，形成树状结构。拿到分组 ID 后，后面创建的所有对象都可以挂进来，这样信息树的结构就是你的业务结构，而不是一串随机堆叠的模型名。实际交付时，客户经常会在信息树里自己勾选显隐，结构理不清的项目连验收这关都难过。

4.3 用经纬度定位相机并创建3DML模型

打开工程、建好分组之后，核心动作来了：把视角飞到目标区域，然后创建三维模型。这里最关键的是TEPosition64这个位置对象，它承载了经纬度、高度和姿态信息，TerraExplorer 里凡是涉及位置的接口，几乎都以它为参数。

// 用经纬度构造位置坐标 TEPosition64 pos = new TEPosition64(); pos.X = 121.4737; // 经度 pos.Y = 31.2304; // 纬度 pos.Altitude = 5.0; // 相对地表 5 米 pos.AltitudeType = TEAltitudeType.TE_AT_TERRAIN_REL; // 飞行定位，第二个参数是飞行秒数，0 表示瞬间到达 _sg.Navigate.SetPosition(pos, 0); // 创建 3DML 模型，最后一个参数指定父节点分组 ID string objId = _sg.CreateObject(TEObjectType.TE_3DML, pos, @"D:\models\hydrant.3dml", group.ID); if (string.IsNullOrEmpty(objId)) { Console.WriteLine("创建失败，检查模型路径和许可"); } else { Console.WriteLine("创建成功，对象ID=" + objId); }

这段代码有三个参数值得多说。第一，X和Y的对应关系：TerraExplorer 所有位置对象统一用X表示经度、Y表示纬度。中国区域内，经度在 73 到 135 之间，纬度在 18 到 53 之间。看到代码里X = 121、Y = 31（上海一带），基本就是对的；一旦出现X = 31、Y = 121，模型大概率被挂到海里或荒地里了。第二，AltitudeType决定高度基准：TE_AT_TERRAIN_REL是相对地表高度，适合路灯、消防栓、摄像头这类贴地摆放的设备；TE_AT_TERRAIN_ABS是绝对海拔高度，适合管线、隧道这类需要真实高程信息的对象。第三，CreateObject返回的对象 ID 是后续所有操作的钥匙，改姿态、换模型、删对象都靠它，务必存进业务数据表，别用完就丢。

提示：TEPosition64 在某些版本里还带 Yaw、Pitch、Roll 三个姿态角。如果你发现创建出来的模型朝向不对，别在创建时直接调这三个参数，某些版本会有兼容问题。稳妥做法是创建完成后，通过对象接口再 SetPosition 一次设置姿态。

5. TerraExplorer二次开发避坑手册：五个血泪现场

5.1 32位与64位进程错位，COM实例化直接崩

现象：代码在开发机一切正常，部署到服务器就报 0x80040154 类未注册；或者同一台机器上，控制台程序能跑，WinForms 程序却闪退。

原因：TerraExplorer 的 COM 组件注册是按位数分区的，64 位注册表里的类，32 位进程看不到。绝大多数服务器上只装了 64 位 SDK，而你的 WinForms 项目如果没关“首选 32 位”，即使平台目标写了 x64，Visual Studio 仍可能以 32 位进程运行调试。

解决：打开项目属性，生成选项卡，平台目标选 x64，同时把“首选 32 位”勾选去掉。改完在Main入口第一行打印Environment.Is64BitProcess，确认输出为 True 再往下走。

5.2 经纬度写反，模型挂到海里

现象：模型创建成功，信息树里看得到，但相机飞到业务坐标后，场景里空空如也；把视图缩小一看，模型出现在距离目标点几百公里的地方。

原因：TerraExplorer 的位置对象用X存经度、Y存纬度，和很多人习惯的“纬度在前、经度在后”刚好相反。从数据库里读坐标时，如果表结构是(lat, lon)，你直接赋值就会反。

解决：赋值时统一写成pos.X = lon; pos.Y = lat;，并且在创建完对象后立刻回读一次位置打印出来对比。回读接口随版本略有差异，但思路一致：拿到刚创建的 objId，通过对象接口读它的 Position，检查 X/Y 是否落在业务区域。这步做成日志输出，部署到现场时能省大量沟通时间。

5.3 相对高度与绝对高度混用，模型要么陷地要么飞上天

现象：同一个模型，放在 A 区域贴地正常，放到 B 区域就陷进地里半截；换成TE_AT_TERRAIN_ABS后，模型又浮在空中。

原因：TERRAIN_ABS是绝对海拔高度，模型会严格钉在海拔面上。地形数据精度不够时，模型底座和地形表面之间就会有缝隙；TERRAIN_REL是相对地表高度，会跟随地形起伏，适合贴地物体，但它需要地形缓存就在当前场景里。

解决：地表设备、建筑白模这类“必须压在地面上”的对象，一律用TE_AT_TERRAIN_REL，高度给一个很小值（比如 0.1 到 1 米），避免模型和地形穿插导致的闪面。必须用绝对海拔的场景，先确认 DEM 数据的精度和坐标系一致，否则高程误差会被模型渲染放大得很明显。

5.4 事件回调不触发：不是玄学，是订阅方式和生命周期

现象：订阅了鼠标点击事件，点击三维场景里的模型，断点始终不进来；偶尔第一次能触发，之后再不触发。

原因：两个坑叠加。第一，COM 事件在 C# 里要绑定到事件插口接口（类似 IEventEvents），直接按普通 .NET 事件写，编译器不报错但运行时收不到；第二，事件源对象如果被 GC 回收，事件就静默失效。局部变量在方法返回后失去引用，事件自然断掉。

解决：把 SGWorld 和事件对象都存成类字段或静态字段，保证长期存活；订阅时用事件插口接口。代码里这样写：

// 事件源对象存入字段，避免被 GC 回收 IEventEvents events = (IEventEvents)_sg.Event; events.OnLButtonClick += (x, y, px, py) => { Console.WriteLine($"点击屏幕坐标: ({x}, {y})，投影坐标: ({px}, {py})"); };

事件回调里不要做耗时操作，它是跑在 TerraExplorer 的 COM 线程上的，你在这里面执行数据库查询或网络请求，会把三维窗口卡死。正确做法是把事件数据塞进队列，由你自己的工作线程去处理。

5.5 许可证被桌面端占用，批处理半夜失败

现象：批处理程序白天运行一切正常，凌晨定时任务跑起来偶尔失败，日志里出现 license 相关错误；人为重启任务后又正常。

原因：TerraExplorer Pro 桌面端如果开着，会占用授权；同一台机器上再启动一个 COM 实例时，软授权或加密锁的并发限制会拒绝服务。批处理任务失败后无人干预，看起来就像偶发故障。

解决：批处理启动前先检测并关闭 Pro 桌面进程；任务里做启动自检，遇到 license 错误就退避重试，别在原进程上反复重试，因为失败的 COM 实例可能残留了锁句柄。多次重试仍失败则告警，让值班人员介入。这一步看着不起眼，但对无人值守的交付项目来说是刚需。

6. 进阶技巧与验证：让示例代码真正能交付

6.1 把Excel点表批量变成三维场景

单个模型创建跑通后，真正的业务场景往往是几百上千个点。从 Excel 或数据库读出经纬度、模型路径、分组信息，循环创建即可。注意三个细节：对象 ID 必须存下来用于后续更新；创建操作隔一段时间让 COM 线程喘口气；分组的 ID 在循环体外取好，别每次重复创建。

foreach (var row in points) { TEPosition64 p = new TEPosition64 { X = row.Lon, Y = row.Lat, Altitude = row.Height, AltitudeType = TEAltitudeType.TE_AT_TERRAIN_REL }; string id = _sg.CreateObject(TEObjectType.TE_3DML, p, row.ModelPath, groupId); if (string.IsNullOrEmpty(id)) { Console.WriteLine($"创建失败: {row.Lon},{row.Lat}"); continue; } // 每 50 个对象让 COM 线程处理一下消息，避免积压 if (++count % 50 == 0) { System.Threading.Thread.Sleep(100); } }

Thread.Sleep不是玄学，是给 COM 底层 UI 线程让出时间片。批量 500 个以上对象时，不加这个 SLeep 有时会出现后续对象创建失败或场景卡死，具体阈值和机器性能有关，跑一次压测就能定下来。

6.2 自动化冒烟验证：不打开界面也能判断是否成功

交付前我只相信自动化验证脚本。固定流程是：创建完所有对象后保存工程，再重新打开，遍历信息树统计对象数量，核对坐标落在预期范围内。这个脚本每次改完代码都跑一遍，接口升级也不怕。

// 保存工程，供自动化验收 _sg.Project.SaveAs(@"D:\scene\out.fly"); // 重新打开，核对对象数 _sg.Project.Open(@"D:\scene\out.fly", "", true); int total = 0; foreach (IObject obj in _sg.Project.Objects) { total++; } Console.WriteLine("场景对象总数: " + total);

把“打开工程、创建模型、统计数量、保存退出”做成一个不依赖界面的人工检查脚本，任何环境问题都会在这里暴露。我最开始做这个方向时，因为没关“首选 32 位”浪费了整整半天，后来每次新建项目都先写一个这样的冒烟脚本，后面所有接口调整都不怕了。TerraExplorer 的 API 版本差异比文档里看起来更野，与其背接口不如先把验证脚本固定下来，希望帮到你。

本文还有配套的精品资源，点击获取