Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
19.1 KB
Raw Blame
/**
 * Turn two captured map frames into the comparison the analyst is reading.
 *
 * This composes pixels, not the Compare DOM: provider menus, zoom buttons and
 * the swipe handle are controls. The picture is the two aligned images plus
 * what explains them: which source and date each side is, where the camera
 * was, a scale bar and north arrow, the Difference legend, the credits, and
 * the annotations projected onto the ground they were pinned to.
 *
 * Everything is placed from each side's camera frame (`groundFrame.js`), so
 * the composer needs no map: a projection is recomputed from the frame, and
 * a change mask computed for an earlier camera is laid where its ground is.
 */

import { comparisonAnnotations, drawAnnotations, onSide, stampInk } from './compareAnnotations.js';
import { AMBER, INK_ON_DARK, drawSignature, signatureWidth } from '../brandMark.js';
import {
  apply,
  compose,
  frameToFrame,
  groundPerPixel,
  invert,
  scale as scaleBy,
  screenToMercator,
  toMercator,
} from './groundFrame.js';
import { CHANGE_PALETTES } from './changeAssist.js';
import { fileDate } from './pictureDate.js';

const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
const INK = '#f3f4f6';
const MUTED = '#a7adb5';
const BAND = '#0f1114';
const ACCENT = '#e8a33d';
const FONT = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
const MONO = 'ui-monospace, "SF Mono", "Cascadia Code", monospace';

/** The inks an export is laid out in, for the other composers to share. */
export const EXPORT_STYLE = Object.freeze({ INK, MUTED, BAND, ACCENT, FONT, MONO });

/** The plate a mark's label sits on, and the ink written on it (`compareAnnotations.js`). */
const LABEL_INKS = ['#f5f6f7'];

const rgbHex = ([red, green, blue]) => `#${[red, green, blue]
  .map((value) => Number(value).toString(16).padStart(2, '0')).join('')}`;

/**
 * The colours a GIF must keep exactly, as the `keep` form field: the colours
 * visible in Difference first, then every mark's colour and the ink of its
 * numeral, followed by the export's own inks and the signature's. The server
 * builds each frame's palette around them; the imagery gets the rest.
 *
 * `changePalette` is supplied only when the exported comparison carries a
 * Difference reading. The final PNG frames already contain the reading; this
 * list keeps its palette from being changed while the GIF encoder quantizes
 * the satellite imagery around it.
 */
export function gifColours(annotations = [], { signed = false, changePalette = null } = {}) {
  const colours = [];
  if (changePalette) {
    const palette = CHANGE_PALETTES[changePalette] ?? CHANGE_PALETTES.directional;
    colours.push(...Object.values(palette).map(rgbHex));
  }
  for (const mark of comparisonAnnotations(annotations)) {
    colours.push(mark.colour);
    if (mark.kind === 'number') colours.push(stampInk(mark));
  }
  colours.push(ACCENT, INK, MUTED, BAND, ...LABEL_INKS);
  if (signed) colours.push(INK_ON_DARK, AMBER);
  const kept = [];
  for (const colour of colours) {
    const hex = String(colour).toLowerCase();
    if (/^#[0-9a-f]{6}$/.test(hex) && !kept.includes(hex)) kept.push(hex);
  }
  return kept.slice(0, 32).join(',');
}

/**
 * Sign a footer band: the Azimut lockup at its right end, centred on `middle`.
 * Answers the width it took, so the credits beside it can stop short.
 */
export function signFooter(ctx, right, middle, scale) {
  return drawSignature(ctx, right, middle, { height: 15 * scale });
}

/** How much of a footer row the signature takes, gap included. */
export const signatureRoom = (scale) => signatureWidth(15 * scale) + 18 * scale;

/**
 * What an exported comparison is called: its title, then the dates of its two
 * pictures, which say what the file shows. When neither picture is dated, the
 * moment of the export stands in, so the name still tells two exports apart.
 *
 * @param {string} [title]
 * @param {{ a?: string | null, b?: string | null }} [dates] each a day or a UTC instant
 * @param {Date} [at]
 */
export function comparisonFilename(title = '', { a = null, b = null } = {}, at = new Date()) {
  const stem = String(title).trim().replace(/[\\/:*?"<>|#%]+/g, ' ').replace(/\s+/g, ' ').slice(0, 80);
  const first = fileDate(a);
  const second = fileDate(b);
  if (first || second) {
    const dates = `${first || 'undated'}_${second || 'undated'}`;
    return stem ? `${stem} ${dates}` : `compare-${dates}`;
  }
  const stamp = at.toISOString().replace(/[^0-9]/g, '').slice(0, 12);
  return stem ? `${stem} ${stamp}` : `compare-${stamp || 'undated'}`;
}

/**
 * The dates a saved comparison files for its two pictures, as form fields.
 *
 * Two instants rather than a range: the image does not say anything happened
 * between them. A date its provider only estimated goes with `exact: false`.
 *
 * @param {{ a?: object, b?: object }} dates each side's `pictureDate()` reading
 * @returns {Array<[string, string]>}
 */
export function pictureDateFields(dates) {
  const fields = [];
  for (const side of ['a', 'b']) {
    const picture = dates?.[side] ?? {};
    if (!picture.imageryWhen) continue;
    fields.push([`imagery_${side}`, picture.imageryWhen]);
    if (picture.imageryExact === false) fields.push([`imagery_${side}_exact`, 'false']);
  }
  return fields;
}

function canvasOf(width, height, makeCanvas) {
  const canvas = makeCanvas ? makeCanvas() : document.createElement('canvas');
  canvas.width = Math.max(1, Math.round(width));
  canvas.height = Math.max(1, Math.round(height));
  return canvas;
}

/** `[lon, lat]` → pixel of a captured canvas, from the frame it was captured at. */
export function captureProjection(capture, offsetX = 0, offsetY = 0) {
  const pixelScale = capture.canvas.width / capture.frame.width;
  const toPixels = compose(scaleBy(pixelScale), invert(screenToMercator(capture.frame)));
  return ([lon, lat]) => {
    const [x, y] = apply(toPixels, ...toMercator(lon, lat));
    return [x + offsetX, y + offsetY];
  };
}

/** A round ground length that fits in about `target` pixels. */
export function scaleBarLength(metresPerPixel, target = 120) {
  const raw = metresPerPixel * target;
  const magnitude = 10 ** Math.floor(Math.log10(raw));
  const step = [1, 2, 5, 10].find((candidate) => candidate * magnitude >= raw * 0.62) ?? 10;
  const metres = step * magnitude;
  return { metres, pixels: metres / metresPerPixel };
}

const readableLength = (metres) =>
  metres >= 1000 ? `${metres / 1000} km` : `${metres} m`;

/** A label on a dark rounded plate, as the corners of an export carry them. */
export function drawTag(ctx, text, x, y, { scale, accent = false, align = 'left' }) {
  ctx.font = `700 ${Math.round(12 * scale)}px ${FONT}`;
  const padX = 8 * scale;
  const height = 22 * scale;
  const width = ctx.measureText(text).width + padX * 2;
  const left = align === 'right' ? x - width : x;
  ctx.fillStyle = 'rgba(12,14,17,.82)';
  ctx.beginPath();
  ctx.roundRect?.(left, y, width, height, 5 * scale) ?? ctx.rect(left, y, width, height);
  ctx.fill();
  ctx.fillStyle = accent ? ACCENT : INK;
  ctx.textBaseline = 'middle';
  ctx.fillText(text, left + padX, y + height / 2 + 0.5);
  ctx.textBaseline = 'alphabetic';
}

/**
 * The scale bar and north needle, bottom-aligned at `y`. `pixelScale` is how many
 * output pixels one CSS pixel of `frame` became, when the marks are drawn at
 * another size than the picture was.
 */
export function drawScaleAndNorth(ctx, frame, x, y, { scale, bearing, units, pixelScale = scale }) {
  const perPixel = groundPerPixel(frame) / pixelScale;
  let { metres, pixels } = scaleBarLength(perPixel, 120 * scale);
  let label = readableLength(metres);
  if (units === 'imperial') {
    const feetPerPixel = perPixel * 3.28084;
    const bar = scaleBarLength(feetPerPixel, 120 * scale);
    pixels = bar.pixels;
    label = bar.metres >= 5280 ? `${bar.metres / 5280} mi` : `${bar.metres} ft`;
  }
  const height = 30 * scale;
  const width = pixels + 70 * scale;
  ctx.fillStyle = 'rgba(12,14,17,.78)';
  ctx.beginPath();
  ctx.roundRect?.(x, y - height, width, height, 5 * scale) ?? ctx.rect(x, y - height, width, height);
  ctx.fill();
  const barX = x + 10 * scale;
  const barY = y - 11 * scale;
  ctx.strokeStyle = INK;
  ctx.lineWidth = 2 * scale;
  ctx.beginPath();
  ctx.moveTo(barX, barY - 5 * scale);
  ctx.lineTo(barX, barY);
  ctx.lineTo(barX + pixels, barY);
  ctx.lineTo(barX + pixels, barY - 5 * scale);
  ctx.stroke();
  ctx.fillStyle = INK;
  ctx.font = `600 ${Math.round(11 * scale)}px ${FONT}`;
  ctx.fillText(label, barX + 2 * scale, barY - 7 * scale);
  // north needle, turned with the picture
  const cx = x + width - 18 * scale;
  const cy = y - height / 2;
  ctx.save();
  ctx.translate(cx, cy);
  ctx.rotate((-bearing * Math.PI) / 180);
  ctx.beginPath();
  ctx.moveTo(0, -10 * scale);
  ctx.lineTo(5 * scale, 7 * scale);
  ctx.lineTo(0, 3 * scale);
  ctx.closePath();
  ctx.fill();
  ctx.beginPath();
  ctx.moveTo(0, -10 * scale);
  ctx.lineTo(-5 * scale, 7 * scale);
  ctx.lineTo(0, 3 * scale);
  ctx.closePath();
  ctx.lineWidth = 1.2 * scale;
  ctx.stroke();
  ctx.restore();
}

/** Lay a change mask computed for `mask.frame` onto a picture captured at `target`. */
function drawChangeMask(ctx, mask, target, x, y, pixelScale, opacity) {
  const toTarget = compose(
    scaleBy(pixelScale),
    compose(frameToFrame(mask.frame, target), scaleBy(mask.frame.width / mask.canvas.width))
  );
  ctx.save();
  ctx.beginPath();
  ctx.rect(x, y, target.width * pixelScale, target.height * pixelScale);
  ctx.clip();
  ctx.globalAlpha *= clamp(opacity, 0, 100) / 100;
  ctx.imageSmoothingEnabled = false;
  ctx.setTransform?.(1, 0, 0, 1, 0, 0);
  ctx.transform(toTarget.a, toTarget.b, toTarget.c, toTarget.d, toTarget.e + x, toTarget.f + y);
  ctx.drawImage(mask.canvas, 0, 0);
  ctx.restore();
}

/**
 * @param {object} input
 * @param {{canvas: HTMLCanvasElement, frame: object}} input.a  A as captured, with its camera frame
 * @param {{canvas: HTMLCanvasElement, frame: object}} input.b
 * @param {'side'|'swipe'|'opacity'|'blink'} input.mode
 * @param {object|null} input.change  a finished difference to lay over the view, or null
 */
export function composeComparison({
  a,
  b,
  mode,
  title = '',
  divider = 50,
  opacity = 50,
  blinkB = false,
  change = null,
  annotations = [],
  labelA = 'Imagery A',
  labelB = 'Imagery B',
  attributionA = '',
  attributionB = '',
  view,
  bearing = 0,
  units = 'metric',
  signed = false,
  makeCanvas,
}) {
  if (!a?.canvas?.width || !b?.canvas?.width || !a?.frame || !b?.frame) {
    throw new Error('both maps must be ready before they can be exported');
  }

  if (change && !(change.canvas?.width && change.frame)) {
    throw new Error('the difference must finish before it can be exported');
  }
  const pixelScale = a.canvas.width / a.frame.width;
  const s = pixelScale;
  const side = mode === 'side';
  const mapWidth = side ? a.canvas.width + b.canvas.width : Math.max(a.canvas.width, b.canvas.width);
  const mapHeight = Math.max(a.canvas.height, b.canvas.height);
  const header = Math.round((title ? 64 : 48) * s);
  const legend = change ? Math.round(30 * s) : 0;
  const footer = Math.round(26 * s) + legend;
  const output = canvasOf(mapWidth, header + mapHeight + footer, makeCanvas);
  const ctx = output.getContext('2d');
  if (!ctx) throw new Error('this browser cannot compose the comparison');

  ctx.fillStyle = BAND;
  ctx.fillRect(0, 0, output.width, output.height);

  const top = header;
  const paneB = side ? a.canvas.width : 0;
  // A framed export cuts the imagery, not the marks pinned to it, so what
  // falls outside the pane has to be held there: unclipped, a note anchored
  // off-frame would be painted over the header band.
  const clipped = (offsetX, width, height, draw) => {
    ctx.save();
    ctx.beginPath();
    ctx.rect(offsetX, top, width, height);
    ctx.clip();
    draw();
    ctx.restore();
  };
  // The highlights ride on the image they were asked over, in whatever view.
  const maskOn = (capture, letter, offsetX) => {
    if (!change || change.opacity <= 0) return;
    if (change.base !== 'both' && change.base !== letter) return;
    drawChangeMask(ctx, change, capture.frame, offsetX, top, s, change.opacity);
  };
  const markAnnotations = (capture, letter, offsetX) => {
    const marks = annotations.filter((mark) => onSide(mark, letter));
    clipped(offsetX, capture.canvas.width, capture.canvas.height, () =>
      drawAnnotations(ctx, marks, captureProjection(capture, offsetX, top), { scale: s, units })
    );
  };

  if (side) {
    ctx.drawImage(a.canvas, 0, top);
    ctx.drawImage(b.canvas, paneB, top);
    maskOn(a, 'a', 0);
    maskOn(b, 'b', paneB);
    markAnnotations(a, 'a', 0);
    markAnnotations(b, 'b', paneB);
    ctx.fillStyle = 'rgba(255,255,255,.92)';
    ctx.fillRect(paneB - Math.round(s), top, Math.max(2, Math.round(2 * s)), mapHeight);
    drawTag(ctx, 'A', 12 * s, top + 12 * s, { scale: s, accent: true });
    drawTag(ctx, 'B', paneB + 12 * s, top + 12 * s, { scale: s, accent: true });
  } else if (mode === 'swipe') {
    const split = Math.round((clamp(Number(divider), 0, 100) / 100) * mapWidth);
    ctx.save();
    ctx.beginPath();
    ctx.rect(0, top, split, mapHeight);
    ctx.clip();
    ctx.drawImage(a.canvas, 0, top);
    maskOn(a, 'a', 0);
    markAnnotations(a, 'a', 0);
    ctx.restore();
    ctx.save();
    ctx.beginPath();
    ctx.rect(split, top, mapWidth - split, mapHeight);
    ctx.clip();
    ctx.drawImage(b.canvas, 0, top);
    maskOn(b, 'b', 0);
    markAnnotations(b, 'b', 0);
    ctx.restore();
    ctx.fillStyle = 'rgba(255,255,255,.95)';
    ctx.fillRect(split - Math.round(s), top, Math.max(2, Math.round(2 * s)), mapHeight);
    if (split > 40 * s) drawTag(ctx, 'A', 12 * s, top + 12 * s, { scale: s, accent: true });
    if (mapWidth - split > 40 * s) {
      drawTag(ctx, 'B', mapWidth - 12 * s, top + 12 * s, { scale: s, accent: true, align: 'right' });
    }
  } else if (mode === 'opacity') {
    ctx.drawImage(a.canvas, 0, top);
    maskOn(a, 'a', 0);
    // B's highlights fade with B, as they do on screen.
    ctx.save();
    ctx.globalAlpha = clamp(Number(opacity), 0, 100) / 100;
    ctx.drawImage(b.canvas, 0, top);
    maskOn(b, 'b', 0);
    ctx.restore();
    markAnnotations(a, 'a', 0);
    const onlyB = annotations.filter((mark) => mark.side === 'b');
    clipped(0, b.canvas.width, b.canvas.height, () =>
      drawAnnotations(ctx, onlyB, captureProjection(b, 0, top), { scale: s, units })
    );
    drawTag(ctx, `B ${Math.round(opacity)}%`, mapWidth - 12 * s, top + 12 * s, { scale: s, accent: true, align: 'right' });
  } else {
    const shown = mode === 'blink' && blinkB ? b : a;
    const letter = shown === b ? 'b' : 'a';
    ctx.drawImage(shown.canvas, 0, top);
    maskOn(shown, letter, 0);
    markAnnotations(shown, letter, 0);
    drawTag(ctx, letter.toUpperCase(), 12 * s, top + 12 * s, { scale: s, accent: true });
  }

  drawScaleAndNorth(ctx, a.frame, 12 * s, top + mapHeight - 12 * s, { scale: s, bearing, units });

  // Header: what is being compared, then where.
  const left = 16 * s;
  let line = 0;
  // Where the written header ends on the row the camera reading would share.
  let taken = left;
  if (title) {
    ctx.fillStyle = INK;
    ctx.font = `700 ${Math.round(17 * s)}px ${FONT}`;
    ctx.fillText(title, left, 25 * s, mapWidth * 0.6);
    taken = left + Math.min(ctx.measureText(title).width, mapWidth * 0.6);
    line = 20 * s;
  }
  ctx.font = `600 ${Math.round(12 * s)}px ${FONT}`;
  ctx.fillStyle = ACCENT;
  ctx.fillText('A', left, 24 * s + line);
  ctx.fillStyle = INK;
  ctx.fillText(labelA, left + 14 * s, 24 * s + line, mapWidth * 0.3);
  const labelAWidth = Math.min(ctx.measureText(labelA).width, mapWidth * 0.3);
  const bx = left + 14 * s + labelAWidth + 22 * s;
  ctx.fillStyle = ACCENT;
  ctx.fillText('B', bx, 24 * s + line);
  ctx.fillStyle = INK;
  ctx.fillText(labelB, bx + 14 * s, 24 * s + line, mapWidth * 0.3);
  if (!title) {
    taken = bx + 14 * s + Math.min(ctx.measureText(labelB).width, mapWidth * 0.3);
  }

  const lat = Number(view?.lat);
  const lon = Number(view?.lon);
  const zoom = Number(view?.zoom);
  if (Number.isFinite(lat) && Number.isFinite(lon)) {
    const camera = `${lat.toFixed(5)}, ${lon.toFixed(5)}  ·  z${Math.round(zoom)}  ·  ${Math.round(bearing)}°`;
    ctx.font = `${Math.round(11 * s)}px ${MONO}`;
    const width = ctx.measureText(camera).width;
    const x = mapWidth - width - 16 * s;
    // The header keeps its height whatever the export is framed to, so on a
    // narrow one the camera reading is what goes: the picture can be read
    // without it, and not without knowing which side is which.
    if (x > taken + 12 * s) {
      ctx.fillStyle = MUTED;
      ctx.fillText(camera, x, (title ? 25 : 24) * s);
    }
  }

  // Legend for a change reading, stated as what it is: an assist.
  const bottom = top + mapHeight;
  if (legend) {
    const palette = CHANGE_PALETTES[change.palette] ?? CHANGE_PALETTES.directional;
    const entries = [
      ['gain', change.labels?.gain ?? 'Appeared or brighter in B'],
      ['loss', change.labels?.loss ?? 'Gone or darker in B'],
      ['changed', 'Other change'],
    ];
    let x = left;
    const y = bottom + 20 * s;
    ctx.font = `${Math.round(11 * s)}px ${FONT}`;
    // On a framed export the legend can outrun the picture: an entry that
    // would run off the edge is dropped rather than half-written.
    for (const [key, text] of entries) {
      const width = ctx.measureText(text).width;
      if (x + 15 * s + width > mapWidth - 16 * s) break;
      const [r, g, bl] = palette[key];
      ctx.fillStyle = `rgb(${r},${g},${bl})`;
      ctx.fillRect(x, y - 9 * s, 10 * s, 10 * s);
      ctx.fillStyle = INK;
      ctx.fillText(text, x + 15 * s, y);
      x += width + 34 * s;
    }
    if (change.summary) {
      const width = ctx.measureText(change.summary).width;
      if (x + width <= mapWidth - 16 * s) {
        ctx.fillStyle = MUTED;
        ctx.fillText(change.summary, mapWidth - width - 16 * s, y);
      }
    }
  }

  ctx.fillStyle = MUTED;
  ctx.font = `${Math.round(10 * s)}px ${FONT}`;
  const credits = `A: ${attributionA || labelA}   |   B: ${attributionB || labelB}`;
  // The signature closes the credits row, off the imagery and clear of the scale bar.
  const signature = signed && signFooter(ctx, mapWidth - 14 * s, output.height - 13 * s, s)
    ? signatureRoom(s)
    : 0;
  ctx.fillStyle = MUTED;
  ctx.font = `${Math.round(10 * s)}px ${FONT}`;
  ctx.fillText(credits, left, output.height - 9 * s, Math.max(0, mapWidth - 32 * s - signature));
  return output;
}

export function canvasBlob(canvas) {
  return new Promise((resolve, reject) => {
    try {
      canvas.toBlob(
        (blob) => (blob ? resolve(blob) : reject(new Error('the comparison could not be encoded'))),
        'image/png'
      );
    } catch (error) {
      reject(new Error(`these imagery pixels cannot be exported: ${error.message}`));
    }
  });
}

export async function blobBase64(blob) {
  const bytes = new Uint8Array(await blob.arrayBuffer());
  let binary = '';
  // Bounded by the server's image limit, but chunking avoids the argument-size
  // limit that spreading a multi-megabyte Uint8Array would hit.
  for (let start = 0; start < bytes.length; start += 0x8000) {
    binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
  }
  return btoa(binary);
}