The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* Analyzers of your own: a list of rules, read the way the engine reads them
* (engine/detect_rules.py). A rule is a quantity, the date it is read on (the
* before pass, the after pass, or the change from one to the other) and the
* line it has to cross. Values travel in the engine's units: an index from -1
* to 1, reflectance from 0 to 1, radar in decibels. Only the words and the
* sliders here show reflectance in percent.
*
* The engine names the two passes A and B, and so do the saved recipes; the
* words here are Before and After, which is what they are to someone building
* a rule. An analyzer declares when it is made which satellite it reads and
* whether it judges one date or the change between two (`sensor`, `dates`).
*/
import { CHANGE_INDICES, indexThreshold } from './changeAssist.js';
const MEASURES = Object.freeze([
{ id: 'index', label: 'Index', hint: 'A published spectral index.' },
{ id: 'nd', label: 'My index', hint: 'Two bands of your choice: (first − second) / (first + second).' },
{ id: 'band', label: 'Band', hint: 'One band’s reflectance.' },
{ id: 'brightness', label: 'Brightness', hint: 'The visible bands, averaged.' },
{ id: 'colour', label: 'Colour change', hint: 'How far the visible bands moved together.' },
{ id: 'class', label: 'Ground class', hint: 'Sentinel-2’s own classification of the ground.' },
{ id: 'radar', label: 'Radar', hint: 'Sentinel-1 backscatter, through cloud and at night.' },
]);
export const INDICES = CHANGE_INDICES;
export const BAND_NAMES = Object.freeze({
B01: 'coastal', B02: 'blue', B03: 'green', B04: 'red', B05: 'red edge 1', B06: 'red edge 2',
B07: 'red edge 3', B08: 'near infrared', B8A: 'narrow near infrared', B09: 'water vapour',
B11: 'short-wave 1.6 µm', B12: 'short-wave 2.2 µm',
});
/** Normalised differences worth a name, offered as a start for My index. */
export const PAIRS = Object.freeze([
{ id: 'ndmi', label: 'NDMI', hint: 'Moisture', bands: ['B8A', 'B11'] },
{ id: 'ndsi', label: 'NDSI', hint: 'Snow', bands: ['B03', 'B11'] },
{ id: 'ndre', label: 'NDRE', hint: 'Red edge', bands: ['B8A', 'B05'] },
{ id: 'nbr2', label: 'NBR2', hint: 'Burns and dry soil', bands: ['B11', 'B12'] },
{ id: 'gndvi', label: 'GNDVI', hint: 'Chlorophyll', bands: ['B08', 'B03'] },
]);
export const CLASS_NAMES = Object.freeze({
vegetation: 'vegetation', bare: 'bare ground', water: 'water', snow: 'snow or ice',
cloud: 'cloud', shadow: 'cloud shadow', dark: 'dark ground',
});
export const POLARISATIONS = Object.freeze([
{ id: 'vv', label: 'VV' }, { id: 'vh', label: 'VH' }, { id: 'ratio', label: 'VV − VH' },
]);
/** One colour a rule, on its row and on the map, in order. */
export const RULE_COLOURS = Object.freeze(['#facc15', '#38bdf8', '#f472b6', '#a3e635', '#fb923c', '#c084fc']);
/** The engine's own lists, for when a catalogue does not carry them. */
export const L2A_BANDS = Object.freeze(['B01', 'B02', 'B03', 'B04', 'B05', 'B06', 'B07', 'B08', 'B8A', 'B09', 'B11', 'B12']);
const SPECTRAL_BANDS = Object.freeze({
ndvi: ['B08', 'B04'], ndwi: ['B03', 'B08'], mndwi: ['B03', 'B11'], nbr: ['B08', 'B12'],
ndbi: ['B11', 'B08'], bsi: ['B11', 'B04', 'B08', 'B02'],
});
const VISIBLE = ['B02', 'B03', 'B04'];
/** Bits of the preview mask past the rules' own. */
export const MEASURED_BIT = 6;
export const KEPT_BIT = 7;
/** Which scale a rule's value lives on. */
export function unitOf(rule) {
if (rule.measure === 'class') return 'class';
if (rule.measure === 'radar') return 'db';
if (['band', 'brightness', 'colour'].includes(rule.measure)) return 'reflectance';
return 'index';
}
/**
* How a rule's line is said. A change is a drop, a rise or a move of some
* amount, and a state on one date is at least or at most some value; both can
* also sit between two values. The engine keeps an operator and a signed value,
* and these are the same thing in words.
*/
export function directionsFor(rule) {
if (rule.measure === 'class') return [['is', 'Is'], ['not', 'Is not']];
const between = ['between', 'Between'];
if (rule.on === 'change' && rule.measure !== 'colour') {
return [['drop', 'Dropped'], ['rise', 'Rose'], ['moved', 'Either way'], between];
}
return [['ge', 'At least'], ['le', 'At most'], between];
}
/** Which of `directionsFor` a rule says. */
export function directionOf(rule) {
if (rule.measure === 'class' || rule.op === 'between') return rule.op;
if (rule.on === 'change' && rule.measure !== 'colour') {
return rule.op === 'le' ? 'drop' : rule.op === 'ge' ? 'rise' : 'moved';
}
return rule.op;
}
/** The fields of a rule after it is said another way, keeping the amount it had. */
export function withDirection(rule, direction) {
const amount = Math.abs(rule.value);
if (direction === 'drop') return retarget(rule, { op: 'le', value: -amount });
if (direction === 'rise') return retarget(rule, { op: 'ge', value: amount });
return retarget(rule, { op: direction });
}
/** A rule's line as an amount: how big a drop, a rise or a move, or else the value itself. */
export function amountOf(rule, value = rule.value) {
if (rule.on !== 'change' || rule.measure === 'colour') return value;
if (rule.op === 'le') return -value;
return rule.op === 'moved' ? Math.abs(value) : value;
}
/** The value a rule's line takes for an amount, the opposite of `amountOf`. */
export function withAmount(rule, amount) {
const number = Number(amount);
if (rule.on !== 'change' || rule.measure === 'colour' || rule.op === 'between') return number;
return rule.op === 'le' ? -Math.abs(number) : Math.abs(number);
}
/**
* The slider a rule's line moves on: the amount of a drop, a rise or a move
* from nothing up, or else the value across its whole range.
*/
export function lineScale(rule) {
const scale = scaleOf(rule);
const directional = rule.on === 'change' && rule.measure !== 'colour' && rule.op !== 'between';
return directional ? { ...scale, min: 0, max: scale.max } : scale;
}
/**
* The slider a rule's value moves on, in the units shown: reflectance in
* percent, the rest as they are. `factor` turns an engine value into a shown one.
*/
export function scaleOf(rule) {
const unit = unitOf(rule);
const magnitude = rule.op === 'moved' || rule.measure === 'colour';
const change = rule.on === 'change' || rule.around > 0;
if (unit === 'reflectance') {
return { factor: 100, suffix: '%', step: 0.5,
min: magnitude ? 0 : change ? -50 : 0, max: magnitude ? 50 : change ? 50 : 100 };
}
if (unit === 'db') {
if (magnitude) return { factor: 1, suffix: ' dB', step: 0.5, min: 0, max: 20 };
if (change) return { factor: 1, suffix: ' dB', step: 0.5, min: -20, max: 20 };
return rule.polarisation === 'ratio'
? { factor: 1, suffix: ' dB', step: 0.5, min: -5, max: 25 }
: { factor: 1, suffix: ' dB', step: 0.5, min: -35, max: 15 };
}
if (magnitude) return { factor: 1, suffix: '', step: 0.01, min: 0, max: 1 };
return { factor: 1, suffix: '', step: 0.01, min: -1, max: 1 };
}
/** A value as the builder shows it, signed where the rule reads a change. */
export function formatValue(rule, value, { signed = false } = {}) {
if (value === null || value === undefined || !Number.isFinite(Number(value))) return '–';
const { factor, suffix } = scaleOf(rule);
const shown = Number(value) * factor;
const digits = unitOf(rule) === 'index' ? 2 : 1;
const text = Math.abs(shown).toFixed(digits);
const sign = shown < 0 ? '−' : signed && shown > 0 ? '+' : '';
return `${sign}${text}${suffix}`;
}
/** A shown value (percent for reflectance) back to the engine's units. */
export function toEngine(rule, shown) {
const { factor } = scaleOf(rule);
return Number((Number(shown) / factor).toFixed(6));
}
// Where a new rule starts: the published marks where there are some, so the
// first preview already means something. A change reads B minus A.
const INDEX_LINES = {
ndvi: { change: ['le', -0.25], state: ['ge', 0.4] },
nbr: { change: ['le', -0.27], state: ['le', 0.1] },
ndwi: { change: ['ge', 0.25], state: ['ge', 0] },
mndwi: { change: ['ge', 0.25], state: ['ge', 0] },
ndbi: { change: ['ge', 0.1], state: ['ge', 0] },
bsi: { change: ['ge', 0.1], state: ['ge', 0] },
};
function line(rule) {
const change = rule.on === 'change';
switch (rule.measure) {
case 'index': return INDEX_LINES[rule.index][change ? 'change' : 'state'];
case 'nd': return change ? ['le', -0.2] : ['ge', 0];
case 'band': return change ? ['moved', 0.05] : ['ge', 0.25];
case 'brightness': return change ? ['moved', 0.05] : ['ge', 0.2];
case 'colour': return ['ge', 0.05];
case 'class': return ['is', 0];
case 'radar':
if (change) return ['moved', 3];
return rule.polarisation === 'ratio' ? ['ge', 8] : ['ge', rule.polarisation === 'vh' ? -12 : -4];
default: return ['ge', 0];
}
}
/**
* A new rule, whole, as the engine's model spells it. It starts on the usual
* line for what it measures unless `extra` names its own op, value or upper.
*/
export function newRule(measure = 'index', on = 'change', extra = {}) {
const { op, value, upper, ...rest } = extra;
const rule = {
measure, index: 'ndvi', bands: ['B08', 'B04'], band: 'B08', polarisation: 'vv', classes: [],
on: measure === 'colour' ? 'change' : measure === 'class' && on === 'change' ? 'b' : on,
op: 'ge', value: 0, upper: 0, around: 0, ...rest,
};
if (rule.measure === 'class' && !rule.classes.length) rule.classes = ['water'];
const lined = withLine(rule);
return {
...lined,
...(op === undefined ? {} : { op }),
...(value === undefined ? {} : { value }),
...(upper === undefined ? {} : { upper }),
};
}
function withLine(rule) {
const [op, value] = line(rule);
const scale = scaleOf({ ...rule, op });
return { ...rule, op, value, upper: op === 'between' ? value + (scale.max - scale.min) / scale.factor / 10 : 0 };
}
/**
* A rule after one of its fields changed. Changing what it measures, or when,
* puts it back on that quantity's usual line; the rest keeps what was set, as
* long as the combination still means something.
*/
export function retarget(rule, patch) {
const next = { ...rule, ...patch };
if (next.measure === 'colour') next.on = 'change';
if (next.measure === 'class') {
if (next.on === 'change') next.on = 'b';
if (!next.classes.length) next.classes = ['water'];
next.around = 0;
}
if ('measure' in patch || 'on' in patch || 'index' in patch || 'polarisation' in patch) return withLine(next);
if ('op' in patch) {
if (next.op === 'moved') next.value = Math.abs(next.value);
if (next.op === 'between' && next.upper <= next.value) {
const scale = scaleOf(next);
next.upper = Number((next.value + (scale.max - scale.min) / scale.factor / 10).toFixed(4));
}
}
return next;
}
/** Why a rule cannot run, or '' when it can, as the engine would refuse it. */
export function ruleProblem(rule) {
if (rule.measure === 'class') {
if (!rule.classes?.length) return 'Choose at least one ground class.';
return '';
}
if (!Number.isFinite(Number(rule.value))) return 'Give the rule a value.';
if (rule.op === 'between' && !(Number(rule.upper) > Number(rule.value))) return 'The upper bound must be above the lower one.';
if (rule.measure === 'nd' && rule.bands[0] === rule.bands[1]) return 'Pick two different bands.';
return '';
}
/** The bands a rule reads. */
export function ruleBands(rule) {
if (rule.measure === 'index') return SPECTRAL_BANDS[rule.index] ?? [];
if (rule.measure === 'nd') return [...rule.bands];
if (rule.measure === 'band') return [rule.band];
if (rule.measure === 'brightness' || rule.measure === 'colour') return VISIBLE;
return [];
}
export function recipeBands(recipe) {
const wanted = new Set((recipe?.rules ?? []).flatMap(ruleBands));
return L2A_BANDS.filter((band) => wanted.has(band));
}
export const isRules = (recipe) => recipe?.method === 'rules';
/**
* What an analyzer reads: the satellite and the number of dates it declared.
* One saved before it declared them is worked out from its rules, as the
* engine does when it loads it.
*/
export const sensorOf = (recipe) => recipe?.sensor
?? ((recipe?.rules ?? []).some((rule) => rule.measure === 'radar') ? 'sentinel1' : 'sentinel2');
export const datesOf = (recipe) => recipe?.dates
?? ((recipe?.rules ?? []).every((rule) => rule.on === 'b') ? 'one' : 'two');
export const readsRadar = (recipe) => isRules(recipe) && sensorOf(recipe) === 'sentinel1';
export const readsOneDate = (recipe) => isRules(recipe) && datesOf(recipe) === 'one';
/** What an analyzer reads, in a few words: "Sentinel-2 · two dates". */
export function describeReads(recipe) {
const radar = sensorOf(recipe) === 'sentinel1';
return `${radar ? 'Sentinel-1 radar' : 'Sentinel-2'} · ${datesOf(recipe) === 'one' ? 'one date' : 'two dates'}`;
}
/** The measures an analyzer can use: its satellite's, and a colour distance only where two dates give it a change. */
export const measuresFor = (recipe) => MEASURES.filter((measure) => (measure.id === 'radar') === readsRadar(recipe)
&& !(measure.id === 'colour' && readsOneDate(recipe)));
/** The dates a rule can be read on, in the words an analyst uses. A single
* date needs no choice, and a colour distance or a ground class fix theirs. */
export function whensFor(recipe, rule) {
if (readsOneDate(recipe)) return [];
const all = [['a', 'Before'], ['b', 'After'], ['change', 'Change']];
if (rule.measure === 'colour') return all.filter(([id]) => id === 'change');
if (rule.measure === 'class') return all.filter(([id]) => id !== 'change');
return all;
}
/** Band products one date costs: every three bands are one request. */
export function productCount(recipe) {
if (readsRadar(recipe)) return 1;
return Math.max(1, Math.ceil(recipeBands(recipe).length / 3));
}
/** Why the recipe cannot run, or '' when it can. */
export function recipeProblem(recipe, limits = {}) {
const rules = recipe?.rules ?? [];
if (!rules.length) return 'Add a rule.';
const most = limits.max_rules ?? 6;
if (rules.length > most) return `An analyzer holds at most ${most} rules.`;
for (const rule of rules) {
const problem = ruleProblem(rule);
if (problem) return problem;
}
const radar = new Set(rules.filter((rule) => rule.measure !== 'class').map((rule) => rule.measure === 'radar'));
if (radar.size > 1) return 'Radar and optical rules read two satellites; keep them in two analyzers.';
if (radar.has(true) && rules.some((rule) => rule.measure === 'class')) return 'Ground classes come from Sentinel-2, which a radar analyzer does not read.';
if (radar.has(true) !== readsRadar(recipe)) {
return radar.has(true) ? 'Radar rules need a radar analyzer.' : 'Optical rules need a Sentinel-2 analyzer.';
}
const single = rules.every((rule) => rule.on === 'b');
if (readsOneDate(recipe) && !single) return 'A one-date analyzer has no before pass for this rule to read.';
if (!readsOneDate(recipe) && single) return 'Put a rule on the before date or on the change, or the before pass is read for nothing.';
const bands = limits.max_bands ?? 6;
if (recipeBands(recipe).length > bands) return `An analyzer reads at most ${bands} bands.`;
return '';
}
/**
* Why the analyzer cannot be saved yet, or '' when it can. Checks are how it
* is proved, so it needs one, with a pin where something should be found.
*/
export function savingProblem(recipe, limits = {}) {
const problem = recipeProblem(recipe, limits);
if (problem) return problem;
const checks = recipe?.checks ?? [];
if (!checks.length) return 'Add a check: a place where this analyzer should find something.';
const unpinned = checks.find((check) => !check.marks?.length);
if (unpinned) return `The check “${unpinned.name}” needs a pin.`;
const undated = checks.find((check) => !checkDated(recipe, check));
if (undated) return `The check “${undated.name}” needs its passes.`;
if (!checks.some((check) => check.marks.some((mark) => mark.expect === 'found'))) {
return 'A check needs a pin where something should be found.';
}
return '';
}
/**
* What the panel asks of a recipe's method, worked out from its rules for an
* analyzer of your own: which dates, which satellite, what a tile costs, and
* the sizes and smoothing that fit.
*/
export function recipeCapability(recipe, methods = []) {
const base = methods.find((entry) => entry.id === recipe?.method) ?? {};
if (!isRules(recipe)) return base;
const radar = readsRadar(recipe);
const single = readsOneDate(recipe);
const radarChange = methods.find((entry) => entry.id === 'sar-change') ?? {};
return {
...base,
single,
sensor: radar ? 'sentinel1' : 'sentinel2',
clouds: !radar,
frames: (single ? 1 : 2) * (1 + productCount(recipe)),
sizes: radar ? radarChange.sizes ?? base.sizes : base.sizes,
smoothing_m: radar ? radarChange.smoothing_m ?? null : null,
};
}
/** The rule that ranks candidates: the first that measures something. */
export const signalOf = (recipe) => (recipe?.rules ?? []).findIndex((rule) => rule.measure !== 'class');
function pairName(bands) {
return PAIRS.find((pair) => pair.bands[0] === bands[0] && pair.bands[1] === bands[1])?.label;
}
/** What a rule measures, in a few words. */
function quantityLabel(rule) {
switch (rule.measure) {
case 'index': return INDICES.find((entry) => entry.id === rule.index)?.label ?? rule.index.toUpperCase();
case 'nd': return pairName(rule.bands) ?? `(${rule.bands[0]} − ${rule.bands[1]}) / (${rule.bands[0]} + ${rule.bands[1]})`;
case 'band': return `${rule.band} (${BAND_NAMES[rule.band] ?? 'band'})`;
case 'brightness': return 'brightness';
case 'colour': return 'colour';
case 'radar': return POLARISATIONS.find((entry) => entry.id === rule.polarisation)?.label ?? 'VV';
case 'class': return 'ground';
default: return rule.measure;
}
}
/**
* A rule in a couple of words, for a chip on the map: "NDVI change", "B12
* after", "VV". An analyzer of one date has no before or after to say.
*/
export function shortRule(rule, { single = false } = {}) {
const name = rule.measure === 'index' ? INDICES.find((entry) => entry.id === rule.index)?.label ?? rule.index.toUpperCase()
: rule.measure === 'nd' ? pairName(rule.bands) ?? `${rule.bands[0]}/${rule.bands[1]}`
: rule.measure === 'band' ? rule.band
: rule.measure === 'radar' ? POLARISATIONS.find((entry) => entry.id === rule.polarisation)?.label ?? 'VV'
: rule.measure === 'class' ? 'ground' : rule.measure;
if (single) return name;
return `${name} ${rule.on === 'change' ? 'change' : rule.on === 'a' ? 'before' : 'after'}`;
}
/** Where a state rule is read, for a sentence: nothing on a single date, else before or after. */
const whenName = (on, single) => (single ? '' : on === 'a' ? ' before' : ' after');
/**
* A rule as a clause: "NDVI dropped by 0.25 or more", "NDVI after is at least
* 0.40", "ground is water". An analyzer of one date has no before or after to say.
*/
export function describeRule(rule, { single = false } = {}) {
const quantity = quantityLabel(rule);
if (rule.measure === 'class') {
const names = rule.classes.map((id) => CLASS_NAMES[id] ?? id);
const list = names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names.at(-1)}` : names[0] ?? 'nothing';
return `ground${whenName(rule.on, single)} ${rule.op === 'not' ? 'is not' : 'is'} ${list}`;
}
const around = rule.around ? ` against the ground within ${rule.around} m` : '';
const value = (v, signed = false) => formatValue(rule, v, { signed });
if (rule.on !== 'change') {
const on = `${quantity}${whenName(rule.on, single)} is`;
if (rule.op === 'between') return `${on} between ${value(rule.value)} and ${value(rule.upper)}${around}`;
if (rule.around) return `${on} ${rule.op === 'ge' ? 'at least' : 'at most'} ${value(rule.value, true)}${around}`;
return `${on} ${rule.op === 'ge' ? 'at least' : 'at most'} ${value(rule.value)}`;
}
if (rule.measure === 'colour') {
if (rule.op === 'between') return `colour moved by between ${value(rule.value)} and ${value(rule.upper)}${around}`;
return `colour moved by ${rule.op === 'ge' ? 'at least' : 'at most'} ${value(rule.value)}${around}`;
}
const size = (v) => formatValue(rule, Math.abs(v));
if (rule.op === 'moved') return `${quantity} moved by ${size(rule.value)} or more either way${around}`;
if (rule.op === 'between') return `${quantity} changed by between ${value(rule.value, true)} and ${value(rule.upper, true)}${around}`;
if (rule.op === 'le' && rule.value <= 0) return `${quantity} dropped by ${size(rule.value)} or more${around}`;
if (rule.op === 'ge' && rule.value >= 0) return `${quantity} rose by ${size(rule.value)} or more${around}`;
return `${quantity} changed by ${rule.op === 'ge' ? 'at least' : 'at most'} ${value(rule.value, true)}${around}`;
}
/** The whole analyzer as one sentence, for "Reads as" and a default description. */
export function describeRecipe(recipe, { clouds = true } = {}) {
const single = readsOneDate(recipe);
const clauses = (recipe?.rules ?? []).map((rule) => describeRule(rule, { single }));
if (!clauses.length) return '';
const joiner = recipe.match === 'any' ? 'or' : 'and';
const list = clauses.length > 1 ? `${clauses.slice(0, -1).join(', ')} ${joiner} ${clauses.at(-1)}` : clauses[0];
const sky = clouds && !readsRadar(recipe) && recipe.parameters?.ignore_clouds ? ', outside cloud' : '';
const text = `Keeps ground where ${list}${sky}.`;
return text.charAt(0).toUpperCase() + text.slice(1);
}
/** A candidate's reading, from its analyzer's signal rule. */
export function describeReading(recipe, measure) {
const index = signalOf(recipe);
if (index < 0 || !measure) return '';
const rule = recipe.rules[index];
const quantity = quantityLabel(rule);
if (rule.on === 'change' && rule.measure !== 'colour' && Number.isFinite(measure.before)) {
const change = formatValue(rule, measure.signed, { signed: true });
return `${quantity} ${formatValue(rule, measure.before)} → ${formatValue(rule, measure.after)} (${change}${rule.around ? ' against its ground' : ''})`;
}
if (!Number.isFinite(measure.value)) return '';
const shown = formatValue(rule, measure.value, { signed: !!rule.around });
return rule.around ? `${quantity} ${shown} against its ground` : `${quantity} ${shown}`;
}
/** The engine's parameter defaults, which a recipe starts from. */
export const DEFAULT_PARAMETERS = Object.freeze({
sensitivity: 60, min_area: 0, max_area: 0, cleanup: 0, smoothing: 0, index: 'ndvi', direction: 'both',
sar_ground: 'any', ignore_clouds: true, ignore_shadows: true, cloud_margin: 5, merge_metres: 0, shape: 'any',
});
/**
* A new analyzer of your own, for the satellite and the number of dates it
* was made for: one rule on the first usual line, at All sizes like every
* built-in. Radar starts from radar change's sizes, whose averaging is what
* keeps speckle from reading as a target.
*/
export function newRecipe(methods = [], { sensor = 'sentinel2', dates = 'two' } = {}) {
const radar = sensor === 'sentinel1';
const sizes = methods.find((entry) => entry.id === (radar ? 'sar-change' : 'rules'))?.sizes;
const two = dates === 'two';
const first = newRule(radar ? 'radar' : 'brightness', two ? 'change' : 'b');
return {
id: 'custom', name: '', description: '', phenomenon: 'Candidate', method: 'rules', sensor, dates,
parameters: { ...DEFAULT_PARAMETERS, ...(sizes?.all ?? {}) },
colour: '#f6a81a', style: 'both', rules: [first], match: 'all', checks: [],
};
}
/**
* Difference's index reading as an analyzer of your own: the same index, the
* same line, the same way it moved, the same cleanup. Difference counts its
* cloud margin in metres; Detect grows its mask in 10 m pixels.
*/
export function fromDifference(settings) {
const index = INDICES.find((entry) => entry.id === settings.index) ?? INDICES[0];
const threshold = Number(indexThreshold(settings.sensitivity).toFixed(2));
const classes = settings.classes ?? [];
const loss = classes.includes('loss') && !classes.includes('gain');
const gain = classes.includes('gain') && !classes.includes('loss');
const rule = newRule('index', 'change', { index: index.id });
const tuned = loss ? { op: 'le', value: -threshold } : gain ? { op: 'ge', value: threshold } : { op: 'moved', value: threshold };
const way = loss ? index.loss : gain ? index.gain : `${index.label} change`;
return {
id: 'custom', name: `${index.label}: ${way}`, description: '', phenomenon: way, method: 'rules',
parameters: {
...DEFAULT_PARAMETERS,
min_area: Math.max(0, Number(settings.min_area) || 0),
cleanup: Math.min(3, Math.max(0, Math.round(settings.cleanup ?? 0))),
smoothing: Math.min(3, Math.max(0, Math.round(settings.smoothing ?? 0))),
ignore_clouds: !!settings.ignore_clouds,
ignore_shadows: !!settings.ignore_shadows,
cloud_margin: Math.min(10, Math.max(0, Math.round((settings.cloud_margin ?? 0) / 10))),
},
sensor: 'sentinel2', dates: 'two',
colour: '#f6a81a', style: 'both', rules: [{ ...rule, ...tuned }], match: 'all', checks: [],
};
}
function rgb(hex) {
const value = parseInt(hex.slice(1), 16);
return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
}
/** The tint over ground a test judged, before any rule has painted it. */
const VEIL = [120, 170, 255];
/**
* A tile's mask painted in the rules' colours: each shown rule lays its pixels
* in its colour, later ones over earlier, and a hovered rule alone, brighter.
* `bits` is one byte a pixel, the engine's mask. With a `veil` the ground the
* test measured is tinted first, so a pixel no rule kept still reads as
* tested, and cloud or missing imagery stays clear.
*/
export function paintMask(bits, { shown = [], hover = null, colours = RULE_COLOURS, alpha = 110, veil = 0 } = {}) {
const out = new Uint8ClampedArray(bits.length * 4);
const order = hover === null ? shown.map((on, i) => (on ? i : -1)).filter((i) => i >= 0) : [hover];
const tints = colours.map(rgb);
const strength = hover === null ? alpha : 190;
for (let p = 0; p < bits.length; p++) {
const value = bits[p];
if (!value) continue;
if (veil && value & (1 << MEASURED_BIT)) {
out[p * 4] = VEIL[0]; out[p * 4 + 1] = VEIL[1]; out[p * 4 + 2] = VEIL[2]; out[p * 4 + 3] = veil;
}
for (const i of order) {
if (!(value & (1 << i))) continue;
const [r, g, b] = tints[i % tints.length];
out[p * 4] = r; out[p * 4 + 1] = g; out[p * 4 + 2] = b; out[p * 4 + 3] = strength;
}
}
return out;
}
/**
* Which part of a split map a rule is painted on: what reads the before pass
* on the before half, the after pass on the after half, and a change across
* both, since it belongs to neither. A map that is not split has one part.
*/
export function sideOf(rule, split) {
if (!split) return 'shared';
return rule.on === 'a' ? 'before' : rule.on === 'b' ? 'after' : 'shared';
}
/** A share of the measured ground, as the funnel prints it. */
export function formatShare(share) {
if (!Number.isFinite(share)) return '–';
const percent = share * 100;
if (percent === 0) return '0 %';
if (percent < 0.1) return '< 0.1 %';
return `${percent < 10 ? percent.toFixed(1) : Math.round(percent)} %`;
}
// -- checks ---------------------------------------------------------------------------
/** JSON with its keys sorted, so the same recipe always reads the same. */
function canonical(value) {
if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
if (value && typeof value === 'object') {
return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
}
return JSON.stringify(value);
}
/**
* A short digest of what a reading depends on: the rules, how they combine
* and the parameters. A check's result keeps the one it was read with, so a
* result from rules changed since shows as stale rather than as an answer.
*/
export function signature(recipe) {
const text = canonical({ rules: recipe?.rules ?? [], match: recipe?.match ?? 'all', parameters: recipe?.parameters ?? {} });
let hash = 0x811c9dc5;
for (let i = 0; i < text.length; i++) {
hash ^= text.charCodeAt(i);
hash = Math.imul(hash, 0x01000193) >>> 0;
}
return hash.toString(36);
}
/** A check on the passes shown, with the pins dropped on them so far. */
export function newCheck({ name, a = {}, b = { date: '' }, marks = [] }) {
const id = `check-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
return { id, name, a: { ...a }, b: { ...b }, marks: marks.map((mark) => ({ ...mark, point: [...mark.point] })), result: null };
}
/** A check with one more pin. Its last result goes, since it answered for the pins it had. */
export function withMark(check, point, expect) {
return { ...check, marks: [...check.marks, { point: [point[0], point[1]], expect }], result: null };
}
export function withoutMark(check, index) {
return { ...check, marks: check.marks.filter((_, i) => i !== index), result: null };
}
/** A check with one pin turned the other way: where it should be found, or where none should. */
export function withFlippedMark(check, index) {
const marks = check.marks.map((mark, i) => (i === index ? { ...mark, expect: mark.expect === 'found' ? 'empty' : 'found' } : mark));
return { ...check, marks, result: null };
}
/** Whether a check has the passes this analyzer reads: the after pass, and the before one when it has two dates. */
export const checkDated = (recipe, check) => !!check.b?.date && (readsOneDate(recipe) || !!check.a?.date);
/** The box round a check's pins, widened so one pin alone still frames some ground. */
export function marksBounds(marks, margin = 0.004) {
const lons = marks.map((mark) => mark.point[0]);
const lats = marks.map((mark) => mark.point[1]);
return { west: Math.min(...lons) - margin, east: Math.max(...lons) + margin,
south: Math.min(...lats) - margin, north: Math.max(...lats) + margin };
}
const passKey = (source) => [source?.provider ?? '', source?.date ?? '', source?.time ?? ''];
/**
* What a check reads, for telling whether its last test still holds: its
* passes and its pins. The layer they are shown in is how they look, not what
* is read, so it is not in it.
*/
export const checkKey = (check) => canonical({ a: passKey(check.a), b: passKey(check.b),
marks: (check.marks ?? []).map((mark) => [mark.point, mark.expect]) });
/** The recipe a test is asked with: what the rules read, and nothing that only names or colours them. */
export function readingRecipe(recipe) {
return { name: 'Test', method: 'rules', sensor: sensorOf(recipe), dates: datesOf(recipe),
rules: recipe.rules, match: recipe.match, parameters: recipe.parameters };
}
/** A check in the form a test is asked with: without the result it would be told. */
export const testedCheck = (check) => ({ ...check, result: null });
/** A pass as a source the engine reads: Sentinel-2 in the layer it is shown in, or a radar pass at its time. */
export function passSource(recipe, pass, layer = 'TRUE_COLOR') {
return readsRadar(recipe)
? { provider: 'sentinel1', date: pass.date, time: pass.time ?? '' }
: { provider: 'sentinel2', date: pass.date, layer, maxcc: 100 };
}
/** Mark by mark, whether it came out as expected, from the last result. */
export function markOutcomes(check) {
const covered = check.result?.covered ?? [];
return check.marks.map((mark, i) => (covered.length ? covered[i] === (mark.expect === 'found') : null));
}
/**
* Where a check stands: 'pass' when every mark came out as it should,
* 'fail' when one did not, 'unpinned' for a check with no pin yet, 'stale'
* when its last result was read with other rules, 'unrun' when it has none.
*/
export function checkState(check, current) {
if (!check.marks.length) return 'unpinned';
const result = check.result;
if (!result) return 'unrun';
if (result.signature !== current) return 'stale';
return markOutcomes(check).every(Boolean) ? 'pass' : 'fail';
}
/** A check's last result in a few words: "2 of 2 found · none flagged". */
export function describeOutcome(check, current) {
const state = checkState(check, current);
if (state === 'unpinned') return 'Needs a pin';
if (state === 'unrun') return 'Not tested yet';
if (state === 'stale') return 'Rules changed since its last test';
const outcomes = markOutcomes(check);
const found = check.marks.map((mark, i) => [mark, outcomes[i]]).filter(([mark]) => mark.expect === 'found');
const empty = check.marks.map((mark, i) => [mark, outcomes[i]]).filter(([mark]) => mark.expect === 'empty');
const parts = [];
if (found.length) parts.push(`${found.filter(([, ok]) => ok).length} of ${found.length} found`);
if (empty.length) {
const flagged = empty.filter(([, ok]) => !ok).length;
parts.push(flagged ? `${flagged} of ${empty.length} flagged` : empty.length === 1 ? 'stayed empty' : 'all stayed empty');
}
return parts.join(' · ');
}
/**
* What the pins would have come to without one rule, in a few words, from
* whether each was on a candidate now and without it. A pin comes out right
* when a candidate is on it and it should be found, or none is and it should
* stay empty, so a rule that keeps pins right is one their count falls
* without, and one that loses pins is one it rises without.
*/
export function describeWithout(marks, covered, without) {
if (!without || !covered?.length || without.length !== marks.length) return '';
let wrong = 0;
let right = 0;
marks.forEach((mark, i) => {
const wanted = mark.expect === 'found';
const now = covered[i] === wanted;
const then = without[i] === wanted;
if (now && !then) wrong++;
else if (!now && then) right++;
});
if (!wrong && !right) return 'Without it, no pin changes.';
const pins = (n) => `${n} pin${n === 1 ? '' : 's'}`;
if (wrong && right) return `Without it, ${pins(right)} would come out right and ${wrong} wrong.`;
return right ? `Without it, ${pins(right)} would come out right.` : `Without it, ${pins(wrong)} would come out wrong.`;
}
/** Every check of a recipe counted by where it stands. */
export function checksSummary(recipe) {
const current = signature(recipe);
const states = (recipe?.checks ?? []).map((check) => checkState(check, current));
const count = (state) => states.filter((entry) => entry === state).length;
return { total: states.length, pass: count('pass'), fail: count('fail'),
waiting: count('stale') + count('unrun') + count('unpinned') };
}
/** The summary as the library prints it under an analyzer. */
export function describeChecks(recipe) {
const { total, pass, fail, waiting } = checksSummary(recipe);
if (!total) return '';
const head = `${total} check${total === 1 ? '' : 's'}`;
if (fail) return `${head} · ${fail} fail${fail === 1 ? 's' : ''}`;
if (waiting === total) return `${head} · not tested`;
if (pass && !waiting) return `${head} · all pass`;
return `${head} · ${pass} pass`;
}
// -- layers ---------------------------------------------------------------------------
const firstOf = (wanted, ids) => wanted.find((id) => ids.includes(id));
/**
* The Copernicus layer that shows best what a rule reads: vegetation in NDVI,
* burns and heat in short-wave infrared, water and hulls in false colour, among
* the layers the configuration offers.
*/
export function suggestedLayer(rule, layers = []) {
const ids = layers.filter((layer) => layer.enabled !== false).map((layer) => layer.id);
const fallback = ids.includes('TRUE_COLOR') ? 'TRUE_COLOR' : ids[0] ?? 'TRUE_COLOR';
if (!rule) return fallback;
const swir = ['B11', 'B12'];
const nir = ['B05', 'B06', 'B07', 'B08', 'B8A'];
let wanted = ['TRUE_COLOR'];
if (rule.measure === 'index') {
wanted = {
ndvi: ['NDVI', 'VEGETATION_INDEX', 'FALSE_COLOR', 'COLOR_INFRARED'], nbr: ['SWIR', 'MOISTURE_INDEX'], ndwi: ['NDWI', 'FALSE_COLOR', 'COLOR_INFRARED'],
mndwi: ['NDWI', 'FALSE_COLOR', 'COLOR_INFRARED'], ndbi: ['FALSE_COLOR_URBAN', 'COLOR_INFRARED__URBAN_', 'SWIR'], bsi: ['SWIR', 'FALSE_COLOR_URBAN', 'COLOR_INFRARED__URBAN_'],
}[rule.index] ?? wanted;
} else if (rule.measure === 'nd' || rule.measure === 'band') {
const bands = ruleBands(rule);
wanted = bands.some((band) => swir.includes(band)) ? ['SWIR', 'FALSE_COLOR', 'COLOR_INFRARED']
: bands.some((band) => nir.includes(band)) ? ['FALSE_COLOR', 'COLOR_INFRARED', 'NDVI', 'VEGETATION_INDEX'] : ['TRUE_COLOR'];
} else if (rule.measure === 'class') {
wanted = ['SCENE_CLASSIFICATION', 'TRUE_COLOR'];
}
return firstOf(wanted, ids) ?? fallback;
}
/**
* Whether a reading crosses a rule's line.
*
* The mirror of `detect_rules._passes`, and it has to stay the mirror: it is
* what repaints the ground while the slider moves, against the very readings
* the last test made. `tests/test_detect_rules.py` proves the two agree pixel
* for pixel at several lines; if this drifts, the line gets set against a
* picture that lies.
*/
export function passesValue(rule, value) {
if (rule.op === 'ge') return value >= rule.value;
if (rule.op === 'le') return value <= rule.value;
if (rule.op === 'between') return value >= rule.value && value <= rule.upper;
return Math.abs(value) >= rule.value;
}
/**
* One rule's bit redrawn through the mask, from the reading the engine sent.
*
* Every other rule's bit, the measured bit and the kept bit are left exactly as
* the test wrote them: only the line of this rule moved, so only its own ground
* may change. Unmeasured ground carries no reading and stays out.
*
* @param {Uint8Array} bits the tile's mask, one byte a pixel
* @param {number} index which rule's bit to redraw
* @param {Float64Array|number[]} values that rule's reading, pixel for pixel
*/
export function redrawRule(bits, index, values, rule) {
const out = new Uint8Array(bits);
const bit = 1 << index;
const seen = 1 << MEASURED_BIT;
for (let p = 0; p < out.length; p++) {
if (!(out[p] & seen)) continue;
if (passesValue(rule, values[p])) out[p] |= bit;
else out[p] &= ~bit;
}
return out;
}
/** The share of the measured ground a redrawn rule keeps, 0 to 1. */
export function shareOf(masks, index) {
let seen = 0;
let kept = 0;
const bit = 1 << index;
const measured = 1 << MEASURED_BIT;
for (const bits of masks) {
for (let p = 0; p < bits.length; p++) {
if (!(bits[p] & measured)) continue;
seen++;
if (bits[p] & bit) kept++;
}
}
return seen ? kept / seen : 0;
}
/**
* What a rule reads, apart from where its line sits.
*
* The reading the engine sends answers for the bands, the dates and the context
* — never for the threshold, which is the point. Two recipes with the same
* reading key can share one download; a change to this key drops it.
*/
export function readingKey(rule) {
return [rule.measure, rule.index, ...rule.bands, rule.band, rule.polarisation,
[...(rule.classes ?? [])].sort().join('+'), rule.on, rule.around].join('|');
}
/** Each rule as what it reads and where its line sits, kept apart. */
export function linesOf(recipe) {
return (recipe?.rules ?? []).map((rule) => ({
key: readingKey(rule),
line: [rule.op, rule.value, rule.upper].join('|'),
}));
}
/**
* What the suggested display layer lets you see, in the words of the data the
* ranking rule reads — "shows B11 · B12".
*
* Not "for rule ★": the star is at the other end of the screen, so naming it
* sends the reader hunting for what it means. The bands say it on the spot.
*/
export function suggestedWords(rule) {
const bands = ruleBands(rule);
if (bands.length) return `shows ${bands.join(' · ')}`;
if (rule?.measure === 'class') return 'shows the ground classes';
return '';
}
// -- pins on a rule's line -----------------------------------------------------------
const unit = (value) => Math.max(0, Math.min(1, value));
/**
* Where each pin's reading falls along a rule's slider, 0 to 1, so the line
* can be set between the pins that should come out and the ones that should
* not. A drop is measured as the size of the drop, so a pin where the ground
* rose sits at nothing. A reading past an end of the slider is pinned to that
* end. `readings` is what a test read under each pin, in the order of the
* check's pins.
*/
export function pinTicks(rule, marks, readings, index) {
if (rule.measure === 'class') return [];
const { factor, min, max } = lineScale(rule);
const ticks = [];
marks.forEach((mark, i) => {
const row = readings?.[i]?.rules?.[index];
if (!row || row.value === null || row.value === undefined || !Number.isFinite(row.value)) return;
const shown = amountOf(rule, row.value) * factor;
ticks.push({ pin: i, expect: mark.expect, at: unit((shown - min) / (max - min)),
clipped: shown < min || shown > max, value: row.value, passes: !!row.passes });
});
return ticks;
}