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
17.3 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import {
  boxBlur,
  cleanMask,
  decodeFrame,
  detectChange,
  estimateAlignment,
  findZones,
  matchTone,
  otsu,
  skyMask,
  sunPosition,
  toLab,
} from './changeDetect.js';

/** An opaque frame filled with one colour, and a way to paint rectangles on it. */
function frame(width, height, colour = [90, 110, 80]) {
  const pixels = new Uint8ClampedArray(width * height * 4);
  for (let index = 0; index < pixels.length; index += 4) {
    pixels.set([...colour, 255], index);
  }
  return {
    pixels,
    paint(x1, y1, x2, y2, rgb) {
      for (let y = y1; y < y2; y += 1) {
        for (let x = x1; x < x2; x += 1) pixels.set([...rgb, 255], (y * width + x) * 4);
      }
      return this;
    },
  };
}

const settings = (patch = {}) => ({
  method: 'colour',
  threshold: 'auto',
  sensitivity: 55,
  normalize: 'none',
  smoothing: 0,
  alignment: 0,
  cleanup: 0,
  ...patch,
});

describe('colour', () => {
  it('converts sRGB to Lab on the standard white and black points', () => {
    const white = toLab(255, 255, 255);
    expect(white[0]).toBeCloseTo(100, 0);
    expect(Math.abs(white[1])).toBeLessThan(0.5);
    expect(toLab(0, 0, 0)[0]).toBeCloseTo(0, 5);
  });
});

describe('preparing the pair', () => {
  it('finds a small translation that registers B onto A', () => {
    const a = frame(24, 24, [0, 0, 0]).paint(8, 8, 12, 12, [240, 240, 240]);
    const b = frame(24, 24, [0, 0, 0]).paint(10, 7, 14, 11, [240, 240, 240]);
    expect(estimateAlignment(a.pixels, b.pixels, 24, 24, 4)).toMatchObject({ x: 2, y: -1 });
  });

  it('moves B’s tones onto A so a brighter day is not change everywhere', () => {
    const a = frame(10, 10, [80, 80, 80]).paint(0, 0, 5, 10, [40, 40, 40]);
    const b = frame(10, 10, [130, 130, 130]).paint(0, 0, 5, 10, [90, 90, 90]);
    for (const mode of ['mean', 'histogram']) {
      const toned = matchTone(a.pixels, b.pixels, mode);
      expect(toned[0]).toBeCloseTo(40, -1);
      expect(toned[(9 * 10 + 9) * 4]).toBeCloseTo(80, -1);
    }
    expect(matchTone(a.pixels, b.pixels, 'none')).toBe(b.pixels);
  });
});

describe('thresholds and filters', () => {
  it('splits a two-population field between its modes', () => {
    const field = new Float32Array([...Array(80).fill(10), ...Array(20).fill(200)]);
    const split = otsu(field, new Uint8Array(100).fill(1));
    expect(split).toBeGreaterThanOrEqual(10);
    expect(split).toBeLessThan(200);
  });

  it('blurs only over valid pixels', () => {
    const field = new Float32Array([0, 90, 0, 0]);
    const blurred = boxBlur(field, 2, 2, 1, new Uint8Array([1, 1, 1, 0]));
    expect(blurred[0]).toBeCloseTo(30);
    expect(blurred[3]).toBe(0);
  });

  it('drops speckle smaller than the cleanup radius and keeps solid regions', () => {
    const width = 12;
    const mask = new Uint8Array(width * width);
    mask[2 * width + 2] = 1; // one stray pixel
    for (let y = 5; y < 10; y += 1) for (let x = 5; x < 10; x += 1) mask[y * width + x] = 1;
    const cleaned = cleanMask(mask, width, width, 1);
    expect(cleaned[2 * width + 2]).toBe(0);
    expect(cleaned[7 * width + 7]).toBe(1);
  });
});

describe('zones', () => {
  it('says how far past the line each zone got, in the words Detect uses', () => {
    const mask = new Uint8Array(36);
    const classes = new Uint8Array(36);
    const strength = new Float32Array(36);
    for (const pixel of [7, 8, 13, 14]) { mask[pixel] = 1; classes[pixel] = 1; strength[pixel] = 200; }
    for (const pixel of [22, 23, 28, 29]) { mask[pixel] = 1; classes[pixel] = 2; strength[pixel] = 60; }
    const { zones } = findZones(mask, classes, strength, 6, 6, 10, 0, 50);
    expect(zones.map((zone) => zone.strength)).toEqual(['strong', 'weak']);
    expect(zones[0].margin).toBe(4);
  });

  it('groups connected pixels with their area on the ground and dominant direction', () => {
    const width = 10;
    const mask = new Uint8Array(100);
    const classes = new Uint8Array(100);
    const strength = new Float32Array(100).fill(128);
    for (let y = 1; y < 3; y += 1) for (let x = 1; x < 4; x += 1) {
      mask[y * width + x] = 1;
      classes[y * width + x] = 2;
    }
    mask[88] = 1;
    classes[88] = 1;
    const { zones } = findZones(mask, classes, strength, width, 10, 2, 10);
    expect(zones).toHaveLength(1);
    expect(zones[0]).toMatchObject({ kind: 'loss', pixels: 6, area: 24 });
    expect(zones[0].box).toEqual({ x1: 0.1, y1: 0.1, x2: 0.4, y2: 0.3 });
  });
});

describe('detecting change', () => {
  it('finds a new bright roof as a gain and nothing where the ground is the same', () => {
    const a = frame(40, 40);
    const b = frame(40, 40).paint(10, 10, 20, 18, [235, 230, 220]);
    const result = detectChange({
      a: a.pixels, b: b.pixels, width: 40, height: 40,
      settings: settings(), metresPerPixel: 0.5,
    });
    expect(result.counts.gained).toBe(80);
    expect(result.counts.lost + result.counts.changed).toBe(0);
    expect(result.zones).toHaveLength(1);
    expect(result.zones[0]).toMatchObject({ kind: 'gain', area: 20 });
    expect(result.pixels[(12 * 40 + 12) * 4 + 3]).toBeGreaterThan(0);
    expect(result.pixels[3]).toBe(0);
  });

  it('reads a hue shift at the same lightness as another change, not a gain', () => {
    const a = frame(30, 30, [120, 120, 120]).paint(5, 5, 15, 15, [170, 60, 60]);
    const b = frame(30, 30, [120, 120, 120]).paint(5, 5, 15, 15, [40, 125, 60]);
    const result = detectChange({ a: a.pixels, b: b.pixels, width: 30, height: 30, settings: settings() });
    expect(result.counts.changed).toBeGreaterThan(90);
    expect(result.counts.gained).toBe(0);
  });

  it('shows only the classes asked for, and drops zones under the minimum area', () => {
    const a = frame(40, 40).paint(25, 25, 35, 35, [230, 230, 230]);
    const b = frame(40, 40).paint(2, 2, 6, 6, [230, 230, 230]);
    const losses = detectChange({
      a: a.pixels, b: b.pixels, width: 40, height: 40,
      settings: settings({ classes: ['loss'] }), metresPerPixel: 1,
    });
    expect(losses.counts.gained).toBe(0);
    expect(losses.zones.map((zone) => zone.kind)).toEqual(['loss']);
    const bigOnly = detectChange({
      a: a.pixels, b: b.pixels, width: 40, height: 40,
      settings: settings({ min_area: 50 }), metresPerPixel: 1,
    });
    expect(bigOnly.zones).toHaveLength(1);
    expect(bigOnly.counts.gained).toBe(0);
  });

  it('ignores a uniform tone shift once tones are matched', () => {
    const a = frame(30, 30, [80, 90, 70]).paint(0, 0, 15, 30, [60, 70, 50]);
    const b = frame(30, 30, [120, 130, 110]).paint(0, 0, 15, 30, [100, 110, 90]);
    const raw = detectChange({ a: a.pixels, b: b.pixels, width: 30, height: 30, settings: settings({ threshold: 'manual', sensitivity: 90 }) });
    const toned = detectChange({ a: a.pixels, b: b.pixels, width: 30, height: 30, settings: settings({ threshold: 'manual', sensitivity: 90, normalize: 'histogram' }) });
    expect(raw.share).toBeGreaterThan(0.9);
    expect(toned.share).toBe(0);
  });

  it('reads structure, so a new wall shows even when its colour matches the ground', () => {
    const a = frame(40, 40, [120, 120, 120]);
    const b = frame(40, 40, [120, 120, 120]).paint(10, 10, 30, 30, [60, 60, 60]);
    const result = detectChange({
      a: a.pixels, b: b.pixels, width: 40, height: 40,
      settings: settings({ method: 'structure', threshold: 'manual', sensitivity: 80 }),
    });
    expect(result.counts.gained).toBeGreaterThan(0);
    // the inside of a flat patch has no edges of its own
    expect(result.pixels[(20 * 40 + 20) * 4 + 3]).toBe(0);
  });

  /** A band frame: R the index, G the sky byte, A the data mask. */
  const bandFrame = (width, height, at) => {
    const pixels = new Uint8ClampedArray(width * height * 4);
    for (let pixel = 0; pixel < width * height; pixel += 1) {
      const x = pixel % width;
      const y = (pixel - x) / width;
      const { value = 0, scene = 4, dark = false, data = true } = at(x, y) ?? {};
      pixels.set([Math.round((value + 1) * 127.5), scene + (dark ? 16 : 0), 0, data ? 255 : 0], pixel * 4);
    }
    return pixels;
  };

  /** Index frames with a cloud class from column `cloudFrom` rightwards. */
  const indexFrame = (width, value, cloudFrom = 99) =>
    bandFrame(width, width, (x) => ({ value: value(x), scene: x >= cloudFrom ? 9 : 4 }));

  it('reads a real spectral index, masking clouded pixels', () => {
    const width = 40;
    const before = indexFrame(width, () => 0.7);
    const after = indexFrame(width, (x) => (x < 20 ? 0.7 : -0.1), 32);
    const blank = new Uint8ClampedArray(width * width * 4);
    const result = detectChange({
      a: blank, b: blank, width, height: width, metresPerPixel: 20,
      settings: settings({ method: 'index', ignore_clouds: true, cloud_margin: 0 }),
      frames: { a: before, b: after },
    });
    expect(result.counts.lost).toBe(12 * width);
    expect(result.coverage).toBeCloseTo(32 / 40);
    expect(decodeFrame(after).value[0]).toBeCloseTo(0.7, 1);
    expect(() => detectChange({
      a: blank, b: blank, width, height: width, settings: settings({ method: 'index' }),
    })).toThrow('index frames');
  });

  it('measures an index against a stated change, not against this view', () => {
    // Detect draws the same line, so a sweep and a reading agree, and panning
    // cannot move it the way a split of the view's own histogram would.
    const width = 40;
    const before = indexFrame(width, () => 0.6);
    const after = indexFrame(width, (x) => (x < 20 ? 0.45 : 0.1));
    const blank = new Uint8ClampedArray(width * width * 4);
    const read = (sensitivity) => detectChange({
      a: blank, b: blank, width, height: width, metresPerPixel: 20,
      settings: settings({ method: 'index', sensitivity }), frames: { a: before, b: after },
    });
    // 0.25 at the default: the 0.15 side is left alone, the 0.5 side is not
    expect(read(55).counts.lost).toBe(20 * width);
    expect(read(95).counts.lost).toBe(40 * width);
  });

  it('grows the cloud mask by a margin in ground metres', () => {
    // A classification calls a cloud's soft rim ground, and that rim is where
    // the ring of highlights around every mask comes from.
    const width = 40;
    const before = indexFrame(width, () => 0.7);
    const after = indexFrame(width, (x) => (x < 20 ? 0.7 : -0.1), 32);
    const blank = new Uint8ClampedArray(width * width * 4);
    const read = (cloud_margin) => detectChange({
      a: blank, b: blank, width, height: width, metresPerPixel: 20,
      settings: settings({ method: 'index', ignore_clouds: true, cloud_margin }),
      frames: { a: before, b: after },
    });
    // columns 20…31 changed and 32… are cloud; 40 m of margin eats 30 and 31 too
    expect(read(40).counts.lost).toBe(10 * width);
    expect(read(40).coverage).toBeCloseTo(30 / 40);
    // and the margin only ever costs what it says: off, the edge is exact
    expect(read(0).counts.lost).toBe(12 * width);
  });

  it('leaves every pixel alone when nothing is being masked', () => {
    // The margin must not eat anything on its own: it grows a mask, and with
    // both switches off there is no mask to grow.
    const width = 40;
    const before = indexFrame(width, () => 0.7);
    const after = indexFrame(width, (x) => (x < 20 ? 0.7 : -0.1), 32);
    const blank = new Uint8ClampedArray(width * width * 4);
    const result = detectChange({
      a: blank, b: blank, width, height: width, metresPerPixel: 20,
      settings: settings({ method: 'index', cloud_margin: 80 }),
      frames: { a: before, b: after },
    });
    expect(result.counts.lost).toBe(20 * width);
    expect(result.coverage).toBeCloseTo(1);
  });

  it('keeps cloud out of the tone match, and skips it on Sentinel-2 altogether', () => {
    // A third of the view under cumulus would otherwise drag the ground of the
    // other date after it; and two corrected passes have nothing to match.
    const width = 40;
    const a = frame(width, width, [90, 100, 80]);
    const b = frame(width, width, [90, 100, 80]).paint(0, 0, 14, width, [245, 245, 245]);
    const clear = bandFrame(width, width, () => ({}));
    const clouded = bandFrame(width, width, (x) => ({ scene: x < 14 ? 9 : 4 }));
    const read = (patch, family) => detectChange({
      a: a.pixels, b: b.pixels, width, height: width, metresPerPixel: 20, family,
      frames: { a: clear, b: clouded },
      settings: settings({ ignore_clouds: true, cloud_margin: 0, ...patch }),
    });
    // masked cloud and a matched histogram: the ground under it must stay quiet
    expect(read({ normalize: 'histogram' }, 'esri').share).toBe(0);
    expect(read({ normalize: 'auto' }, 'esri').settings.normalize).toBe('auto');
    expect(read({ normalize: 'auto' }, 'sentinel2').share).toBe(0);
    // a burn covering most of a view is real change, and matching would eat it
    const dark = frame(width, width, [40, 42, 34]);
    const burnt = detectChange({ a: a.pixels, b: dark.pixels, width, height: width,
      settings: settings({ normalize: 'auto' }), family: 'sentinel2' });
    const matched = detectChange({ a: a.pixels, b: dark.pixels, width, height: width,
      settings: settings({ normalize: 'auto' }), family: 'esri' });
    expect(burnt.share).toBeGreaterThan(0.9);
    expect(matched.share).toBe(0);
  });

  it('draws outlines and a heat ramp from the same zones', () => {
    const a = frame(30, 30);
    const b = frame(30, 30).paint(5, 5, 20, 20, [240, 240, 240]);
    const outline = detectChange({ a: a.pixels, b: b.pixels, width: 30, height: 30, settings: settings({ display: 'outline' }) });
    expect(outline.pixels[(5 * 30 + 10) * 4 + 3]).toBe(255);
    expect(outline.pixels[(12 * 30 + 12) * 4 + 3]).toBeLessThan(60);
    const heat = detectChange({ a: a.pixels, b: b.pixels, width: 30, height: 30, settings: settings({ display: 'heat' }) });
    expect(heat.pixels[(12 * 30 + 12) * 4 + 3]).toBeGreaterThan(89);
  });

  it('refuses frames of different sizes', () => {
    expect(() => detectChange({
      a: new Uint8ClampedArray(16), b: new Uint8ClampedArray(12), width: 2, height: 2, settings: {},
    })).toThrow('same pixel geometry');
  });
});

describe('the sky over a Sentinel-2 pair', () => {
  const sky = (width, height, at) => {
    const pixels = new Uint8ClampedArray(width * height * 4);
    for (let pixel = 0; pixel < width * height; pixel += 1) {
      const x = pixel % width;
      const y = (pixel - x) / width;
      const { scene = 4, dark = false } = at(x, y) ?? {};
      pixels.set([0, scene + (dark ? 16 : 0), 0, 255], pixel * 4);
    }
    return decodeFrame(pixels);
  };
  const ground = (patch = {}) => ({
    width: 60, height: 60, metresPerPixel: 20, lat: 48, bearing: 0, day: '2026-06-21', ...patch,
  });
  const inside = (mask, x, y, width = 60) => Boolean(mask[y * width + x]);

  it('ignores a classified cloud too small to be one, and takes the veil around a real one', () => {
    // Sen2Cor calls white hulls and bright roofs cloud; no cumulus is under 5 ha.
    const frame = sky(60, 60, (x, y) => {
      if (x >= 4 && x < 8 && y >= 4 && y < 8) return { scene: 9 };          // 0.6 ha: a roof
      if (x >= 20 && x < 40 && y >= 20 && y < 40) return { scene: 9 };      // 16 ha: a cloud
      if (x >= 18 && x < 20 && y >= 20 && y < 40) return { scene: 7 };      // its veil
      if (x >= 50 && x < 54 && y >= 4 && y < 8) return { scene: 7 };        // unsure, alone
      return {};
    });
    const { cloud } = skyMask(frame, null, ground());
    expect(inside(cloud, 6, 6)).toBe(false);
    expect(inside(cloud, 30, 30)).toBe(true);
    expect(inside(cloud, 19, 30)).toBe(true);
    expect(inside(cloud, 52, 6)).toBe(false);
  });

  it('casts a cloud away from the sun, onto dark ground only, and turns with the map', () => {
    const { azimuth } = sunPosition('2026-06-21', 48);
    expect(azimuth).toBeGreaterThan(120);   // late morning at 48°N: the sun is south-east
    expect(azimuth).toBeLessThan(200);
    const frame = sky(60, 60, (x, y) => {
      if (x >= 24 && x < 36 && y >= 34 && y < 46) return { scene: 9 };
      if (y < 34 && x >= 24) return { dark: true };   // dark ground north of the cloud
      if (y >= 34 && x < 24) return { dark: true };   // and dark ground west of it
      return {};
    });
    const north = skyMask(frame, null, ground()).shadow;
    expect(inside(north, 30, 28)).toBe(true);
    expect(inside(north, 30, 52)).toBe(false);   // never towards the sun
    expect(inside(north, 16, 44)).toBe(false);
    // Turned so that east is up, the same cast lands on the ground that is west.
    const turned = skyMask(frame, null, ground({ bearing: 90 })).shadow;
    expect(inside(turned, 16, 44)).toBe(true);
    expect(inside(turned, 30, 28)).toBe(false);
  });

  it('believes dark water only when the other date sees water too', () => {
    // Sen2Cor reads a deep cloud shadow as water, so a cast shadow that spares
    // water finds none of it; a lake, which is water on both dates, is spared.
    const frame = sky(60, 60, (x, y) => {
      if (x >= 24 && x < 36 && y >= 34 && y < 46) return { scene: 9 };
      if (y < 34 && x < 30) return { scene: 6, dark: true };   // called water under the cloud
      if (y < 34) return { scene: 6, dark: true };             // a real lake
      return {};
    });
    const other = sky(60, 60, (x, y) => (y < 34 && x >= 30 ? { scene: 6 } : {}));
    const { shadow } = skyMask(frame, other, ground());
    expect(inside(shadow, 28, 28)).toBe(true);
    expect(inside(shadow, 32, 28)).toBe(false);
    // with no second date to ask, water is water and the shadow is missed
    expect(inside(skyMask(frame, null, ground()).shadow, 28, 28)).toBe(false);
  });
});