cesium-xs-sdk 1.0.0 → 1.0.1

package/dist/cesium-xs-sdk.cjs.js

@@ -1005,12 +1005,13 @@ class PlotGeometryUtil {
     let angleDiff = endAngle - startAngle;
     angleDiff = angleDiff < 0 ? angleDiff + Math.PI * 2 : angleDiff;
 
-    const points = [startPoint];
-    for (let i = 1; i < segments; i++) {
+    // 所有圆弧点必须严格在 radiusMeters 为半径的圆上，不能直接使用输入控制点，
+    // 否则鼠标位置到圆心的距离可能与半径不一致，导致扇形闭合边出现三角形或穿入内部。
+    const points = [];
+    for (let i = 0; i <= segments; i++) {
       const angle = startAngle + (angleDiff * i) / segments;
       points.push(this._getPointAtBearingAndDistance(center, radiusMeters, angle));
     }
-    points.push(endPoint);
     return points;
   }
 
@@ -1450,11 +1451,14 @@ class PlotGeometryUtil {
     // 使用球面距离作为半径，与圆弧插值函数保持一致
     const radius = this._calcSphericalDistance(pnt2, center);
 
-    // 弧线精确经过两个控制点，避免端点漂移
+    // 弧线精确经过两个控制点方向，半径统一为圆心到起始控制点的球面距离，
+    // 避免结束控制点（鼠标位置）到圆心距离与半径不一致导致扇形畸变。
     const arcPoints = this._getGeoArcPointsBetween(center, pnt2, pnt3, radius);
-    arcPoints.push(center);
 
-    return this.toPositions(arcPoints, height);
+    // 扇形轮廓：圆心 -> 圆弧起点 -> 圆弧终点 -> 回到圆心（Cesium polygon 自动闭合）
+    const sectorPoints = [center, ...arcPoints];
+
+    return this.toPositions(sectorPoints, height);
   }
 
   /**
@@ -4387,7 +4391,7 @@ class EditTool extends BaseTool {
     const screenPos = movement.position || (movement && movement.endPosition);
     if (!screenPos) return;
 
-    const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+    const picked = this._viewer.scene.pick(screenPos);
     console.log('EditTool _onClick:', { picked, screenPos });
 
     if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
@@ -4425,7 +4429,7 @@ class EditTool extends BaseTool {
 
     // 如果已经选中了图元，检查是否点击了控制点
     if (this._selectedEntity && !this._isDragging) {
-      const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+      const picked = this._viewer.scene.pick(screenPos);
       if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
         const entityId = picked.id.id;
         if (entityId && (entityId.startsWith('__edit_handle_') || entityId.includes('__edit_handle_'))) {
@@ -4478,7 +4482,7 @@ class EditTool extends BaseTool {
       this._lastMoveTime = now;
 
       // 检测是否悬停在控制点上
-      const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+      const picked = this._viewer.scene.pick(screenPos);
       const isOverHandle = Cesium.defined(picked) && Cesium.defined(picked.id) &&
         picked.id.id && picked.id.id.startsWith('__edit_handle_');
       this._setCursorStyle(isOverHandle ? 'move' : 'default');
@@ -5970,7 +5974,7 @@ class SelectTool extends BaseTool {
     const screenPos = movement.position || (movement && movement.endPosition);
     if (!screenPos) return;
 
-    const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+    const picked = this._viewer.scene.pick(screenPos);
 
     if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
       const entityId = picked.id.id;
@@ -6024,6 +6028,7 @@ class SelectTool extends BaseTool {
   }
 
   _updateSelectionRectPreview(currentPos) {
+    this._currentEndPos = currentPos;
     if (this._selectType === SelectType.RECTANGLE) {
       this._updateRectPreview(currentPos);
     } else if (this._selectType === SelectType.CIRCLE) {
@@ -6041,7 +6046,10 @@ class SelectTool extends BaseTool {
       this._selectionRect = this.createTempEntity(this.generateId('sel_rect'), {
         polyline: {
           positions: new Cesium.CallbackProperty(() => {
-            const pos = this._getRectPositions(corner1, corner2);
+            const c1 = this._startPos;
+            const c2 = this._currentEndPos;
+            if (!c1 || !c2) return [];
+            const pos = this._getRectPositions(c1, c2);
             return Cesium.Cartesian3.fromDegreesArrayHeights(pos.flatMap(c => [c[0], c[1], 0]));
           }, false),
           material: Cesium.Color.CYAN,
@@ -6049,7 +6057,10 @@ class SelectTool extends BaseTool {
         },
         polygon: {
           hierarchy: new Cesium.CallbackProperty(() => {
-            const pos = this._getRectPositions(corner1, corner2);
+            const c1 = this._startPos;
+            const c2 = this._currentEndPos;
+            if (!c1 || !c2) return new Cesium.PolygonHierarchy([]);
+            const pos = this._getRectPositions(c1, c2);
             return new Cesium.PolygonHierarchy(
               Cesium.Cartesian3.fromDegreesArrayHeights(pos.flatMap(c => [c[0], c[1], 0]))
             );
@@ -6072,8 +6083,11 @@ class SelectTool extends BaseTool {
       this._selectionRect = this.createTempEntity(this.generateId('sel_circle'), {
         polygon: {
           hierarchy: new Cesium.CallbackProperty(() => {
-            const radius = this._calcDistance(center, currentPos);
-            const positions = this._generateCirclePositions(center, radius, 36);
+            const c = this._startPos;
+            const edge = this._currentEndPos;
+            if (!c || !edge) return new Cesium.PolygonHierarchy([]);
+            const radius = this._calcDistance(c, edge);
+            const positions = this._generateCirclePositions(c, radius, 36);
             return new Cesium.PolygonHierarchy(
               Cesium.Cartesian3.fromDegreesArrayHeights(
                 positions.flatMap(c => [c[0], c[1], 0])
@@ -6459,7 +6473,7 @@ class DeleteTool extends BaseTool {
     const screenPos = movement.position || (movement && movement.endPosition);
     if (!screenPos) return;
 
-    const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+    const picked = this._viewer.scene.pick(screenPos);
 
     if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
       const entityId = picked.id.id;
@@ -6481,7 +6495,7 @@ class DeleteTool extends BaseTool {
     const screenPos = data.position || data.endPosition;
     if (!screenPos) return;
 
-    const picked = this._viewer.scene.pick({ x: screenPos.x, y: screenPos.y });
+    const picked = this._viewer.scene.pick(screenPos);
 
     let hoveredId = null;
 
@@ -7022,6 +7036,1213 @@ class EditorModule {
   }
 }
 
+/**
+ * 控件基类
+ * 所有地图控件的抽象基类，提供 DOM 容器管理、挂载/移除、事件绑定等通用能力。
+ * 参考 Mars3D BaseControl 设计，但保持轻量，不依赖 jQuery。
+ */
+class BaseControl {
+  /**
+   * @param {object} options 控件配置
+   * @param {string} options.type 控件类型标识
+   * @param {string} [options.className] 容器额外 CSS 类名
+   * @param {string|HTMLElement} [options.container] 自定义父容器，默认挂到 viewer.container
+   * @param {number} [options.bottom=0] 底部偏移（px）
+   * @param {number} [options.left] 左侧偏移（px）
+   * @param {number} [options.right] 右侧偏移（px）
+   * @param {number} [options.top] 顶部偏移（px）
+   * @param {boolean} [options.visible=true] 初始是否可见
+   */
+  constructor(options = {}) {
+    this._type = options.type || 'base';
+    this._options = options;
+    this._viewer = null;
+    this._container = null;
+    this._parentContainer = null;
+    this._isAdded = false;
+    this._handlers = [];
+  }
+
+  /**
+   * 控件类型
+   */
+  get type() {
+    return this._type;
+  }
+
+  /**
+   * 获取控件 DOM 容器
+   */
+  get container() {
+    return this._container;
+  }
+
+  /**
+   * 创建控件 DOM 容器
+   * 子类可重写以自定义容器结构
+   */
+  _createContainer() {
+    const div = document.createElement('div');
+    div.className = `xs3d-control xs3d-control-${this._type}`;
+    if (this._options.className) {
+      div.className += ` ${this._options.className}`;
+    }
+    div.style.position = 'absolute';
+    div.style.zIndex = '1000';
+    div.style.pointerEvents = 'auto';
+
+    const positions = ['left', 'right', 'top', 'bottom'];
+    positions.forEach(key => {
+      if (this._options[key] !== undefined) {
+        div.style[key] = typeof this._options[key] === 'number'
+          ? `${this._options[key]}px`
+          : this._options[key];
+      }
+    });
+
+    if (this._options.visible === false) {
+      div.style.display = 'none';
+    }
+
+    return div;
+  }
+
+  /**
+   * 获取父容器
+   * 子类可重写，例如挂到 Cesium 工具栏
+   */
+  _getParentContainer() {
+    if (this._options.container) {
+      if (typeof this._options.container === 'string') {
+        return document.querySelector(this._options.container);
+      }
+      return this._options.container;
+    }
+    return this._viewer?.container;
+  }
+
+  /**
+   * 获取或创建 SDK 统一工具栏（xs3d-viewer-toolbar）
+   * 供内置控件共享一个右上角的垂直工具栏容器。
+   */
+  _getOrCreateToolbar() {
+    const viewerContainer = this._viewer?.container;
+    if (!viewerContainer) return null;
+
+    let toolbar = viewerContainer.querySelector('.xs3d-viewer-toolbar');
+    if (!toolbar) {
+      toolbar = document.createElement('div');
+      toolbar.className = 'xs3d-viewer-toolbar';
+      toolbar.style.position = 'absolute';
+      toolbar.style.top = '5px';
+      toolbar.style.right = '5px';
+      toolbar.style.display = 'flex';
+      toolbar.style.flexDirection = 'column';
+      toolbar.style.alignItems = 'center';
+      toolbar.style.gap = '4px';
+      toolbar.style.padding = '4px';
+      toolbar.style.background = 'rgba(63, 72, 84, 0.95)';
+      toolbar.style.borderRadius = '4px';
+      toolbar.style.boxShadow = '0 1px 4px rgba(0,0,0,0.35)';
+      toolbar.style.zIndex = '1001';
+      viewerContainer.appendChild(toolbar);
+    }
+    return toolbar;
+  }
+
+  /**
+   * 若当前父容器是统一工具栏，清除子容器的 absolute 定位
+   */
+  _clearAbsolutePositionIfInToolbar() {
+    if (this._parentContainer?.classList?.contains('xs3d-viewer-toolbar') ||
+        this._parentContainer?.classList?.contains('cesium-viewer-toolbar')) {
+      this._container.style.position = 'static';
+      this._container.style.top = '';
+      this._container.style.right = '';
+      this._container.style.bottom = '';
+      this._container.style.left = '';
+    }
+  }
+
+  /**
+   * 挂载到 Cesium Viewer
+   * @param {Cesium.Viewer} viewer
+   */
+  addTo(viewer) {
+    if (this._isAdded || !viewer) return this;
+
+    this._viewer = viewer;
+    this._parentContainer = this._getParentContainer();
+    this._container = this._createContainer();
+
+    // 若父容器是统一工具栏，子容器取消 absolute 定位，避免被自身 top/right 撑出工具栏
+    if (this._parentContainer?.classList?.contains('xs3d-viewer-toolbar') ||
+        this._parentContainer?.classList?.contains('cesium-viewer-toolbar')) {
+      this._container.style.position = 'static';
+      this._container.style.top = '';
+      this._container.style.right = '';
+      this._container.style.bottom = '';
+      this._container.style.left = '';
+    }
+
+    // 确保父容器有定位，否则 absolute 子元素会相对于 body 定位
+    if (this._parentContainer) {
+      const style = window.getComputedStyle(this._parentContainer);
+      if (style.position === 'static') {
+        this._parentContainer.style.position = 'relative';
+      }
+    }
+
+    // 子类挂载 DOM 内容
+    this._mount();
+
+    if (this._parentContainer) {
+      this._parentContainer.appendChild(this._container);
+    }
+
+    // 绑定地图事件
+    this._bindEvents();
+
+    this._isAdded = true;
+    return this;
+  }
+
+  /**
+   * 从地图移除
+   * @param {boolean} destroy 是否销毁控件
+   */
+  remove(destroy = true) {
+    if (!this._isAdded) return this;
+
+    this._unbindEvents();
+
+    if (this._container && this._container.parentNode) {
+      this._container.parentNode.removeChild(this._container);
+    }
+
+    if (destroy) {
+      this._destroy();
+    }
+
+    this._container = null;
+    this._parentContainer = null;
+    this._viewer = null;
+    this._isAdded = false;
+    return this;
+  }
+
+  /**
+   * 显示控件
+   */
+  show() {
+    if (this._container) {
+      this._container.style.display = '';
+    }
+    return this;
+  }
+
+  /**
+   * 隐藏控件
+   */
+  hide() {
+    if (this._container) {
+      this._container.style.display = 'none';
+    }
+    return this;
+  }
+
+  /**
+   * 注册 Viewer/Cesium 事件处理器
+   * @param {Cesium.Event} event Cesium 事件对象
+   * @param {Function} callback 回调
+   */
+  _addCesiumHandler(event, callback) {
+    const handler = event.addEventListener(callback);
+    this._handlers.push({ type: 'cesium', event, handler });
+    return handler;
+  }
+
+  /**
+   * 注册原生 DOM 事件
+   */
+  _addDomEvent(element, eventType, callback, options = false) {
+    element.addEventListener(eventType, callback, options);
+    this._handlers.push({ type: 'dom', element, eventType, callback, options });
+    return this;
+  }
+
+  /**
+   * 解除所有事件绑定
+   */
+  _unbindEvents() {
+    this._handlers.forEach(h => {
+      if (h.type === 'cesium' && h.event && typeof h.handler === 'function') {
+        h.handler();
+      } else if (h.type === 'dom' && h.element) {
+        h.element.removeEventListener(h.eventType, h.callback, h.options);
+      }
+    });
+    this._handlers = [];
+  }
+
+  /**
+   * 子类重写：创建控件内部 DOM
+   */
+  _mount() { }
+
+  /**
+   * 子类重写：绑定地图事件
+   */
+  _bindEvents() { }
+
+  /**
+   * 子类重写：销毁内部资源
+   */
+  _destroy() { }
+}
+
+/**
+ * 状态栏控件
+ * 显示鼠标位置经纬度、海拔、相机方向/俯仰角/视高、地图层级、FPS 等信息。
+ * 支持自定义模板和显示字段。
+ */
+class LocationBar extends BaseControl {
+  /**
+   * @param {object} options
+   * @param {string} [options.template='经度:{lng} 纬度:{lat} 海拔:{alt}米 方向:{heading}° 俯仰:{pitch}° 视高:{cameraHeight}米']
+   * @param {number} [options.latDecimal=6] 纬度小数位
+   * @param {number} [options.lngDecimal=6] 经度小数位
+   * @param {boolean} [options.showFPS=false] 是否显示 FPS
+   * @param {number} [options.bottom=0] 底部偏移
+   * @param {number} [options.left=0] 左侧偏移
+   * @param {number} [options.right] 右侧偏移
+   */
+  constructor(options = {}) {
+    super({
+      type: 'locationBar',
+      bottom: 0,
+      right: 0,
+      ...options
+    });
+
+    this._template = options.template || '经度:{lng} 纬度:{lat} 海拔:{alt}米 方向:{heading}° 俯仰:{pitch}° 视高:{cameraHeight}米 层级:{level}';
+    this._latDecimal = options.latDecimal ?? 6;
+    this._lngDecimal = options.lngDecimal ?? 6;
+    this._showFPS = options.showFPS ?? false;
+    this._lastCameraData = {};
+    this._lastMouseData = {};
+    this._fps = 0;
+  }
+
+  _createContainer() {
+    const div = super._createContainer();
+    div.className += ' xs3d-locationbar';
+    div.style.display = 'flex';
+    div.style.alignItems = 'center';
+    div.style.gap = '12px';
+    div.style.padding = '6px 12px';
+    div.style.background = 'rgba(0, 0, 0, 0.55)';
+    div.style.color = '#fff';
+    div.style.fontSize = '12px';
+    div.style.fontFamily = 'Microsoft YaHei, sans-serif';
+    div.style.pointerEvents = 'none';
+    div.style.userSelect = 'none';
+    div.style.whiteSpace = 'nowrap';
+    return div;
+  }
+
+  _mount() {
+    this._updateContent();
+  }
+
+  _bindEvents() {
+    // 鼠标移动：更新鼠标位置信息
+    const canvas = this._viewer.scene.canvas;
+    this._addDomEvent(canvas, 'mousemove', this._onMouseMove.bind(this));
+    this._addDomEvent(canvas, 'mouseleave', this._onMouseLeave.bind(this));
+
+    // 相机变化：更新方向/俯仰/视高/层级
+    this._addCesiumHandler(this._viewer.camera.changed, this._onCameraChanged.bind(this));
+
+    // FPS
+    if (this._showFPS) {
+      this._addCesiumHandler(this._viewer.scene.postRender, this._onPostRender.bind(this));
+      this._fpsFrameCount = 0;
+      this._fpsLastTime = performance.now();
+    }
+
+    // 初始更新一次
+    this._onCameraChanged();
+  }
+
+  _onMouseMove(e) {
+    const rect = this._viewer.scene.canvas.getBoundingClientRect();
+    const x = e.clientX - rect.left;
+    const y = e.clientY - rect.top;
+    const screenPos = new Cesium.Cartesian2(x, y);
+
+    let cartesian = null;
+
+    // 优先使用 globe.pick 获取真实地表（含地形）高度
+    const ray = this._viewer.camera.getPickRay(screenPos);
+    if (ray) {
+      cartesian = this._viewer.scene.globe.pick(ray, this._viewer.scene);
+    }
+
+    // 如果地表不可见，回退到椭球面
+    if (!cartesian) {
+      cartesian = this._viewer.camera.pickEllipsoid(screenPos, this._viewer.scene.globe.ellipsoid);
+    }
+
+    if (cartesian) {
+      const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
+      this._lastMouseData = {
+        lng: Cesium.Math.toDegrees(cartographic.longitude).toFixed(this._lngDecimal),
+        lat: Cesium.Math.toDegrees(cartographic.latitude).toFixed(this._latDecimal),
+        alt: cartographic.height.toFixed(2)
+      };
+    } else {
+      this._lastMouseData = { lng: '-', lat: '-', alt: '-' };
+    }
+
+    this._updateContent();
+  }
+
+  _onMouseLeave() {
+    this._lastMouseData = { lng: '-', lat: '-', alt: '-' };
+    this._updateContent();
+  }
+
+  _onCameraChanged() {
+    const camera = this._viewer.camera;
+    const positionCartographic = camera.positionCartographic;
+
+    this._lastCameraData = {
+      heading: Cesium.Math.toDegrees(camera.heading).toFixed(2),
+      pitch: Cesium.Math.toDegrees(camera.pitch).toFixed(2),
+      cameraHeight: positionCartographic.height.toFixed(2),
+      level: this._getZoomLevel().toFixed(0)
+    };
+
+    this._updateContent();
+  }
+
+  _onPostRender() {
+    this._fpsFrameCount++;
+    const now = performance.now();
+    const elapsed = now - this._fpsLastTime;
+
+    if (elapsed >= 1000) {
+      this._fps = Math.round((this._fpsFrameCount * 1000) / elapsed);
+      this._fpsFrameCount = 0;
+      this._fpsLastTime = now;
+      this._updateContent();
+    }
+  }
+
+  _getZoomLevel() {
+    const camera = this._viewer.camera;
+    const positionCartographic = camera.positionCartographic;
+
+    // 计算相机到正下方地表点的距离（视高），而不是到自己位置的距离
+    const surfaceCartesian = Cesium.Cartesian3.fromRadians(
+      positionCartographic.longitude,
+      positionCartographic.latitude,
+      0
+    );
+    const distance = Cesium.Cartesian3.distance(camera.position, surfaceCartesian);
+
+    if (!distance || distance <= 0 || !Number.isFinite(distance)) return 0;
+
+    // 赤道周长约 40075017 米，映射为类似瓦片层级
+    const equatorCircumference = 6378137 * 2 * Math.PI;
+    return Math.max(0, Math.floor(Math.log2(equatorCircumference / distance)) + 1);
+  }
+
+  _updateContent() {
+    if (!this._container) return;
+
+    const data = {
+      ...this._lastMouseData,
+      ...this._lastCameraData,
+      fps: this._fps
+    };
+
+    let html = this._template;
+    Object.keys(data).forEach(key => {
+      html = html.replace(new RegExp(`{${key}}`, 'g'), data[key]);
+    });
+
+    // 如果开启 FPS 但模板里没有 {fps}，则自动追加到末尾
+    if (this._showFPS && !this._template.includes('{fps}')) {
+      html += ` FPS:${this._fps}`;
+    }
+
+    this._container.innerHTML = html;
+  }
+}
+
+/**
+ * 缩放控件
+ * 提供放大/缩小两个按钮，默认挂到 SDK 统一工具栏（xs3d-viewer-toolbar）。
+ */
+class Zoom extends BaseControl {
+  /**
+   * @param {object} options
+   * @param {number} [options.duration=0.5] 缩放动画时长（秒）
+   */
+  constructor(options = {}) {
+    super({
+      type: 'zoom',
+      ...options
+    });
+
+    this._duration = options.duration ?? 0.5;
+  }
+
+  _createContainer() {
+    const div = super._createContainer();
+    div.className += ' xs3d-zoom';
+    div.style.display = 'contents';
+    return div;
+  }
+
+  _getParentContainer() {
+    if (this._options.container) {
+      return super._getParentContainer();
+    }
+    return this._getOrCreateToolbar();
+  }
+
+  _mount() {
+    this._clearAbsolutePositionIfInToolbar();
+
+    this._zoomInBtn = this._createButton('+', '放大');
+    this._zoomOutBtn = this._createButton('-', '缩小');
+
+    this._container.appendChild(this._zoomInBtn);
+    this._container.appendChild(this._zoomOutBtn);
+  }
+
+  _createButton(label, title) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.title = title;
+    btn.className = 'cesium-button cesium-toolbar-button xs3d-zoom-button';
+    btn.textContent = label;
+    btn.style.width = '32px';
+    btn.style.height = '32px';
+    btn.style.lineHeight = '1';
+    btn.style.fontSize = '18px';
+    btn.style.fontWeight = 'bold';
+    btn.style.display = 'flex';
+    btn.style.alignItems = 'center';
+    btn.style.justifyContent = 'center';
+    btn.style.cursor = 'pointer';
+    // 在统一工具栏内按 order 排列：指南针 -1，放大 1，缩小 2
+    btn.style.order = label === '+' ? '1' : '2';
+    return btn;
+  }
+
+  _bindEvents() {
+    this._addDomEvent(this._zoomInBtn, 'click', (e) => {
+      e.stopPropagation();
+      this._zoomIn();
+    });
+
+    this._addDomEvent(this._zoomOutBtn, 'click', (e) => {
+      e.stopPropagation();
+      this._zoomOut();
+    });
+  }
+
+  _zoomIn() {
+    this._zoomBy(1);
+  }
+
+  _zoomOut() {
+    this._zoomBy(-1);
+  }
+
+  /**
+   * 按地图层级步进缩放
+   * @param {number} levelDelta 层级变化量，+1 放大一级，-1 缩小一级
+   */
+  _zoomBy(levelDelta) {
+    const camera = this._viewer.camera;
+    const cartographic = camera.positionCartographic;
+    const currentLevel = this._getZoomLevel();
+    const targetLevel = Math.max(0, Math.min(24, currentLevel + levelDelta));
+    const targetHeight = this._getHeightByZoomLevel(targetLevel);
+
+    camera.flyTo({
+      destination: Cesium.Cartesian3.fromRadians(
+        cartographic.longitude,
+        cartographic.latitude,
+        targetHeight
+      ),
+      orientation: {
+        heading: camera.heading,
+        pitch: camera.pitch,
+        roll: camera.roll
+      },
+      duration: this._duration
+    });
+  }
+
+  _getZoomLevel() {
+    const positionCartographic = this._viewer.camera.positionCartographic;
+    const surfaceCartesian = Cesium.Cartesian3.fromRadians(
+      positionCartographic.longitude,
+      positionCartographic.latitude,
+      0
+    );
+    const distance = Cesium.Cartesian3.distance(this._viewer.camera.position, surfaceCartesian);
+    if (!distance || distance <= 0 || !Number.isFinite(distance)) return 0;
+    const equatorCircumference = 6378137 * 2 * Math.PI;
+    return Math.max(0, Math.floor(Math.log2(equatorCircumference / distance)) + 1);
+  }
+
+  _getHeightByZoomLevel(level) {
+    const equatorCircumference = 6378137 * 2 * Math.PI;
+    return equatorCircumference / Math.pow(2, Math.max(0, level - 1));
+  }
+}
+
+/**
+ * 指南针控件
+ * 参考 Mars3D：外环随相机 heading 旋转，拖拽外环可旋转视角，
+ * 拖拽中心球可调整俯仰角，双击复位到正北。
+ */
+class Compass extends BaseControl {
+  /**
+   * @param {object} options
+   * @param {number} [options.size=60] 指南针尺寸（px）
+   * @param {boolean} [options.rotation=true] 是否启用中心拖拽调整俯仰角
+   * @param {number} [options.top=5] 顶部偏移（未挂到工具栏时生效）
+   * @param {number} [options.right=10] 右侧偏移（未挂到工具栏时生效）
+   */
+  constructor(options = {}) {
+    super({
+      type: 'compass',
+      top: 5,
+      right: 5,
+      ...options
+    });
+
+    this._size = options.size ?? 60;
+    this._rotationEnabled = options.rotation !== false;
+
+    // 临时鼠标事件句柄（需要手动清理）
+    this._moveHandle = null;
+    this._upHandle = null;
+  }
+
+  _createContainer() {
+    const div = super._createContainer();
+    div.className += ' xs3d-compass';
+    div.style.width = `${this._size}px`;
+    div.style.height = `${this._size}px`;
+    div.style.borderRadius = '50%';
+    div.style.background = '#3f4854';
+    div.style.boxShadow = '0 1px 4px rgba(0,0,0,0.35)';
+    div.style.cursor = 'pointer';
+    div.style.display = 'flex';
+    div.style.alignItems = 'center';
+    div.style.justifyContent = 'center';
+    div.style.overflow = 'hidden';
+    div.style.userSelect = 'none';
+    return div;
+  }
+
+  _getParentContainer() {
+    if (this._options.container) {
+      return super._getParentContainer();
+    }
+    // 指南针单独定位在地图右上角，不放入工具栏
+    return this._viewer?.container;
+  }
+
+  _mount() {
+    this._clearAbsolutePositionIfInToolbar();
+
+    // 外环：随 heading 旋转
+    this._outerEl = document.createElement('div');
+    this._outerEl.style.position = 'absolute';
+    this._outerEl.style.top = '0';
+    this._outerEl.style.left = '0';
+    this._outerEl.style.width = '100%';
+    this._outerEl.style.height = '100%';
+    this._outerEl.innerHTML = this._getOuterSvg();
+    this._outerEl.style.transition = 'transform 0.1s linear';
+
+    // 内球：固定中心
+    this._innerEl = document.createElement('div');
+    this._innerEl.style.position = 'absolute';
+    this._innerEl.style.top = '50%';
+    this._innerEl.style.left = '50%';
+    this._innerEl.style.width = `${Math.round(this._size * 0.42)}px`;
+    this._innerEl.style.height = `${Math.round(this._size * 0.42)}px`;
+    this._innerEl.style.transform = 'translate(-50%, -50%)';
+    this._innerEl.innerHTML = this._getInnerSvg();
+
+    // 旋转弧：拖拽中心时显示
+    this._arcEl = document.createElement('div');
+    this._arcEl.style.position = 'absolute';
+    this._arcEl.style.top = '0';
+    this._arcEl.style.left = '0';
+    this._arcEl.style.width = '100%';
+    this._arcEl.style.height = '100%';
+    this._arcEl.style.visibility = 'hidden';
+    this._arcEl.innerHTML = this._getArcSvg();
+
+    this._container.appendChild(this._outerEl);
+    this._container.appendChild(this._innerEl);
+    this._container.appendChild(this._arcEl);
+  }
+
+  _getOuterSvg() {
+    return `
+      <svg viewBox="0 0 100 100" width="100%" height="100%">
+        <defs>
+          <linearGradient id="compass-ring" x1="0%" y1="0%" x2="0%" y2="100%">
+            <stop offset="0%" style="stop-color:#4a5563"/>
+            <stop offset="100%" style="stop-color:#2d333b"/>
+          </linearGradient>
+        </defs>
+        <circle cx="50" cy="50" r="48" fill="url(#compass-ring)" stroke="#5a6470" stroke-width="1"/>
+        <g stroke="#ffffff" stroke-width="1" opacity="0.7">
+          <line x1="50" y1="4" x2="50" y2="12"/>
+          <line x1="50" y1="88" x2="50" y2="96"/>
+          <line x1="4" y1="50" x2="12" y2="50"/>
+          <line x1="88" y1="50" x2="96" y2="50"/>
+        </g>
+        <text x="50" y="24" text-anchor="middle" fill="#ff4d4f" font-size="12" font-weight="bold">N</text>
+        <text x="50" y="86" text-anchor="middle" fill="#999" font-size="10">S</text>
+        <text x="86" y="54" text-anchor="middle" fill="#999" font-size="10">E</text>
+        <text x="14" y="54" text-anchor="middle" fill="#999" font-size="10">W</text>
+      </svg>
+    `;
+  }
+
+  _getInnerSvg() {
+    return `
+      <svg viewBox="0 0 100 100" width="100%" height="100%">
+        <circle cx="50" cy="50" r="48" fill="#ffffff"/>
+        <circle cx="50" cy="50" r="38" fill="#68adfe"/>
+        <circle cx="50" cy="50" r="14" fill="#ffffff"/>
+        <path d="M50 30 L56 46 L50 44 L44 46 Z" fill="#3f4854"/>
+        <circle cx="50" cy="50" r="4" fill="#3f4854"/>
+      </svg>
+    `;
+  }
+
+  _getArcSvg() {
+    return `
+      <svg viewBox="0 0 100 100" width="100%" height="100%">
+        <path d="M50 4 A46 46 0 0 1 96 50" fill="none" stroke="#68adfe" stroke-width="4" opacity="0.6"/>
+      </svg>
+    `;
+  }
+
+  _bindEvents() {
+    // 相机方向变化时旋转外环
+    this._addCesiumHandler(this._viewer.camera.changed, this._updateRotation.bind(this));
+
+    // 鼠标交互
+    this._addDomEvent(this._container, 'mousedown', this._onMouseDown.bind(this));
+    this._addDomEvent(this._container, 'dblclick', this._onDoubleClick.bind(this));
+
+    this._updateRotation();
+  }
+
+  _updateRotation() {
+    if (!this._outerEl) return;
+    const heading = Cesium.Math.toDegrees(this._viewer.camera.heading);
+    this._outerEl.style.transform = `rotate(${-heading}deg)`;
+  }
+
+  _onMouseDown(e) {
+    e.preventDefault();
+    e.stopPropagation();
+
+    const rect = this._container.getBoundingClientRect();
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+    const dx = e.clientX - centerX;
+    const dy = e.clientY - centerY;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    const radius = rect.width / 2;
+
+    if (this._rotationEnabled && distance < radius * 0.38) {
+      this._startOrbit(e);
+    } else if (distance < radius) {
+      this._startRotate(e);
+    }
+  }
+
+  _getAngle(e) {
+    const rect = this._container.getBoundingClientRect();
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+    return Math.atan2(e.clientY - centerY, e.clientX - centerX);
+  }
+
+  _startRotate(e) {
+    this._mode = 'rotate';
+    this._lastAngle = this._getAngle(e);
+    this._rotateFrame = this._getRotateFrame();
+
+    this._moveHandle = (ev) => this._onRotateMove(ev);
+    this._upHandle = () => this._stopRotate();
+    document.addEventListener('mousemove', this._moveHandle, false);
+    document.addEventListener('mouseup', this._upHandle, false);
+  }
+
+  _onRotateMove(e) {
+    if (this._mode !== 'rotate') return;
+    const angle = this._getAngle(e);
+    let delta = angle - this._lastAngle;
+    this._lastAngle = angle;
+
+    // 处理角度跳变（-PI 到 PI）
+    if (delta > Math.PI) delta -= Math.PI * 2;
+    if (delta < -Math.PI) delta += Math.PI * 2;
+
+    const camera = this._viewer.camera;
+    if (this._rotateFrame) {
+      const oldTransform = Cesium.Matrix4.clone(camera.transform);
+      camera.lookAtTransform(this._rotateFrame);
+      camera.rotateRight(delta);
+      camera.lookAtTransform(oldTransform);
+    } else {
+      camera.setView({
+        destination: camera.position,
+        orientation: {
+          heading: camera.heading - delta,
+          pitch: camera.pitch,
+          roll: camera.roll
+        }
+      });
+    }
+  }
+
+  _stopRotate() {
+    this._mode = null;
+    this._rotateFrame = null;
+    document.removeEventListener('mousemove', this._moveHandle, false);
+    document.removeEventListener('mouseup', this._upHandle, false);
+    this._moveHandle = null;
+    this._upHandle = null;
+  }
+
+  _startOrbit(e) {
+    this._mode = 'orbit';
+    this._startY = e.clientY;
+    this._startPitch = this._viewer.camera.pitch;
+    this._startHeading = this._viewer.camera.heading;
+    if (this._arcEl) this._arcEl.style.visibility = 'visible';
+
+    this._moveHandle = (ev) => this._onOrbitMove(ev);
+    this._upHandle = () => this._stopOrbit();
+    document.addEventListener('mousemove', this._moveHandle, false);
+    document.addEventListener('mouseup', this._upHandle, false);
+  }
+
+  _onOrbitMove(e) {
+    if (this._mode !== 'orbit') return;
+    const deltaY = this._startY - e.clientY;
+    const sensitivity = 0.004;
+    const newPitch = Cesium.Math.clamp(
+      this._startPitch + deltaY * sensitivity,
+      -Cesium.Math.PI_OVER_TWO + 0.01,
+      Cesium.Math.PI_OVER_TWO - 0.01
+    );
+    this._viewer.camera.setView({
+      destination: this._viewer.camera.position,
+      orientation: {
+        heading: this._startHeading,
+        pitch: newPitch,
+        roll: this._viewer.camera.roll
+      }
+    });
+  }
+
+  _stopOrbit() {
+    this._mode = null;
+    if (this._arcEl) this._arcEl.style.visibility = 'hidden';
+    document.removeEventListener('mousemove', this._moveHandle, false);
+    document.removeEventListener('mouseup', this._upHandle, false);
+    this._moveHandle = null;
+    this._upHandle = null;
+  }
+
+  _getRotateFrame() {
+    const scene = this._viewer.scene;
+    const camera = this._viewer.camera;
+    if (scene.mode === Cesium.SceneMode.MORPHING) return null;
+
+    let center;
+    if (this._viewer.trackedEntity) {
+      center = this._viewer.trackedEntity.position.getValue(this._viewer.clock.currentTime);
+    } else {
+      const ray = new Cesium.Ray(camera.positionWC, camera.directionWC);
+      center = scene.globe.pick(ray, scene);
+    }
+    if (!center) {
+      center = camera.positionWC;
+    }
+    return Cesium.Transforms.eastNorthUpToFixedFrame(center, scene.globe.ellipsoid);
+  }
+
+  _onDoubleClick() {
+    const camera = this._viewer.camera;
+    const cartographic = camera.positionCartographic;
+    camera.flyTo({
+      destination: Cesium.Cartesian3.fromRadians(
+        cartographic.longitude,
+        cartographic.latitude,
+        cartographic.height
+      ),
+      orientation: {
+        heading: 0,
+        pitch: camera.pitch,
+        roll: camera.roll
+      },
+      duration: 0.5
+    });
+  }
+
+  remove(destroy = true) {
+    this._stopRotate();
+    this._stopOrbit();
+    return super.remove(destroy);
+  }
+}
+
+/**
+ * 比例尺控件
+ * 参考 Mars3D 实现：在屏幕底部取水平相邻两像素点，计算其地表测地距离，
+ * 从而得到“1 像素对应多少米”，再动态选择合适刻度显示。
+ */
+class DistanceLegend extends BaseControl {
+  /**
+   * @param {object} options
+   * @param {number} [options.bottom=20] 底部偏移
+   * @param {number} [options.left=20] 左侧偏移
+   * @param {number} [options.maxWidth=100] 比例尺最大宽度（px）
+   */
+  constructor(options = {}) {
+    super({
+      type: 'distanceLegend',
+      bottom: 20,
+      left: 20,
+      ...options
+    });
+
+    this._maxWidth = options.maxWidth ?? 100;
+
+    // 刻度基数 1,2,3,5 及其 10^n 倍
+    const base = [1, 2, 3, 5];
+    this._distances = [];
+    for (let i = 0; i < 7; i++) {
+      const factor = Math.pow(10, i);
+      base.forEach(b => this._distances.push(b * factor));
+    }
+
+    this._geodesic = new Cesium.EllipsoidGeodesic();
+    this._lastUpdate = 0;
+  }
+
+  _createContainer() {
+    const div = super._createContainer();
+    div.className += ' xs3d-distance-legend';
+    div.style.display = 'flex';
+    div.style.flexDirection = 'column';
+    div.style.alignItems = 'center';
+    div.style.color = '#fff';
+    div.style.fontSize = '11px';
+    div.style.fontFamily = 'Microsoft YaHei, sans-serif';
+    div.style.textShadow = '0 1px 2px rgba(0,0,0,0.5)';
+    div.style.userSelect = 'none';
+    div.style.pointerEvents = 'none';
+    div.style.visibility = 'hidden';
+    return div;
+  }
+
+  _mount() {
+    this._label = document.createElement('div');
+    this._label.style.marginBottom = '2px';
+
+    this._line = document.createElement('div');
+    this._line.style.height = '6px';
+    this._line.style.borderLeft = '2px solid #fff';
+    this._line.style.borderRight = '2px solid #fff';
+    this._line.style.borderBottom = '2px solid #fff';
+    this._line.style.boxSizing = 'border-box';
+
+    this._container.appendChild(this._label);
+    this._container.appendChild(this._line);
+  }
+
+  _bindEvents() {
+    this._addCesiumHandler(this._viewer.scene.postRender, this._update.bind(this));
+  }
+
+  _update(scene, time) {
+    if (!this._viewer) return;
+
+    // 每 250ms 更新一次，避免频繁重绘
+    const now = performance.now();
+    if (now < this._lastUpdate + 250) return;
+    this._lastUpdate = now;
+
+    const camera = this._viewer.camera;
+    const canvas = scene.canvas;
+    const width = canvas.width;
+    const height = canvas.height;
+
+    if (!width || !height) return;
+
+    // 屏幕底部中心相邻两像素
+    const x = Math.floor(width / 2);
+    const y = Math.max(0, height - 1);
+
+    const leftRay = camera.getPickRay(new Cesium.Cartesian2(x, y));
+    const rightRay = camera.getPickRay(new Cesium.Cartesian2(x + 1, y));
+    if (!leftRay || !rightRay) return;
+
+    const leftPosition = scene.globe.pick(leftRay, scene);
+    const rightPosition = scene.globe.pick(rightRay, scene);
+    if (!leftPosition || !rightPosition) {
+      this._container.style.visibility = 'hidden';
+      return;
+    }
+
+    this._geodesic.setEndPoints(
+      scene.globe.ellipsoid.cartesianToCartographic(leftPosition),
+      scene.globe.ellipsoid.cartesianToCartographic(rightPosition)
+    );
+
+    const pixelDistance = this._geodesic.surfaceDistance;
+    if (!pixelDistance || pixelDistance <= 0 || !Number.isFinite(pixelDistance)) {
+      this._container.style.visibility = 'hidden';
+      return;
+    }
+
+    let distance = 0;
+    for (let i = this._distances.length - 1; i >= 0; i--) {
+      if (this._distances[i] / pixelDistance < this._maxWidth) {
+        distance = this._distances[i];
+        break;
+      }
+    }
+
+    if (distance) {
+      const barWidth = Math.floor(distance / pixelDistance);
+      this._label.textContent = distance >= 1000 ? `${distance / 1000} km` : `${distance} m`;
+      this._line.style.width = `${barWidth}px`;
+      this._container.style.visibility = 'visible';
+    } else {
+      this._container.style.visibility = 'hidden';
+    }
+  }
+}
+
+/**
+ * 控件管理模块
+ * 统一管理地图控件的添加、移除和访问。
+ */
+class ControlModule {
+  constructor(viewer) {
+    this._viewer = viewer;
+    this._controls = new Map();
+    this._toolbar = null;
+  }
+
+  /**
+   * 添加控件
+   * @param {string|BaseControl} type 控件类型或控件实例
+   * @param {object} [options] 控件配置（当 type 为字符串时）
+   * @returns {BaseControl} 控件实例
+   */
+  addControl(type, options = {}) {
+    // 内置工具栏控件（zoom）共享统一容器，compass 单独定位在工具栏上方
+    if (typeof type === 'string' && !options.container && type === 'zoom') {
+      options = { ...options, container: this._getOrCreateToolbar() };
+    }
+
+    let control;
+
+    if (typeof type === 'string') {
+      control = this._createControl(type, options);
+    } else if (type && typeof type.addTo === 'function') {
+      control = type;
+    } else {
+      console.warn(`ControlModule: 未知控件类型 ${type}`);
+      return null;
+    }
+
+    if (!control) return null;
+
+    // 同类型控件先移除
+    if (this._controls.has(control.type)) {
+      this.removeControl(control.type);
+    }
+
+    control.addTo(this._viewer);
+    this._controls.set(control.type, control);
+
+    return control;
+  }
+
+  /**
+   * 移除控件
+   * @param {string} type 控件类型
+   * @param {boolean} [destroy=true] 是否销毁
+   * @returns {boolean} 是否移除成功
+   */
+  removeControl(type, destroy = true) {
+    const control = this._controls.get(type);
+    if (!control) return false;
+
+    control.remove(destroy);
+    this._controls.delete(type);
+    return true;
+  }
+
+  /**
+   * 获取控件
+   * @param {string} type 控件类型
+   * @returns {BaseControl|undefined}
+   */
+  getControl(type) {
+    return this._controls.get(type);
+  }
+
+  /**
+   * 获取所有已添加的控件
+   * @returns {BaseControl[]}
+   */
+  getAllControls() {
+    return Array.from(this._controls.values());
+  }
+
+  /**
+   * 显示控件
+   * @param {string} type
+   */
+  showControl(type) {
+    const control = this._controls.get(type);
+    if (control) control.show();
+    return this;
+  }
+
+  /**
+   * 隐藏控件
+   * @param {string} type
+   */
+  hideControl(type) {
+    const control = this._controls.get(type);
+    if (control) control.hide();
+    return this;
+  }
+
+  /**
+   * 批量添加控件
+   * @param {object} controlsConfig { locationBar: true, zoom: { ... }, ... }
+   */
+  addControls(controlsConfig = {}) {
+    const keys = Object.keys(controlsConfig);
+    // 让 compass 先于 zoom 添加，确保指南针在工具栏顶部
+    keys.sort((a, b) => {
+      if (a === 'compass') return -1;
+      if (b === 'compass') return 1;
+      return 0;
+    });
+
+    keys.forEach(type => {
+      const config = controlsConfig[type];
+      if (config === true) {
+        this.addControl(type);
+      } else if (config && typeof config === 'object') {
+        this.addControl(type, config);
+      }
+    });
+    return this;
+  }
+
+  /**
+   * 移除所有控件
+   * @param {boolean} [destroy=true]
+   */
+  removeAllControls(destroy = true) {
+    this._controls.forEach((control, type) => {
+      control.remove(destroy);
+    });
+    this._controls.clear();
+    return this;
+  }
+
+  /**
+   * 销毁模块
+   */
+  destroy() {
+    this.removeAllControls(true);
+    if (this._toolbar && this._toolbar.parentNode) {
+      this._toolbar.parentNode.removeChild(this._toolbar);
+    }
+    this._toolbar = null;
+    this._viewer = null;
+  }
+
+  /**
+   * 获取或创建统一工具栏
+   */
+  _getOrCreateToolbar() {
+    if (this._toolbar) return this._toolbar;
+
+    const viewerContainer = this._viewer?.container;
+    if (!viewerContainer) return null;
+
+    this._toolbar = document.createElement('div');
+    this._toolbar.className = 'xs3d-viewer-toolbar';
+    this._toolbar.style.position = 'absolute';
+    this._toolbar.style.top = '70px';
+    this._toolbar.style.right = '10px';
+    this._toolbar.style.display = 'flex';
+    this._toolbar.style.flexDirection = 'column';
+    this._toolbar.style.alignItems = 'center';
+    this._toolbar.style.gap = '4px';
+    this._toolbar.style.padding = '4px';
+    // this._toolbar.style.background = 'rgba(63, 72, 84, 0.95)';
+    this._toolbar.style.borderRadius = '4px';
+    this._toolbar.style.boxShadow = '0 1px 4px rgba(0,0,0,0.35)';
+    this._toolbar.style.zIndex = '1001';
+    viewerContainer.appendChild(this._toolbar);
+    return this._toolbar;
+  }
+
+  /**
+   * 根据类型创建内置控件
+   */
+  _createControl(type, options) {
+    switch (type) {
+      case 'locationBar':
+        return new LocationBar(options);
+      case 'zoom':
+        return new Zoom(options);
+      case 'compass':
+        return new Compass(options);
+      case 'distanceLegend':
+        return new DistanceLegend(options);
+      default:
+        console.warn(`ControlModule: 未注册的内置控件类型 "${type}"`);
+        return null;
+    }
+  }
+}
+
 /**
  * 模块管理器（对应平台 GetModule 逻辑）
  * 统一管理场景、图元、事件模块的实例
@@ -7070,6 +8291,16 @@ class ModuleManager {
         }).init();
         this.registerModule('EditorModule', editorModule);
 
+        // 初始化控件模块
+        const controlModule = new ControlModule(this.cesiumViewer);
+        this.registerModule('ControlModule', controlModule);
+
+        // 如果配置中声明了 controls，自动挂载
+        const controlsConfig = Config.getInstance().getConfig().controls;
+        if (controlsConfig) {
+            controlModule.addControls(controlsConfig);
+        }
+
         return this.cesiumViewer;
     }
 
@@ -7125,6 +8356,14 @@ class ModuleManager {
         return this.getModule('EditorModule');
     }
 
+    /**
+     * 控件模块快捷访问
+     * @returns {ControlModule}
+     */
+    get controlModule() {
+        return this.getModule('ControlModule');
+    }
+
     /**
      * 注册模块（内部使用）
      * @param {string} moduleName 模块名称
@@ -7158,6 +8397,15 @@ class ModuleManager {
                 console.warn('EditorModule 销毁失败:', e);
             }
 
+            try {
+                const controlModule = this.modules.get('ControlModule');
+                if (controlModule && typeof controlModule.destroy === 'function') {
+                    controlModule.destroy();
+                }
+            } catch (e) {
+                console.warn('ControlModule 销毁失败:', e);
+            }
+
             this.cesiumViewer.destroy();
             this.cesiumViewer = null;
             this.modules.clear();
@@ -7371,8 +8619,15 @@ const xs3d = {
     GraphicModule,
     EventModule,
     EditorModule,
+    ControlModule,
     CoordinateUtil,
     GeoCalcUtil,
+    // 导出控件类
+    BaseControl,
+    LocationBar,
+    Zoom,
+    Compass,
+    DistanceLegend,
     // 导出工具枚举
     DrawType,
     EditMode,