The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* An evolution: the dated pictures of one point, played in order.
*
* A comparison reads two pictures. An evolution reads every picture the archive
* A and B share holds between them, so a building going up or a burn greening
* again shows as it happened rather than as two ends. The list is the one the
* pictures strip reads (`passStrip.js`); this module chooses among its rows and
* lays each picture out on the ground.
*
* Each picture is drawn from the tile proxy, not from the maps on screen: A and
* B keep what they show while the export runs, and every picture of one export
* covers exactly the same ground at the same scale. The pixels are kept as the
* archive gives them, tones unmatched, since matching them can erase the change
* being shown. Only reference layers are left out: the export is the imagery,
* its date and the marks pinned to the ground.
*
* Everything here is pure; `evolutionExport.js` fetches and draws.
*/
import { SENTINEL_ID } from '../sentinel.js';
import { WAYBACK_ID } from '../wayback.js';
import { entryOf } from './passStrip.js';
import {
apply, compassAngle, compose, fromMercator, invert, mercatorPerPixel, scale,
screenToMercator, turnedBox,
} from './groundFrame.js';
export const EVOLUTION_ARCHIVES = Object.freeze([SENTINEL_ID, WAYBACK_ID]);
export const WORLD_IMAGERY_ID = 'esri-world-imagery';
/** The first month Sentinel-2 imaged the ground: Sentinel-2A began in June 2015. */
export const SENTINEL2_FIRST_MONTH = '2015-06';
/** A month the Sentinel-2 picker can open, `YYYY-MM`, held between 2015 and `today`; null for no month. */
export function pickerMonth(month, today) {
if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(String(month ?? ''))) return null;
if (month < SENTINEL2_FIRST_MONTH) return SENTINEL2_FIRST_MONTH;
return month > today ? today : month;
}
/** The most pictures one export holds; `MAX_SEQUENCE_FRAMES` in `api/compare.py`. */
export const MAX_EVOLUTION_FRAMES = 40;
/** The widest a GIF frame is drawn; `MAX_GIF_EDGE` in `api/compare.py`. */
export const GIF_EDGE = 1280;
/** The width a contact sheet aims at, gaps included. */
export const SHEET_WIDTH = 2400;
/** The most pixels the pictures of a sheet add up to. */
export const SHEET_PIXELS = 8_000_000;
/** A picture needing more tiles than this is refused rather than fetched. */
export const MAX_PICTURE_TILES = 128;
/** How long each picture of a GIF stays up by default, in ms. */
export const DEFAULT_INTERVAL = 800;
const WORLD = mercatorPerPixel(0) * 512;
const HALF = WORLD / 2;
/**
* The archive an evolution plays, when A and B allow one: Sentinel-2 or Wayback
* on both sides, or Wayback against World Imagery, whose history Wayback is.
*/
export function evolutionArchive(a, b) {
if (!a?.present || !b?.present) return null;
if (a.provider === b.provider) return EVOLUTION_ARCHIVES.includes(a.provider) ? a.provider : null;
const pair = [a.provider, b.provider];
return pair.includes(WAYBACK_ID) && pair.includes(WORLD_IMAGERY_ID) ? WAYBACK_ID : null;
}
/**
* The row a side shows. World Imagery stands for the newest Wayback release.
*
* The Wayback list holds only the releases that first published a picture of
* the point, and a side usually shows a release that republished one: it shows
* the picture of the last listed release published on or before its own, so
* the side carries its release's date as `wayback_date`.
*/
export function sideEntry(entries, archive, side) {
if (!side) return null;
if (archive !== WAYBACK_ID) return entryOf(entries, archive, side);
if (side.provider !== WAYBACK_ID || side.wayback_release == null) return entries.at(-1) ?? null;
const exact = entryOf(entries, archive, side);
if (exact) return exact;
const day = side.wayback_date;
if (!day) return null;
return entries.filter((entry) => entry.released && entry.released <= day).at(-1) ?? null;
}
/**
* The rows in the order an evolution plays them: by the day each picture was
* taken. The Wayback list comes in release order, and a later release can carry
* an older picture; a row with no acquisition date stands at its release's.
*/
export function playOrder(entries) {
return entries
.map((entry, index) => [entry, index])
.sort(([x, i], [y, j]) => (x.date < y.date ? -1 : x.date > y.date ? 1 : i - j))
.map(([entry]) => entry);
}
/** Evenly spaced keys, both ends kept, when there are more than `max`. */
export function spreadKeys(keys, max = MAX_EVOLUTION_FRAMES) {
if (keys.length <= max) return [...keys];
if (max < 2) return keys.slice(0, Math.max(0, max));
const picked = [];
for (let index = 0; index < max; index += 1) {
picked.push(keys[Math.round((index * (keys.length - 1)) / (max - 1))]);
}
return picked;
}
/**
* The usable rows from A's picture to B's, both included, in the list's order
* (release order for Wayback). A side the list does not hold (a Sentinel-2 side
* on its latest pass) stands at that end.
*/
export function rangeKeys(entries, first, last) {
if (!entries.length) return [];
let from = first ? entries.indexOf(first) : 0;
let to = last ? entries.indexOf(last) : entries.length - 1;
if (from < 0) from = 0;
if (to < 0) to = entries.length - 1;
if (from > to) [from, to] = [to, from];
return entries.slice(from, to + 1).filter((entry) => entry.usable).map((entry) => entry.key);
}
/** Every usable row. */
export const allKeys = (entries) => entries.filter((entry) => entry.usable).map((entry) => entry.key);
/**
* What an export starts on: A to B, or every usable picture when A and B are one
* row, spread down to the most one export holds.
*/
export function defaultKeys(entries, first, last) {
const range = rangeKeys(entries, first, last);
return spreadKeys(range.length >= 2 ? range : allKeys(entries));
}
const cloudOf = (entry) => (Number.isFinite(entry.cloud) ? entry.cloud : 101);
/**
* One picture per calendar month or year among `keys`: the clearest, or the
* earliest of equally clear ones. Wayback states no cloud, so it keeps the first.
*/
export function thinKeys(entries, keys, period) {
const chosen = new Set(keys);
const best = new Map();
for (const entry of entries) {
if (!chosen.has(entry.key)) continue;
const bucket = String(entry.date).slice(0, period === 'year' ? 4 : 7);
const held = best.get(bucket);
if (!held || cloudOf(entry) < cloudOf(held)) best.set(bucket, entry);
}
const kept = new Set([...best.values()].map((entry) => entry.key));
return entries.filter((entry) => kept.has(entry.key)).map((entry) => entry.key);
}
/** The chosen rows, in the order they play whatever order they were ticked in. */
export function chosenEntries(entries, keys) {
const chosen = new Set(keys);
return playOrder(entries).filter((entry) => chosen.has(entry.key));
}
/**
* How a picture is dated on the export. A Wayback date is Esri's estimate of when
* the pixels were taken, or only the release date when it has none.
*/
export function pictureLabel(archive, entry) {
if (archive !== WAYBACK_ID) return entry.date;
if (entry.note === 'taken') return `~${entry.date}`;
return entry.date ? `Release ${entry.date}` : 'Release, undated';
}
/**
* The ground an evolution shows, as a frame in CSS pixels: the view, or the
* export frame at the view's scale, upright at the bearing it was drawn at.
* Nothing needs to be on screen, since every picture is fetched for it.
*/
export function evolutionFrame(view, exportFrame) {
if (!exportFrame?.points) return { ...view };
const angle = compassAngle(exportFrame.angle);
const box = turnedBox(exportFrame.points, angle);
const perPixel = mercatorPerPixel(view.zoom);
const [lng, lat] = fromMercator(...box.centre);
return {
...view,
lng,
lat,
width: Math.max(1, Math.round(Math.abs(box.width) / perPixel)),
height: Math.max(1, Math.round(Math.abs(box.height) / perPixel)),
bearing: angle,
};
}
/**
* How many output pixels one CSS pixel of the frame becomes: the screen's density,
* held under `edge` on the longer side.
*/
export function pictureScale(frame, edge, density = 1) {
const most = edge / Math.max(1, frame.width, frame.height);
return Math.max(Number.EPSILON, Math.min(Math.max(1, density), most));
}
/**
* The tiles that draw one picture of `frame` at `pixelScale`, each with the
* matrix that lays its pixels on the output.
*
* The level holds about one tile pixel per output pixel, capped at the
* provider's native level so nothing is bought that is only upsampled; the proxy
* magnifies past it for free. Only tiles that touch the output are listed, which
* matters on a turned frame. The matrices are composed in doubles here and handed
* to the canvas in output pixels, never as Mercator metres.
*/
export function pictureTiles(frame, provider, pixelScale) {
const size = provider?.tile_size ?? 256;
const shift = Math.log2(size / 256);
const native = Math.floor((provider?.max_native_zoom ?? provider?.max_zoom ?? 18) - shift);
const perOutputPixel = mercatorPerPixel(frame.zoom) / pixelScale;
const wanted = Math.round(Math.log2(WORLD / (size * perOutputPixel)));
const z = Math.max(0, Math.min(native, wanted));
const count = 2 ** z;
const span = WORLD / count;
const width = Math.max(1, Math.round(frame.width * pixelScale));
const height = Math.max(1, Math.round(frame.height * pixelScale));
const toGround = compose(screenToMercator(frame), scale(1 / pixelScale));
const toOutput = invert(toGround);
const corners = [[0, 0], [width, 0], [0, height], [width, height]];
const ground = corners.map(([x, y]) => apply(toGround, x, y));
const columns = ground.map(([x]) => (x + HALF) / span);
const rows = ground.map(([, y]) => (HALF - y) / span);
const tiles = [];
const firstRow = Math.max(0, Math.floor(Math.min(...rows)));
const lastRow = Math.min(count - 1, Math.floor(Math.max(...rows)));
for (let ty = firstRow; ty <= lastRow; ty += 1) {
for (let tx = Math.floor(Math.min(...columns)); tx <= Math.floor(Math.max(...columns)); tx += 1) {
const matrix = compose(toOutput, {
a: span / size, b: 0, c: 0, d: -span / size, e: tx * span - HALF, f: HALF - ty * span,
});
if (!touches(matrix, size, width, height)) continue;
tiles.push({ z, x: ((tx % count) + count) % count, y: ty, size, matrix });
}
}
return { width, height, z, tiles };
}
/**
* Whether a tile laid by `matrix` overlaps the output. Two rectangles are apart
* only along one of their own sides, so it is enough to look from each.
*/
function touches(matrix, size, width, height) {
const square = [[0, 0], [size, 0], [0, size], [size, size]].map(([x, y]) => apply(matrix, x, y));
if (!overlaps(square, width, height)) return false;
const back = invert(matrix);
const output = [[0, 0], [width, 0], [0, height], [width, height]].map(([x, y]) => apply(back, x, y));
return overlaps(output, size, size);
}
function overlaps(points, width, height) {
const xs = points.map(([x]) => x);
const ys = points.map(([, y]) => y);
return Math.max(...xs) > 0 && Math.min(...xs) < width && Math.max(...ys) > 0 && Math.min(...ys) < height;
}
/** Whether two pictures hold the same pixels: one Wayback release can repeat another. */
export function samePixels(first, second) {
if (!first || !second || first.length !== second.length) return false;
for (let index = 0; index < first.length; index += 1) {
if (first[index] !== second[index]) return false;
}
return true;
}
/** How many columns a contact sheet of `count` pictures is laid in. */
export function sheetColumns(count) {
return Math.max(1, Math.min(6, Math.ceil(Math.sqrt(count))));
}
/**
* The output scale of one sheet cell: the sheet's width shared out, never finer
* than the screen, and small enough that the whole sheet stays a PNG the plates
* route takes (24 MB) when a tall frame stacks its rows.
*/
export function sheetCellScale(frame, count, density = 1, gap = 8) {
const columns = sheetColumns(count);
const rows = Math.ceil(Math.max(1, count) / columns);
const width = Math.max(1, frame.width);
const height = Math.max(1, frame.height);
const byWidth = (SHEET_WIDTH - gap * (columns + 1)) / columns / width;
const byArea = Math.sqrt(SHEET_PIXELS / (columns * rows * width * height));
return Math.max(Number.EPSILON, Math.min(Math.max(1, density), byWidth, byArea));
}
/** Where each picture's day sits on a line from the first to the last, 0 to 1. */
export function timelinePositions(dates) {
const times = dates.map((date) => Date.parse(`${String(date).slice(0, 10)}T00:00:00Z`));
const known = times.filter(Number.isFinite);
if (!known.length) return dates.map((_, index) => (dates.length > 1 ? index / (dates.length - 1) : 0));
const first = Math.min(...known);
const last = Math.max(...known);
return times.map((time, index) => {
if (!Number.isFinite(time)) return dates.length > 1 ? index / (dates.length - 1) : 0;
return last > first ? (time - first) / (last - first) : 0;
});
}