Skip to content

A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.

8.4 KB
Raw Blame
/**
 * Draped-imagery renderer for the Recent Imagery layer: at most two GIBS
 * imagery layers (slot `a`, left of a swipe; slot `b`, right) on whichever
 * host the map stack offers. Against the basemap slot `a` splits left and
 * slot `b` stays empty. Every layer is removed from the collection that owns it, so a
 * host switch or a replaced image never strands one. Tile requests pass a
 * small semaphore of our own; Cesium's global request limits stay untouched.
 */
import * as Cesium from 'cesium';
import { PRODUCTS, gibsTemplate } from './model.js';

const SLOT_IDS = ['a', 'b'];
const SPLIT_ENUM = { left: 'LEFT', right: 'RIGHT', none: 'NONE' };
const NO_HOST = Object.freeze({ collection: null, kind: 'none' });

/** Render reason for a deferred or settled tile request. */
export const TILE_RENDER_REASON = 'recent-imagery-tiles';
/** Delay before the one frame that retries tiles Cesium itself deferred. */
export const TILE_RETRY_DELAY_MS = 250;

function clampAlpha(value) {
  const alpha = Number(value);
  return Number.isFinite(alpha) ? Math.max(0, Math.min(1, alpha)) : 1;
}

const boxKey = (box) =>
  [box.west, box.south, box.east, box.north].map(Number).join(',');

/**
 * Gate a provider's `requestImage` through the semaphore. Returning
 * `undefined` tells Cesium to retry on a later frame, but under
 * `requestRenderMode` there is no later frame unless something asks — and a
 * deferral must never ask for one itself: the retried tile would defer again
 * and ask again, keeping the scene rendering every frame. So a request that
 * finds our semaphore full asks for nothing (the request holding the slot
 * asks for one frame when it settles), and a request the provider itself
 * deferred goes through the one coalesced delayed retry.
 */
function admitTileRequests(provider, admission, requestRender, retry) {
  const original = provider.requestImage.bind(provider);
  provider.requestImage = (x, y, level, request) => {
    if (admission.inFlight >= admission.limit) return undefined;
    admission.inFlight += 1;
    const release = () => {
      admission.inFlight -= 1;
    };
    let promise;
    try {
      promise = original(x, y, level, request);
    } catch (error) {
      release();
      throw error;
    }
    if (!promise) {
      release();
      retry.schedule();
      return undefined;
    }
    return Promise.resolve(promise).finally(() => {
      release();
      requestRender(TILE_RENDER_REASON);
    });
  };
  return provider;
}

/**
 * Create the renderer.
 * @param {{ cesium?: object, maxTileRequests?: number, requestRender?: (reason: string) => void, setTimeoutImpl?: Function, clearTimeoutImpl?: Function }} [options]
 */
export function createRecentImageryRenderer({
  cesium = Cesium,
  tileTemplate = gibsTemplate,
  credit = 'NASA GIBS',
  maxTileRequests = 6,
  requestRender = () => {},
  setTimeoutImpl = (fn, ms) => globalThis.setTimeout(fn, ms),
  clearTimeoutImpl = (id) => globalThis.clearTimeout(id),
} = {}) {
  let host = NO_HOST;
  let destroyed = false;
  const admission = { limit: maxTileRequests, inFlight: 0 };
  /** @type {Record<'a'|'b', null | { layer: object, collection: object, candidate: object, box: object, alpha: number, split: string }>} */
  const owned = { a: null, b: null };

  // One timer for both slots: any number of upstream deferrals while it is
  // armed share the same single retry frame.
  let retryTimer = null;
  const retry = {
    schedule() {
      if (retryTimer !== null) return;
      retryTimer = setTimeoutImpl(() => {
        retryTimer = null;
        if (!destroyed) requestRender(TILE_RENDER_REASON);
      }, TILE_RETRY_DELAY_MS);
    },
    cancel() {
      if (retryTimer !== null) clearTimeoutImpl(retryTimer);
      retryTimer = null;
    },
  };

  function createProvider(candidate, box) {
    const spec = PRODUCTS[candidate.product];
    const provider = new cesium.UrlTemplateImageryProvider({
      url: tileTemplate(candidate.product, candidate.day),
      subdomains: ['a', 'b', 'c'],
      minimumLevel: 0,
      maximumLevel: spec.maxLevel,
      tilingScheme: new cesium.WebMercatorTilingScheme(),
      rectangle: cesium.Rectangle.fromDegrees(
        box.west,
        box.south,
        box.east,
        box.north,
      ),
      credit,
      hasAlphaChannel: spec.format === 'png',
    });
    return admitTileRequests(provider, admission, requestRender, retry);
  }

  function removeOwned(slotId) {
    const record = owned[slotId];
    if (!record) return false;
    owned[slotId] = null;
    try {
      record.collection.remove(record.layer, true);
    } catch {
      /* the collection is already gone */
    }
    return true;
  }

  function applyLook(record) {
    record.layer.alpha = record.alpha;
    record.layer.splitDirection =
      cesium.SplitDirection?.[SPLIT_ENUM[record.split] || 'NONE'] ?? 0;
  }

  function mount(slotId, { candidate, box, alpha, split }) {
    const layer = host.collection.addImageryProvider(
      createProvider(candidate, box),
    );
    owned[slotId] = {
      layer,
      collection: host.collection,
      candidate,
      box,
      alpha,
      split,
    };
    applyLook(owned[slotId]);
  }

  return {
    /**
     * Drape a candidate into a slot. The same candidate on the same host only
     * updates its look; anything else replaces the slot's layer.
     * @param {'a'|'b'} slotId
     * @param {object} candidate
     * @param {object} box Degrees box.
     * @param {{ alpha?: number, splitDirection?: 'left'|'right'|'none' }} [look]
     * @returns {boolean} Whether a layer is now draped for the slot.
     */
    showSlot(
      slotId,
      candidate,
      box,
      { alpha = 1, splitDirection = 'none' } = {},
    ) {
      if (destroyed || !candidate?.key || !box) return false;
      if (!host.collection) {
        removeOwned(slotId);
        return false;
      }
      const current = owned[slotId];
      const look = { alpha: clampAlpha(alpha), split: splitDirection };
      if (
        current &&
        current.collection === host.collection &&
        current.candidate.key === candidate.key &&
        boxKey(current.box) === boxKey(box)
      ) {
        if (current.alpha !== look.alpha || current.split !== look.split) {
          Object.assign(current, look);
          applyLook(current);
          requestRender('recent-imagery-look');
        }
        return true;
      }
      removeOwned(slotId);
      mount(slotId, { candidate, box, ...look });
      requestRender('recent-imagery-show');
      return true;
    },

    /** @param {'a'|'b'} slotId */
    hideSlot(slotId) {
      if (removeOwned(slotId)) requestRender('recent-imagery-hide');
    },

    /**
     * @param {'a'|'b'} slotId
     * @param {number} alpha 0–1
     */
    setAlpha(slotId, alpha) {
      const record = owned[slotId];
      const next = clampAlpha(alpha);
      if (!record || record.alpha === next) return;
      record.alpha = next;
      applyLook(record);
      requestRender('recent-imagery-alpha');
    },

    /**
     * Move every owned layer to a new host. Layers are rebuilt there, never
     * re-parented, so the old collection is left as it was found.
     * @param {{ collection: object | null, kind: string }} nextHost
     */
    rebind(nextHost) {
      host = nextHost || NO_HOST;
      let changed = false;
      for (const slotId of SLOT_IDS) {
        const record = owned[slotId];
        if (!record || record.collection === host.collection) continue;
        removeOwned(slotId);
        changed = true;
        if (host.collection && !destroyed) mount(slotId, record);
      }
      if (changed) requestRender('recent-imagery-rebind');
    },

    /** What is draped right now, per slot. */
    getOwned() {
      const out = {};
      for (const slotId of SLOT_IDS) {
        const record = owned[slotId];
        out[slotId] = record
          ? {
              key: record.candidate.key,
              kind: host.kind,
              alpha: record.alpha,
              split: record.split,
            }
          : null;
      }
      return out;
    },

    /** Number of layers this renderer owns (never above two). */
    ownedCount() {
      return SLOT_IDS.filter((slotId) => owned[slotId]).length;
    },

    /** Remove everything and refuse further work. */
    destroy() {
      if (destroyed) return;
      destroyed = true;
      retry.cancel();
      let changed = false;
      for (const slotId of SLOT_IDS) changed = removeOwned(slotId) || changed;
      host = NO_HOST;
      if (changed) requestRender('recent-imagery-destroy');
    },
  };
}