@zendir/ui 0.5.0 → 0.6.0

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

@@ -1,307 +1,388 @@
-import { DEG_TO_RAD, RAD_TO_DEG, EARTH_RADIUS_KM } from "./ZenSpace3DUtils.js";
+import { DEG_TO_RAD, EARTH_RADIUS_KM, RAD_TO_DEG } from "./ZenSpace3DUtils.js";
+//#region src/react/3d/CesiumCaptureSource.ts
+/** Lazy import avoids circular deps; returns bundled placeholder PNG on capture failure */
 async function loadPlaceholderFallback() {
-  const { loadCapturePlaceholderImage } = await import("../core/widgets/Capture.js");
-  return loadCapturePlaceholderImage();
+	const { loadCapturePlaceholderImage } = await import("../core/widgets/Capture.js");
+	return loadCapturePlaceholderImage();
 }
+/**
+* Convert ECEF meters (Unreal / game-engine format) to SDK's ECI-like km format.
+*
+* ECEF (Earth-Centered Earth-Fixed): X→0°N 0°E, Y→0°N 90°E, Z→North Pole (meters)
+* SDK (ECI-like):                    X/Z→equatorial plane,   Y→North Pole  (km)
+*
+* Axis mapping:  SDK.x = ECEF.x / 1000
+*                SDK.y = ECEF.z / 1000   (ECEF Z=north → SDK Y=north)
+*                SDK.z = ECEF.y / 1000
+*
+* Export this so callers (e.g. MQTT handlers) can normalize at the boundary
+* before passing positions to CaptureArgs.
+*/
 function ecefMetersToSdkPosition(ecef) {
-  const [ex, ey, ez] = ecef;
-  return [ex / 1e3, ez / 1e3, ey / 1e3];
+	const [ex, ey, ez] = ecef;
+	return [
+		ex / 1e3,
+		ez / 1e3,
+		ey / 1e3
+	];
 }
+/**
+* Convert world-frame Euler XYZ rotation + ECEF position to Cesium HPR (degrees).
+*
+* The game engine sends the camera's absolute orientation as Euler 1-2-3
+* (XYZ intrinsic, right-handed, X=right Y=forward Z=up) in the ECEF world frame.
+* Cesium's heading/pitch/roll are relative to the local ENU (East-North-Up) frame
+* at the camera's geographic position, so we must:
+*
+*   1. Build the rotation matrix R from Euler XYZ (camera axes in ECEF)
+*   2. Extract the camera's forward (+Y) and up (+Z) vectors in ECEF
+*   3. Compute the ECEF→ENU rotation matrix at the camera's lat/lon
+*   4. Transform forward/up into the ENU frame
+*   5. Extract heading, pitch, roll from those ENU vectors
+*
+* @param ecefPos  Camera position in ECEF meters [x, y, z]
+* @param eulerDeg Euler XYZ rotation in degrees [rx, ry, rz]
+* @returns [heading, pitch, roll] in degrees (Cesium convention)
+*/
 function ecefEulerXyzToHpr(ecefPos, eulerDeg) {
-  const [px, py, pz] = ecefPos;
-  const rHoriz = Math.sqrt(px * px + py * py);
-  const lat = Math.atan2(pz, rHoriz);
-  const lon = Math.atan2(py, px);
-  const slat = Math.sin(lat), clat = Math.cos(lat);
-  const slon = Math.sin(lon), clon = Math.cos(lon);
-  const rx = eulerDeg[0] * DEG_TO_RAD;
-  const ry = eulerDeg[1] * DEG_TO_RAD;
-  const rz = eulerDeg[2] * DEG_TO_RAD;
-  const cx = Math.cos(rx), sx = Math.sin(rx);
-  const cy = Math.cos(ry), sy = Math.sin(ry);
-  const cz = Math.cos(rz), sz = Math.sin(rz);
-  const fX = sx * sy * cz - cx * sz;
-  const fY = sx * sy * sz + cx * cz;
-  const fZ = sx * cy;
-  const uX = cx * sy * cz + sx * sz;
-  const uY = cx * sy * sz - sx * cz;
-  const uZ = cx * cy;
-  const fE = -slon * fX + clon * fY;
-  const fN = -slat * clon * fX - slat * slon * fY + clat * fZ;
-  const fU = clat * clon * fX + clat * slon * fY + slat * fZ;
-  const uE = -slon * uX + clon * uY;
-  const uN = -slat * clon * uX - slat * slon * uY + clat * uZ;
-  const uU = clat * clon * uX + clat * slon * uY + slat * uZ;
-  const horizLen = Math.sqrt(fE * fE + fN * fN);
-  const heading = Math.atan2(fE, fN) * RAD_TO_DEG;
-  const pitch = Math.atan2(fU, horizLen) * RAD_TO_DEG;
-  if (horizLen < 1e-9) {
-    const roll2 = Math.atan2(uE, uN) * RAD_TO_DEG;
-    return [heading, pitch, roll2];
-  }
-  const drLen = Math.sqrt(fN * fN + fE * fE);
-  const drE = fN / drLen;
-  const drN = -fE / drLen;
-  const fLen = Math.sqrt(fE * fE + fN * fN + fU * fU);
-  const fnE = fE / fLen, fnN = fN / fLen, fnU = fU / fLen;
-  const duE = drN * fnU;
-  const duN = -drE * fnU;
-  const duU = drE * fnN - drN * fnE;
-  const roll = Math.atan2(
-    uE * drE + uN * drN,
-    // up · default_right (drU=0)
-    uE * duE + uN * duN + uU * duU
-    // up · default_up
-  ) * RAD_TO_DEG;
-  return [heading, pitch, roll];
+	const [px, py, pz] = ecefPos;
+	const rHoriz = Math.sqrt(px * px + py * py);
+	const lat = Math.atan2(pz, rHoriz);
+	const lon = Math.atan2(py, px);
+	const slat = Math.sin(lat), clat = Math.cos(lat);
+	const slon = Math.sin(lon), clon = Math.cos(lon);
+	const rx = eulerDeg[0] * DEG_TO_RAD;
+	const ry = eulerDeg[1] * DEG_TO_RAD;
+	const rz = eulerDeg[2] * DEG_TO_RAD;
+	const cx = Math.cos(rx), sx = Math.sin(rx);
+	const cy = Math.cos(ry), sy = Math.sin(ry);
+	const cz = Math.cos(rz), sz = Math.sin(rz);
+	const fX = sx * sy * cz - cx * sz;
+	const fY = sx * sy * sz + cx * cz;
+	const fZ = sx * cy;
+	const uX = cx * sy * cz + sx * sz;
+	const uY = cx * sy * sz - sx * cz;
+	const uZ = cx * cy;
+	const fE = -slon * fX + clon * fY;
+	const fN = -slat * clon * fX - slat * slon * fY + clat * fZ;
+	const fU = clat * clon * fX + clat * slon * fY + slat * fZ;
+	const uE = -slon * uX + clon * uY;
+	const uN = -slat * clon * uX - slat * slon * uY + clat * uZ;
+	const uU = clat * clon * uX + clat * slon * uY + slat * uZ;
+	const horizLen = Math.sqrt(fE * fE + fN * fN);
+	const heading = Math.atan2(fE, fN) * RAD_TO_DEG;
+	const pitch = Math.atan2(fU, horizLen) * RAD_TO_DEG;
+	if (horizLen < 1e-9) return [
+		heading,
+		pitch,
+		Math.atan2(uE, uN) * RAD_TO_DEG
+	];
+	const drLen = Math.sqrt(fN * fN + fE * fE);
+	const drE = fN / drLen;
+	const drN = -fE / drLen;
+	const fLen = Math.sqrt(fE * fE + fN * fN + fU * fU);
+	const fnE = fE / fLen, fnN = fN / fLen, fnU = fU / fLen;
+	const duE = drN * fnU;
+	const duN = -drE * fnU;
+	const duU = drE * fnN - drN * fnE;
+	return [
+		heading,
+		pitch,
+		Math.atan2(uE * drE + uN * drN, uE * duE + uN * duN + uU * duU) * RAD_TO_DEG
+	];
 }
+/**
+* Convert local-frame Euler XYZ intrinsic rotation (right-handed, degrees)
+* to Cesium heading/pitch/roll (degrees).
+*
+* Use this when the rotation is already relative to a local frame aligned with
+* ENU (e.g. manual test inputs). For world-frame ECEF rotations from Unreal,
+* use `ecefEulerXyzToHpr` instead — it accounts for the ENU frame at the
+* camera's geographic position.
+*
+* Euler XYZ: rotation[0] around X, [1] around Y, [2] around Z.
+* Decomposed into Cesium HPR via the rotation matrix R = Rz·Ry·Rx.
+*/
 function eulerXyzToHpr(eulerDeg) {
-  const rx = eulerDeg[0] * DEG_TO_RAD;
-  const ry = eulerDeg[1] * DEG_TO_RAD;
-  const rz = eulerDeg[2] * DEG_TO_RAD;
-  const cx = Math.cos(rx), sx = Math.sin(rx);
-  const cy = Math.cos(ry), sy = Math.sin(ry);
-  const cz = Math.cos(rz), sz = Math.sin(rz);
-  const R02 = cx * sy * cz + sx * sz;
-  const R00 = cy * cz;
-  const R01 = sx * sy * cz - cx * sz;
-  const R12 = cx * sy * sz - sx * cz;
-  const R22 = cx * cy;
-  const heading = Math.atan2(R01, R00) * RAD_TO_DEG;
-  const pitch = Math.asin(Math.max(-1, Math.min(1, -R02))) * RAD_TO_DEG;
-  const roll = Math.atan2(-R12, R22) * RAD_TO_DEG;
-  return [heading, pitch, roll];
+	const rx = eulerDeg[0] * DEG_TO_RAD;
+	const ry = eulerDeg[1] * DEG_TO_RAD;
+	const rz = eulerDeg[2] * DEG_TO_RAD;
+	const cx = Math.cos(rx), sx = Math.sin(rx);
+	const cy = Math.cos(ry), sy = Math.sin(ry);
+	const cz = Math.cos(rz), sz = Math.sin(rz);
+	const R02 = cx * sy * cz + sx * sz;
+	const R00 = cy * cz;
+	const R01 = sx * sy * cz - cx * sz;
+	const R12 = cx * sy * sz - sx * cz;
+	const R22 = cx * cy;
+	return [
+		Math.atan2(R01, R00) * RAD_TO_DEG,
+		Math.asin(Math.max(-1, Math.min(1, -R02))) * RAD_TO_DEG,
+		Math.atan2(-R12, R22) * RAD_TO_DEG
+	];
 }
+/**
+* Convert CaptureArgs position [x, y, z] (km from Earth center, ECI-like)
+* to Cesium Cartesian3 (WGS84 meters).
+*
+* The Y axis points to the North Pole, X/Z define the equatorial plane
+* (matching the ZenSpace3D rendering convention after scale correction).
+*
+* Callers sending ECEF meter coordinates (e.g. Unreal Engine) should convert
+* with `ecefMetersToSdkPosition()` before passing to CaptureArgs.
+*/
 function positionToCartesian3(Cesium, position) {
-  const [x, y, z] = position;
-  const r = Math.sqrt(x * x + y * y + z * z);
-  if (r < 1) {
-    return Cesium.Cartesian3.fromDegrees(0, 0, 4e5);
-  }
-  const lat = 90 - Math.acos(Math.min(1, Math.max(-1, y / r))) * RAD_TO_DEG;
-  const lon = Math.atan2(z, -x) * RAD_TO_DEG - 180;
-  const altKm = r - EARTH_RADIUS_KM;
-  return Cesium.Cartesian3.fromDegrees(lon, lat, altKm * 1e3);
+	const [x, y, z] = position;
+	const r = Math.sqrt(x * x + y * y + z * z);
+	if (r < 1) return Cesium.Cartesian3.fromDegrees(0, 0, 4e5);
+	const lat = 90 - Math.acos(Math.min(1, Math.max(-1, y / r))) * RAD_TO_DEG;
+	const lon = Math.atan2(z, -x) * RAD_TO_DEG - 180;
+	const altKm = r - EARTH_RADIUS_KM;
+	return Cesium.Cartesian3.fromDegrees(lon, lat, altKm * 1e3);
 }
+/**
+* Compute the optical field of view from physical sensor parameters.
+*
+* Real satellite cameras derive FOV from:
+*   FOV = 2 × atan( (sensor_size / 2) / focal_length )
+* where sensor_size = resolution × pixel_pitch (mm).
+*
+* Returns the FOV in degrees, or null if the parameters are insufficient
+* (zero focal_length, zero pixel_pitch, or zero resolution).
+*/
 function computeOpticalFov(focalLengthMm, pixelPitchMm, resolutionPx) {
-  if (focalLengthMm <= 0 || pixelPitchMm <= 0 || resolutionPx <= 0) return null;
-  const sensorSizeMm = resolutionPx * pixelPitchMm;
-  return 2 * Math.atan(sensorSizeMm / (2 * focalLengthMm)) * RAD_TO_DEG;
+	if (focalLengthMm <= 0 || pixelPitchMm <= 0 || resolutionPx <= 0) return null;
+	const sensorSizeMm = resolutionPx * pixelPitchMm;
+	return 2 * Math.atan(sensorSizeMm / (2 * focalLengthMm)) * RAD_TO_DEG;
 }
+/**
+* Apply grayscale filter to canvas pixel data in-place.
+* Uses luminance weights (ITU-R BT.709).
+*/
 function applyGrayscale(ctx, width, height) {
-  const imageData = ctx.getImageData(0, 0, width, height);
-  const data = imageData.data;
-  for (let i = 0; i < data.length; i += 4) {
-    const lum = 0.2126 * data[i] + 0.7152 * data[i + 1] + 0.0722 * data[i + 2];
-    data[i] = data[i + 1] = data[i + 2] = lum;
-  }
-  ctx.putImageData(imageData, 0, 0);
+	const imageData = ctx.getImageData(0, 0, width, height);
+	const data = imageData.data;
+	for (let i = 0; i < data.length; i += 4) {
+		const lum = .2126 * data[i] + .7152 * data[i + 1] + .0722 * data[i + 2];
+		data[i] = data[i + 1] = data[i + 2] = lum;
+	}
+	ctx.putImageData(imageData, 0, 0);
 }
+/**
+* Estimate the nadir subject distance in meters from the camera position.
+*
+* The SDK position is in ECI-like coordinates (km). Camera altitude above
+* the Earth surface gives the approximate distance to the ground plane
+* directly below (nadir). For oblique views the actual distance is larger,
+* but nadir is the dominant case for satellite imagery.
+*/
 function estimateSubjectDistanceM(position) {
-  const [x, y, z] = position;
-  const rKm = Math.sqrt(x * x + y * y + z * z);
-  const altKm = Math.max(0, rKm - EARTH_RADIUS_KM);
-  return altKm * 1e3;
+	const [x, y, z] = position;
+	const rKm = Math.sqrt(x * x + y * y + z * z);
+	return Math.max(0, rKm - EARTH_RADIUS_KM) * 1e3;
 }
+/**
+* Compute depth-of-field blur radius in CSS pixels using the thin lens model.
+*
+* Thin lens circle of confusion (CoC) diameter:
+*   c = |f²/N × (S - D) / (D × (S - f))|
+*
+* where:
+*   f = focal length (mm)
+*   N = f-number (aperture)
+*   S = focusing distance (mm) — the plane in sharp focus
+*   D = subject distance (mm) — actual distance to the scene
+*
+* The CoC diameter is converted to pixels via pixel_pitch, then halved to
+* get a blur radius. The result is clamped by the sensor's maximum
+* acceptable CoC (args.coc) to model physical diffraction limits.
+*
+* Returns 0 when the scene is in acceptable focus (blur < 0.5px).
+* Exported for unit testing.
+*/
 function computeDofBlurPx(args, subjectDistanceM) {
-  const fMm = args.focal_length;
-  const N = args.aperture;
-  const sMm = args.focusing_distance * 1e3;
-  const dMm = subjectDistanceM * 1e3;
-  const ppMm = args.pixel_pitch;
-  if (N <= 0 || fMm <= 0 || dMm <= 0 || ppMm <= 0 || sMm <= fMm) return 0;
-  if (Math.abs(sMm - dMm) < 1) return 0;
-  const cocDiameterMm = Math.abs(
-    fMm * fMm / N * (sMm - dMm) / (dMm * (sMm - fMm))
-  );
-  const radiusPx = cocDiameterMm / ppMm / 2;
-  if (radiusPx < 0.5) return 0;
-  return Math.min(radiusPx, args.resolution / 4);
+	const fMm = args.focal_length;
+	const N = args.aperture;
+	const sMm = args.focusing_distance * 1e3;
+	const dMm = subjectDistanceM * 1e3;
+	const ppMm = args.pixel_pitch;
+	if (N <= 0 || fMm <= 0 || dMm <= 0 || ppMm <= 0 || sMm <= fMm) return 0;
+	if (Math.abs(sMm - dMm) < 1) return 0;
+	const radiusPx = Math.abs(fMm * fMm / N * (sMm - dMm) / (dMm * (sMm - fMm))) / ppMm / 2;
+	if (radiusPx < .5) return 0;
+	return Math.min(radiusPx, args.resolution / 4);
 }
+/**
+* Apply Gaussian depth-of-field blur to a 2D canvas context.
+* Uses the native CSS `filter: blur()` for GPU-accelerated performance.
+*
+* The blur is applied by:
+*  1. Drawing the current canvas content onto a temp canvas with blur filter
+*  2. Copying the blurred result back
+*
+* This simulates the optical defocus that occurs when the subject distance
+* doesn't match the focusing distance — exactly what happens when a
+* satellite camera's focus plane is set incorrectly.
+*/
 function applyDofBlur(ctx, width, height, radiusPx) {
-  const tmp = document.createElement("canvas");
-  tmp.width = width;
-  tmp.height = height;
-  const tmpCtx = tmp.getContext("2d");
-  tmpCtx.filter = `blur(${radiusPx}px)`;
-  tmpCtx.drawImage(ctx.canvas, 0, 0);
-  ctx.clearRect(0, 0, width, height);
-  ctx.drawImage(tmp, 0, 0);
+	const tmp = document.createElement("canvas");
+	tmp.width = width;
+	tmp.height = height;
+	const tmpCtx = tmp.getContext("2d");
+	tmpCtx.filter = `blur(${radiusPx}px)`;
+	tmpCtx.drawImage(ctx.canvas, 0, 0);
+	ctx.clearRect(0, 0, width, height);
+	ctx.drawImage(tmp, 0, 0);
 }
+/**
+* Convert a data-URL string to a Uint8Array of the underlying binary data.
+*/
 function dataUrlToBytes(dataUrl) {
-  const base64 = dataUrl.split(",")[1];
-  const binaryStr = atob(base64);
-  const bytes = new Uint8Array(binaryStr.length);
-  for (let i = 0; i < binaryStr.length; i++) {
-    bytes[i] = binaryStr.charCodeAt(i);
-  }
-  return bytes;
+	const base64 = dataUrl.split(",")[1];
+	const binaryStr = atob(base64);
+	const bytes = new Uint8Array(binaryStr.length);
+	for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i);
+	return bytes;
 }
+/**
+* Creates a reusable CesiumJS capture source backed by a hidden viewer.
+*
+* The viewer is initialized once with `preserveDrawingBuffer: true` so
+* canvas pixels survive after `scene.render()`. All Cesium UI widgets
+* are disabled. The container is positioned off-screen (1x1 px) and
+* resized to the requested resolution on each capture.
+*
+* @param options - Configuration for the hidden viewer
+* @returns Handle with `capture(args)`, `destroy()`, and `ready` flag
+*/
 async function createCesiumCaptureSource(options = {}) {
-  const Cesium = await import("cesium");
-  if (options.accessToken) {
-    Cesium.Ion.defaultAccessToken = options.accessToken;
-  }
-  let container = options.container ?? null;
-  let ownsContainer = false;
-  if (!container) {
-    container = document.createElement("div");
-    container.style.cssText = "position:fixed;left:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(100%);pointer-events:none;z-index:-1;";
-    document.body.appendChild(container);
-    ownsContainer = true;
-  }
-  const viewer = new Cesium.Viewer(container, {
-    baseLayerPicker: false,
-    fullscreenButton: false,
-    vrButton: false,
-    geocoder: false,
-    homeButton: false,
-    sceneModePicker: false,
-    timeline: false,
-    navigationHelpButton: false,
-    animation: false,
-    scene3DOnly: true,
-    // Only render when we explicitly call scene.render()
-    useDefaultRenderLoop: false,
-    requestRenderMode: true,
-    contextOptions: {
-      webgl: { preserveDrawingBuffer: true }
-    }
-  });
-  viewer.scene.globe.enableLighting = false;
-  viewer.scene.backgroundColor = Cesium.Color.BLACK;
-  viewer.scene.skyBox = void 0;
-  viewer.scene.moon = void 0;
-  const useOsm = options.useOpenStreetMapImagery !== false;
-  if (useOsm) {
-    viewer.imageryLayers.removeAll();
-    const tileUrl = options.imageryUrl || "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}";
-    viewer.imageryLayers.addImageryProvider(
-      new Cesium.UrlTemplateImageryProvider({
-        url: tileUrl,
-        credit: "© Esri, Maxar, Earthstar Geographics",
-        maximumLevel: 19
-      })
-    );
-  }
-  if (options.terrain && options.accessToken) {
-    try {
-      viewer.scene.terrainProvider = await Cesium.CesiumTerrainProvider.fromIonAssetId(1);
-    } catch {
-    }
-  }
-  let destroyed = false;
-  const capture = async (args) => {
-    var _a;
-    if (destroyed) return new Uint8Array(0);
-    try {
-      const res = args.sample ? Math.max(64, Math.round(args.resolution / 2)) : args.resolution;
-      container.style.width = `${res}px`;
-      container.style.height = `${res}px`;
-      void container.clientWidth;
-      viewer.resize();
-      await new Promise((r) => requestAnimationFrame(() => r()));
-      await new Promise((r) => requestAnimationFrame(() => r()));
-      viewer.resize();
-      const cameraPosition = positionToCartesian3(Cesium, args.position);
-      const [heading, pitch, roll] = args.rotation;
-      viewer.camera.setView({
-        destination: cameraPosition,
-        orientation: {
-          heading: Cesium.Math.toRadians(heading),
-          pitch: Cesium.Math.toRadians(pitch),
-          roll: Cesium.Math.toRadians(roll)
-        }
-      });
-      const opticalFov = computeOpticalFov(args.focal_length, args.pixel_pitch, args.resolution);
-      let effectiveFov = args.fov;
-      if (effectiveFov <= 0 || effectiveFov >= 180) {
-        if (opticalFov !== null && opticalFov > 0 && opticalFov < 180) {
-          effectiveFov = opticalFov;
-          if (false) ;
-        }
-      } else if (false) ;
-      if (effectiveFov > 0 && effectiveFov < 180) {
-        viewer.camera.frustum.fov = effectiveFov * DEG_TO_RAD;
-      }
-      const maxWaitMs = options.tileLoadTimeoutMs ?? 1e4;
-      const pollIntervalMs = 200;
-      const startMs = performance.now();
-      const deadline = startMs + maxWaitMs;
-      viewer.scene.requestRender();
-      viewer.scene.forceRender();
-      let tileWaitLoops = 0;
-      while (!viewer.scene.globe.tilesLoaded && performance.now() < deadline) {
-        tileWaitLoops++;
-        (_a = options.onTileLoadProgress) == null ? void 0 : _a.call(options, performance.now() - startMs);
-        await new Promise((r) => setTimeout(r, pollIntervalMs));
-        viewer.scene.requestRender();
-        viewer.scene.forceRender();
-      }
-      viewer.scene.requestRender();
-      viewer.scene.forceRender();
-      await new Promise((r) => requestAnimationFrame(() => r()));
-      viewer.scene.requestRender();
-      viewer.scene.forceRender();
-      await new Promise((r) => requestAnimationFrame(() => r()));
-      viewer.scene.forceRender();
-      const canvas = viewer.scene.canvas;
-      if (false) ;
-      if (false) ;
-      const fmt = args.format === "jpeg" ? "image/jpeg" : "image/png";
-      const jpegQuality = args.format === "jpeg" ? args.jpeg_quality ?? 0.92 : void 0;
-      let dofBlurRadius = 0;
-      if (args.focusing_distance > 0 && args.aperture > 0) {
-        const subjectDist = estimateSubjectDistanceM(args.position);
-        dofBlurRadius = computeDofBlurPx(args, subjectDist);
-      }
-      const needsOffscreen = dofBlurRadius > 0 || args.monochromatic;
-      if (needsOffscreen) {
-        const offscreen = document.createElement("canvas");
-        offscreen.width = canvas.width;
-        offscreen.height = canvas.height;
-        const ctx = offscreen.getContext("2d");
-        ctx.drawImage(canvas, 0, 0);
-        if (dofBlurRadius > 0) {
-          applyDofBlur(ctx, offscreen.width, offscreen.height, dofBlurRadius);
-          if (false) ;
-        }
-        if (args.monochromatic) {
-          applyGrayscale(ctx, offscreen.width, offscreen.height);
-        }
-        const dataUrl2 = jpegQuality !== void 0 ? offscreen.toDataURL(fmt, jpegQuality) : offscreen.toDataURL(fmt);
-        return dataUrlToBytes(dataUrl2);
-      }
-      const dataUrl = jpegQuality !== void 0 ? canvas.toDataURL(fmt, jpegQuality) : canvas.toDataURL(fmt);
-      return dataUrlToBytes(dataUrl);
-    } catch (err) {
-      return loadPlaceholderFallback();
-    }
-  };
-  const destroy = () => {
-    if (destroyed) return;
-    destroyed = true;
-    try {
-      viewer.destroy();
-    } catch {
-    }
-    if (ownsContainer && container && container.parentNode) {
-      container.parentNode.removeChild(container);
-    }
-  };
-  return {
-    capture,
-    destroy,
-    get ready() {
-      return !destroyed;
-    }
-  };
+	const Cesium = await import("cesium");
+	if (options.accessToken) Cesium.Ion.defaultAccessToken = options.accessToken;
+	let container = options.container ?? null;
+	let ownsContainer = false;
+	if (!container) {
+		container = document.createElement("div");
+		container.style.cssText = "position:fixed;left:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(100%);pointer-events:none;z-index:-1;";
+		document.body.appendChild(container);
+		ownsContainer = true;
+	}
+	const viewer = new Cesium.Viewer(container, {
+		baseLayerPicker: false,
+		fullscreenButton: false,
+		vrButton: false,
+		geocoder: false,
+		homeButton: false,
+		sceneModePicker: false,
+		timeline: false,
+		navigationHelpButton: false,
+		animation: false,
+		scene3DOnly: true,
+		useDefaultRenderLoop: false,
+		requestRenderMode: true,
+		contextOptions: { webgl: { preserveDrawingBuffer: true } }
+	});
+	viewer.scene.globe.enableLighting = false;
+	viewer.scene.backgroundColor = Cesium.Color.BLACK;
+	viewer.scene.skyBox = void 0;
+	viewer.scene.moon = void 0;
+	if (options.useOpenStreetMapImagery !== false) {
+		viewer.imageryLayers.removeAll();
+		const tileUrl = options.imageryUrl || "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}";
+		viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({
+			url: tileUrl,
+			credit: "© Esri, Maxar, Earthstar Geographics",
+			maximumLevel: 19
+		}));
+	}
+	if (options.terrain && options.accessToken) try {
+		viewer.scene.terrainProvider = await Cesium.CesiumTerrainProvider.fromIonAssetId(1);
+	} catch {}
+	let destroyed = false;
+	const capture = async (args) => {
+		if (destroyed) return /* @__PURE__ */ new Uint8Array(0);
+		try {
+			const res = args.sample ? Math.max(64, Math.round(args.resolution / 2)) : args.resolution;
+			container.style.width = `${res}px`;
+			container.style.height = `${res}px`;
+			container.clientWidth;
+			viewer.resize();
+			await new Promise((r) => requestAnimationFrame(() => r()));
+			await new Promise((r) => requestAnimationFrame(() => r()));
+			viewer.resize();
+			const cameraPosition = positionToCartesian3(Cesium, args.position);
+			const [heading, pitch, roll] = args.rotation;
+			viewer.camera.setView({
+				destination: cameraPosition,
+				orientation: {
+					heading: Cesium.Math.toRadians(heading),
+					pitch: Cesium.Math.toRadians(pitch),
+					roll: Cesium.Math.toRadians(roll)
+				}
+			});
+			const opticalFov = computeOpticalFov(args.focal_length, args.pixel_pitch, args.resolution);
+			let effectiveFov = args.fov;
+			if (effectiveFov <= 0 || effectiveFov >= 180) {
+				if (opticalFov !== null && opticalFov > 0 && opticalFov < 180) effectiveFov = opticalFov;
+			}
+			if (effectiveFov > 0 && effectiveFov < 180) viewer.camera.frustum.fov = effectiveFov * DEG_TO_RAD;
+			const maxWaitMs = options.tileLoadTimeoutMs ?? 1e4;
+			const pollIntervalMs = 200;
+			const startMs = performance.now();
+			const deadline = startMs + maxWaitMs;
+			viewer.scene.requestRender();
+			viewer.scene.forceRender();
+			let tileWaitLoops = 0;
+			while (!viewer.scene.globe.tilesLoaded && performance.now() < deadline) {
+				tileWaitLoops++;
+				options.onTileLoadProgress?.(performance.now() - startMs);
+				await new Promise((r) => setTimeout(r, pollIntervalMs));
+				viewer.scene.requestRender();
+				viewer.scene.forceRender();
+			}
+			viewer.scene.requestRender();
+			viewer.scene.forceRender();
+			await new Promise((r) => requestAnimationFrame(() => r()));
+			viewer.scene.requestRender();
+			viewer.scene.forceRender();
+			await new Promise((r) => requestAnimationFrame(() => r()));
+			viewer.scene.forceRender();
+			const canvas = viewer.scene.canvas;
+			const fmt = args.format === "jpeg" ? "image/jpeg" : "image/png";
+			const jpegQuality = args.format === "jpeg" ? args.jpeg_quality ?? .92 : void 0;
+			let dofBlurRadius = 0;
+			if (args.focusing_distance > 0 && args.aperture > 0) dofBlurRadius = computeDofBlurPx(args, estimateSubjectDistanceM(args.position));
+			if (dofBlurRadius > 0 || args.monochromatic) {
+				const offscreen = document.createElement("canvas");
+				offscreen.width = canvas.width;
+				offscreen.height = canvas.height;
+				const ctx = offscreen.getContext("2d");
+				ctx.drawImage(canvas, 0, 0);
+				if (dofBlurRadius > 0) applyDofBlur(ctx, offscreen.width, offscreen.height, dofBlurRadius);
+				if (args.monochromatic) applyGrayscale(ctx, offscreen.width, offscreen.height);
+				return dataUrlToBytes(jpegQuality !== void 0 ? offscreen.toDataURL(fmt, jpegQuality) : offscreen.toDataURL(fmt));
+			}
+			return dataUrlToBytes(jpegQuality !== void 0 ? canvas.toDataURL(fmt, jpegQuality) : canvas.toDataURL(fmt));
+		} catch (err) {
+			return loadPlaceholderFallback();
+		}
+	};
+	const destroy = () => {
+		if (destroyed) return;
+		destroyed = true;
+		try {
+			viewer.destroy();
+		} catch {}
+		if (ownsContainer && container && container.parentNode) container.parentNode.removeChild(container);
+	};
+	return {
+		capture,
+		destroy,
+		get ready() {
+			return !destroyed;
+		}
+	};
 }
-export {
-  computeDofBlurPx,
-  createCesiumCaptureSource,
-  ecefEulerXyzToHpr,
-  ecefMetersToSdkPosition,
-  eulerXyzToHpr
-};
-//# sourceMappingURL=CesiumCaptureSource.js.map
+//#endregion
+export { computeDofBlurPx, createCesiumCaptureSource, ecefEulerXyzToHpr, ecefMetersToSdkPosition, eulerXyzToHpr };
+
+//# sourceMappingURL=CesiumCaptureSource.js.map