Star Burst【译】

原文链接及内容

原文链接：https://sandcastle.cesium.com/?src=Star%20Burst.html&label=All

效果如下图所示：

示例代码如下：

const viewer = new Cesium.Viewer("cesiumContainer", {
  geocoder: false,
  homeButton: false,
  navigationHelpButton: false,
  navigationInstructionsInitiallyVisible: false,
  animation: false,
  timeline: false,
  fullscreenButton: false,
  skyBox: false,
  sceneModePicker: false,
  baseLayerPicker: false,
  selectionIndicator: false,//禁用选中实体时的绿色指示器
});
viewer.cesiumWidget.creditContainer.style.display = "none";

// 在同一位置添加聚类标签
const numBillboards = 30;
for (let i = 0; i < numBillboards; ++i) {
  //这30个实体的文字默认隐藏
  const position = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
  viewer.entities.add({
    position: position,
    billboard: {
      image: "../images/facility.gif",
      scale: 2.5,
    },
    label: {
      text: `Label${i}`,
      show: false,
      font: "24px 'Maple Mono Normal NF CN'",//这里的字体用的我电脑上自己安装的字体
      fillColor: Cesium.Color.RED,
      outlineColor: Cesium.Color.WHITE,
      outlineWidth: 2,
      style: Cesium.LabelStyle.FILL_AND_OUTLINE,
    },
  });
}

const scene = viewer.scene;
const camera = scene.camera;
const handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);

handler.setInputAction(function (movement) {
  // 调用 starBurst 函数，触发广告牌分散。
  starBurst(movement.position);
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

handler.setInputAction(function (movement) {
  // 鼠标移动（MOUSE_MOVE）：调用 updateStarBurst 函数，更新标签显示或撤销星爆。
  updateStarBurst(movement.endPosition);
}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);

camera.moveStart.addEventListener(function () {
  // 相机移动（moveStart）：调用 undoStarBurst 函数，重置星爆状态。
  undoStarBurst();
});

// 保存星爆效果的状态，用于跟踪交互过程中的数据。
const starBurstState = {
  enabled: false, //星爆是否激活
  pickedEntities: undefined,//点击时拾取的广告牌实体列表
  billboardEyeOffsets: undefined,//保存广告牌的原始偏移量，用于恢复
  labelEyeOffsets: undefined,//保存标签的原始偏移量，用于恢复
  linePrimitive: undefined,//连接线的图元对象
  radius: undefined,//星爆圆形的最大半径
  center: undefined,//星爆中心位置
  pixelPadding: 10.0,//广告牌之间的像素间距（10 像素）
  // 星爆的角度范围（0 到 π，半圆）
  angleStart: 0.0,
  angleEnd: Cesium.Math.PI,
  maxDimension: undefined,//广告牌的最大尺寸（宽度或高度）
};

/**
 * 将广告牌和标签偏移到指定角度（angle）和距离（magnitude）的位置，生成连接线端点。
 */
function offsetBillboard(
  entity,
  entityPosition,
  angle,
  magnitude,
  lines,
  billboardEyeOffsets,
  labelEyeOffsets,
) {
  /**
   * 1. 偏移计算：根据角度和距离计算屏幕空间偏移
   * x = magnitude * cos(angle)，y = magnitude * sin(angle)
   */
  const x = magnitude * Math.cos(angle);
  const y = magnitude * Math.sin(angle);

  const offset = new Cesium.Cartesian2(x, y);

  const drawingBufferWidth = scene.drawingBufferWidth;
  const drawingBufferHeight = scene.drawingBufferHeight;
  const pixelRatio = scene.pixelRatio;

  const diff = Cesium.Cartesian3.subtract(
    entityPosition,
    camera.positionWC,
    new Cesium.Cartesian3(),
  );
  const distance = Cesium.Cartesian3.dot(camera.directionWC, diff);

  /**
   * 2. 像素调整：使用相机的像素尺寸（frustum.getPixelDimensions）
   *  将偏移量转换为屏幕像素，确保视觉一致性
   */
  const dimensions = camera.frustum.getPixelDimensions(
    drawingBufferWidth,
    drawingBufferHeight,
    distance,
    pixelRatio,
    new Cesium.Cartesian2(),
  );
  Cesium.Cartesian2.multiplyByScalar(
    offset,
    Cesium.Cartesian2.maximumComponent(dimensions),
    offset,
  );

  let labelOffset;
  const billboardOffset = entity.billboard.eyeOffset;

  // 3. 设置广告牌偏移和标签偏移
  const eyeOffset = new Cesium.Cartesian3(offset.x, offset.y, 0.0);
  entity.billboard.eyeOffset = eyeOffset;
  if (Cesium.defined(entity.label)) {
    labelOffset = entity.label.eyeOffset;
    entity.label.eyeOffset = new Cesium.Cartesian3(offset.x, offset.y, -10.0);
  }

  // 4. 计算连接线的端点（从中心到偏移后的广告牌位置），存储在 lines 数组。
  const endPoint = Cesium.Matrix4.multiplyByPoint(
    camera.viewMatrix,
    entityPosition,
    new Cesium.Cartesian3(),
  );
  Cesium.Cartesian3.add(eyeOffset, endPoint, endPoint);
  Cesium.Matrix4.multiplyByPoint(camera.inverseViewMatrix, endPoint, endPoint);
  lines.push(endPoint);

  // 5. 记录原始偏移量（billboardEyeOffsets 和 labelEyeOffsets），用于恢复。
  billboardEyeOffsets.push(billboardOffset);
  labelEyeOffsets.push(labelOffset);
}

/**
 * 在鼠标点击位置触发星爆效果，将重叠的广告牌分散排列，绘制白色连接线。 
 */
function starBurst(mousePosition) {
  if (Cesium.defined(starBurstState.pickedEntities)) {
    return;
  }

  // 使用 scene.drillPick 获取鼠标位置下的所有对象，仅处理至少 2 个广告牌的情况
  const pickedObjects = scene.drillPick(mousePosition);
  if (!Cesium.defined(pickedObjects) || pickedObjects.length < 2) {
    return;
  }

  // 从拾取对象中提取广告牌实体，存储在 pickedEntities
  const billboardEntities = [];
  let length = pickedObjects.length;
  let i;

  for (i = 0; i < length; ++i) {
    const pickedObject = pickedObjects[i];
    if (pickedObject.primitive instanceof Cesium.Billboard) {
      billboardEntities.push(pickedObject);
    }
  }

  if (billboardEntities.length === 0) {
    return;
  }

  const pickedEntities = (starBurstState.pickedEntities = []);
  const billboardEyeOffsets = (starBurstState.billboardEyeOffsets = []);
  const labelEyeOffsets = (starBurstState.labelEyeOffsets = []);
  const lines = [];
  starBurstState.maxDimension = Number.NEGATIVE_INFINITY;

  const angleStart = starBurstState.angleStart;
  const angleEnd = starBurstState.angleEnd;

  let angle = angleStart;
  let angleIncrease;
  let magnitude;
  let magIncrease;
  let maxDimension;

  // 使用Drill pick获取鼠标指针下的所有实体。找到广告牌并以圆形模式设置它们的像素偏移量。
  length = billboardEntities.length;
  i = 0;
  while (i < length) {
    let object = billboardEntities[i];
    if (pickedEntities.length === 0) {
      starBurstState.center = Cesium.Cartesian3.clone(object.primitive.position);
    }

    if (!Cesium.defined(angleIncrease)) {
      const width = object.primitive.width;
      const height = object.primitive.height;
      maxDimension =
        Math.max(width, height) * object.primitive.scale +
        starBurstState.pixelPadding;
      magnitude = maxDimension + maxDimension * 0.5;
      magIncrease = magnitude;
      angleIncrease = maxDimension / magnitude;
    }

    offsetBillboard(
      object.id,
      object.primitive.position,
      angle,
      magnitude,
      lines,
      billboardEyeOffsets,
      labelEyeOffsets,
    );
    pickedEntities.push(object);

    const reflectedAngle = angleEnd - angle;
    if (
      i + 1 < length &&
      reflectedAngle - angleIncrease * 0.5 > angle + angleIncrease * 0.5
    ) {
      object = billboardEntities[++i];
      offsetBillboard(
        object.id,
        object.primitive.position,
        reflectedAngle,
        magnitude,
        lines,
        billboardEyeOffsets,
        labelEyeOffsets,
      );
      pickedEntities.push(object);
    }

    angle += angleIncrease;
    if (reflectedAngle - angleIncrease * 0.5 < angle + angleIncrease * 0.5) {
      magnitude += magIncrease;
      angle = angleStart;
      angleIncrease = maxDimension / magnitude;
    }

    ++i;
  }

  // 从拾取中心向外添加线条至平移后的广告牌。
  const instances = [];
  length = lines.length;
  for (i = 0; i < length; ++i) {
    const pickedEntity = pickedEntities[i];
    starBurstState.maxDimension = Math.max(
      pickedEntity.primitive.width,
      pickedEntity.primitive.height,
      starBurstState.maxDimension,
    );

    instances.push(
      new Cesium.GeometryInstance({
        geometry: new Cesium.SimplePolylineGeometry({
          positions: [starBurstState.center, lines[i]],
          arcType: Cesium.ArcType.NONE,
          granularity: Cesium.Math.PI_OVER_FOUR,
        }),
        attributes: {
          color: Cesium.ColorGeometryInstanceAttribute.fromColor(
            Cesium.Color.WHITE,
          ),
        },
      }),
    );
  }

  starBurstState.linePrimitive = scene.primitives.add(
    new Cesium.Primitive({
      geometryInstances: instances,
      appearance: new Cesium.PerInstanceColorAppearance({
        flat: true,
        translucent: false,
      }),
      asynchronous: false,
    }),
  );

  viewer.selectedEntity = undefined;
  starBurstState.radius = magnitude + magIncrease;
}

/**
 * 
 * 根据鼠标位置更新星爆状态：
 *  - 如果鼠标移出星爆圆形范围或过高，撤销星爆（undoStarBurst）。
 *  - 如果鼠标在范围内，显示悬停广告牌的标签（showLabels）。
 */
function updateStarBurst(mousePosition) {
  if (!Cesium.defined(starBurstState.pickedEntities)) {
    return;
  }

  if (!starBurstState.enabled) {
    // 由于某些原因，点击时会触发鼠标移动事件，因此不要在首次事件时显示标签。
    starBurstState.enabled = true;
    return;
  }

  // 如果鼠标离开屏幕空间圆，则移除星爆效果。如果鼠标在圆内，则显示鼠标悬停的招牌的标签。
  const screenPosition = Cesium.SceneTransforms.worldToWindowCoordinates(
    scene,
    starBurstState.center,
  );
  const fromCenter = Cesium.Cartesian2.subtract(
    mousePosition,
    screenPosition,
    new Cesium.Cartesian2(),
  );
  const radius = starBurstState.radius;

  if (
    Cesium.Cartesian2.magnitudeSquared(fromCenter) > radius * radius ||
    fromCenter.y >
      3.0 * (starBurstState.maxDimension + starBurstState.pixelPadding)
  ) {
    undoStarBurst();
  } else {
    showLabels(mousePosition);
  }
}

function undoStarBurst() {
  const pickedEntities = starBurstState.pickedEntities;
  if (!Cesium.defined(pickedEntities)) {
    return;
  }

  const billboardEyeOffsets = starBurstState.billboardEyeOffsets;
  const labelEyeOffsets = starBurstState.labelEyeOffsets;

  // 重置广告牌和标签的像素偏移。隐藏重叠的标签。
  for (let i = 0; i < pickedEntities.length; ++i) {
    const entity = pickedEntities[i].id;
    entity.billboard.eyeOffset = billboardEyeOffsets[i];
    if (Cesium.defined(entity.label)) {
      entity.label.eyeOffset = labelEyeOffsets[i];
      entity.label.show = false;
    }
  }

  // 移除场景中的线条。释放资源并重置状态。
  scene.primitives.remove(starBurstState.linePrimitive);
  starBurstState.linePrimitive = undefined;
  starBurstState.pickedEntities = undefined;
  starBurstState.billboardEyeOffsets = undefined;
  starBurstState.labelEyeOffsets = undefined;
  starBurstState.radius = undefined;
  starBurstState.enabled = false;
}

let currentObject;

function showLabels(mousePosition) {
  const pickedObjects = scene.drillPick(mousePosition);
  let pickedObject;

  if (Cesium.defined(pickedObjects)) {
    const length = pickedObjects.length;
    for (let i = 0; i < length; ++i) {
      if (pickedObjects[i].primitive instanceof Cesium.Billboard) {
        pickedObject = pickedObjects[i];
        break;
      }
    }
  }

  if (pickedObject !== currentObject) {
    if (Cesium.defined(pickedObject) && Cesium.defined(pickedObject.id.label)) {
      if (Cesium.defined(currentObject)) {
        currentObject.id.label.show = false;
      }

      currentObject = pickedObject;
      pickedObject.id.label.show = true;
    } else if (Cesium.defined(currentObject)) {
      currentObject.id.label.show = false;
      currentObject = undefined;
    }
  }
}