@zendir/ui 0.4.1 → 0.6.0

package/dist/react/3d/ZenSpace3DCesium.js

@@ -1,579 +1,532 @@
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
-import { forwardRef, useRef, useEffect, useCallback, useImperativeHandle } from "react";
-const EARTH_RADIUS_KM = 6371;
+//#region src/react/3d/ZenSpace3DCesium.tsx
+/**
+* @zendir/ui - ZenSpace3D Cesium Backend
+*
+* Cesium-based 3D Earth/orbit view. Entities are reconciled **in-place** on
+* each data update (position changes only) to avoid the WebGL context churn
+* that occurs when entities are removed and re-added every polling tick.
+*
+* Layer visibility is controlled via the `layers` prop
+* (all default to "sensible" if the key is absent):
+*
+*   layers.labels   — spacecraft / GS name labels          (default: false)
+*   layers.coverage — coverage footprint ellipses + cones  (default: false)
+*   layers.orbits   — orbit-path polylines                 (default: true)
+*
+* Coverage geometry sources (checked in order per satellite):
+*   1. Explicit `satelliteCoverages[].footprintPolygon` — ground polygon from SDK
+*   2. Explicit `satelliteCoverages[].halfAngle`        — circular cone from half-angle
+*   3. Auto-computed circular ellipse from altitude     (when layers.coverage = true)
+*
+* Additional explicit coverage options per `SatelliteCoverage`:
+*   showCone      — 3-D sensor cone from satellite to footprint
+*   showNadirLine — dashed line from satellite to sub-satellite point
+*/
+var EARTH_RADIUS_KM = 6371;
+/**
+* Convert an ECI / J2000 position (km, Earth-centred) into a Cesium
+* `Cartesian3`. Cesium's Cartesian3 lives in the **ECEF (Earth-Fixed)**
+* frame — the same frame Cesium for Unreal exposes when its
+* `CesiumGeoreference` origin is set to `TrueOrigin (0,0,0)`. We rotate
+* ECI → ECEF using `Transforms.computeTemeToPseudoFixedMatrix(jd)`,
+* which is GMST-based and accurate to sub-arcsec for visualisation
+* (no IERS data required, fully synchronous).
+*
+* Returns `null` for non-finite inputs so callers can skip stale ticks
+* without crashing Cesium's Cartesian primitives.
+*
+* @param positionKm  ECI position in km (Earth-centred).
+* @param julianDate  Cesium JulianDate at which to evaluate Earth's rotation.
+*                    Caller is responsible for advancing this with sim time.
+*/
 function eciKmToFixedCartesian3(Cesium, positionKm, julianDate) {
-  if (!positionKm || !Number.isFinite(positionKm.x) || !Number.isFinite(positionKm.y) || !Number.isFinite(positionKm.z)) {
-    return null;
-  }
-  const eciM = new Cesium.Cartesian3(
-    positionKm.x * 1e3,
-    positionKm.y * 1e3,
-    positionKm.z * 1e3
-  );
-  const rot = Cesium.Transforms.computeTemeToPseudoFixedMatrix(julianDate);
-  if (!rot) {
-    return eciM;
-  }
-  return Cesium.Matrix3.multiplyByVector(rot, eciM, new Cesium.Cartesian3());
+	if (!positionKm || !Number.isFinite(positionKm.x) || !Number.isFinite(positionKm.y) || !Number.isFinite(positionKm.z)) return null;
+	const eciM = new Cesium.Cartesian3(positionKm.x * 1e3, positionKm.y * 1e3, positionKm.z * 1e3);
+	const rot = Cesium.Transforms.computeTemeToPseudoFixedMatrix(julianDate);
+	if (!rot) return eciM;
+	return Cesium.Matrix3.multiplyByVector(rot, eciM, new Cesium.Cartesian3());
 }
+/**
+* Sub-satellite (lat/lon) point + altitude (km) of an ECI position at a
+* given epoch. Used by coverage/cone code that needs to draw on Earth's
+* surface beneath the satellite.
+*/
 function eciKmToSubSatellite(Cesium, positionKm, julianDate) {
-  const fixed = eciKmToFixedCartesian3(Cesium, positionKm, julianDate);
-  if (!fixed) return null;
-  const carto = Cesium.Cartographic.fromCartesian(fixed);
-  if (!carto || !Number.isFinite(carto.height)) return null;
-  return {
-    latitude: Cesium.Math.toDegrees(carto.latitude),
-    longitude: Cesium.Math.toDegrees(carto.longitude),
-    altitude: carto.height / 1e3
-    // m → km
-  };
+	const fixed = eciKmToFixedCartesian3(Cesium, positionKm, julianDate);
+	if (!fixed) return null;
+	const carto = Cesium.Cartographic.fromCartesian(fixed);
+	if (!carto || !Number.isFinite(carto.height)) return null;
+	return {
+		latitude: Cesium.Math.toDegrees(carto.latitude),
+		longitude: Cesium.Math.toDegrees(carto.longitude),
+		altitude: carto.height / 1e3
+	};
 }
+/**
+* Circular coverage footprint radius (m) on Earth surface.
+*
+* Spherical geometry:
+*   α = arcsin(R·cos(ε) / (R+h))   — nadir angle
+*   λ = π/2 − ε − α                — Earth central angle
+*   radius = R · λ                 — arc length on surface
+*/
 function autoFootprintRadiusM(altitudeKm, minElevDeg) {
-  if (altitudeKm <= 0) return 0;
-  const R = EARTH_RADIUS_KM;
-  const eps = minElevDeg * Math.PI / 180;
-  const sinAlpha = R * Math.cos(eps) / (R + altitudeKm);
-  if (sinAlpha >= 1) return 0;
-  const alpha = Math.asin(sinAlpha);
-  const lambda = Math.PI / 2 - eps - alpha;
-  return R * 1e3 * lambda;
+	if (altitudeKm <= 0) return 0;
+	const R = EARTH_RADIUS_KM;
+	const eps = minElevDeg * Math.PI / 180;
+	const sinAlpha = R * Math.cos(eps) / (R + altitudeKm);
+	if (sinAlpha >= 1) return 0;
+	const alpha = Math.asin(sinAlpha);
+	const lambda = Math.PI / 2 - eps - alpha;
+	return R * 1e3 * lambda;
 }
+/** Radius (m) of the footprint circle for a sensor with the given half-angle. */
 function halfAngleFootprintRadiusM(altitudeKm, halfAngleDeg) {
-  return altitudeKm * 1e3 * Math.tan(halfAngleDeg * Math.PI / 180);
+	return altitudeKm * 1e3 * Math.tan(halfAngleDeg * Math.PI / 180);
 }
 function removeFromMap(viewer, id, map) {
-  if (map.current.has(id)) {
-    try {
-      viewer.entities.removeById(id);
-    } catch (_) {
-    }
-    map.current.delete(id);
-  }
+	if (map.current.has(id)) {
+		try {
+			viewer.entities.removeById(id);
+		} catch (_) {}
+		map.current.delete(id);
+	}
 }
 function makePointGraphics(Cesium, color, pixelSize = 8) {
-  return {
-    pixelSize,
-    color,
-    outlineColor: Cesium.Color.WHITE,
-    outlineWidth: 1,
-    scaleByDistance: new Cesium.NearFarScalar(1e6, 1.5, 5e7, 0.5),
-    // Always render on top so satellites hidden behind Earth are still visible
-    disableDepthTestDistance: Number.POSITIVE_INFINITY
-  };
+	return {
+		pixelSize,
+		color,
+		outlineColor: Cesium.Color.WHITE,
+		outlineWidth: 1,
+		scaleByDistance: new Cesium.NearFarScalar(1e6, 1.5, 5e7, .5),
+		disableDepthTestDistance: Number.POSITIVE_INFINITY
+	};
 }
 function makeLabelOpts(Cesium, text, fillColor) {
-  return {
-    text,
-    font: "12px monospace",
-    fillColor: fillColor ?? Cesium.Color.WHITE,
-    outlineColor: Cesium.Color.BLACK,
-    outlineWidth: 2,
-    style: Cesium.LabelStyle.FILL_AND_OUTLINE,
-    pixelOffset: new Cesium.Cartesian2(12, 0),
-    scaleByDistance: new Cesium.NearFarScalar(1e6, 1, 5e7, 0.3),
-    // Fade out label when camera is very far away
-    distanceDisplayCondition: new Cesium.DistanceDisplayCondition(0, 3e7),
-    disableDepthTestDistance: Number.POSITIVE_INFINITY
-  };
+	return {
+		text,
+		font: "12px monospace",
+		fillColor: fillColor ?? Cesium.Color.WHITE,
+		outlineColor: Cesium.Color.BLACK,
+		outlineWidth: 2,
+		style: Cesium.LabelStyle.FILL_AND_OUTLINE,
+		pixelOffset: new Cesium.Cartesian2(12, 0),
+		scaleByDistance: new Cesium.NearFarScalar(1e6, 1, 5e7, .3),
+		distanceDisplayCondition: new Cesium.DistanceDisplayCondition(0, 3e7),
+		disableDepthTestDistance: Number.POSITIVE_INFINITY
+	};
 }
+/** Add or update a circular ellipse entity on the Earth surface. */
 function upsertEllipse(viewer, Cesium, id, position, radiusM, color, map) {
-  const existing = map.current.get(id);
-  if (existing) {
-    existing.position = new Cesium.ConstantPositionProperty(position);
-    existing.ellipse.semiMajorAxis = new Cesium.ConstantProperty(radiusM);
-    existing.ellipse.semiMinorAxis = new Cesium.ConstantProperty(radiusM);
-  } else {
-    const entity = viewer.entities.add({
-      id,
-      position,
-      ellipse: {
-        semiMajorAxis: radiusM,
-        semiMinorAxis: radiusM,
-        material: color.withAlpha(0.08),
-        outline: true,
-        outlineColor: color.withAlpha(0.5),
-        outlineWidth: 1,
-        height: 0
-      }
-    });
-    map.current.set(id, entity);
-  }
+	const existing = map.current.get(id);
+	if (existing) {
+		existing.position = new Cesium.ConstantPositionProperty(position);
+		existing.ellipse.semiMajorAxis = new Cesium.ConstantProperty(radiusM);
+		existing.ellipse.semiMinorAxis = new Cesium.ConstantProperty(radiusM);
+	} else {
+		const entity = viewer.entities.add({
+			id,
+			position,
+			ellipse: {
+				semiMajorAxis: radiusM,
+				semiMinorAxis: radiusM,
+				material: color.withAlpha(.08),
+				outline: true,
+				outlineColor: color.withAlpha(.5),
+				outlineWidth: 1,
+				height: 0
+			}
+		});
+		map.current.set(id, entity);
+	}
 }
+/**
+* Render (or update in-place) the full coverage geometry for one satellite
+* from an explicit `SatelliteCoverage` record supplied by the Zendir SDK.
+*/
 function renderExplicitCoverage(viewer, Cesium, satId, satPos3, cov, julianDate, covMap, coneMap, nadirMap) {
-  var _a, _b;
-  const baseColor = cov.color ? Cesium.Color.fromCssColorString(cov.color) : Cesium.Color.CYAN;
-  const opacity = cov.opacity ?? 0.2;
-  const resolvedPos = cov.satellitePosition ?? satPos3;
-  const satCesPos = eciKmToFixedCartesian3(Cesium, resolvedPos, julianDate);
-  const subSat = eciKmToSubSatellite(Cesium, resolvedPos, julianDate);
-  const latitude = (subSat == null ? void 0 : subSat.latitude) ?? NaN;
-  const longitude = (subSat == null ? void 0 : subSat.longitude) ?? NaN;
-  const altitude = (subSat == null ? void 0 : subSat.altitude) ?? NaN;
-  const nadirLat = ((_a = cov.nadirPoint) == null ? void 0 : _a.latitude) ?? latitude;
-  const nadirLon = ((_b = cov.nadirPoint) == null ? void 0 : _b.longitude) ?? longitude;
-  const covId = `cov-${satId}`;
-  if (cov.showFootprint !== false && cov.footprintPolygon && cov.footprintPolygon.length >= 3) {
-    const positions = Cesium.Cartesian3.fromDegreesArray(
-      cov.footprintPolygon.flatMap((pt) => [pt.longitude, pt.latitude])
-    );
-    const existing = covMap.current.get(covId);
-    if (existing) {
-      existing.polygon.hierarchy = new Cesium.ConstantProperty(
-        new Cesium.PolygonHierarchy(positions)
-      );
-    } else {
-      const entity = viewer.entities.add({
-        id: covId,
-        polygon: {
-          hierarchy: new Cesium.PolygonHierarchy(positions),
-          material: baseColor.withAlpha(opacity),
-          outline: true,
-          outlineColor: baseColor.withAlpha(opacity * 3),
-          height: 0,
-          clampToGround: true
-        }
-      });
-      covMap.current.set(covId, entity);
-    }
-  } else if (cov.showFootprint !== false && cov.halfAngle != null && Number.isFinite(altitude) && altitude > 0) {
-    const subSatPos = Cesium.Cartesian3.fromDegrees(nadirLon, nadirLat, 0);
-    const radius = halfAngleFootprintRadiusM(altitude, cov.halfAngle);
-    upsertEllipse(viewer, Cesium, covId, subSatPos, radius, baseColor, covMap);
-  } else {
-    removeFromMap(viewer, covId, covMap);
-  }
-  const coneId = `cone-${satId}`;
-  if (cov.showCone && satCesPos && Number.isFinite(altitude) && altitude > 0) {
-    const radius = cov.halfAngle != null ? halfAngleFootprintRadiusM(altitude, cov.halfAngle) : autoFootprintRadiusM(altitude, 5);
-    const coneLength = altitude * 1e3;
-    const midPos = Cesium.Cartesian3.fromDegrees(nadirLon, nadirLat, coneLength / 2);
-    const existing = coneMap.current.get(coneId);
-    if (existing) {
-      existing.position = new Cesium.ConstantPositionProperty(midPos);
-      existing.cylinder.length = new Cesium.ConstantProperty(coneLength);
-      existing.cylinder.bottomRadius = new Cesium.ConstantProperty(radius);
-    } else {
-      const entity = viewer.entities.add({
-        id: coneId,
-        position: midPos,
-        cylinder: {
-          length: coneLength,
-          topRadius: 0,
-          bottomRadius: radius,
-          material: baseColor.withAlpha(0.06),
-          outline: true,
-          outlineColor: baseColor.withAlpha(0.25),
-          numberOfVerticalLines: 12
-        }
-      });
-      coneMap.current.set(coneId, entity);
-    }
-  } else {
-    removeFromMap(viewer, coneId, coneMap);
-  }
-  const nadirId = `nadir-${satId}`;
-  if (cov.showNadirLine && satCesPos) {
-    const groundPos = Cesium.Cartesian3.fromDegrees(nadirLon, nadirLat, 0);
-    const existing = nadirMap.current.get(nadirId);
-    if (existing) {
-      existing.polyline.positions = new Cesium.ConstantProperty([satCesPos, groundPos]);
-    } else {
-      const entity = viewer.entities.add({
-        id: nadirId,
-        polyline: {
-          positions: [satCesPos, groundPos],
-          width: 1,
-          material: new Cesium.PolylineDashMaterialProperty({
-            color: baseColor.withAlpha(0.5),
-            dashLength: 8
-          })
-        }
-      });
-      nadirMap.current.set(nadirId, entity);
-    }
-  } else {
-    removeFromMap(viewer, nadirId, nadirMap);
-  }
+	const baseColor = cov.color ? Cesium.Color.fromCssColorString(cov.color) : Cesium.Color.CYAN;
+	const opacity = cov.opacity ?? .2;
+	const resolvedPos = cov.satellitePosition ?? satPos3;
+	const satCesPos = eciKmToFixedCartesian3(Cesium, resolvedPos, julianDate);
+	const subSat = eciKmToSubSatellite(Cesium, resolvedPos, julianDate);
+	const latitude = subSat?.latitude ?? NaN;
+	const longitude = subSat?.longitude ?? NaN;
+	const altitude = subSat?.altitude ?? NaN;
+	const nadirLat = cov.nadirPoint?.latitude ?? latitude;
+	const nadirLon = cov.nadirPoint?.longitude ?? longitude;
+	const covId = `cov-${satId}`;
+	if (cov.showFootprint !== false && cov.footprintPolygon && cov.footprintPolygon.length >= 3) {
+		const positions = Cesium.Cartesian3.fromDegreesArray(cov.footprintPolygon.flatMap((pt) => [pt.longitude, pt.latitude]));
+		const existing = covMap.current.get(covId);
+		if (existing) existing.polygon.hierarchy = new Cesium.ConstantProperty(new Cesium.PolygonHierarchy(positions));
+		else {
+			const entity = viewer.entities.add({
+				id: covId,
+				polygon: {
+					hierarchy: new Cesium.PolygonHierarchy(positions),
+					material: baseColor.withAlpha(opacity),
+					outline: true,
+					outlineColor: baseColor.withAlpha(opacity * 3),
+					height: 0,
+					clampToGround: true
+				}
+			});
+			covMap.current.set(covId, entity);
+		}
+	} else if (cov.showFootprint !== false && cov.halfAngle != null && Number.isFinite(altitude) && altitude > 0) upsertEllipse(viewer, Cesium, covId, Cesium.Cartesian3.fromDegrees(nadirLon, nadirLat, 0), halfAngleFootprintRadiusM(altitude, cov.halfAngle), baseColor, covMap);
+	else removeFromMap(viewer, covId, covMap);
+	const coneId = `cone-${satId}`;
+	if (cov.showCone && satCesPos && Number.isFinite(altitude) && altitude > 0) {
+		const radius = cov.halfAngle != null ? halfAngleFootprintRadiusM(altitude, cov.halfAngle) : autoFootprintRadiusM(altitude, 5);
+		const coneLength = altitude * 1e3;
+		const midPos = Cesium.Cartesian3.fromDegrees(nadirLon, nadirLat, coneLength / 2);
+		const existing = coneMap.current.get(coneId);
+		if (existing) {
+			existing.position = new Cesium.ConstantPositionProperty(midPos);
+			existing.cylinder.length = new Cesium.ConstantProperty(coneLength);
+			existing.cylinder.bottomRadius = new Cesium.ConstantProperty(radius);
+		} else {
+			const entity = viewer.entities.add({
+				id: coneId,
+				position: midPos,
+				cylinder: {
+					length: coneLength,
+					topRadius: 0,
+					bottomRadius: radius,
+					material: baseColor.withAlpha(.06),
+					outline: true,
+					outlineColor: baseColor.withAlpha(.25),
+					numberOfVerticalLines: 12
+				}
+			});
+			coneMap.current.set(coneId, entity);
+		}
+	} else removeFromMap(viewer, coneId, coneMap);
+	const nadirId = `nadir-${satId}`;
+	if (cov.showNadirLine && satCesPos) {
+		const groundPos = Cesium.Cartesian3.fromDegrees(nadirLon, nadirLat, 0);
+		const existing = nadirMap.current.get(nadirId);
+		if (existing) existing.polyline.positions = new Cesium.ConstantProperty([satCesPos, groundPos]);
+		else {
+			const entity = viewer.entities.add({
+				id: nadirId,
+				polyline: {
+					positions: [satCesPos, groundPos],
+					width: 1,
+					material: new Cesium.PolylineDashMaterialProperty({
+						color: baseColor.withAlpha(.5),
+						dashLength: 8
+					})
+				}
+			});
+			nadirMap.current.set(nadirId, entity);
+		}
+	} else removeFromMap(viewer, nadirId, nadirMap);
 }
-const ZenSpace3DCesium = forwardRef(
-  function ZenSpace3DCesium2({
-    satellites = [],
-    stations = [],
-    groundStations = [],
-    customObjects = [],
-    orbitPaths = [],
-    satelliteCoverages = [],
-    view = "earth-orbit",
-    height = 600,
-    callbacks,
-    showTools = false,
-    layers,
-    visibility,
-    referenceTime,
-    cesium: Cesium
-  }, ref) {
-    const containerRef = useRef(null);
-    const viewerRef = useRef(null);
-    const callbacksRef = useRef(callbacks);
-    useEffect(() => {
-      callbacksRef.current = callbacks;
-    }, [callbacks]);
-    const satMapRef = useRef(/* @__PURE__ */ new Map());
-    const gsMapRef = useRef(/* @__PURE__ */ new Map());
-    const covMapRef = useRef(/* @__PURE__ */ new Map());
-    const coneMapRef = useRef(/* @__PURE__ */ new Map());
-    const nadirMapRef = useRef(/* @__PURE__ */ new Map());
-    const orbitMapRef = useRef(/* @__PURE__ */ new Map());
-    const eciPositionsRef = useRef(/* @__PURE__ */ new Map());
-    const showLabels = (layers == null ? void 0 : layers.labels) === true;
-    const showCoverage = (layers == null ? void 0 : layers.coverage) === true;
-    const showOrbits = (layers == null ? void 0 : layers.orbits) !== false;
-    const showSpacecraft = (visibility == null ? void 0 : visibility.spacecraft) !== false;
-    const showGroundStations = (visibility == null ? void 0 : visibility.groundStations) !== false;
-    const showCelestialBodies = (visibility == null ? void 0 : visibility.celestialBodies) !== false;
-    const focusOn = useCallback(
-      (objectId, options) => {
-        const viewer = viewerRef.current;
-        if (!viewer) return;
-        const entity = viewer.entities.getById(objectId);
-        if (entity) {
-          viewer.zoomTo(entity, { duration: (options == null ? void 0 : options.animate) !== false ? 1.5 : 0 });
-        }
-      },
-      []
-    );
-    const setView = useCallback(
-      (mode) => {
-        const viewer = viewerRef.current;
-        if (!viewer) return;
-        if (mode === "earth-orbit") {
-          viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(0, 0, 2e7) });
-        } else if (mode === "solar-system") {
-          viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(0, 0, 5e7) });
-        }
-      },
-      [Cesium]
-    );
-    useImperativeHandle(
-      ref,
-      () => ({
-        focusOn,
-        flyTo: focusOn,
-        setView,
-        setTime: () => {
-        },
-        setTimeScale: () => {
-        },
-        togglePlay: () => {
-        },
-        setLayerVisibility: () => {
-        },
-        getCameraState: () => ({}),
-        setCameraState: () => {
-        },
-        exportImage: () => "",
-        exportScene: () => new Blob(),
-        getVisibleObjects: () => [],
-        findObjects: () => [],
-        addObject: () => {
-        },
-        removeObject: () => {
-        },
-        updateObject: () => {
-        },
-        measureDistance: () => 0
-      }),
-      [focusOn, setView]
-    );
-    useEffect(() => {
-      if (!containerRef.current || !Cesium) return;
-      satMapRef.current.clear();
-      gsMapRef.current.clear();
-      covMapRef.current.clear();
-      coneMapRef.current.clear();
-      nadirMapRef.current.clear();
-      orbitMapRef.current.clear();
-      eciPositionsRef.current.clear();
-      const viewer = new Cesium.Viewer(containerRef.current, {
-        baseLayerPicker: false,
-        fullscreenButton: false,
-        vrButton: false,
-        geocoder: false,
-        homeButton: !!showTools,
-        sceneModePicker: false,
-        timeline: false,
-        navigationHelpButton: !!showTools,
-        animation: false,
-        scene3DOnly: true,
-        useDefaultRenderLoop: true,
-        requestRenderMode: false
-      });
-      viewer.scene.globe.enableLighting = true;
-      viewer.scene.backgroundColor = Cesium.Color.BLACK;
-      viewer.scene.renderError.addEventListener((scene, err) => {
-        console.error("[ZenSpace3D] Cesium render error:", err);
-      });
-      viewer.clock.currentTime = Cesium.JulianDate.now();
-      viewer.clock.multiplier = 1;
-      viewer.clock.shouldAnimate = true;
-      viewerRef.current = viewer;
-      const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
-      handler.setInputAction((movement) => {
-        var _a;
-        const picked = viewer.scene.pick(movement.position);
-        if (Cesium.defined(picked) && picked.id && ((_a = callbacksRef.current) == null ? void 0 : _a.onSelect)) {
-          callbacksRef.current.onSelect({
-            id: picked.id.id,
-            name: picked.id.name,
-            category: "satellite",
-            position: { x: 0, y: 0, z: 0 },
-            visualRadius: 0
-          });
-        }
-      }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
-      handler.setInputAction((movement) => {
-        var _a, _b, _c, _d;
-        const picked = viewer.scene.pick(movement.endPosition);
-        if (Cesium.defined(picked) && picked.id) {
-          (_b = (_a = callbacksRef.current) == null ? void 0 : _a.onHover) == null ? void 0 : _b.call(_a, {
-            id: picked.id.id,
-            name: picked.id.name,
-            category: "satellite",
-            position: { x: 0, y: 0, z: 0 },
-            visualRadius: 0
-          });
-        } else {
-          (_d = (_c = callbacksRef.current) == null ? void 0 : _c.onHover) == null ? void 0 : _d.call(_c, null);
-        }
-      }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
-      return () => {
-        handler.destroy();
-        satMapRef.current.clear();
-        gsMapRef.current.clear();
-        covMapRef.current.clear();
-        coneMapRef.current.clear();
-        nadirMapRef.current.clear();
-        orbitMapRef.current.clear();
-        eciPositionsRef.current.clear();
-        viewer.destroy();
-        viewerRef.current = null;
-      };
-    }, [Cesium, showTools]);
-    useEffect(() => {
-      const viewer = viewerRef.current;
-      if (!viewer || !Cesium) return;
-      const jd = referenceTime ? Cesium.JulianDate.fromDate(referenceTime) : Cesium.JulianDate.now();
-      const seenSats = /* @__PURE__ */ new Set();
-      const renderedSats = showSpacecraft ? [...satellites, ...stations] : [];
-      renderedSats.forEach((obj) => {
-        const id = obj.id;
-        const pos3 = obj.position;
-        if (!pos3) return;
-        if (!Number.isFinite(pos3.x) || !Number.isFinite(pos3.y) || !Number.isFinite(pos3.z)) return;
-        eciPositionsRef.current.set(id, pos3);
-        seenSats.add(id);
-        const name = obj.name ?? id;
-        const existing = satMapRef.current.get(id);
-        if (existing) {
-          if (existing.label) {
-            existing.label.show = new Cesium.ConstantProperty(showLabels);
-          } else if (showLabels) {
-            existing.label = new Cesium.LabelGraphics(makeLabelOpts(Cesium, name));
-          }
-        } else {
-          const capturedId = id;
-          const posProperty = new Cesium.CallbackPositionProperty(
-            (time) => {
-              try {
-                const eciKm = eciPositionsRef.current.get(capturedId);
-                if (!eciKm) return void 0;
-                const fixed = eciKmToFixedCartesian3(Cesium, eciKm, time);
-                if (!fixed || !Number.isFinite(fixed.x) || !Number.isFinite(fixed.y) || !Number.isFinite(fixed.z)) {
-                  return void 0;
-                }
-                return fixed;
-              } catch {
-                return void 0;
-              }
-            },
-            false,
-            // not constant — must be re-evaluated every frame
-            Cesium.ReferenceFrame.FIXED
-          );
-          const entity = viewer.entities.add({
-            id,
-            name,
-            position: posProperty,
-            point: makePointGraphics(Cesium, Cesium.Color.CYAN),
-            label: showLabels ? new Cesium.LabelGraphics(makeLabelOpts(Cesium, name)) : void 0
-          });
-          satMapRef.current.set(id, entity);
-        }
-        const explicitCov = (satelliteCoverages ?? []).find((c) => c.satelliteId === id);
-        if (explicitCov) {
-          renderExplicitCoverage(
-            viewer,
-            Cesium,
-            id,
-            pos3,
-            explicitCov,
-            jd,
-            covMapRef,
-            coneMapRef,
-            nadirMapRef
-          );
-        } else if (showCoverage) {
-          const subSat = eciKmToSubSatellite(Cesium, pos3, jd);
-          if (subSat && subSat.altitude > 0) {
-            const subSatPos = Cesium.Cartesian3.fromDegrees(subSat.longitude, subSat.latitude, 0);
-            const radius = autoFootprintRadiusM(subSat.altitude, 5);
-            upsertEllipse(viewer, Cesium, `cov-${id}`, subSatPos, radius, Cesium.Color.CYAN, covMapRef);
-          }
-        } else {
-          removeFromMap(viewer, `cov-${id}`, covMapRef);
-          removeFromMap(viewer, `cone-${id}`, coneMapRef);
-          removeFromMap(viewer, `nadir-${id}`, nadirMapRef);
-        }
-      });
-      satMapRef.current.forEach((_, id) => {
-        if (!seenSats.has(id)) {
-          eciPositionsRef.current.delete(id);
-          removeFromMap(viewer, id, satMapRef);
-          removeFromMap(viewer, `cov-${id}`, covMapRef);
-          removeFromMap(viewer, `cone-${id}`, coneMapRef);
-          removeFromMap(viewer, `nadir-${id}`, nadirMapRef);
-        }
-      });
-      const seenCustom = /* @__PURE__ */ new Set();
-      const renderedCustom = showCelestialBodies ? customObjects ?? [] : [];
-      renderedCustom.forEach((obj) => {
-        if (/^earth$/i.test(obj.name ?? "")) return;
-        const id = obj.id;
-        const cesPos = eciKmToFixedCartesian3(Cesium, obj.position, jd);
-        if (!cesPos) return;
-        seenCustom.add(id);
-        const existing = satMapRef.current.get(`custom-${id}`);
-        if (existing) {
-          existing.position = new Cesium.ConstantPositionProperty(cesPos);
-          if (existing.label) {
-            existing.label.show = new Cesium.ConstantProperty(showLabels);
-          } else if (showLabels) {
-            existing.label = new Cesium.LabelGraphics(
-              makeLabelOpts(Cesium, obj.name ?? id, Cesium.Color.ORANGE)
-            );
-          }
-        } else {
-          const entity = viewer.entities.add({
-            id: `custom-${id}`,
-            name: obj.name,
-            position: cesPos,
-            point: makePointGraphics(Cesium, Cesium.Color.ORANGE, 10),
-            label: showLabels ? new Cesium.LabelGraphics(makeLabelOpts(Cesium, obj.name ?? id, Cesium.Color.ORANGE)) : void 0
-          });
-          satMapRef.current.set(`custom-${id}`, entity);
-        }
-      });
-      satMapRef.current.forEach((_, key) => {
-        if (key.startsWith("custom-") && !seenCustom.has(key.slice(7))) {
-          removeFromMap(viewer, key, satMapRef);
-        }
-      });
-      const seenGs = /* @__PURE__ */ new Set();
-      const renderedGs = showGroundStations ? groundStations ?? [] : [];
-      renderedGs.forEach((gs) => {
-        if (!Number.isFinite(gs.longitude) || !Number.isFinite(gs.latitude)) return;
-        seenGs.add(gs.id);
-        const heightM = Number.isFinite(gs.elevation) ? gs.elevation : 0;
-        const gsPos = Cesium.Cartesian3.fromDegrees(gs.longitude, gs.latitude, heightM);
-        const name = gs.name ?? gs.id;
-        const existing = gsMapRef.current.get(gs.id);
-        if (existing) {
-          existing.position = new Cesium.ConstantPositionProperty(gsPos);
-          if (existing.label) {
-            existing.label.show = new Cesium.ConstantProperty(showLabels);
-          } else if (showLabels) {
-            existing.label = new Cesium.LabelGraphics(
-              makeLabelOpts(Cesium, name, Cesium.Color.YELLOW)
-            );
-          }
-        } else {
-          const entity = viewer.entities.add({
-            id: gs.id,
-            name,
-            position: gsPos,
-            point: makePointGraphics(Cesium, Cesium.Color.YELLOW, 6),
-            label: showLabels ? new Cesium.LabelGraphics(makeLabelOpts(Cesium, name, Cesium.Color.YELLOW)) : void 0
-          });
-          gsMapRef.current.set(gs.id, entity);
-        }
-      });
-      gsMapRef.current.forEach((_, id) => {
-        if (!seenGs.has(id)) removeFromMap(viewer, id, gsMapRef);
-      });
-      if (showOrbits) {
-        const seenOrbits = /* @__PURE__ */ new Set();
-        (orbitPaths ?? []).forEach((path) => {
-          const orbitId = `orbit-${path.objectId}`;
-          seenOrbits.add(orbitId);
-          const positions = path.points.map((p) => eciKmToFixedCartesian3(Cesium, p, jd)).filter((p) => p != null);
-          if (positions.length < 2) return;
-          const orbitColor = path.color ? Cesium.Color.fromCssColorString(path.color).withAlpha(0.65) : Cesium.Color.YELLOW.withAlpha(0.55);
-          const existing = orbitMapRef.current.get(orbitId);
-          if (existing) {
-            existing.polyline.positions = new Cesium.ConstantProperty(positions);
-          } else {
-            const entity = viewer.entities.add({
-              id: orbitId,
-              name: path.objectId,
-              polyline: {
-                positions,
-                width: 1.5,
-                material: new Cesium.PolylineDashMaterialProperty({
-                  color: orbitColor,
-                  dashLength: 16
-                })
-              }
-            });
-            orbitMapRef.current.set(orbitId, entity);
-          }
-        });
-        orbitMapRef.current.forEach((_, id) => {
-          if (!seenOrbits.has(id)) removeFromMap(viewer, id, orbitMapRef);
-        });
-      } else {
-        orbitMapRef.current.forEach((_, id) => removeFromMap(viewer, id, orbitMapRef));
-      }
-    }, [
-      Cesium,
-      satellites,
-      stations,
-      customObjects,
-      groundStations,
-      orbitPaths,
-      satelliteCoverages,
-      showLabels,
-      showCoverage,
-      showOrbits,
-      showSpacecraft,
-      showGroundStations,
-      showCelestialBodies,
-      referenceTime
-    ]);
-    useEffect(() => {
-      setView(view);
-    }, [view]);
-    const h = typeof height === "number" ? `${height}px` : height;
-    return /* @__PURE__ */ jsx(
-      "div",
-      {
-        ref: containerRef,
-        className: "zendir-zenspace3d-cesium",
-        style: { width: "100%", height: h, minHeight: 200 }
-      }
-    );
-  }
-);
-export {
-  ZenSpace3DCesium
-};
-//# sourceMappingURL=ZenSpace3DCesium.js.map
+var ZenSpace3DCesium = forwardRef(function ZenSpace3DCesium({ satellites = [], stations = [], groundStations = [], customObjects = [], orbitPaths = [], satelliteCoverages = [], view = "earth-orbit", height = 600, callbacks, showTools = false, layers, visibility, referenceTime, cesium: Cesium }, ref) {
+	const containerRef = useRef(null);
+	const viewerRef = useRef(null);
+	const callbacksRef = useRef(callbacks);
+	useEffect(() => {
+		callbacksRef.current = callbacks;
+	}, [callbacks]);
+	const satMapRef = useRef(/* @__PURE__ */ new Map());
+	const gsMapRef = useRef(/* @__PURE__ */ new Map());
+	const covMapRef = useRef(/* @__PURE__ */ new Map());
+	const coneMapRef = useRef(/* @__PURE__ */ new Map());
+	const nadirMapRef = useRef(/* @__PURE__ */ new Map());
+	const orbitMapRef = useRef(/* @__PURE__ */ new Map());
+	const eciPositionsRef = useRef(/* @__PURE__ */ new Map());
+	const showLabels = layers?.labels === true;
+	const showCoverage = layers?.coverage === true;
+	const showOrbits = layers?.orbits !== false;
+	const showSpacecraft = visibility?.spacecraft !== false;
+	const showGroundStations = visibility?.groundStations !== false;
+	const showCelestialBodies = visibility?.celestialBodies !== false;
+	const focusOn = useCallback((objectId, options) => {
+		const viewer = viewerRef.current;
+		if (!viewer) return;
+		const entity = viewer.entities.getById(objectId);
+		if (entity) viewer.zoomTo(entity, { duration: options?.animate !== false ? 1.5 : 0 });
+	}, []);
+	const setView = useCallback((mode) => {
+		const viewer = viewerRef.current;
+		if (!viewer) return;
+		if (mode === "earth-orbit") viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(0, 0, 2e7) });
+		else if (mode === "solar-system") viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(0, 0, 5e7) });
+	}, [Cesium]);
+	useImperativeHandle(ref, () => ({
+		focusOn,
+		flyTo: focusOn,
+		setView,
+		setTime: () => {},
+		setTimeScale: () => {},
+		togglePlay: () => {},
+		setLayerVisibility: () => {},
+		getCameraState: () => ({}),
+		setCameraState: () => {},
+		exportImage: () => "",
+		exportScene: () => new Blob(),
+		getVisibleObjects: () => [],
+		findObjects: () => [],
+		addObject: () => {},
+		removeObject: () => {},
+		updateObject: () => {},
+		measureDistance: () => 0
+	}), [focusOn, setView]);
+	useEffect(() => {
+		if (!containerRef.current || !Cesium) return;
+		satMapRef.current.clear();
+		gsMapRef.current.clear();
+		covMapRef.current.clear();
+		coneMapRef.current.clear();
+		nadirMapRef.current.clear();
+		orbitMapRef.current.clear();
+		eciPositionsRef.current.clear();
+		const viewer = new Cesium.Viewer(containerRef.current, {
+			baseLayerPicker: false,
+			fullscreenButton: false,
+			vrButton: false,
+			geocoder: false,
+			homeButton: !!showTools,
+			sceneModePicker: false,
+			timeline: false,
+			navigationHelpButton: !!showTools,
+			animation: false,
+			scene3DOnly: true,
+			useDefaultRenderLoop: true,
+			requestRenderMode: false
+		});
+		viewer.scene.globe.enableLighting = true;
+		viewer.scene.backgroundColor = Cesium.Color.BLACK;
+		viewer.scene.renderError.addEventListener((scene, err) => {
+			console.error("[ZenSpace3D] Cesium render error:", err);
+		});
+		viewer.clock.currentTime = Cesium.JulianDate.now();
+		viewer.clock.multiplier = 1;
+		viewer.clock.shouldAnimate = true;
+		viewerRef.current = viewer;
+		const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
+		handler.setInputAction((movement) => {
+			const picked = viewer.scene.pick(movement.position);
+			if (Cesium.defined(picked) && picked.id && callbacksRef.current?.onSelect) callbacksRef.current.onSelect({
+				id: picked.id.id,
+				name: picked.id.name,
+				category: "satellite",
+				position: {
+					x: 0,
+					y: 0,
+					z: 0
+				},
+				visualRadius: 0
+			});
+		}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+		handler.setInputAction((movement) => {
+			const picked = viewer.scene.pick(movement.endPosition);
+			if (Cesium.defined(picked) && picked.id) callbacksRef.current?.onHover?.({
+				id: picked.id.id,
+				name: picked.id.name,
+				category: "satellite",
+				position: {
+					x: 0,
+					y: 0,
+					z: 0
+				},
+				visualRadius: 0
+			});
+			else callbacksRef.current?.onHover?.(null);
+		}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
+		return () => {
+			handler.destroy();
+			satMapRef.current.clear();
+			gsMapRef.current.clear();
+			covMapRef.current.clear();
+			coneMapRef.current.clear();
+			nadirMapRef.current.clear();
+			orbitMapRef.current.clear();
+			eciPositionsRef.current.clear();
+			viewer.destroy();
+			viewerRef.current = null;
+		};
+	}, [Cesium, showTools]);
+	useEffect(() => {
+		const viewer = viewerRef.current;
+		if (!viewer || !Cesium) return;
+		const jd = referenceTime ? Cesium.JulianDate.fromDate(referenceTime) : Cesium.JulianDate.now();
+		const seenSats = /* @__PURE__ */ new Set();
+		(showSpacecraft ? [...satellites, ...stations] : []).forEach((obj) => {
+			const id = obj.id;
+			const pos3 = obj.position;
+			if (!pos3) return;
+			if (!Number.isFinite(pos3.x) || !Number.isFinite(pos3.y) || !Number.isFinite(pos3.z)) return;
+			eciPositionsRef.current.set(id, pos3);
+			seenSats.add(id);
+			const name = obj.name ?? id;
+			const existing = satMapRef.current.get(id);
+			if (existing) {
+				if (existing.label) existing.label.show = new Cesium.ConstantProperty(showLabels);
+				else if (showLabels) existing.label = new Cesium.LabelGraphics(makeLabelOpts(Cesium, name));
+			} else {
+				const capturedId = id;
+				const posProperty = new Cesium.CallbackPositionProperty((time) => {
+					try {
+						const eciKm = eciPositionsRef.current.get(capturedId);
+						if (!eciKm) return void 0;
+						const fixed = eciKmToFixedCartesian3(Cesium, eciKm, time);
+						if (!fixed || !Number.isFinite(fixed.x) || !Number.isFinite(fixed.y) || !Number.isFinite(fixed.z)) return;
+						return fixed;
+					} catch {
+						return;
+					}
+				}, false, Cesium.ReferenceFrame.FIXED);
+				const entity = viewer.entities.add({
+					id,
+					name,
+					position: posProperty,
+					point: makePointGraphics(Cesium, Cesium.Color.CYAN),
+					label: showLabels ? new Cesium.LabelGraphics(makeLabelOpts(Cesium, name)) : void 0
+				});
+				satMapRef.current.set(id, entity);
+			}
+			const explicitCov = (satelliteCoverages ?? []).find((c) => c.satelliteId === id);
+			if (explicitCov) renderExplicitCoverage(viewer, Cesium, id, pos3, explicitCov, jd, covMapRef, coneMapRef, nadirMapRef);
+			else if (showCoverage) {
+				const subSat = eciKmToSubSatellite(Cesium, pos3, jd);
+				if (subSat && subSat.altitude > 0) {
+					const subSatPos = Cesium.Cartesian3.fromDegrees(subSat.longitude, subSat.latitude, 0);
+					const radius = autoFootprintRadiusM(subSat.altitude, 5);
+					upsertEllipse(viewer, Cesium, `cov-${id}`, subSatPos, radius, Cesium.Color.CYAN, covMapRef);
+				}
+			} else {
+				removeFromMap(viewer, `cov-${id}`, covMapRef);
+				removeFromMap(viewer, `cone-${id}`, coneMapRef);
+				removeFromMap(viewer, `nadir-${id}`, nadirMapRef);
+			}
+		});
+		satMapRef.current.forEach((_, id) => {
+			if (!seenSats.has(id)) {
+				eciPositionsRef.current.delete(id);
+				removeFromMap(viewer, id, satMapRef);
+				removeFromMap(viewer, `cov-${id}`, covMapRef);
+				removeFromMap(viewer, `cone-${id}`, coneMapRef);
+				removeFromMap(viewer, `nadir-${id}`, nadirMapRef);
+			}
+		});
+		const seenCustom = /* @__PURE__ */ new Set();
+		(showCelestialBodies ? customObjects ?? [] : []).forEach((obj) => {
+			if (/^earth$/i.test(obj.name ?? "")) return;
+			const id = obj.id;
+			const cesPos = eciKmToFixedCartesian3(Cesium, obj.position, jd);
+			if (!cesPos) return;
+			seenCustom.add(id);
+			const existing = satMapRef.current.get(`custom-${id}`);
+			if (existing) {
+				existing.position = new Cesium.ConstantPositionProperty(cesPos);
+				if (existing.label) existing.label.show = new Cesium.ConstantProperty(showLabels);
+				else if (showLabels) existing.label = new Cesium.LabelGraphics(makeLabelOpts(Cesium, obj.name ?? id, Cesium.Color.ORANGE));
+			} else {
+				const entity = viewer.entities.add({
+					id: `custom-${id}`,
+					name: obj.name,
+					position: cesPos,
+					point: makePointGraphics(Cesium, Cesium.Color.ORANGE, 10),
+					label: showLabels ? new Cesium.LabelGraphics(makeLabelOpts(Cesium, obj.name ?? id, Cesium.Color.ORANGE)) : void 0
+				});
+				satMapRef.current.set(`custom-${id}`, entity);
+			}
+		});
+		satMapRef.current.forEach((_, key) => {
+			if (key.startsWith("custom-") && !seenCustom.has(key.slice(7))) removeFromMap(viewer, key, satMapRef);
+		});
+		const seenGs = /* @__PURE__ */ new Set();
+		(showGroundStations ? groundStations ?? [] : []).forEach((gs) => {
+			if (!Number.isFinite(gs.longitude) || !Number.isFinite(gs.latitude)) return;
+			seenGs.add(gs.id);
+			const heightM = Number.isFinite(gs.elevation) ? gs.elevation : 0;
+			const gsPos = Cesium.Cartesian3.fromDegrees(gs.longitude, gs.latitude, heightM);
+			const name = gs.name ?? gs.id;
+			const existing = gsMapRef.current.get(gs.id);
+			if (existing) {
+				existing.position = new Cesium.ConstantPositionProperty(gsPos);
+				if (existing.label) existing.label.show = new Cesium.ConstantProperty(showLabels);
+				else if (showLabels) existing.label = new Cesium.LabelGraphics(makeLabelOpts(Cesium, name, Cesium.Color.YELLOW));
+			} else {
+				const entity = viewer.entities.add({
+					id: gs.id,
+					name,
+					position: gsPos,
+					point: makePointGraphics(Cesium, Cesium.Color.YELLOW, 6),
+					label: showLabels ? new Cesium.LabelGraphics(makeLabelOpts(Cesium, name, Cesium.Color.YELLOW)) : void 0
+				});
+				gsMapRef.current.set(gs.id, entity);
+			}
+		});
+		gsMapRef.current.forEach((_, id) => {
+			if (!seenGs.has(id)) removeFromMap(viewer, id, gsMapRef);
+		});
+		if (showOrbits) {
+			const seenOrbits = /* @__PURE__ */ new Set();
+			(orbitPaths ?? []).forEach((path) => {
+				const orbitId = `orbit-${path.objectId}`;
+				seenOrbits.add(orbitId);
+				const positions = path.points.map((p) => eciKmToFixedCartesian3(Cesium, p, jd)).filter((p) => p != null);
+				if (positions.length < 2) return;
+				const orbitColor = path.color ? Cesium.Color.fromCssColorString(path.color).withAlpha(.65) : Cesium.Color.YELLOW.withAlpha(.55);
+				const existing = orbitMapRef.current.get(orbitId);
+				if (existing) existing.polyline.positions = new Cesium.ConstantProperty(positions);
+				else {
+					const entity = viewer.entities.add({
+						id: orbitId,
+						name: path.objectId,
+						polyline: {
+							positions,
+							width: 1.5,
+							material: new Cesium.PolylineDashMaterialProperty({
+								color: orbitColor,
+								dashLength: 16
+							})
+						}
+					});
+					orbitMapRef.current.set(orbitId, entity);
+				}
+			});
+			orbitMapRef.current.forEach((_, id) => {
+				if (!seenOrbits.has(id)) removeFromMap(viewer, id, orbitMapRef);
+			});
+		} else orbitMapRef.current.forEach((_, id) => removeFromMap(viewer, id, orbitMapRef));
+	}, [
+		Cesium,
+		satellites,
+		stations,
+		customObjects,
+		groundStations,
+		orbitPaths,
+		satelliteCoverages,
+		showLabels,
+		showCoverage,
+		showOrbits,
+		showSpacecraft,
+		showGroundStations,
+		showCelestialBodies,
+		referenceTime
+	]);
+	useEffect(() => {
+		setView(view);
+	}, [view]);
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className: "zendir-zenspace3d-cesium",
+		style: {
+			width: "100%",
+			height: typeof height === "number" ? `${height}px` : height,
+			minHeight: 200
+		}
+	});
+});
+//#endregion
+export { ZenSpace3DCesium, ZenSpace3DCesium as default };
+
+//# sourceMappingURL=ZenSpace3DCesium.js.map