The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* Sentinel-2 basemap choices: which layer, and over which window.
*
* Both ride on the provider id as a variant — `sentinel2~SWIR~2026-05-01~2026-05-31`
* — which is what the tile URL, the capture and the disk cache all key on
* (engine/sentinel.py owns the same format on the backend). The map only ever
* has to know the id; nothing downstream can forget the window.
*/
export const SENTINEL_ID = 'sentinel2';
const SEP = '~';
/** Layer ids we know the reason for. The real list comes from the backend
* (/api/satellite/sentinel/layers) — a user's instance serves whatever its
* configuration says, and only the instance knows. */
export const DEFAULT_LAYER = 'TRUE_COLOR';
/**
* The cloud ceiling in percent, sent on every request. 100 means no filter,
* which is the default because a configuration instance ships one of its own
* (20% in the standard template) and a scene above it renders as nothing at
* all. Lower it and cloudy passes drop out of the calendar, out of "most
* recent" and out of the tiles together — one number, one meaning.
*/
export const DEFAULT_MAXCC = 100;
/**
* Pack a layer + window + cloud ceiling into a provider id. The plain default
* (true colour, most recent, no ceiling) stays the bare id: it must not read as
* a second provider.
*/
export function variantId(
baseId,
{ layer = DEFAULT_LAYER, from = '', to = '', maxcc = DEFAULT_MAXCC } = {}
) {
if (baseId !== SENTINEL_ID) return baseId;
const windowed = from && to;
const ceiling = validMaxcc(maxcc) ? Math.round(maxcc) : DEFAULT_MAXCC;
if ((layer || DEFAULT_LAYER) === DEFAULT_LAYER && !windowed && ceiling === DEFAULT_MAXCC) {
return baseId;
}
const parts = [baseId, layer || DEFAULT_LAYER];
if (windowed) parts.push(from, to);
if (ceiling !== DEFAULT_MAXCC) parts.push(`CC${ceiling}`);
return parts.join(SEP);
}
/** True for a cloud ceiling the backend will accept: a whole 0…100. */
export function validMaxcc(value) {
return Number.isFinite(value) && value >= 0 && value <= 100 && Number.isInteger(value);
}
/** How a ceiling reads in the UI. */
export function maxccLabel(maxcc) {
return maxcc >= DEFAULT_MAXCC ? 'Any cloud' : `Up to ${maxcc}%`;
}
/**
* Is this pass above the ceiling? Sentinel Hub drops such a scene before
* rendering, so the day is not selectable — the calendar says so rather than
* spending a tile on a black square. A pass the service gave no figure for is
* never filtered: an unknown is not a reason to hide real imagery.
*/
export function overCloudCeiling(cloud, maxcc = DEFAULT_MAXCC) {
if (cloud === null || cloud === undefined) return false;
return cloud > maxcc;
}
/**
* The newest pass at or before `today` that the ceiling still allows — what
* "most recent" actually renders once a ceiling is set. `days` is the
* `{ 'YYYY-MM-DD': {cloud} }` map a month lookup returns.
*/
export function latestAllowedPass(days, today, maxcc = DEFAULT_MAXCC) {
return (
Object.keys(days || {})
.filter((day) => day <= today && !overCloudCeiling(days[day]?.cloud, maxcc))
.sort()
.at(-1) ?? ''
);
}
/** ISO date (YYYY-MM-DD) for a Date, in UTC — the calendar Sentinel-2 passes
* are dated by, not the viewer's timezone. */
export function isoDay(date) {
return date.toISOString().slice(0, 10);
}
/** `n` days before `date`, as an ISO day. */
export function daysBefore(n, date = new Date()) {
const out = new Date(date.getTime());
out.setUTCDate(out.getUTCDate() - n);
return isoDay(out);
}
/** True when both ends are ISO days in order — the shape the backend accepts,
* checked here so a half-typed date never becomes a request. */
export function validWindow(from, to) {
const iso = /^\d{4}-\d{2}-\d{2}$/;
if (!iso.test(from || '') || !iso.test(to || '')) return false;
if (Number.isNaN(Date.parse(from)) || Number.isNaN(Date.parse(to))) return false;
return from <= to;
}
/** True for a single well-formed ISO day. */
export function validDay(day) {
return validWindow(day, day);
}
/**
* The calendar month a day belongs to, and month arithmetic on 'YYYY-MM'.
* Day 1 of the target month, so a 31st can never spill into the next one.
*/
export function monthOf(day) {
return (day || isoDay(new Date())).slice(0, 7);
}
export function addMonths(month, delta) {
const [y, m] = month.split('-').map(Number);
const d = new Date(Date.UTC(y, m - 1 + delta, 1));
return isoDay(d).slice(0, 7);
}
export function monthLabel(month) {
const [y, m] = month.split('-').map(Number);
return new Date(Date.UTC(y, m - 1, 1)).toLocaleDateString('en-US', {
month: 'long',
year: 'numeric',
timeZone: 'UTC',
});
}
/** First and last day of a month, as ISO days — the span a pass lookup covers. */
export function monthBounds(month) {
const [y, m] = month.split('-').map(Number);
return {
from: `${month}-01`,
to: isoDay(new Date(Date.UTC(y, m, 0))), // day 0 of next month = last of this
};
}
/**
* A month as calendar cells, Monday-first, padded with nulls so the first day
* lands under its weekday. Trailing padding is left out — an empty last row is
* just whitespace.
*/
export function monthGrid(month) {
const { to } = monthBounds(month);
const days = Number(to.slice(8));
const [y, m] = month.split('-').map(Number);
const firstWeekday = (new Date(Date.UTC(y, m - 1, 1)).getUTCDay() + 6) % 7; // Mon = 0
const cells = Array(firstWeekday).fill(null);
for (let d = 1; d <= days; d++) cells.push(`${month}-${String(d).padStart(2, '0')}`);
return cells;
}
/**
* How usable a pass is, at a glance. Sentinel-2 revisits every ~5 days but most
* passes are cloud: the point of showing cover is to skip the ones that cost a
* tile to discover are white.
*/
export function cloudClass(cloud) {
if (cloud === null || cloud === undefined) return 'unknown';
if (cloud < 20) return 'clear';
if (cloud < 60) return 'part';
return 'cloudy';
}
/** Cloud cover as a short badge — the reason to skip a date without paying for
* a tile to find out. */
export function cloudLabel(cloud) {
if (cloud === null || cloud === undefined) return '';
return `${Math.round(cloud)}% cloud`;
}
/** Stable place bucket for pass and coverage caches (about 100 m). */
export function sentinelPlaceKey(lat, lon) {
return `${Number(lat).toFixed(3)},${Number(lon).toFixed(3)}`;
}
/** Local API request that verifies rendered coverage for one candidate day. */
export function coverageRequestPath({ lat, lon, layer, date, maxcc = DEFAULT_MAXCC }) {
const query = new URLSearchParams({
lat: String(lat),
lon: String(lon),
layer,
date,
maxcc: String(validMaxcc(maxcc) ? maxcc : DEFAULT_MAXCC),
});
return `/api/satellite/sentinel/coverage?${query}`;
}
/** Keep the working map unless the candidate day passed its coverage check. */
export function dateAfterCoverage(current, candidate, available) {
return available ? candidate : current;
}