写完这个工具之前我建议你先想清楚一个问题你是在画“一个长轴方向和短轴方向确定的椭圆”还是在画“一个抽象的椭圆形状范围”这个区别直接决定了后续交互流程怎么设计、数据怎么存、地图上怎么更新。很多 Cesium 新手在接触 Ellipse 时会下意识觉得“不就是画个椭圆吗用ellipse属性加两个半轴长度就行。” 这句话对了一半。只要会配置semiMajorAxis和semiMinorAxis确实能在 3D 地球上快速画出一个椭圆。但真正到了业务项目里你会立刻遇到另一堆问题椭圆是贴地还是离地单位到底是米还是经纬度椭圆画出来为什么被地形埋住用户能不能用鼠标点击动态画点完中心之后半长轴和半短轴怎么由第二次、第三次点击确定这每一个问题都不是“加一个属性”能解决的。这篇博客就从“Cesium 绘图工具 - Ellipse”这个主题出发先帮你建立 Ellipse 相关 API 的完整认知再给你一个可以直接放到项目里的EllipseDrawTool交互式绘图工具实现最后补充高频踩坑点和工程最佳实践。读完以后你不只能画出一个静态椭圆还能根据真实业务需求动手改出一套适合自己的椭圆绘图能力。1. 这篇文章真正要解决的问题在 GIS 前端项目里“在地图上画一个椭圆形区域”是一个出现频率高、但难度很容易被低估的需求。比如做基站信号覆盖评估时需要在地图上画出某个扇区的椭圆覆盖范围做环保影响分析时需要把一个污染源的影响范围近似成一个椭圆做土地规划时需要把预征收区域在地图上圈出来。这些业务场景的共同点是最终交付物不是一个写死的测试图形而是用户能在地图上交互绘制、能修改参数、能叠加到底图上的真实业务数据。Ellipse 绘图工具要解决的核心问题可以拆成四层API 层知道 Cesium 里有哪些类型可以绘制椭圆Entity 方式和 Primitive 方式的差异是什么。数据层清楚椭圆几何参数如何映射到 Cesium 坐标系半长轴、半短轴的物理单位是什么。交互层能够通过鼠标点击、输入参数和实时预览把用户意图转化成一个椭圆 Entity。工程层在真实项目里需要做到点击生成、批量管理、动态更新、按图层清除避免绘图代码和业务代码混在一起难以维护。这四层里面最容易被忽略的是数据层。很多人看过 API 示例知道要设置semiMajorAxis和semiMinorAxis但不知道这两个值的单位是米结果把经纬度差值直接填进去画出来的椭圆大得离谱。也有人不知道 Cesium 的椭圆默认是放置在椭球表面或指定高度上的平面几何体当地形起伏比较大时椭圆会被地形盖住看起来像没画出来。这篇文章适合正在做 Cesium 二三维 GIS 开发、需要把绘图工具接入业务系统的前端工程师。如果你是初学者建议先能运行基础示例再逐步理解交互工具内部的事件处理和坐标系转换如果你已经有 Cesium 基础可以直接跳到交互式绘图工具章节参考工具类的封装方式。2. Cesium 中椭圆相关核心概念2.1 不要混淆 Entity、Graphics、GeometryCesium 绘制椭圆有两种完全不同的技术路线Entity API面向对象、声明式适合业务图层管理。通过viewer.entities.add()添加一个 Entity并给这个 Entity 配置ellipse属性。Primitive API面向底层几何绘制适合需要高性能渲染大量几何体的场景。需要手动创建Cesium.EllipseGeometry或Cesium.EllipseOutlineGeometry再通过Cesium.Primitive添加到场景中。很多新手会把这两套 API 混在一起理解这是导致代码混乱的第一个原因。Entity 的ellipse属性只是一个高层描述它内部的实现最终也会创建几何体并交给渲染引擎而 Primitive 则让你直接控制顶点、材质和渲染批次。Entity 方式对应到源码主要涉及三个不同类型它们名字相近但职责不同Cesium.EllipseGraphics描述 Entity 上椭圆外观配置的类型配置项包括材质、高度、拉伸高度、旋转角度等。Cesium.EllipseGeometry真正参与几何计算的椭圆几何体包含顶点位置、法线、切线和纹理坐标。Cesium.EllipseOutlineGeometry只生成椭圆轮廓的几何体对应我们常说的“描边”。在用 Entity 时我们给ellipse配置的其实是EllipseGraphics类型的参数。而在用 Primitive 时我们创建的是后两种 Geometry 对象。2.2 椭圆的几何含义Cesium 里的椭圆并不是地球表面的一条椭圆弧线而是在空间直角坐标系中定义的一个平面几何体。它的中心点由一个position坐标决定再以这个中心点对应的椭球面法线方向为基准在水平面上展开图形。参数含义说明position椭圆中心点Entity 的位置属性通常用Cartesian3.fromDegrees创建semiMajorAxis半长轴长度单位是米而不是经纬度semiMinorAxis半短轴长度单位是米必须小于等于半长轴height椭圆所在高度单位是米默认值是 0表示在椭球表面extrudedHeight拉伸高度设置后椭圆变成三维立体形状rotation几何旋转角度控制椭圆本身绕法向方向的旋转granularity三角剖分粒度控制椭圆边缘的平滑程度material表面材质可以设置颜色、图片或自定义材质outline是否显示描边配合outlineColor使用这里要特别注意position和semiMajorAxis、semiMinorAxis的配合。position告诉你椭圆的中心点在哪但椭圆平面具体是怎样的方向取决于 Cesium 内部建立局部坐标系的方式。因此在实际业务中如果用户对椭圆的朝向有严格要求除了设置半轴长度还需要处理旋转角度。从数学上看椭圆是“到两个焦点距离之和为常数”的轨迹。但在 Cesium 的日常用法中我们很少通过焦点来创建椭圆而是通过“中心点 两个半轴长度”来确定。这种定义方式的好处是用户只需要关心中心坐标、长半轴距离、短半轴距离三个语义明确的量。它与圆的区别也很直接当semiMajorAxis semiMinorAxis时椭圆就退化成了圆。Cesium 也提供了独立的circle属性但如果你使用ellipse绘制等半径图形效果是完全等价的。3. 环境准备与项目初始化3.1 开发环境Cesium Ellipse 绘制不涉及后端只需要本机能运行静态页面即可。本文示例代码不绑定某个精确的 Cesium 版本本地需要准备一个现代浏览器推荐 Chrome 或 Edge。CesiumJS 本地包可以是 npm 安装后拷贝出来的Build/Cesium目录也可以直接下载官方 Release 包。一个纯静态服务器。如果只是双击 HTML 文件无法正常加载 Cesium本地开发推荐使用 VSCode 的 Live Server 插件或执行npx serve .。建议项目目录结构如下cesium-ellipse-demo/ |-- index.html |-- js/ | |-- Cesium/ | | -- EllipseDrawTool.js | -- Cesium/ | |-- Cesium.js | -- Widgets/实际目录名可以灵活调整关键在于Cesium.js的路径必须写对并且需要提前设置CESIUM_BASE_URL让 Cesium 能正确找到图片、字体等静态资源。3.2 初始化 Viewer创建一个基础的index.html初始化 Cesium Viewer。为了演示效果更清晰可以关闭默认的动画控制、时间线和地理编码搜索框这样页面会自动加载全球影像便于直接看到绘制的椭圆。!DOCTYPE html html langzh-CN head meta charsetutf-8 / titleCesium Ellipse 绘图入门/title link hreflibs/Cesium/Widgets/widgets.css relstylesheet / style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; } /style /head body div idcesiumContainer/div script window.CESIUM_BASE_URL ./libs/Cesium/; /script script srclibs/Cesium/Cesium.js/script script const viewer new Cesium.Viewer(cesiumContainer, { animation: false, timeline: false, geocoder: false, baseLayerPicker: false }); // 后面所有示例都构建在 viewer 上 window.viewer viewer; /script /body /html在网页里直接嵌入Cesium.Viewer时会占用一整个容器如果项目本身是 Vue 或 React只要把cesiumContainer替换成对应的 DOM 组件 ref并在生命周期内完成初始化思路是一样的。3.3 版本与许可证提醒Cesium 的 API 在 1.100 之后整体趋于稳定本文核心示例在常见版本中都可以运行。但不同大版本之间仍有细微差异例如某些Material.fromType的字符串常量、某些默认材质颜色呈现方式。遇到 API 不生效时先查看当前版本对应的官方 Sandcastle 示例避免用旧版本思维调试新版本。如果项目需要商用或内网部署请注意 Cesium ion 的 Token 和在线地图资源授权问题。本文示例使用默认底图和本地几何绘制不依赖在线 Token适合先跑通逻辑。4. Entity 方式快速绘制椭圆4.1 最小可用示例先实现一个最基础的在北京某个坐标点画一个长半轴 5000 米、短半轴 2000 米的椭圆并添加中心点文字标签方便观察位置关系。!DOCTYPE html html langzh-CN head meta charsetutf-8 / titleCesium Ellipse 基础示例/title link hreflibs/Cesium/Widgets/widgets.css relstylesheet / style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; }