Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
13.0 KB
Raw Blame
/**
 * What Difference is allowed to read, and the settings it reads with.
 *
 * A pixel difference is only worth showing when both pictures come from one
 * rendering chain: a highlighted provider or style difference would otherwise
 * pass for a change on the ground. `changeCompatibility` answers that before
 * anything is computed, and grades a fair pair as `matched` (one product, one
 * render) or `indicative` (one chain, but something the analyst should keep in
 * mind). It also names the `family` behind the pair, which decides two things a
 * picture cannot answer on its own: whether Sentinel-2's sky classification can
 * be fetched for the cloud filter, and whether matching tones is honest.
 *
 * The detection itself lives in `changeDetect.js` and runs in a worker.
 */

import { RADAR_ID, sameTrack } from '../radar.js';

const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);

export const CHANGE_METHODS = Object.freeze([
  { id: 'colour', label: 'Colour', hint: 'Perceptual colour distance. The general reading.' },
  { id: 'structure', label: 'Structure', hint: 'Edges that appear or vanish. Steadier across seasons and sensors.' },
  { id: 'brightness', label: 'Brightness', hint: 'Lighter or darker only. Suits night lights and burn scars.' },
  { id: 'index', label: 'Spectral index', hint: 'Real Sentinel-2 bands for both dates, fetched on demand.' },
]);

// The same six indices Detect measures, so a reading here and a sweep there
// speak of one quantity.
export const CHANGE_INDICES = Object.freeze([
  { id: 'ndvi', label: 'NDVI', hint: 'Vegetation', gain: 'Greener', loss: 'Vegetation lost' },
  { id: 'ndwi', label: 'NDWI', hint: 'Water', gain: 'Wetter', loss: 'Water receded' },
  { id: 'mndwi', label: 'MNDWI', hint: 'Water, past built-up land', gain: 'Wetter', loss: 'Water receded' },
  { id: 'nbr', label: 'NBR', hint: 'Burn scars', gain: 'Recovered', loss: 'Burnt' },
  { id: 'ndbi', label: 'NDBI', hint: 'Built-up', gain: 'Built or cleared', loss: 'Less built-up' },
  { id: 'bsi', label: 'BSI', hint: 'Bare soil', gain: 'Barer', loss: 'Covered' },
]);

// How far an index has to move to count, at the sensitivity either end. The
// published marks sit mid-scale: 0.27 for a burn ratio, 0.25 for vegetation
// lost. Detect scales the same way, so both modes draw one line.
export const INDEX_CHANGE = Object.freeze({ loosest: 0.05, strictest: 0.5 });

export const indexThreshold = (sensitivity) =>
  INDEX_CHANGE.loosest + (INDEX_CHANGE.strictest - INDEX_CHANGE.loosest) * (1 - sensitivity / 100);

export const CHANGE_DISPLAYS = Object.freeze([
  { id: 'classes', label: 'Classes' },
  { id: 'heat', label: 'Heat' },
  { id: 'outline', label: 'Outline' },
]);

export const CHANGE_PALETTES = Object.freeze({
  // Cyan and magenta are rare on the ground, so they stand out over soil,
  // vegetation and roofs alike, where green and red sank into them.
  directional: Object.freeze({
    gain: [0, 229, 255],
    loss: [255, 0, 170],
    changed: [255, 221, 0],
  }),
  // Okabe-Ito hues: distinguishable under the common red/green deficiencies.
  colourblind: Object.freeze({
    gain: [0, 114, 178],
    loss: [230, 159, 0],
    changed: [204, 121, 167],
  }),
  // Direction still reads through hue, but the three sit on one warm ramp so a
  // heat display stays legible over green vegetation and blue water.
  thermal: Object.freeze({
    gain: [255, 214, 10],
    loss: [120, 40, 200],
    changed: [255, 120, 30],
  }),
});

export const CHANGE_CLASSES = Object.freeze(['gain', 'loss', 'changed']);

/**
 * Which images carry the highlights, whatever view mode the pair is read in.
 * Both is the default: "change from what into what" needs the two pictures.
 */
export const CHANGE_BASES = Object.freeze([
  { id: 'a', label: 'A' },
  { id: 'b', label: 'B' },
  { id: 'both', label: 'Both' },
]);

export const CHANGE_DEFAULTS = Object.freeze({
  method: 'colour',
  index: 'ndvi',
  threshold: 'auto',
  sensitivity: 70,
  normalize: 'auto',
  smoothing: 1,
  alignment: 4,
  cleanup: 1,
  min_area: 0,
  ignore_clouds: false,
  ignore_shadows: false,
  // A cloud fades out at its edges and its shadow has no edge at all, so the
  // mask stops short of where a reader would put the cloud. Growing it takes
  // the fringe that otherwise survives as a ring of highlights around the mask.
  // In ground metres, because this reading follows the camera.
  cloud_margin: 50,
  classes: ['gain', 'loss', 'changed'],
  display: 'classes',
  palette: 'directional',
  zones: true,
  opacity: 70,
  base: 'both',
  blink: false,
});

const pick = (value, allowed, fallback) => (allowed.includes(value) ? value : fallback);
const whole = (value, min, max, fallback) => {
  const number = Number(value);
  return Number.isFinite(number) ? Math.min(max, Math.max(min, Math.round(number))) : fallback;
};

/** Every setting inside its range, whatever a saved session or a slider held. */
export function changeSettings(raw = {}) {
  const value = raw && typeof raw === 'object' ? raw : {};
  const classes = Array.isArray(value.classes)
    ? CHANGE_CLASSES.filter((entry) => value.classes.includes(entry))
    : [...CHANGE_DEFAULTS.classes];
  const area = Number(value.min_area);
  return {
    method: pick(value.method, CHANGE_METHODS.map((entry) => entry.id), CHANGE_DEFAULTS.method),
    index: pick(value.index, CHANGE_INDICES.map((entry) => entry.id), CHANGE_DEFAULTS.index),
    threshold: pick(value.threshold, ['auto', 'manual'], CHANGE_DEFAULTS.threshold),
    sensitivity: whole(value.sensitivity, 0, 100, CHANGE_DEFAULTS.sensitivity),
    normalize: pick(value.normalize, ['auto', 'none', 'mean', 'histogram'], CHANGE_DEFAULTS.normalize),
    smoothing: whole(value.smoothing, 0, 4, CHANGE_DEFAULTS.smoothing),
    alignment: whole(value.alignment, 0, 8, CHANGE_DEFAULTS.alignment),
    cleanup: whole(value.cleanup, 0, 3, CHANGE_DEFAULTS.cleanup),
    min_area: Number.isFinite(area) ? Math.min(1_000_000, Math.max(0, area)) : 0,
    ignore_clouds: value.ignore_clouds ?? CHANGE_DEFAULTS.ignore_clouds,
    ignore_shadows: value.ignore_shadows ?? CHANGE_DEFAULTS.ignore_shadows,
    cloud_margin: whole(value.cloud_margin, 0, 200, CHANGE_DEFAULTS.cloud_margin),
    classes,
    display: pick(value.display, CHANGE_DISPLAYS.map((entry) => entry.id), CHANGE_DEFAULTS.display),
    palette: pick(value.palette, Object.keys(CHANGE_PALETTES), CHANGE_DEFAULTS.palette),
    zones: value.zones ?? CHANGE_DEFAULTS.zones,
    opacity: whole(value.opacity, 0, 100, CHANGE_DEFAULTS.opacity),
    base: pick(value.base, CHANGE_BASES.map((entry) => entry.id), CHANGE_DEFAULTS.base),
    blink: value.blink === true,
  };
}

/**
 * A side as a reading sees it: its picture, and its night lights when they are
 * on, never the layers laid over it. What a reading is keyed on, so switching a
 * layer leaves the highlights up to date.
 */
export function readSide(side) {
  const { overlays = [], firms: _firms, nightlights, ...picture } = side;
  const night = overlays.includes('nightlights');
  return { ...picture, overlays: night ? ['nightlights'] : [], nightlights: night ? nightlights : null };
}

const refuse = (reason) => ({ ok: false, reason, methods: [], clouds: false });
const PIXEL_METHODS = ['colour', 'structure', 'brightness'];
const ESRI = new Set(['esri-world-imagery', 'esri-wayback']);

/**
 * Whether a pixel reading of this pair is honest, and how much to trust it.
 *
 * The layers laid over either side play no part: Difference reads the picture
 * alone (`snapshot`'s `keep` in `facade.js`), so a layer may stay on A and not
 * on B. Night lights are the one overlay it reads, when they are the picture.
 *
 * @returns {{ ok: boolean, reason?: string, grade?: 'matched'|'indicative',
 *   label?: string, from?: string, to?: string, notes?: string[], methods: string[] }}
 */
export function changeCompatibility(a, b) {
  if (!a?.present || !b?.present) return refuse('Add imagery A and B first.');
  if (a.widget || b.widget) {
    return refuse('Difference needs app-rendered pixels, not a web map widget.');
  }

  if (a.provider === 'sentinel2' && b.provider === 'sentinel2') {
    const dateA = a.sentinel?.effectiveDate || a.sentinel?.date;
    const dateB = b.sentinel?.effectiveDate || b.sentinel?.date;
    if (!dateA || !dateB || dateA === dateB) {
      return refuse('Choose two different dated Sentinel-2 passes.');
    }
    const notes = [];
    const methods = ['index'];
    if (a.sentinel?.layer === b.sentinel?.layer) {
      methods.unshift(...PIXEL_METHODS);
    } else {
      notes.push('Pixel methods need the same Sentinel-2 layer on A and B.');
    }
    if (a.sentinel?.maxcc !== b.sentinel?.maxcc) {
      notes.push('A and B use different cloud ceilings.');
    }
    return {
      ok: true,
      family: 'sentinel2',
      // Sentinel-2 carries its own scene classification, so cloud and shadow
      // are read rather than guessed — the one family where the filter is offered.
      clouds: true,
      grade: notes.length ? 'indicative' : 'matched',
      label: `Sentinel-2 · ${String(a.sentinel.layer).replace(/_/g, ' ')}`,
      from: dateA,
      to: dateB,
      notes,
      methods,
    };
  }

  if (a.provider === RADAR_ID && b.provider === RADAR_ID) {
    const passA = a.radar ?? {};
    const passB = b.radar ?? {};
    if (!passA.date || !passB.date) return refuse('Choose a dated Sentinel-1 pass on both sides.');
    if (passA.date === passB.date && passA.time === passB.time) {
      return refuse('Choose two different Sentinel-1 passes.');
    }
    // Another track sees the ground from another angle, and that difference is
    // not change. The picker marks the passes on the other side's track.
    if (!sameTrack(passA.time, passB.time)) {
      return refuse('Radar compares two passes of one track. Pick passes at the same time of day.');
    }
    return {
      ok: true,
      family: 'sentinel1',
      clouds: false,
      grade: 'indicative',
      label: 'Sentinel-1 radar',
      from: passA.date,
      to: passB.date,
      notes: ['Reads the radar picture, not the backscatter.'],
      methods: PIXEL_METHODS,
    };
  }

  if (ESRI.has(a.provider) && ESRI.has(b.provider)) {
    const releaseA = a.provider === 'esri-wayback' ? a.waybackRelease : 'current';
    const releaseB = b.provider === 'esri-wayback' ? b.waybackRelease : 'current';
    if (a.provider === b.provider && releaseA === releaseB) {
      // Not "Difference needs two Esri releases": it reads Sentinel-2 passes and
      // VIIRS nights too, and a refusal that named one road sent analysts looking
      // for a second Wayback release they did not need.
      return refuse('Both sides show the same picture. Pick another Esri release, or two dated Sentinel-2 passes.');
    }
    const mixed = a.provider !== b.provider;
    return {
      ok: true,
      family: 'esri',
      clouds: false,
      grade: mixed ? 'indicative' : 'matched',
      label: mixed ? 'Esri World Imagery and Wayback' : 'Esri Wayback',
      from: releaseA == null ? 'latest' : String(releaseA),
      to: releaseB == null ? 'latest' : String(releaseB),
      notes: [
        ...(mixed ? ['World Imagery’s date varies by place.'] : []),
        'Releases share pixels, so no highlight is no proof.',
      ],
      methods: PIXEL_METHODS,
    };
  }

  const nightA = (a.overlays ?? []).includes('nightlights');
  const nightB = (b.overlays ?? []).includes('nightlights');
  if (nightA && nightB) {
    if (a.provider !== b.provider) {
      return refuse('Night lights need the same background imagery on A and B.');
    }
    if (a.nightlights?.source !== b.nightlights?.source) {
      return refuse('Night lights need the same VIIRS product on A and B.');
    }
    if (a.nightlights?.source === 'composite') {
      return refuse('The night-light composite has one date only.');
    }
    if (!a.nightlights?.day || !b.nightlights?.day || a.nightlights.day === b.nightlights.day) {
      return refuse('Choose two different nights from the same VIIRS sensor.');
    }
    if (!same(a.sentinel, b.sentinel) || a.waybackRelease !== b.waybackRelease) {
      return refuse('Match the background imagery on A and B before comparing night lights.');
    }
    return {
      ok: true,
      family: 'viirs',
      clouds: false,
      grade: 'matched',
      label: `VIIRS · ${a.nightlights.source === 'noaa20' ? 'NOAA-20' : 'Suomi NPP'}`,
      from: a.nightlights.day,
      to: b.nightlights.day,
      notes: ['Moon and cloud sway one night. Compare several.'],
      methods: ['brightness', 'colour'],
    };
  }

  return refuse('Difference reads Sentinel-2 passes, Esri releases or VIIRS night lights.');
}

/**
 * Whether a reading needs Sentinel-2 bands, which are fetched and metered.
 *
 * A spectral index is nothing but bands. The cloud filter over the picture
 * methods needs the scene classification behind them, which is one small frame
 * a side. The reading still follows the camera on the frames already held; what
 * it will not do is spend a request on a pan.
 */
export function changeNeedsFrames(settings, status) {
  if (settings.method === 'index') return 'index';
  const filtered = settings.ignore_clouds || settings.ignore_shadows;
  return status?.clouds && filtered ? 'sky' : '';
}