The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* 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' : '';
}