The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* Photograph the guide's pages in the real app.
*
* npm run guide:shots # every picture
* npm run guide:shots -- media proof # only these, and the ones they start from
*
* Starts a private Azimut on a throwaway workspace, files the demo case into it through
* the routes the app itself uses (demo.mjs), serves the current frontend over it, and
* takes each picture `src/lib/guide.js` names, staged as stages.mjs says. Writes
* `src/assets/guide/<shot>.webp` and, beside it, `<shot>.json`: the rectangle of every
* `data-guide` anchor drawn on that picture.
*
* A picture keeps the part of the window its frames are in, plus a margin, so a page
* shows the controls it explains rather than the whole app. It fails when an anchor the
* guide cites is missing: a control that moved is followed, a control that went is
* reported instead of framed in the void.
*
* A stage with a `film` also writes `<shot>.webm`, which the guide plays in the picture's
* place, the picture standing for it for a reader who asked for less motion.
*
* The Extension tabs are taken in a second browser with the capture extension loaded
* (extension.mjs), over OpenStreetMap's own tiles.
*
* Needs `uv` for the backend, ffmpeg on PATH for the demo video, and the network for the
* public imagery and the map tiles the pictures are drawn from. Horizon draws 3D, so the
* browser asks for the GPU and falls back to software where there is none. Run it
* before a release, look at the pictures it changed, and commit them with the release.
*/
import { chromium } from '@playwright/test';
import { spawn, spawnSync } from 'node:child_process';
import { linkSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { build, createServer, loadConfigFromFile, mergeConfig, preview } from 'vite';
import { copyPasses } from './airbase.mjs';
import { buildDemo, CHANNEL, IMAGERY } from './demo.mjs';
import { openExtension } from './extension.mjs';
import { DEFAULT_WINDOW, STAGES } from './stages.mjs';
const frontend = join(dirname(fileURLToPath(import.meta.url)), '..');
const root = join(frontend, '..');
const OUT = join(frontend, 'src/assets/guide');
const API_PORT = Number(process.env.GUIDE_API_PORT ?? 18571);
const WEB_PORT = Number(process.env.GUIDE_WEB_PORT ?? 18572);
const api = `http://127.0.0.1:${API_PORT}`;
const web = `http://127.0.0.1:${WEB_PORT}`;
/** The tool, without the app's bars: the guide's own menu and tabs stand for them. */
const CLIP = 'main.canvas .canvas-body';
/** Room kept round the frames when a picture is cut down to them, in CSS pixels. */
const MARGIN = 28;
/** The tallest a picture may be against its width, so the guide shows it whole. */
const LANDSCAPE = 0.66;
/** Anchors that frame a group of controls rather than the first one found. */
const UNION = new Set(['start.stages', 'start.tabs', 'notebook.insert', 'compare.session', 'proof.save', 'proof.meta', 'inspect.file', 'horizon.views']);
const say = (line) => process.stdout.write(` ${line}\n`);
const pause = (ms) => new Promise((done) => setTimeout(done, ms));
async function until(what, test, timeout = 60_000) {
const end = Date.now() + timeout;
for (;;) {
try {
if (await test()) return;
} catch {
/* not up yet */
}
if (Date.now() > end) throw new Error(`gave up waiting for ${what}`);
await pause(250);
}
}
async function call(method, path, body) {
const send = () =>
fetch(`${api}${path}`, {
method,
headers: body instanceof FormData || !body ? undefined : { 'content-type': 'application/json' },
body: body instanceof FormData ? body : body && JSON.stringify(body),
});
// The server drops a kept-alive connection after a few idle seconds (an ffmpeg encode
// is enough), and a request sent on it as it closes fails before reaching it. Sent
// again a moment later it is safe, since that request never arrived; the pool may
// hand out another dying connection first, so it is tried a few times.
let response = null;
for (let attempt = 0; !response; attempt += 1) {
response = await send().catch(async (error) => {
if (error?.message !== 'fetch failed' || attempt >= 3) throw error;
await new Promise((resolve) => setTimeout(resolve, 250));
return null;
});
}
if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${await response.text()}`);
return response.json();
}
/** Where each anchor and focus element stands, and the part of the clip that holds them. */
async function measure(page, { anchors, clip, crop, focus }) {
return page.evaluate(
({ anchors, clip, crop, focus, union, margin, landscape }) => {
const seen = (el) => {
const box = el.getBoundingClientRect();
return box.width > 0 && box.height > 0 ? box : null;
};
const frame = document.querySelector(clip).getBoundingClientRect();
const boxes = {};
const problems = [];
for (const anchor of anchors) {
const shown = [...document.querySelectorAll(`[data-guide="${anchor}"]`)].map(seen).filter(Boolean);
if (!shown.length) {
problems.push(`${anchor} is not on the page`);
continue;
}
const taken = union.includes(anchor) ? shown : shown.slice(0, 1);
const left = Math.min(...taken.map((b) => b.left));
const top = Math.min(...taken.map((b) => b.top));
const right = Math.max(...taken.map((b) => b.right));
const bottom = Math.max(...taken.map((b) => b.bottom));
boxes[anchor] = { left, top, right, bottom };
}
const held = [...Object.values(boxes)];
for (const selector of focus) {
const el = [...document.querySelectorAll(selector)].find(seen);
if (el) {
const b = el.getBoundingClientRect();
held.push({ left: b.left, top: b.top, right: b.right, bottom: b.bottom });
} else problems.push(`${selector} is not on the page`);
}
// the part kept: the whole clip, or what the frames and focus need with a margin
let cut = { left: frame.left, top: frame.top, right: frame.right, bottom: frame.bottom };
if (crop !== 'full' && held.length) {
cut = {
left: Math.max(frame.left, Math.min(...held.map((b) => b.left)) - margin),
top: Math.max(frame.top, Math.min(...held.map((b) => b.top)) - margin),
right: Math.min(frame.right, Math.max(...held.map((b) => b.right)) + margin),
bottom: Math.min(frame.bottom, Math.max(...held.map((b) => b.bottom)) + margin),
};
// never a sliver: a picture narrower than this reads as a crop, not a screen
const grow = (lo, hi, least, min, max) => {
const missing = Math.min(least, max - min) - (hi - lo);
if (missing <= 0) return [lo, hi];
let a = lo - missing / 2;
let b = hi + missing / 2;
if (a < min) [a, b] = [min, b + (min - a)];
if (b > max) [a, b] = [a - (b - max), max];
return [Math.max(min, a), Math.min(max, b)];
};
[cut.left, cut.right] = grow(cut.left, cut.right, 620, frame.left, frame.right);
[cut.top, cut.bottom] = grow(cut.top, cut.bottom, 360, frame.top, frame.bottom);
// a tall cut, a panel's column, takes in the screen beside it rather than
// standing as a strip the guide would have to scroll through
[cut.left, cut.right] = grow(cut.left, cut.right, (cut.bottom - cut.top) / landscape, frame.left, frame.right);
}
const round = (v) => Math.round(v * 10) / 10;
const rects = Object.fromEntries(
Object.entries(boxes).map(([anchor, b]) => {
const x = Math.max(b.left, cut.left);
const y = Math.max(b.top, cut.top);
const w = Math.min(b.right, cut.right) - x;
const h = Math.min(b.bottom, cut.bottom) - y;
if (w < 4 || h < 4) {
const at = [b.left, b.top, b.right, b.bottom].map(Math.round).join(', ');
problems.push(`${anchor} lies outside the picture (at ${at}, the tool spans ${Math.round(frame.left)}–${Math.round(frame.right)} × ${Math.round(frame.top)}–${Math.round(frame.bottom)})`);
}
return [anchor, { x: round(x - cut.left), y: round(y - cut.top), w: round(w), h: round(h) }];
})
);
return {
cut: { x: cut.left, y: cut.top, width: cut.right - cut.left, height: cut.bottom - cut.top },
rects,
problems,
};
},
{ anchors, clip, crop, focus, union: [...UNION], margin: MARGIN, landscape: LANDSCAPE }
);
}
/** A PNG of the cut, re-encoded as WebP by the browser that took it. */
async function photograph(page, cut) {
const png = await page.screenshot({ clip: cut, animations: 'disabled', caret: 'hide' });
const dataUrl = await page.evaluate(async (b64) => {
const image = new Image();
image.src = `data:image/png;base64,${b64}`;
await image.decode();
const canvas = document.createElement('canvas');
canvas.width = image.naturalWidth;
canvas.height = image.naturalHeight;
canvas.getContext('2d').drawImage(image, 0, 0);
return canvas.toDataURL('image/webp', 0.86);
}, png.toString('base64'));
return Buffer.from(dataUrl.slice(dataUrl.indexOf(',') + 1), 'base64');
}
/** The frames of a film per second, and how wide it is written: a guide picture is seen well under this. */
const FILM_FPS = 25;
const FILM_WIDTH = 1400;
/**
* Play a stage's film and write it: `play` moves the page, takes each frame with
* `frame()`, and answers the frames in the order they run, so a held or a rewound part
* costs no second picture. Two passes at a set rate, so its weight in every download is
* known ahead.
*/
async function film(page, cut, { play, rate }, out, scratch) {
const dir = mkdtempSync(join(scratch, 'film-'));
let taken = 0;
const frame = async () => {
const path = join(dir, `taken-${(taken += 1)}.png`);
await page.screenshot({ path, clip: cut, animations: 'disabled', caret: 'hide' });
return path;
};
const frames = await play({ page, frame });
frames.forEach((path, at) => linkSync(path, join(dir, `${String(at).padStart(4, '0')}.png`)));
const encode = (pass, target) => {
const run = spawnSync(
'ffmpeg',
[
'-hide_banner', '-loglevel', 'error', '-y',
'-framerate', String(FILM_FPS), '-i', join(dir, '%04d.png'),
'-vf', `scale=${FILM_WIDTH}:-2:flags=lanczos,format=yuv420p`,
'-c:v', 'libvpx-vp9', '-b:v', rate, '-pass', String(pass), '-passlogfile', join(dir, 'pass'),
'-row-mt', '1', '-deadline', 'good', '-cpu-used', pass === 1 ? '4' : '1', '-an',
...target,
],
{ stdio: 'inherit' }
);
if (run.status !== 0) throw new Error(`ffmpeg could not write ${out}`);
};
encode(1, ['-f', 'null', process.platform === 'win32' ? 'NUL' : '/dev/null']);
encode(2, [out]);
say(`${out.split(/[\\/]/).pop()} ${Math.round(statSync(out).size / 1024)} kB, ${(frames.length / FILM_FPS).toFixed(1)} s`);
}
/** Wait for the screen to stop changing: requests, fonts, every picture in the clip. */
async function settle(page, clip, extra) {
await page.waitForLoadState('networkidle', { timeout: 15_000 }).catch(() => {});
await page.evaluate(() => document.fonts.ready);
await page
.waitForFunction(
(clip) => [...document.querySelectorAll(`${clip} img`)].every((img) => img.complete && (img.naturalWidth > 0 || img.loading === 'lazy')),
clip,
{ timeout: 20_000 }
)
.catch(() => say(' some pictures had not loaded'));
await pause(extra);
}
async function run() {
const wanted = process.argv.slice(2);
const scratch = mkdtempSync(join(tmpdir(), 'azimut-guide-'));
const home = join(scratch, 'workspace');
// The public imagery the maps are drawn from, added as a user adds a provider; the
// maps opening on the demo's ground; and a stand-in Copernicus id, so Detect shows
// its tools rather than its setup. The id reaches nothing: no stage runs a detection.
mkdirSync(join(home, '.azimut/settings'), { recursive: true });
writeFileSync(
join(home, '.azimut/settings/settings.json'),
JSON.stringify({
tile_providers: [IMAGERY],
update_check_on_start: false,
home_view: { ...CHANNEL, zoom: 15 },
api_keys: { sentinelhub: 'guide-demo-instance' },
})
);
// the two Sentinel-2 passes the analyzer journey is photographed on, from a tile cache
// that already holds them: tiles only, so no Copernicus request is spent (airbase.mjs)
const passes = copyPasses(home);
say(passes ? `${passes} cached Sentinel-2 tile sets for the airbase` : 'no cached airbase passes: its pictures will fail');
// a group of its own, so stopping it stops the app `uv` started too, not uv alone
const own = process.platform !== 'win32';
const backend = spawn('uv', ['run', 'azimut', '--port', String(API_PORT), '--no-browser'], {
cwd: root,
env: { ...process.env, AZIMUT_HOME: home },
stdio: ['ignore', 'ignore', 'inherit'],
detached: own,
});
let vite = null;
let browser = null;
let ext = null;
const failed = [];
const made = [];
try {
await until('the backend', async () => (await fetch(`${api}/api/cases`)).ok);
// The app as it ships, built into the scratch folder: a dev server reloads the page
// whenever it meets a new dependency, which throws away what a stage set up. The
// build never lands in src/azimut/static, which the owner's running app serves.
const { config } = await loadConfigFromFile({ command: 'build', mode: 'production' }, join(frontend, 'vite.config.js'));
const dist = join(scratch, 'dist');
const shared = mergeConfig(config, { root: frontend, configFile: false, logLevel: 'warn', cacheDir: join(scratch, 'vite') });
await build(mergeConfig(shared, { build: { outDir: dist, emptyOutDir: true } }));
vite = await preview(
mergeConfig(shared, {
build: { outDir: dist },
preview: { host: '127.0.0.1', port: WEB_PORT, strictPort: true, proxy: { '/api': api, '/files': api } },
})
);
const reading = mergeConfig(shared, { server: { middlewareMode: true, hmr: false }, appType: 'custom' });
// it only reads the guide's list: no file watchers, which a busy machine may be out of
reading.server.watch = null;
const loader = await createServer(reading);
const { allShots } = await loader.ssrLoadModule('/src/lib/guide.js');
await loader.close();
const shots = new Map(allShots().map((one) => [one.shot, one.anchors]));
const staged = new Set(STAGES.map((stage) => stage.shot));
for (const name of shots.keys()) if (!staged.has(name)) failed.push(`${name} is in the guide but has no stage`);
for (const name of staged) if (!shots.has(name)) failed.push(`${name} is staged but the guide shows no such picture`);
if (failed.length) throw new Error(failed.join('\n'));
// a picture taken from another needs that one staged first, and that one its own:
// read last to first, a chain is followed back to its start in one pass
const take = new Set(wanted.length ? wanted : staged);
for (const stage of [...STAGES].reverse()) if (take.has(stage.shot) && stage.from) take.add(stage.from);
// WebGL on the GPU for Horizon's 3D; 2D canvases in software, since a 2D canvas read
// back under Vulkan comes out empty, and a proof saved from it is a blank picture
browser = await chromium.launch({
channel: 'chromium',
args: ['--use-angle=vulkan', '--enable-features=Vulkan', '--ignore-gpu-blocklist', '--enable-gpu', '--disable-accelerated-2d-canvas'],
});
const demo = await buildDemo({ call, scratch });
say(`demo case filed: ${demo.caseId}`);
const context = await browser.newContext({
viewport: DEFAULT_WINDOW,
deviceScaleFactor: 2,
colorScheme: 'dark',
reducedMotion: 'reduce',
});
// the tour, this version's What's new and Find's beta notice would cover every
// picture: the workspace has taken the one and read the others (components/Onboarding.svelte)
const { version } = await call('GET', '/api/health');
await call('PUT', '/api/settings/prefs', { tour: 'done', whats_new_seen: version, find_beta_seen: true });
await context.addInitScript(({ caseId }) => {
localStorage.setItem('azimut:lastCase', caseId);
localStorage.setItem('azimut:theme', 'dark');
}, { caseId: demo.caseId });
const page = await context.newPage();
page.setDefaultTimeout(20_000);
let loads = 0;
const go = async (hash) => {
loads += 1;
await page.goto(`${web}/?load=${loads}#${hash}`);
await page.locator(CLIP).waitFor();
await page.addStyleTag({ content: '.toasts { display: none !important; }' });
await pause(1200);
};
mkdirSync(OUT, { recursive: true });
for (const stage of STAGES) {
if (!take.has(stage.shot)) continue;
const clip = stage.clip ?? CLIP;
// the extension's pictures are taken in its own browser, on the map tab
const outside = stage.browser === 'extension';
try {
if (outside && !ext) {
const { ingest_token: token } = await call('POST', '/api/settings/ingest-token');
ext = await openExtension({
source: join(root, 'extension'),
scratch,
api,
token,
caseId: demo.caseId,
view: { ...CHANNEL, zoom: 16 },
window: stage.window ?? DEFAULT_WINDOW,
});
}
const shooter = outside ? ext.map : page;
if (!outside) await page.setViewportSize(stage.window ?? DEFAULT_WINDOW);
if (stage.from) await pause(300);
await stage.run({ page, go, demo, ext, passes });
// The case sidebar is a second column the tool pages do not explain. A picture
// taken from another keeps it as it was: pressing the toggle would close the
// menu that picture is about.
const sidebar = page.locator('aside[data-guide="start.sidebar"]');
if (!outside && !stage.from && (await sidebar.isVisible()) !== Boolean(stage.sidebar)) {
await page.locator('.topbar button[title="Toggle case sidebar"]').click();
}
await settle(shooter, clip, stage.settle ?? (stage.map ? 5000 : 800));
await shooter.mouse.move(1, 1);
// no caret or focus ring on the field the stage typed in; a picture taken from
// another keeps its focus, which may be what holds its menu open
if (!stage.from) await shooter.evaluate(() => document.activeElement?.blur?.());
const anchors = shots.get(stage.shot);
const { cut, rects, problems } = await measure(shooter, {
anchors,
clip,
crop: stage.crop,
focus: stage.focus ?? [],
});
if (problems.length) throw new Error(problems.join('; '));
const picture = await photograph(shooter, cut);
writeFileSync(join(OUT, `${stage.shot}.webp`), picture);
writeFileSync(
join(OUT, `${stage.shot}.json`),
`${JSON.stringify({ width: Math.round(cut.width), height: Math.round(cut.height), anchors: rects }, null, 2)}\n`
);
if (stage.film) await film(shooter, cut, stage.film, join(OUT, `${stage.shot}.webm`), scratch);
made.push(stage.shot);
say(`${stage.shot}.webp ${Math.round(picture.length / 1024)} kB, ${Object.keys(rects).length} frames`);
} catch (error) {
failed.push(`${stage.shot}: ${String(error.message ?? error).split('\n')[0]}`);
// what the screen showed when it failed, for whoever is fixing the stage
if (process.env.GUIDE_DEBUG_DIR) {
const shown = outside ? ext?.map : page;
await shown?.screenshot({ path: join(process.env.GUIDE_DEBUG_DIR, `${stage.shot}.png`) }).catch(() => {});
}
} finally {
// a picture taken from another one closes what it opened, for the next one
if (stage.from && stage.after !== false) {
if (stage.after) await stage.after({ page }).catch(() => {});
else await page.keyboard.press('Escape').catch(() => {});
await pause(300);
}
}
}
// a full run leaves no picture the guide no longer shows
if (!wanted.length && !failed.length) {
// a hidden entry is an editor's or a system's, never a picture
for (const file of readdirSync(OUT)) {
if (!file.startsWith('.') && !shots.has(file.replace(/\.(webp|json|webm)$/, ''))) unlinkSync(join(OUT, file));
}
}
} finally {
await ext?.close();
await browser?.close();
await vite?.close();
if (own) {
try {
process.kill(-backend.pid, 'SIGTERM');
} catch {
/* already gone */
}
} else backend.kill();
rmSync(scratch, { recursive: true, force: true });
}
if (failed.length) {
process.stderr.write(`\nSome pictures could not be made:\n${failed.map((f) => ` ${f}`).join('\n')}\n`);
process.exit(1);
}
say(`${made.length} pictures`);
}
run().catch((error) => {
process.stderr.write(`${error.stack ?? error}\n`);
process.exit(1);
});