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
16.8 KB
Raw Blame
/**
 * The demo case the guide is photographed in: one small, coherent investigation.
 *
 * A photo of a container ship under a green suspension bridge, posted without a
 * caption, is placed on the west bank of the Main Channel of the Port of Los Angeles,
 * dated, argued in a proof and written up, while two other ports are ruled out. Every
 * tool then has something of the same story to show, so the journeys read as one job
 * from tab to tab.
 *
 * Built through the routes the app serves, as `tests/fullcase.py` builds its case. The
 * photos are in the public domain (photos.mjs), and so is the USGS imagery the maps
 * are drawn from. Where and when each photo was taken is true; the accounts that posted
 * them are made up, and nothing happens in the case that did not happen in the photos.
 */

import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';

import { PHOTOS } from './photos.mjs';

/** Public domain imagery the guide's maps are drawn from, added as the user would add a provider. */
export const IMAGERY = {
  id: 'usgs-imagery',
  label: 'USGS Imagery',
  url: 'https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}',
  attribution: 'USGS The National Map: Orthoimagery (public domain)',
  max_zoom: 16,
  imagery: true,
};

/**
 * Where the story happens. The maps open on the channel between the bridge and the
 * terminal; the camera stood on the west bank, south of them, and looked north through
 * a long lens: the cruise gangway below it, the YM Success mid-channel, the Evergreen
 * cranes in front of the bridge's east tower, the west tower out of frame.
 */
export const CHANNEL = { lat: 33.7455, lon: -118.274 };
export const CAMERA = { lat: 33.7398, lon: -118.2782 };
export const TERMINAL = { lat: 33.7474, lon: -118.2706 };
export const BRIDGE = { lat: 33.7497, lon: -118.2716 };
export const GLACIER_POINT = { lat: 37.7307, lon: -119.5737 };
const ZONE = 'America/Los_Angeles';

/** The place the proof names: where the photo was taken from. */
export const CAMERA_PLACE = 'Main Channel, west bank';

/**
 * The analyst's own map of the channel, filed as a layer of their own (My layers) so the
 * guide can show it being edited. Traced by eye over the USGS imagery, as an analyst
 * would: the bridge deck, three of the Evergreen cranes and the terminal's yard.
 */
const SURVEY = `<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Channel survey</name>
<Folder><name>Cranes</name>
<Placemark><name>Crane 1</name><Point><coordinates>-118.2716,33.7472,0</coordinates></Point></Placemark>
<Placemark><name>Crane 2</name><Point><coordinates>-118.2719,33.7466,0</coordinates></Point></Placemark>
<Placemark><name>Crane 3</name><Point><coordinates>-118.2722,33.7460,0</coordinates></Point></Placemark>
</Folder>
<Folder><name>Structures</name>
<Placemark><name>Bridge deck</name><LineString><coordinates>-118.2782,33.7502 -118.2748,33.7499 -118.2694,33.7492 -118.2651,33.7488</coordinates></LineString></Placemark>
<Placemark><name>Evergreen yard</name><Polygon><outerBoundaryIs><LinearRing><coordinates>-118.2712,33.7480 -118.2676,33.7478 -118.2662,33.7442 -118.2700,33.7418 -118.2728,33.7452 -118.2712,33.7480</coordinates></LinearRing></outerBoundaryIs></Polygon></Placemark>
</Folder></Document></kml>`;

/** The stretch of channel Detect watches, between the bridge and the cruise berths. */
const WATCHED = [
  [-118.2785, 33.7508], [-118.2670, 33.7508], [-118.2670, 33.7405], [-118.2785, 33.7405], [-118.2785, 33.7508],
];

const KML = `<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Channel observations</name>
<Folder><name>Line of sight</name>
<Placemark><name>Camera position</name><Point><coordinates>${CAMERA.lon},${CAMERA.lat},0</coordinates></Point></Placemark>
<Placemark><name>Evergreen berth</name><Point><coordinates>${TERMINAL.lon},${TERMINAL.lat},0</coordinates></Point></Placemark>
<Placemark><name>Line of sight</name><LineString><coordinates>${CAMERA.lon},${CAMERA.lat} ${TERMINAL.lon},${TERMINAL.lat}</coordinates></LineString></Placemark>
</Folder>
<Folder><name>Landmarks</name>
<Placemark><name>Vincent Thomas Bridge</name><Point><coordinates>${BRIDGE.lon},${BRIDGE.lat},0</coordinates></Point></Placemark>
</Folder></Document></kml>`;

const NOTES = `# Ship under a green bridge

A photo posted without a caption: a container ship passing under a green suspension
bridge, a terminal with green cranes beyond it. Where was it taken, and when?

- A suspension bridge over a working channel, mountains behind it.
- The ship is the YM Success, and the terminal's ship and cranes read EVERGREEN.
- A cruise gangway stands on the near bank, below the camera.

\`\`\`mermaid
flowchart LR
  A[harbor_watch posts] --> B[Photo]
  B --> C{Which port?}
  C -->|no bridge| D[Charleston, Miami ruled out]
  C -->|bridge and Evergreen cranes| E[Los Angeles, Main Channel]
  E --> F[Geolocated]
\`\`\`

Next: date the departure clip, and archive the post.
`;

/**
 * Fill a case through the app's own routes. `call(method, path, body)` reaches the
 * backend; `scratch` holds what ffmpeg writes.
 */
export async function buildDemo({ call, scratch }) {
  const demo = await call('POST', '/api/cases', { name: 'Demo case' });
  const caseId = demo.id;
  const at = (path) => `/api/cases/${caseId}${path}`;
  const entity = async (type, label, attrs = {}) =>
    (await call('POST', at('/entities'), { type, label, attrs })).id;
  const link = (from, to, type) => call('POST', at('/links'), { from_id: from, to_id: to, type });

  // -- the files, from the photos ---------------------------------------------
  const files = {};
  for (const one of PHOTOS) {
    let bytes = readFileSync(one.path);
    if (one.video) {
      const clip = join(scratch, one.file);
      const made = spawnSync('ffmpeg', [
        '-y', '-loglevel', 'error', '-loop', '1', '-i', one.path,
        '-vf', "zoompan=z='1+on*0.0025':d=150:s=1280x852:fps=25,format=yuv420p",
        '-t', '6', '-c:v', 'libx264', clip,
      ]);
      if (made.status !== 0) throw new Error(`ffmpeg could not make the demo video: ${made.stderr}`);
      bytes = readFileSync(clip);
    }
    const form = new FormData();
    form.append('file', new Blob([bytes]), one.file);
    form.append('source_url', one.source);
    const filed = await call('POST', at('/media/upload'), form);
    files[one.file] = filed.item.path;
  }
  const photo = files['bridge_channel.jpg'];
  const video = files['channel_departure.mp4'];
  const lookup = async (path) =>
    (await call('GET', at(`/entities/lookup?attr=path&value=${encodeURIComponent(path)}`))).entity.id;
  const photoId = await lookup(photo);
  const videoId = await lookup(video);

  // -- places, and a capture of the channel from the public imagery ----------
  const camera = (await call('POST', at('/satellite/place'), { ...CAMERA, zoom: 16, title: CAMERA_PLACE })).id;
  const bridgePlace = (await call('POST', at('/satellite/place'), { ...BRIDGE, zoom: 15, title: 'Vincent Thomas Bridge' })).id;
  await call('POST', at('/satellite/capture'), {
    ...CHANNEL, zoom: 16, width: 1000, height: 700, provider: IMAGERY.id,
  });
  const captures = await call('GET', at('/satellite'));
  const capture = captures[0]?.path ?? null;

  // -- who and what ----------------------------------------------------------
  const account = await entity('account', '@harbor_watch');
  const vessel = await entity('vessel', 'YM Success', { condition: 'intact' });
  const bridge = await entity('structure', 'Vincent Thomas Bridge', { kind: 'suspension bridge', condition: 'intact' });
  const cranes = await entity('structure', 'Evergreen terminal cranes', { kind: 'crane', condition: 'intact' });
  const post = await entity('bookmark', 'harbor_watch post', {
    url: 'https://example.org/posts/0412',
    fetched_at: '2026-03-15T06:02:00+00:00',
    reliability: 'C',
  });
  for (const [from, to, verb] of [
    [account, photoId, 'posted'],
    [account, videoId, 'posted'],
    [vessel, photoId, 'appears-in'],
    [bridge, photoId, 'appears-in'],
    [cranes, photoId, 'appears-in'],
    [bridge, bridgePlace, 'sited-at'],
    [photoId, camera, 'located-at'],
  ]) {
    await link(from, to, verb);
  }

  // -- what the case says, dated in the port's own time -----------------------
  const claim = async (label, attrs, about, place, cites = []) => {
    const id = await entity('claim', label, { when_zone: ZONE, ...attrs });
    for (const target of about) await link(id, target, 'about');
    if (place) await link(id, place, 'at');
    for (const source of cites) await link(id, source, 'cites');
    return id;
  };
  await claim(
    'The YM Success passes under the Vincent Thomas Bridge',
    { when: '2009-02-03', time_role: 'observed', confidence: 'probable' },
    [photoId, vessel], bridgePlace, [post]
  );
  await claim(
    'The photo was taken from the west bank of the Main Channel',
    {
      when: '2009-02-03',
      time_role: 'occurred',
      confidence: 'probable',
      method: 'The bridge, the Evergreen cranes and the cruise gangway line up only from there, matched against USGS imagery.',
    },
    [photoId], camera, [post]
  );
  await claim(
    'The container yard on Terminal Island, the bridge behind it',
    { when: '2006-11-02', time_role: 'observed', confidence: 'certain' },
    [await lookup(files['container_yard.jpg'])], bridgePlace
  );
  await claim(
    'A ship leaves the port by the Main Channel',
    { when: '2020-05-15', time_role: 'observed', confidence: 'possible' },
    [videoId], camera
  );

  // -- notes, a sheet, the running notes ------------------------------------
  await call('POST', at('/folders'), { name: 'Sources' });
  await call('POST', at('/notes'), {
    title: 'What the post says',
    folder: 'Sources',
    content: '# What the post says\n\nNo caption and no place. The account posts port photos from several countries.\n',
  });
  await call('PUT', at('/notes'), { text: NOTES });
  const sheet = await call('POST', at('/sheets'), { title: 'Files to geolocate' });
  await call('PUT', at(`/sheets/${sheet.id}`), {
    columns: ['id', 'File', 'Status', 'Coordinates', 'Notes'],
    rows: [
      ['r1', 'bridge_channel', 'done', `${CAMERA.lat}, ${CAMERA.lon}`, 'west bank of the Main Channel'],
      ['r2', 'channel_departure', 'to do', '', 'same channel, date the clip'],
      ['r3', 'container_yard', 'to do', '', 'same bridge, from Terminal Island'],
      ['r4', 'wando_terminal', 'ruled out', '', 'Charleston: no bridge over the berths'],
      ['r5', 'miami_port_aerial', 'ruled out', '', 'Miami: an island port, no bridge'],
    ],
    meta: {
      colours: { r1: 'green', r4: 'grey', r5: 'grey' },
      widths: { File: 200, Notes: 240 },
      frozen: 'File',
      roles: {
        Status: { kind: 'state', values: ['to do', 'done', 'ruled out'] },
        Coordinates: { kind: 'latlon' },
      },
      progress: 'Coordinates',
      description: 'Every file of the case still to place on the map.',
    },
  });

  // -- checklists ------------------------------------------------------------
  await call('PUT', at('/todos'), {
    revision: 0,
    lists: [
      {
        id: 'checks',
        name: 'Checks',
        tasks: [
          { id: 'source', text: 'Archive the post', done: true },
          { id: 'place', text: 'Geolocate the photo', done: true },
          { id: 'clip', text: 'Date the departure clip', done: false },
        ],
      },
    ],
  });

  // -- Inspect work on the clip, and a collage of the two pictures ----------
  await call('PUT', at('/inspect/work'), {
    path: video,
    spec: {
      frames: [
        { id: 'fr_1', path: video, time: 1.2, adjust: {}, crop: null },
        { id: 'fr_2', path: video, time: 3.6, adjust: { brightness: 1.15, contrast: 1.1 }, crop: null },
      ],
      marks: [{ id: 'mk_1', time: 3.6, label: 'Tug ahead' }],
    },
  });
  await call('POST', at('/collages'), {
    title: 'The bridge from both banks',
    spec: {
      width: 1200,
      height: 420,
      nodes: [
        { id: 'nd_1', save: { path: photo, time: null, ops: [] }, w: 528, h: 350,
          quad: [[46, 35], [574, 35], [574, 385], [46, 385]] },
        { id: 'nd_2', save: { path: files['container_yard.jpg'], time: null, ops: [] }, w: 526, h: 350,
          quad: [[626, 35], [1152, 35], [1152, 385], [626, 385]] },
      ],
    },
  });

  // -- the map: a layer of observations, a comparison, a plate, a view ------
  const kml = new FormData();
  kml.append('file', new Blob([KML]), 'channel-observations.kml');
  kml.append('title', 'Channel observations');
  await call('POST', at('/map-layers/upload'), kml);
  const survey = new FormData();
  survey.append('file', new Blob([SURVEY]), 'channel-survey.kml');
  survey.append('title', 'Channel survey');
  await call('POST', at('/map-layers/editable/upload'), survey);
  await call('POST', at('/analysis/areas'), {
    name: 'Main Channel berths',
    colour: '#38bdf8',
    geometry: { type: 'Polygon', coordinates: [WATCHED] },
  });
  await call('POST', at('/compare/sessions'), {
    title: 'Main Channel, imagery against the map',
    spec: {
      version: 2,
      camera: { ...CHANNEL, zoom: 16, bearing: 0 },
      mode: 'swipe',
      divider: 50,
      opacity: 50,
      a: { present: true, provider: IMAGERY.id, overlays: [] },
      b: { present: true, provider: 'opentopomap', overlays: [] },
    },
  });
  await call('POST', at('/map-plates'), {
    title: 'Main Channel, Port of Los Angeles',
    spec: {
      elements: [
        { id: 'map', kind: 'map', box: [10, 20, 200, 150], view: { ...CHANNEL, zoom: 15 } },
        { id: 'legend', kind: 'legend', box: [215, 20, 70, 60], of: 'map' },
        { id: 'title', kind: 'text', box: [10, 6, 200, 12], text: 'Main Channel, Port of Los Angeles', size: 18, weight: 700 },
      ],
    },
  });
  // one house style of each kind, so Settings, Templates shows what it keeps
  await call('POST', '/api/templates/proof', {
    name: 'Harbour desk',
    data: { bg: '#0b1220', font: 'inter', footer: 'Harbour desk · open sources' },
  });
  await call('POST', '/api/templates/post', {
    name: 'Geolocation thread',
    data: { mention: '', body: 'Geolocated: #place\n\n#coordinates\n\nSource: #source' },
  });
  await call('POST', '/api/templates/map', {
    name: 'Harbour situation',
    data: {
      elements: [
        { id: 'map', kind: 'map', box: [10, 20, 200, 150] },
        { id: 'legend', kind: 'legend', box: [215, 20, 70, 60], of: 'map' },
        { id: 'title', kind: 'text', box: [10, 6, 200, 12], text: '{case}', size: 18, weight: 700 },
      ],
    },
  });
  await call('PUT', at('/search-grids/channel-sweep'), {
    title: 'Channel sweep',
    spec: {
      azimut_grid: 1,
      cell_m: 250,
      anchor: { lat: 33.738, lon: -118.284 },
      lat_step: 0.00225,
      lon_step: 0.0027,
      aoi: { type: 'rect', bounds: { south: 33.738, west: -118.284, north: 33.752, east: -118.263 } },
      statuses: { '0:0': 'cleared', '0:1': 'cleared', '1:0': 'cleared', '2:3': 'flagged' },
    },
  });

  // Horizon wants relief, so its view stands on a mountain rather than on the quay:
  // the one the case's 1901 photo was taken from.
  await call('POST', at('/horizon/views'), {
    title: 'Half Dome from Glacier Point',
    spec: {
      eye: { ...GLACIER_POINT, mode: 'ground', height: 1.7 },
      look: { heading: 64, tilt: 1, fov: 62 },
      picture: { ground: 'imagery', imagery: IMAGERY.id, lines: true, names: true },
    },
  });
  // The case's 1901 photo was taken from the same point: laid over the view, it is what
  // Overlay is for. The look is the photo's own, read off it: Half Dome's summit (64.5°
  // from the point, +7°) a tenth of the way across and down, Nevada Fall (100.6°) at 87%
  // across, so a lens 46° wide turned to 83° and tilted 7.4° down.
  await call('POST', at('/horizon/views'), {
    title: 'Glacier Point, the 1901 photo',
    spec: {
      eye: { ...GLACIER_POINT, mode: 'ground', height: 1.7 },
      look: { heading: 83.2, tilt: -7.4, fov: 46 },
      picture: { ground: 'imagery', imagery: IMAGERY.id, lines: true, names: true },
      photo: { path: files['half_dome_1901.jpg'], kind: 'image', title: 'half_dome_1901', mix: 0.6 },
    },
  });

  // -- folders, as an analyst would have filed the case ----------------------
  await call('POST', at('/folders'), { name: 'Sources/harbor_watch' });
  const file = (id, folder) => call('PATCH', at(`/entities/${encodeURIComponent(id)}`), { attrs: { folder } });
  for (const id of [photoId, videoId, post, account]) await file(id, 'Sources/harbor_watch');

  // -- the Board as the analyst left it --------------------------------------
  await call('POST', at('/analysis-views'), {
    name: 'Everything on the Main Channel',
    mode: 'live',
    surface: 'board',
    spec: { query: { filter: {}, terms: { place: CAMERA_PLACE } } },
  });

  return { caseId, photo, video, capture, files, camera, bridge: bridgePlace, account, sheet: sheet.id };
}