release: bump version to 0.40.0

frontend/public/earth/index.html

@@ -687,6 +687,19 @@
                   </div>
                 </div>
               </div>
+              <div class="earth-mobile-settings-group">
+                <div class="earth-mobile-settings-title">卫星</div>
+                <div class="earth-mobile-settings-card earth-mobile-settings-card--stacked">
+                  <div class="earth-mobile-settings-copy">
+                    <span class="earth-mobile-settings-label">卫星显示风格</span>
+                    <span class="earth-mobile-settings-subtitle">可选自身发光或真实地表覆盖两种选中表现</span>
+                  </div>
+                  <div class="earth-mobile-settings-segmented" role="group" aria-label="移动端选择卫星显示风格">
+                    <button type="button" class="earth-mobile-settings-pill is-active" data-satellite-display-style="self_glow" aria-pressed="true">自身发光</button>
+                    <button type="button" class="earth-mobile-settings-pill" data-satellite-display-style="ground_footprint" aria-pressed="false">真实地表覆盖</button>
+                  </div>
+                </div>
+              </div>
               <div class="earth-mobile-settings-group">
                 <div class="earth-mobile-settings-title">视图</div>
                 <label class="earth-mobile-settings-card">
@@ -875,6 +888,30 @@
                   </button>
                 </div>
               </div>
+              <div class="earth-settings-item earth-settings-item--stacked">
+                <div class="earth-settings-copy">
+                  <span class="earth-settings-item-title">卫星显示风格</span>
+                  <span class="earth-settings-item-subtitle">选择卫星锁定态使用自身发光，还是强调真实地表覆盖范围。</span>
+                </div>
+                <div class="earth-settings-segmented" role="group" aria-label="选择卫星显示风格">
+                  <button
+                    type="button"
+                    class="earth-settings-segmented-btn is-active"
+                    data-satellite-display-style="self_glow"
+                    aria-pressed="true"
+                  >
+                    自身发光
+                  </button>
+                  <button
+                    type="button"
+                    class="earth-settings-segmented-btn"
+                    data-satellite-display-style="ground_footprint"
+                    aria-pressed="false"
+                  >
+                    真实地表覆盖
+                  </button>
+                </div>
+              </div>
             </div>
           </section>
           <section class="earth-settings-section">

frontend/public/earth/js/constants.js

@@ -25,6 +25,14 @@ export const CRUISE_MODULES = {
 
 export const DEFAULT_CRUISE_MODULES = [CRUISE_MODULES.BGP];
 
+export const SATELLITE_DISPLAY_STYLES = {
+  SELF_GLOW: "self_glow",
+  GROUND_FOOTPRINT: "ground_footprint",
+};
+
+export const DEFAULT_SATELLITE_DISPLAY_STYLE =
+  SATELLITE_DISPLAY_STYLES.SELF_GLOW;
+
 export const CRUISE_CONFIG = {
   dwellMs: 7_000,
   focusDurationMs: 1_400,

frontend/public/earth/js/controls.js

@@ -4,9 +4,11 @@ import * as THREE from "three";
 import {
   CONFIG,
   CRUISE_MODULES,
+  DEFAULT_SATELLITE_DISPLAY_STYLE,
   DEFAULT_CRUISE_MODULES,
   EARTH_CONFIG,
   ROTATION_MODE,
+  SATELLITE_DISPLAY_STYLES,
 } from "./constants.js";
 import { setEarthStatValue, updateZoomDisplay, showStatusMessage } from "./ui.js";
 import {
@@ -34,6 +36,8 @@ import {
   toggleTrails,
   getShowTrails,
   getSatelliteCount,
+  getSatelliteDisplayStyle,
+  setSatelliteDisplayStyle as applySatelliteDisplayStyle,
 } from "./satellites.js";
 import { getShowCables } from "./cables.js";
 import { toggleBGP, getShowBGP, getBGPCount } from "./bgp.js";
@@ -116,6 +120,9 @@ let mobileDrawerOpen = false;
 let mobileDrawerCard = "layers";
 let mobileDrawerHintTimer = null;
 const ALLOWED_CRUISE_MODULES = new Set(Object.values(CRUISE_MODULES));
+const ALLOWED_SATELLITE_DISPLAY_STYLES = new Set(
+  Object.values(SATELLITE_DISPLAY_STYLES),
+);
 
 function detectLayoutMode() {
   const width = window.innerWidth;
@@ -641,6 +648,7 @@ function getCurrentSharedSettingsSnapshot() {
   return {
     rotationMode,
     cruiseModules: getCruiseModules(),
+    satelliteDisplayStyle: getSatelliteDisplayStyle(),
     layerVisibility: Object.fromEntries(
       getPersistedLayers().map((layer) => [layer.id, Boolean(layer.getVisible?.())]),
     ),
@@ -676,6 +684,8 @@ function cloneEarthSettings(settings) {
     shared: {
       rotationMode: settings.shared.rotationMode,
       cruiseModules: [...(settings.shared.cruiseModules || DEFAULT_CRUISE_MODULES)],
+      satelliteDisplayStyle:
+        settings.shared.satelliteDisplayStyle || DEFAULT_SATELLITE_DISPLAY_STYLE,
       terrainOpacity: settings.shared.terrainOpacity,
       dayNightEnabled: settings.shared.dayNightEnabled,
       defaultEarthZoom: settings.shared.defaultEarthZoom,
@@ -755,6 +765,11 @@ function normalizeEarthSettings(rawSettings, defaults) {
       requestedCruiseModules.filter((moduleId) => ALLOWED_CRUISE_MODULES.has(moduleId)),
     ),
   );
+  const nextSatelliteDisplayStyle = ALLOWED_SATELLITE_DISPLAY_STYLES.has(
+    sharedSettings?.satelliteDisplayStyle,
+  )
+    ? sharedSettings.satelliteDisplayStyle
+    : defaults.shared.satelliteDisplayStyle;
   const nextTerrainOpacity = Number.parseFloat(sharedSettings?.terrainOpacity);
   const nextDayNightEnabled = typeof sharedSettings?.dayNightEnabled === "boolean"
     ? sharedSettings.dayNightEnabled
@@ -770,6 +785,7 @@ function normalizeEarthSettings(rawSettings, defaults) {
       cruiseModules: nextCruiseModules.length > 0
         ? nextCruiseModules
         : [...DEFAULT_CRUISE_MODULES],
+      satelliteDisplayStyle: nextSatelliteDisplayStyle,
       layerVisibility: normalizedLayerVisibility,
       terrainOpacity: Number.isFinite(nextTerrainOpacity)
         ? nextTerrainOpacity
@@ -883,6 +899,17 @@ function syncCruiseModuleControls() {
   });
 }
 
+function syncSatelliteDisplayStyleControls() {
+  const activeStyle = getSatelliteDisplayStyle();
+  document.querySelectorAll("[data-satellite-display-style]").forEach((button) => {
+    if (!(button instanceof HTMLButtonElement)) return;
+    const styleId = button.dataset.satelliteDisplayStyle || "";
+    const active = styleId === activeStyle;
+    button.classList.toggle("is-active", active);
+    button.setAttribute("aria-pressed", active ? "true" : "false");
+  });
+}
+
 export function getCruiseModules() {
   const configuredModules = earthSettingsState?.shared?.cruiseModules;
   return normalizeCruiseModules(configuredModules);
@@ -925,6 +952,42 @@ export function setCruiseModules(nextModules, { persist = true, suppressStatus =
   return normalizedModules;
 }
 
+export function setSatelliteDisplayStyle(
+  nextStyle,
+  { persist = true, suppressStatus = false } = {},
+) {
+  const normalizedStyle = ALLOWED_SATELLITE_DISPLAY_STYLES.has(nextStyle)
+    ? nextStyle
+    : DEFAULT_SATELLITE_DISPLAY_STYLE;
+  const previousStyle = getSatelliteDisplayStyle();
+
+  if (normalizedStyle === previousStyle) {
+    syncSatelliteDisplayStyleControls();
+    return normalizedStyle;
+  }
+
+  earthSettingsState = cloneEarthSettings(
+    earthSettingsState || cloneEarthSettings(captureEarthSettingsDefaults()),
+  );
+  earthSettingsState.shared.satelliteDisplayStyle = normalizedStyle;
+  applySatelliteDisplayStyle(normalizedStyle);
+  syncSatelliteDisplayStyleControls();
+
+  if (persist) {
+    persistEarthSettings();
+  }
+
+  if (!suppressStatus) {
+    const nextLabel =
+      normalizedStyle === SATELLITE_DISPLAY_STYLES.GROUND_FOOTPRINT
+        ? "真实地表覆盖"
+        : "自身发光";
+    showStatusMessage(`卫星显示风格已切换为：${nextLabel}`, "info");
+  }
+
+  return normalizedStyle;
+}
+
 function syncDefaultEarthZoomUi(nextZoom) {
   const sliders = document.querySelectorAll("#default-earth-size-slider, [data-default-earth-size-slider]");
   const values = document.querySelectorAll("#default-earth-size-value, [data-default-earth-size-value]");
@@ -988,6 +1051,10 @@ async function applyEarthSettings(settings) {
 
   setRotationMode(settings.shared.rotationMode, { persist: false, suppressStatus: true });
   setCruiseModules(settings.shared.cruiseModules, { persist: false, suppressStatus: true });
+  setSatelliteDisplayStyle(settings.shared.satelliteDisplayStyle, {
+    persist: false,
+    suppressStatus: true,
+  });
 
   if (typeof settings.shared.dayNightEnabled === "boolean") {
     applyDayNightEnabled(settings.shared.dayNightEnabled, { persist: false });
@@ -1797,6 +1864,7 @@ function setupSettingsControls() {
   const defaultEarthSizeSliders = document.querySelectorAll("#default-earth-size-slider, [data-default-earth-size-slider]");
   const rotationModeButtons = document.querySelectorAll("[data-rotation-mode]");
   const cruiseModuleButtons = document.querySelectorAll("[data-cruise-module-toggle]");
+  const satelliteDisplayStyleButtons = document.querySelectorAll("[data-satellite-display-style]");
   const syncTerrainOpacityUi = (nextOpacity) => {
     const safeOpacity = Math.round(nextOpacity * 100);
     terrainOpacitySliders.forEach((slider) => {
@@ -1869,6 +1937,16 @@ function setupSettingsControls() {
     });
   });
 
+  satelliteDisplayStyleButtons.forEach((button) => {
+    bindListener(button, "click", (event) => {
+      const target = event.currentTarget;
+      if (!(target instanceof HTMLButtonElement)) return;
+      const nextStyle = target.dataset.satelliteDisplayStyle;
+      if (!nextStyle) return;
+      setSatelliteDisplayStyle(nextStyle);
+    });
+  });
+
   document.querySelectorAll("#toggle-daynight, [data-daynight-toggle]").forEach((dayNightToggle) => {
     if (!(dayNightToggle instanceof HTMLInputElement)) return;
     bindListener(dayNightToggle, "change", () => {
@@ -1886,6 +1964,7 @@ function setupSettingsControls() {
   syncAllHudPanelToggles();
   syncRotationModeButtons();
   syncCruiseModuleControls();
+  syncSatelliteDisplayStyleControls();
   syncDayNightToggle(dayNightEnabled);
 }
 

frontend/public/earth/js/info-card.js

@@ -437,6 +437,10 @@ const CARD_CONFIG = {
     fields: [
       { key: 'name', label: '名称' },
       { key: 'norad_id', label: 'NORAD ID' },
+      { key: 'constellation', label: '星座/分组' },
+      { key: 'footprint_capability', label: '覆盖能力' },
+      { key: 'current_display', label: '当前显示' },
+      { key: 'footprint_model', label: '覆盖模型' },
       { key: 'inclination', label: '倾角', unit: '°' },
       { key: 'period', label: '周期', unit: '分钟' },
       { key: 'perigee', label: '近地点', unit: 'km' },

frontend/public/earth/js/iridium-footprint-adapter.js

@@ -0,0 +1,167 @@
+import * as THREE from "three";
+
+const EARTH_RADIUS_KM = 6378.137;
+const SURFACE_SCALE = 1.003;
+const SURFACE_OFFSET = 0.72;
+const CLUSTER_DIAMETER_KM_APPROX = 4500;
+const CLUSTER_RADIUS_KM_BASE = CLUSTER_DIAMETER_KM_APPROX / 2;
+const SURFACE_AXIS = new THREE.Vector3(0, 0, 1);
+
+function disposeMaterial(material) {
+  if (!material) return;
+  if (Array.isArray(material)) {
+    material.forEach(disposeMaterial);
+    return;
+  }
+  material.dispose();
+}
+
+function disposeObjectTree(object) {
+  if (!object) return;
+  object.traverse((child) => {
+    if (child.geometry) {
+      child.geometry.dispose();
+    }
+    if (child.material) {
+      disposeMaterial(child.material);
+    }
+  });
+}
+
+function createIridiumClusterMaterial() {
+  return new THREE.ShaderMaterial({
+    transparent: true,
+    side: THREE.DoubleSide,
+    depthTest: true,
+    depthWrite: false,
+    polygonOffset: true,
+    polygonOffsetFactor: -3,
+    polygonOffsetUnits: -3,
+    blending: THREE.AdditiveBlending,
+    uniforms: {
+      uColor: { value: new THREE.Color(0x5faeff) },
+      uOpacity: { value: 0.24 },
+    },
+    vertexShader: `
+      varying vec2 vUv;
+
+      void main() {
+        vUv = uv;
+        gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+      }
+    `,
+    fragmentShader: `
+      uniform vec3 uColor;
+      uniform float uOpacity;
+      varying vec2 vUv;
+
+      void main() {
+        vec2 p = vUv * 2.0 - 1.0;
+        float ellipseMetric = p.x * p.x * 0.82 + p.y * p.y * 1.06;
+        float alpha = exp(-ellipseMetric * 1.05) * (1.0 - smoothstep(0.86, 1.24, ellipseMetric));
+        alpha *= uOpacity;
+        if (alpha <= 0.001) discard;
+        gl_FragColor = vec4(uColor, alpha);
+      }
+    `,
+  });
+}
+
+function projectOffsetToSurface(
+  centerNormal,
+  alongTrack,
+  crossTrack,
+  alongKm,
+  crossKm,
+  earthRadiusWorld,
+) {
+  const worldUnitsPerKm = earthRadiusWorld / EARTH_RADIUS_KM;
+  const surfaceRadius = earthRadiusWorld * SURFACE_SCALE + SURFACE_OFFSET;
+  return centerNormal
+    .clone()
+    .multiplyScalar(earthRadiusWorld)
+    .addScaledVector(alongTrack, alongKm * worldUnitsPerKm)
+    .addScaledVector(crossTrack, crossKm * worldUnitsPerKm)
+    .normalize()
+    .multiplyScalar(surfaceRadius);
+}
+
+function computeClusterRadiusKm(altitudeKm) {
+  const altitudeScale = THREE.MathUtils.clamp(
+    (Number(altitudeKm) || 780) / 780,
+    0.88,
+    1.18,
+  );
+  return CLUSTER_RADIUS_KM_BASE * altitudeScale;
+}
+
+export function createIridiumFootprintAdapter({
+  earthObj,
+  earthRadiusWorld,
+  renderOrder,
+}) {
+  if (!earthObj) return null;
+
+  const group = new THREE.Group();
+  group.name = "iridium-footprint-overlay";
+  group.renderOrder = renderOrder;
+  group.userData = {
+    earthRadiusWorld,
+    clusterGlow: null,
+  };
+
+  const clusterGlow = new THREE.Mesh(
+    new THREE.CircleGeometry(1, 72),
+    createIridiumClusterMaterial(),
+  );
+  clusterGlow.name = "iridium-cluster-glow";
+  clusterGlow.renderOrder = renderOrder - 1;
+  group.add(clusterGlow);
+  group.userData.clusterGlow = clusterGlow;
+
+  earthObj.add(group);
+  return group;
+}
+
+export function updateIridiumFootprintAdapter(
+  group,
+  { position, alongTrack, crossTrack, altitudeKm },
+) {
+  if (!group || !position || !alongTrack || !crossTrack) return;
+
+  const earthRadiusWorld =
+    group.userData?.earthRadiusWorld || EARTH_RADIUS_KM;
+  const centerNormal = position.clone().normalize();
+  const clusterRadiusKm = computeClusterRadiusKm(altitudeKm);
+  const clusterGlow = group.userData?.clusterGlow || null;
+  const worldUnitsPerKm = earthRadiusWorld / EARTH_RADIUS_KM;
+
+  if (clusterGlow) {
+    const clusterCenter = projectOffsetToSurface(
+      centerNormal,
+      alongTrack,
+      crossTrack,
+      0,
+      0,
+      earthRadiusWorld,
+    );
+    const clusterNormal = clusterCenter.clone().normalize();
+    clusterGlow.position.copy(clusterCenter);
+    clusterGlow.quaternion.setFromUnitVectors(SURFACE_AXIS, clusterNormal);
+    clusterGlow.scale.set(
+      clusterRadiusKm * worldUnitsPerKm * 1.18,
+      clusterRadiusKm * worldUnitsPerKm * 0.96,
+      1,
+    );
+  }
+}
+
+export function disposeIridiumFootprintAdapter(group, earthObj) {
+  if (!group) return;
+  if (earthObj) {
+    earthObj.remove(group);
+  } else if (group.parent) {
+    group.parent.remove(group);
+  }
+  disposeObjectTree(group);
+}

frontend/public/earth/js/main.js

@@ -80,6 +80,7 @@ import {
   getSatelliteCount,
   selectSatellite,
   getSatellitePoints,
+  getSatellitePresentationInfo,
   setSatelliteRingState,
   updateLockedRingPosition,
   updateHoverRingPosition,
@@ -93,6 +94,7 @@ import {
   updateBreathingPhase,
   isSatelliteFrontFacing,
   setSatelliteCamera,
+  setSatelliteSunDirection,
   setLockedSatelliteIndex,
   resetSatelliteState,
   clearSatelliteData,
@@ -576,6 +578,14 @@ function showSatelliteInfo(props, coords) {
   const ecc = props?.eccentricity || 0;
   const perigee = (6371 * (1 - ecc)).toFixed(0);
   const apogee = (6371 * (1 + ecc)).toFixed(0);
+  const presentation = getSatellitePresentationInfo(props);
+
+  let footprintModel = "不适用";
+  if (presentation.footprintPolicy === "starlink_ground_footprint") {
+    footprintModel = "Starlink 单星地表覆盖";
+  } else if (presentation.footprintPolicy === "iridium_coverage_ring") {
+    footprintModel = "Iridium 外圈半透明覆盖";
+  }
 
   setSelectedSatelliteLegend(props);
   setLegendItems("satellites", getSatelliteLegendItems());
@@ -583,6 +593,10 @@ function showSatelliteInfo(props, coords) {
   showInfoCard("satellite", {
     name: props?.name || "-",
     norad_id: props?.norad_cat_id,
+    constellation: presentation.constellationLabel,
+    footprint_capability: presentation.footprintCapabilityLabel,
+    current_display: presentation.presentationModeLabel,
+    footprint_model: footprintModel,
     inclination: props?.inclination ? props.inclination.toFixed(2) : "-",
     period,
     perigee,
@@ -1050,7 +1064,9 @@ function resolveEarthSearchResults(query) {
       icon: "satellite_alt",
       typeLabel: "卫星",
       title: props?.name || `NORAD ${props?.norad_cat_id || index}`,
-      subtitle: props?.norad_cat_id ? `NORAD ${props.norad_cat_id}` : "在轨卫星",
+      subtitle: props?.norad_cat_id
+        ? `NORAD ${props.norad_cat_id} · ${getSatellitePresentationInfo(props).constellationLabel}`
+        : `${getSatellitePresentationInfo(props).constellationLabel} · 在轨卫星`,
       score,
       entity: { index },
     });
@@ -3115,7 +3131,9 @@ function animate() {
   updateBreathingPhase(deltaTime);
   updateRelatedSatelliteHighlights();
   updateCelestialLayer(new Date(), camera);
-  setEarthSunDirection(getSunDirection());
+  const currentSunDirection = getSunDirection();
+  setEarthSunDirection(currentSunDirection);
+  setSatelliteSunDirection(currentSunDirection);
   updateNewsViewFocus(getCurrentViewCenterCoords());
   const satPositions = getSatellitePositions();
   if (