The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/** Find where a photo was taken: the area, the alignments and where they cross. */
import { describe, expect, it } from 'vitest';
import {
ALIGN_STEPS,
alignmentBearing,
alignmentLine,
alignmentWedge,
areaMiddle,
areaPoints,
areaProblem,
areaText,
bestSoFar,
chanceFit,
cleanFacing,
cleanStands,
cleanSun,
crossing,
facingFan,
facingFrom,
facingRings,
facingSectors,
facingText,
fanOf,
fromLocal,
groundText,
HEAT_RAMP,
heatFloor,
heatOf,
latticeNear,
mapCells,
heatStyle,
overText,
inArea,
local,
meeting,
neighbourFit,
onAlignment,
photoOffset,
reliability,
resultOf,
ruledLines,
boundedText,
sameAsk,
searchedPoints,
searchedReach,
ringsOf,
searchedWhen,
searchEnding,
searchTone,
standsText,
SUN_SIDES,
sunAsked,
toggleFacing,
toggleStand,
traceTurns,
withGround,
lookingOf,
traceSpan,
triedScore,
settlesOnArrival,
} from './find.js';
import { containsPoint, destination, haversine } from '../measure.js';
import { bearingBetween } from './geometry.js';
const CAMERA = { lat: 16.9988, lon: 45.0938 };
/** An alignment as the camera at `camera` would see it: a near point and a far one on the same bearing. */
function lined(camera, bearing, nearM, farM, { offset = 0 } = {}) {
const near = destination(camera, bearing, nearM);
const far = destination(camera, bearing + offset, farM);
return { map: { near, far }, photo: { near: { u: 0.5, v: 0.6 }, far: { u: 0.5, v: 0.4 } }, offset };
}
describe('a place looked from', () => {
it('says the skyline and the ridges apart once both were judged, else the one score', () => {
expect(triedScore({ explained: 0.63, sky: 0.749, inner: 0.508 })).toBe('skyline 75%, ridges 51%');
expect(triedScore({ explained: 0.71 })).toBe('explains 71%');
// judged on key lines or the sky alone: no ridges to set beside the skyline
expect(triedScore({ explained: 0.6, sky: 0.7 })).toBe('explains 60%');
expect(triedScore({ explained: -1, sky: -0.2, inner: 0 })).toBe('skyline 0%, ridges 0%');
});
it('settles on the trace on arrival unless the search laid the photo itself', () => {
const place = { heading: 80, tilt: -7, fov: 43 };
expect(settlesOnArrival(place)).toBe(true);
expect(settlesOnArrival({ ...place, scale: 1 })).toBe(true);
expect(settlesOnArrival({ lat: 1, lon: 2 })).toBe(false);
expect(settlesOnArrival({ ...place, pieces: [[0, 1, 0, 0]] })).toBe(false);
expect(settlesOnArrival({ ...place, mirrored: true })).toBe(false);
expect(settlesOnArrival({ ...place, scale: 1.15 })).toBe(false);
expect(settlesOnArrival(place, { framed: { span: 97 } })).toBe(false);
expect(settlesOnArrival(place, { cuts: [0.5] })).toBe(false);
});
});
describe('the area searched', () => {
const square = [
{ lat: 16.95, lon: 45.05 },
{ lat: 16.95, lon: 45.15 },
{ lat: 17.05, lon: 45.15 },
{ lat: 17.05, lon: 45.05 },
];
it('says its size in words, and holds the points inside it', () => {
expect(areaText(square)).toMatch(/^1[01] × 11 km · 1[12]\d km²$/);
expect(inArea(square, CAMERA)).toBe(true);
expect(inArea(square, { lat: 17.2, lon: 45.1 })).toBe(false);
expect(areaText(square.slice(0, 2))).toBe('');
});
it('asks for three corners and an area within reason', () => {
expect(areaProblem(square)).toBe('');
expect(areaProblem(square.slice(0, 2))).toBe('Draw at least three corners');
const tiny = square.map((p) => ({ lat: 16.95 + (p.lat - 16.95) / 1000, lon: 45.05 + (p.lon - 45.05) / 1000 }));
expect(areaProblem(tiny)).toBe('The area is too small to search');
const huge = square.map((p) => ({ lat: 16.95 + (p.lat - 16.95) * 10, lon: 45.05 + (p.lon - 45.05) * 10 }));
expect(areaProblem(huge)).toMatch(/too large/);
});
it('works flat about a point, there and back', () => {
const away = { lat: 17.01, lon: 45.12 };
const back = fromLocal(CAMERA, local(CAMERA, away));
expect(back.lat).toBeCloseTo(away.lat, 9);
expect(back.lon).toBeCloseTo(away.lon, 9);
const { x, y } = local(CAMERA, away);
expect(Math.hypot(x, y)).toBeCloseTo(haversine(CAMERA, away), -1);
});
});
describe('an alignment', () => {
it('has the guided clicks in order: two on the photo, then the same two on the map', () => {
expect(ALIGN_STEPS.map((s) => `${s.on} ${s.end}`)).toEqual(['photo near', 'photo far', 'map near', 'map far']);
});
it('puts the camera on the line through the two, on the near side', () => {
const one = lined(CAMERA, 40, 800, 12_000);
expect(alignmentBearing(one)).toBeCloseTo(220, 1);
const [from, to] = alignmentLine(one);
expect(from).toBe(one.map.near);
expect(haversine(from, to)).toBeCloseTo(40_000, -2);
expect(onAlignment(one, CAMERA)).toBe(true);
// beyond the far one is the wrong side
expect(onAlignment(one, destination(CAMERA, 40, 20_000))).toBe(false);
expect(onAlignment(one, destination(CAMERA, 130, 500))).toBe(false);
expect(alignmentWedge(one)).toHaveLength(3);
});
it('turns about the near one by how far apart the two stand across the photo', () => {
// the far peak stands 6° right of the near mast in the photo
const one = lined(CAMERA, 40, 600, 30_000, { offset: 6 });
expect(onAlignment(one, CAMERA, 0.3)).toBe(true);
expect(onAlignment({ ...one, offset: 0 }, CAMERA, 0.3)).toBe(false);
});
it('reads that offset through the lens, or says it cannot', () => {
expect(photoOffset({ u: 0.5, v: 0.6 }, { u: 0.5, v: 0.2 })).toBe(0);
expect(photoOffset({ u: 0.5, v: 0.6 }, { u: 0.6, v: 0.2 })).toBeNull();
// two hand clicks a hair apart are one above the other, lens or not
expect(photoOffset({ u: 0.5, v: 0.6 }, { u: 0.508, v: 0.2 })).toBe(0);
expect(photoOffset({ u: 0.5, v: 0.6 }, { u: 0.508, v: 0.2 }, { fov: 60 })).not.toBe(0);
// through a 60° lens, the right edge is 30° off the middle
expect(photoOffset({ u: 0.5, v: 0.6 }, { u: 1, v: 0.2 }, { fov: 60 })).toBeCloseTo(30, 9);
// along a panorama's strip, as many degrees as it spans
expect(photoOffset({ u: 0.25, v: 0.6 }, { u: 0.75, v: 0.2 }, { fov: 200, projection: 'panorama' })).toBeCloseTo(100, 9);
});
it('says which way the photo faces from a place', () => {
const one = lined(CAMERA, 40, 800, 12_000);
// the near mast at the photo's middle: the photo faces it
expect(facingFrom(one, CAMERA, { fov: 60 })).toBeCloseTo(40, 1);
const right = { ...one, photo: { ...one.photo, near: { u: 0.75, v: 0.6 } } };
// a quarter across a 60° lens is atan(0.5 · tan 30°) right of the middle
expect(facingFrom(right, CAMERA, { fov: 60 })).toBeCloseTo(40 - (Math.atan(0.5 * Math.tan(Math.PI / 6)) * 180) / Math.PI, 1);
expect(facingFrom(one, CAMERA)).toBeNull();
});
});
describe('alignments crossing', () => {
it('meet where the photo was taken', () => {
const a = lined(CAMERA, 40, 800, 12_000);
const b = lined(CAMERA, 115, 1500, 20_000);
const at = crossing(a, b);
expect(haversine(at, CAMERA)).toBeLessThan(1);
const met = meeting([a, b, lined(CAMERA, 300, 2000, 9000)]);
expect(haversine(met.at, CAMERA)).toBeLessThan(1);
expect(met.spread).toBeLessThan(1);
expect(met.crossings).toBe(3);
});
it('say how far apart they miss when the clicks are a little off', () => {
const a = lined(CAMERA, 40, 800, 12_000);
const b = lined(CAMERA, 115, 1500, 20_000);
const off = { ...lined(CAMERA, 300, 2000, 9000), map: { near: destination(destination(CAMERA, 300, 2000), 30, 60), far: destination(CAMERA, 300, 9000) } };
const met = meeting([a, b, off]);
expect(met.spread).toBeGreaterThan(5);
expect(haversine(met.at, CAMERA)).toBeLessThan(80);
});
it('say nothing when they run side by side, or cross behind a near point', () => {
const a = lined(CAMERA, 40, 800, 12_000);
const near = lined(destination(CAMERA, 130, 300), 41, 800, 12_000);
expect(crossing(a, near)).toBeNull();
// seen the other way round, their lines cross on the far side of both
const back = { ...a, map: { near: a.map.far, far: a.map.near } };
const back2 = (() => {
const b = lined(CAMERA, 115, 1500, 20_000);
return { ...b, map: { near: b.map.far, far: b.map.near } };
})();
expect(crossing(back, back2)).toBeNull();
expect(meeting([a])).toBeNull();
expect(bearingBetween(CAMERA, a.map.near)).toBeCloseTo(40, 3);
});
});
describe('the heatmap', () => {
it('shows the grid before the search, while it runs and once the setup changed, the scores once it is done', () => {
const previewed = { points: [[46.5, 7.8, 'slope', true]] };
const scored = { status: 'done', result: { points: [{ lat: 46.5, lon: 7.8, explained: 0.4 }] } };
expect(mapCells({ previewed })).toEqual({ kind: 'grid', points: previewed.points });
expect(mapCells({ search: { status: 'running', result: null }, edited: false, previewed }).kind).toBe('grid');
expect(mapCells({ search: scored, edited: false, previewed })).toEqual({ kind: 'scores', points: scored.result.points });
expect(mapCells({ search: scored, edited: true, previewed }).kind).toBe('grid');
// a search that scored nothing leaves the grid on the map
expect(mapCells({ search: { status: 'done', result: { points: [] } }, edited: false, previewed }).kind).toBe('grid');
expect(mapCells({ drawing: 'area', previewed }).points).toEqual([]);
// while it runs, the points scored so far over the grid; stopped, what it had found
const live = [{ lat: 46.5, lon: 7.8, explained: 0.3 }];
expect(mapCells({ search: { status: 'running', result: null }, previewed, live })).toEqual({ kind: 'live', points: previewed.points, scored: live });
const stopped = { status: 'cancelled', result: { partial: true, points: live } };
expect(mapCells({ search: stopped, edited: false, previewed })).toEqual({ kind: 'scores', points: live });
expect(resultOf(stopped)).toBe(stopped.result);
expect(resultOf({ status: 'running', result: null })).toBeNull();
});
it('says what a search ranked best-first left out, and nothing when it searched every point', () => {
expect(boundedText({ cells: 1107, filled: 214, skipped: 7800 })).toBe(
'Searched point by point in 214 of 1,107 cells, where a place could still win; 7,800 points elsewhere were not needed.'
);
expect(boundedText({ cells: 10, filled: 10, skipped: 0 })).toBe('');
expect(boundedText(undefined)).toBe('');
});
it('says what the photo rules out of the grid, a line for each reason', () => {
expect(ruledLines({ total: 200, ruled: { nosea: 150, high: 1, waterhidden: 20, unknown: 3 } })).toEqual([
{ reason: 'nosea', text: 'No sea within its horizon: 150 points left out (75%)' },
{ reason: 'high', text: 'Higher than the land round it: 1 point left out (1%)' },
{ reason: 'waterhidden', text: 'Water hidden by the land: 20 points left out (10%)' },
]);
expect(ruledLines({ total: 200, ruled: {} })).toEqual([]);
expect(ruledLines(null)).toEqual([]);
// what is said of the photo is part of what a search was asked
expect(sameAsk({ area: [], water: true }, { area: [] })).toBe(false);
expect(sameAsk({ area: [], over: 'above' }, { area: [], over: 'above' })).toBe(true);
});
it('lays the points the brush paints in where the app’s grid lays them, the area’s own lattice held', () => {
// as engine/finder.py lays a 250 m grid over a stroke 400 m wide painted in south of the area (its points, rounded)
const area = [[-4.08, 28.67], [-4.086, 28.748], [-4.142, 28.74], [-4.138, 28.662]].map(([lat, lon]) => ({ lat, lon }));
const app = [[-4.16227, 28.717212], [-4.16227, 28.719972], [-4.16227, 28.722733], [-4.159885, 28.713071], [-4.159885, 28.715832], [-4.159885, 28.718592], [-4.159885, 28.721353], [-4.1575, 28.70893], [-4.1575, 28.711691], [-4.1575, 28.714451], [-4.1575, 28.717212], [-4.1575, 28.719972], [-4.155116, 28.704789], [-4.155116, 28.70755], [-4.155116, 28.71031], [-4.155116, 28.713071], [-4.155116, 28.715832], [-4.152731, 28.697888], [-4.152731, 28.700648], [-4.152731, 28.703409], [-4.152731, 28.706169], [-4.152731, 28.70893], [-4.152731, 28.711691], [-4.150346, 28.696507], [-4.150346, 28.699268], [-4.150346, 28.702029], [-4.150346, 28.704789], [-4.150346, 28.70755], [-4.147962, 28.697888], [-4.147962, 28.700648], [-4.147962, 28.703409]];
const painted = latticeNear(area, 250, { lat: -4.15, lon: 28.72 - 0.02 }, { lat: -4.16, lon: 28.72 }, 400);
const beyond = painted.filter(([lat, lon]) => !containsPoint(area, { lat, lon }));
const key = ([lat, lon]) => `${lat},${lon}`;
expect(beyond.map(key).sort()).toEqual(app.map(key).sort());
expect(latticeNear(area.slice(0, 2), 250, area[0], area[0], 400)).toEqual([]);
});
it('starts the heat at the middle of the points scored, so the best stand out of the better half', () => {
expect(heatFloor([{ explained: 0.2 }, { explained: 0.5 }, { explained: 0.7 }])).toBe(0.5);
expect(heatFloor([{ explained: -0.1 }, { explained: -0.2 }, { explained: 0.6 }])).toBe(0);
expect(heatFloor([])).toBe(0);
const heats = heatOf([{ explained: 0.62 }, { explained: 0.4 }, { explained: 0.3 }, { explained: 0.77 }, { explained: 0.2 }]);
expect(heats[3].fill).toBe(HEAT_RAMP.at(-1));
expect(heats[1].fill).toBe(HEAT_RAMP[0]);
expect(HEAT_RAMP.indexOf(heats[0].fill)).toBeLessThan(HEAT_RAMP.length - 1);
});
it('names the best points a running search has scored so far, apart from each other', () => {
const at = (north, explained) => ({ ...fromLocal({ lat: 46.5, lon: 7.8 }, { x: 0, y: north }), explained });
const points = [at(0, 0.5), at(300, 0.6), at(2_000, 0.55), at(5_000, 0.2), at(9_000, 0), at(12_000, 0.4)];
// the 0.5 stands 300 m from the 0.6: one hot spot, its best named
expect(bestSoFar(points).map((p) => p.explained)).toEqual([0.6, 0.55, 0.4]);
expect(bestSoFar(points, 1_500, 2)).toHaveLength(2);
expect(bestSoFar([at(0, 0)])).toEqual([]);
});
it('draws the best ground in the ramp’s lightest step, nearly opaque, and the worst kept faint and dark', () => {
expect(heatStyle(0.9, 0.9, 0.2)).toEqual({ fill: HEAT_RAMP.at(-1), opacity: 0.72 });
expect(heatStyle(0.2, 0.9, 0.2)).toEqual({ fill: HEAT_RAMP[0], opacity: 0.12 });
const middle = heatStyle(0.55, 0.9, 0.2);
expect(HEAT_RAMP.indexOf(middle.fill)).toBeGreaterThan(0);
expect(middle.opacity).toBeGreaterThan(0.12);
expect(middle.opacity).toBeLessThan(0.72);
// one point alone is the best
expect(heatStyle(0.4, 0.4, 0.4).fill).toBe(HEAT_RAMP.at(-1));
});
it('shades by how far off the terrain the trace lies where nothing explains it, so the map is never blank', () => {
const scored = heatOf([{ explained: 0.6, gap: 0.2 }, { explained: 0.1, gap: 0.9 }]);
expect(scored[0]).toMatchObject({ fill: HEAT_RAMP.at(-1), tip: 'Explains 60% of the trace' });
const none = heatOf([{ explained: 0, gap: 0.3 }, { explained: 0, gap: 2.1 }, { explained: 0 }]);
expect(none[0]).toMatchObject({ fill: HEAT_RAMP.at(-1), tip: 'Explains 0%: the trace lies 0.3° off the terrain' });
expect(none[1].fill).toBe(HEAT_RAMP[0]);
expect(none[2]).toMatchObject({ fill: HEAT_RAMP[0], tip: 'Explains 0%' });
// a search kept before points said their gap draws as it did
expect(heatOf([{ explained: 0 }, { explained: 0 }])[0].tip).toBe('Explains 0% of the trace');
});
it('says why a point was ruled out: land over a sky-only line, on what share and how far out', () => {
expect(overText(0.234, 7_400)).toBe('land rises over the sky-only lines on 23%, 7 km out');
expect(overText(0.03)).toBe('land rises over the sky-only lines on 3%');
const tips = heatOf([{ explained: 0.6, gap: 0.2 }, { explained: 0, gap: 0.4, over: 0.4, over_far: 12_000 }]);
expect(tips[0].tip).toBe('Explains 60% of the trace');
expect(tips[1].tip).toBe('Ruled out: land rises over the sky-only lines on 40%, 12 km out');
// nothing explains the trace anywhere: the ruled-out points still say why
const none = heatOf([{ explained: 0, gap: 0.3, over: 0.2, over_far: 5_000 }, { explained: 0, gap: 1.1 }]);
expect(none.map((p) => p.tip)).toEqual([
'Ruled out: land rises over the sky-only lines on 20%, 5 km out',
'Explains 0%: the trace lies 1.1° off the terrain',
]);
});
});
describe('a reach the analyst gives', () => {
it('is searched on to twice as far, within Auto\'s farthest, as the engine reads it', () => {
expect(searchedReach(5_000)).toBe(10_000);
expect(searchedReach(40_000)).toBe(50_000);
expect(searchedReach(100_000)).toBe(100_000);
});
});
describe('a search kept, against the setup now', () => {
const ask = {
area: [[46.5, 7.8], [46.5, 7.9], [46.6, 7.9]],
who: { mode: 'ground', low: 1.7, high: 1.7 },
spacing: null,
alignments: [{ near: { lat: 46.55, lon: 7.85 }, far: { lat: 46.6, lon: 7.95 }, tops: false, heights: { near: 0, far: 0 } }],
photo: { path: 'media/ridge.jpg', strokes: [[{ u: 0.1, v: 0.4 }, { u: 0.5, v: 0.38 }]], marks: null },
hints: { zoom: 'wide', reach: 'auto' },
};
const now = () => ({
...structuredClone(ask),
area: ask.area.map(([lat, lon]) => ({ lat, lon })),
photo: { ...structuredClone(ask.photo), marks: { lines: [0], inner: [], pairs: [], cuts: [] } },
});
it('reads the same setup the same, the area as pairs or points and empty marks as none', () => {
expect(sameAsk(ask, now())).toBe(true);
// a zoom word kept alone reads as that word ticked alone
expect(sameAsk(ask, { ...now(), hints: { zoom: ['wide'], reach: 'auto' } })).toBe(true);
});
it('reads any change as changed, and nothing as not kept', () => {
const moved = now();
moved.area[0].lat += 0.01;
expect(sameAsk(ask, moved)).toBe(false);
const traced = now();
traced.photo.strokes.push([{ u: 0.6, v: 0.3 }]);
expect(sameAsk(ask, traced)).toBe(false);
const told = now();
told.hints = { zoom: 'zoomed', reach: 'auto' };
expect(sameAsk(ask, told)).toBe(false);
const flown = now();
flown.who = { mode: 'drone', low: 10, high: 120 };
expect(sameAsk(ask, flown)).toBe(false);
const cut = now();
cut.photo.marks.cuts = [0.5];
expect(sameAsk(ask, cut)).toBe(false);
// a line said sea, sky only or key is a change too
for (const said of ['sea', 'clear', 'key']) {
const marked = now();
marked.photo.marks[said] = [0];
expect(sameAsk(ask, marked)).toBe(false);
}
// and so is a part brushed as bent or where far land may be hidden
for (const brush of ['bent', 'hazy']) {
const brushed = now();
brushed.photo.marks[brush] = [{ path: [{ u: 0.3, v: 0.4 }], r: 0.05 }];
expect(sameAsk(ask, brushed)).toBe(false);
}
expect(sameAsk(ask, { ...now(), facing: ['n'] })).toBe(false);
expect(sameAsk(ask, { ...now(), stands: ['summit'] })).toBe(false);
expect(sameAsk(ask, { ...now(), view: ['down'] })).toBe(false);
expect(sameAsk(ask, { ...now(), mirror: true })).toBe(false);
const zoned = { ...ask, zones: [{ area: [[46.5, 7.8], [46.5, 7.81], [46.51, 7.81]], spacing: 100, out: false }] };
const zonedNow = { ...now(), zones: [{ area: [{ lat: 46.5, lon: 7.8 }, { lat: 46.5, lon: 7.81 }, { lat: 46.51, lon: 7.81 }], spacing: 100, out: false }] };
expect(sameAsk(zoned, zonedNow)).toBe(true);
expect(sameAsk(zoned, { ...zonedNow, zones: [{ ...zonedNow.zones[0], spacing: 250 }] })).toBe(false);
expect(sameAsk(zoned, now())).toBe(false);
const said = now();
said.photo.marks = { ...said.photo.marks, far: [{ line: 0, bands: ['b1'] }] };
expect(sameAsk(ask, said)).toBe(false);
expect(sameAsk(ask, null)).toBe(false);
expect(sameAsk(null, now())).toBe(false);
});
});
describe('a search in a line', () => {
it('says when it was made on this computer’s clock, and nothing for no date', () => {
expect(searchedWhen('2026-10-14T19:05:00')).toBe('14 Oct 2026, 19:05');
expect(searchedWhen(null)).toBe('');
expect(searchedWhen('not a date')).toBe('');
});
it('reads an area kept as pairs or drawn as points', () => {
expect(areaPoints([[1, 2]])).toEqual([{ lat: 1, lon: 2 }]);
expect(areaPoints([{ lat: 1, lon: 2, extra: true }])).toEqual([{ lat: 1, lon: 2 }]);
expect(areaPoints(null)).toEqual([]);
});
});
describe('which way the photo faces', () => {
it('ticks directions in the compass order, once each, and nothing else', () => {
expect(cleanFacing(['e', 'n', 'e', 'north'])).toEqual(['n', 'e']);
expect(cleanFacing(undefined)).toEqual([]);
expect(toggleFacing(['n'], 'ne')).toEqual(['n', 'ne']);
expect(toggleFacing(['n', 'ne'], 'n')).toEqual(['ne']);
});
it('joins directions side by side into one sector, round north too, as the app does', () => {
expect(facingSectors(['n'])).toEqual([{ centre: 0, half: 22.5 }]);
expect(facingSectors(['n', 'ne', 'e'])).toEqual([{ centre: 45, half: 67.5 }]);
expect(facingSectors(['nw', 'n', 'ne'])).toEqual([{ centre: 0, half: 67.5 }]);
expect(facingSectors(['n', 's'])).toEqual([
{ centre: 0, half: 22.5 },
{ centre: 180, half: 22.5 },
]);
// none ticked, or all, is any way
expect(facingSectors([])).toEqual([]);
expect(facingSectors(['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw'])).toEqual([]);
expect(facingText(['nw', 'n', 'ne', 's'])).toBe('S, NW to NE');
expect(facingText(['ne'])).toBe('NE');
expect(facingText([])).toBe('');
});
it('frames a search over every point it was drawn with, the unusable left out', () => {
const points = searchedPoints({
area: [{ lat: 10, lon: 40 }, { lat: 10, lon: 41 }, { lat: 11, lon: 41 }],
areas: [{ points: [{ lat: 12, lon: 42 }] }],
zones: [{ points: [{ lat: 9, lon: 39 }, { lat: null, lon: 39 }] }],
strokes: [{ path: [{ lat: 13, lon: 43 }] }],
});
expect(points).toEqual([
{ lat: 10, lon: 40 },
{ lat: 10, lon: 41 },
{ lat: 11, lon: 41 },
{ lat: 12, lon: 42 },
{ lat: 9, lon: 39 },
{ lat: 13, lon: 43 },
]);
expect(searchedPoints({})).toEqual([]);
});
it('draws a fan from the middle of the area, out as far as the search reads', () => {
const area = [
{ lat: 10, lon: 40 },
{ lat: 10, lon: 41 },
{ lat: 11, lon: 41 },
{ lat: 11, lon: 40 },
];
const middle = areaMiddle(area);
expect(middle).toEqual({ lat: 10.5, lon: 40.5 });
const [ring] = facingFan(middle, ['e'], 20_000);
expect(ring[0]).toEqual(middle);
for (const point of ring.slice(1)) {
expect(haversine(middle, point)).toBeCloseTo(20_000, -1);
const bearing = bearingBetween(middle, point);
expect(bearing).toBeGreaterThanOrEqual(67.4);
expect(bearing).toBeLessThanOrEqual(112.6);
}
expect(facingFan(middle, ['n', 's'], 5_000)).toHaveLength(2);
expect(facingFan(middle, [], 5_000)).toEqual([]);
});
it('rings the fan at 2, 5, 10, 20, 50 and 100 km, as far as the search reads', () => {
const middle = { lat: 10.5, lon: 40.5 };
const rings = facingRings(middle, ['e'], 20_000);
expect(rings.map((r) => r.metres)).toEqual([2_000, 5_000, 10_000, 20_000]);
for (const ring of rings) {
for (const point of ring.points) expect(haversine(middle, point)).toBeCloseTo(ring.metres, -1);
// its words stand on the sector's middle
expect(bearingBetween(middle, ring.label)).toBeCloseTo(90, 3);
}
expect(facingRings(middle, ['n', 's'], 50_000)).toHaveLength(10);
expect(facingRings(middle, [], 50_000)).toEqual([]);
});
});
describe('how far a result can be trusted', () => {
const points = Array.from({ length: 21 }, (_, i) => ({ lat: 0, lon: 0, explained: i / 50 }));
const ask = { trace: { known: false, within: [30, 65] }, who: { mode: 'ground' }, photo: { path: 'media/p.png' } };
const best = { lat: 12.9, lon: 43.6, explained: 0.79, heading: 123, fov: 42, tilt: -3, roll: 1.7 };
const far = (km) => destination(best, 90, km * 1000);
it('reads the area’s chance fits off its top tenth', () => {
expect(chanceFit(points)).toBeCloseTo(0.36, 6);
expect(chanceFit(points.slice(0, 5))).toBeNull();
});
it('is solid when one place stands out and nothing speaks against it', () => {
const second = { ...far(10), explained: 0.5 };
expect(reliability({ verdict: 'match', places: [best, second], points }, { ask })).toEqual({ level: 'solid', reasons: [], chance: chanceFit(points) });
});
it('says each thing that lowers it, one alone asking for a check and two making it weak', () => {
const rival = { ...far(12), explained: 0.72 };
const one = reliability({ verdict: 'match', places: [best, rival], points }, { ask });
expect(one).toMatchObject({ level: 'check', reasons: ['Another place 12 km away explains nearly as much'] });
// a rival nearer than 3 km is the same hot spot
expect(reliability({ verdict: 'match', places: [best, { ...far(2), explained: 0.78 }], points }, { ask }).level).toBe('solid');
const pushed = { ...best, fov: 64, roll: -4.9, tilt: -16 };
expect(reliability({ verdict: 'match', places: [pushed], points }, { ask }).reasons).toEqual([
'The lens found, 64°, is the widest tried',
'The camera had to roll 5°, the most allowed',
'The camera tilts 16° down',
]);
// a drone looks down as it likes; a lens the photo says has no edge to sit at
const drone = reliability({ verdict: 'match', places: [{ ...best, tilt: -30 }], points }, { ask: { ...ask, who: { mode: 'drone' } } });
expect(drone.level).toBe('solid');
const known = reliability({ verdict: 'match', places: [{ ...best, fov: 30 }], points }, { ask: { ...ask, trace: { known: true, within: [30, 65] } } });
expect(known.level).toBe('solid');
const marked = reliability({ verdict: 'match', places: [{ ...best, inner: 0.3, pairs: [1, 3] }], points }, { ask });
expect(marked).toMatchObject({ level: 'weak', reasons: ['The ridges in front lie off the terrain there', '2 of 3 front and behind pairs are out of order'] });
});
it('says what does not fit at the best place: marks it does better without, a piece at its edge, land over Sky only', () => {
const costly = reliability({ verdict: 'match', places: [{ ...best, bare: 0.96 }], points }, { ask });
expect(costly).toMatchObject({ look: true, reasons: ['Without your distances, Sky only, pairs and key lines it explains 96%: one of them may be wrong here'] });
// marks that cost a little say nothing
expect(reliability({ verdict: 'match', places: [{ ...best, bare: 0.9 }], points }, { ask }).level).toBe('solid');
const pieces = [{ piece: 0, turn: 0.25 }, { piece: 1, turn: 1, edge: true }, { piece: 2, tilt: 0.5 }];
expect(reliability({ verdict: 'match', places: [{ ...best, pieces }], points }, { ask }).reasons).toEqual([
'The 2nd piece from the left fits badly here: check how it is laid or stretched',
]);
const both = pieces.map((p) => ({ ...p, edge: true }));
expect(reliability({ verdict: 'match', places: [{ ...best, pieces: both }], points }, { ask }).reasons).toEqual([
'3 pieces fit badly here: check how they are laid or stretched',
]);
const over = reliability({ verdict: 'match', places: [{ ...best, over: 0.08, over_far: 4465 }], points }, { ask });
expect(over).toMatchObject({ look: true, reasons: ['Land rises over your Sky only lines here (8%, 4 km away)'] });
expect(reliability({ verdict: 'match', places: [{ ...best, over: 0.03 }], points }, { ask }).level).toBe('solid');
// a reason that is not about the lines offers no look at them
expect(reliability({ verdict: 'match', places: [{ ...best, inner: 0.3 }], points }, { ask }).look).toBeUndefined();
});
it('offers a photo when a panorama’s lens sits at the narrowest a panorama is tried, or little explains it', () => {
const strip = { ...ask, hints: { picture: 'panorama' }, trace: { known: false, within: [60, 360] } };
const narrow = reliability({ verdict: 'match', places: [{ ...best, fov: 60 }], points }, { ask: strip });
expect(narrow).toMatchObject({ level: 'check', photo: true });
expect(narrow.reasons).toEqual(['Found with the narrowest panorama lens (60°): if the frames are zoomed or the collage leans, try Read as a photo']);
for (const verdict of ['none', 'loose']) {
const lost = reliability({ verdict, places: [{ ...best, fov: 68, explained: 0 }], points: [] }, { ask: strip });
expect(lost).toMatchObject({ photo: true, reasons: ['Little fits as a panorama: if the frames are zoomed or the collage leans, try Read as a photo'] });
}
// a photo that little explains is told nothing of the kind
expect(reliability({ verdict: 'none', places: [{ ...best, explained: 0 }], points: [] }, { ask }).photo).toBeUndefined();
// a wider one, or the widest, says nothing: a panorama's top is its own width
expect(reliability({ verdict: 'match', places: [{ ...best, fov: 92 }], points }, { ask: strip })).toEqual({ level: 'solid', reasons: [], chance: chanceFit(points) });
expect(reliability({ verdict: 'match', places: [{ ...best, fov: 350 }], points }, { ask: strip }).level).toBe('solid');
});
it('says when a decoy of the trace fits the best place nearly as well', () => {
const decoyed = reliability({ verdict: 'match', places: [{ ...best, decoy: 0.7 }], points }, { ask });
expect(decoyed.reasons).toEqual(['A decoy of the trace fits there nearly as well (70%)']);
expect(reliability({ verdict: 'match', places: [{ ...best, decoy: 0.3 }], points }, { ask }).level).toBe('solid');
});
it('says when the best barely rises above what the area fits by chance', () => {
const low = reliability({ verdict: 'match', places: [{ ...best, explained: 0.45 }], points }, { ask });
expect(low.reasons).toEqual(['Barely above the chance fits of the area (36%)']);
});
it('is weak whenever the verdict names no single place, without saying the verdict again', () => {
const rival = { ...far(30), explained: 0.77 };
const ambiguous = reliability({ verdict: 'ambiguous', places: [best, rival], points }, { ask });
expect(ambiguous).toMatchObject({ level: 'weak', reasons: [] });
expect(reliability({ verdict: 'loose', places: [best], points }, { ask }).level).toBe('weak');
expect(reliability({ verdict: 'none', places: [], points }, { ask }).level).toBe('weak');
});
it('weighs the other searches of the same photo that named a place elsewhere as strongly', () => {
const elsewhere = { name: 'other', title: 'Ridge search 2', status: 'done', verdict: 'match', photo: 'media/p.png', best: { ...far(29), explained: 0.75 } };
const told = reliability({ verdict: 'match', places: [best], points }, { ask, name: 'mine', others: [elsewhere] });
expect(told).toMatchObject({ level: 'check', reasons: ['“Ridge search 2” found a place 29 km away that explains 75%'] });
// not the search itself, another photo's, one that named no single place, a weaker one, or one that agrees
for (const row of [
{ ...elsewhere, name: 'mine' },
{ ...elsewhere, photo: 'media/q.png' },
{ ...elsewhere, verdict: 'ambiguous' },
{ ...elsewhere, best: { ...elsewhere.best, explained: 0.5 } },
{ ...elsewhere, best: { ...far(1), explained: 0.8 } },
]) {
expect(reliability({ verdict: 'match', places: [best], points }, { ask, name: 'mine', others: [row] }).level).toBe('solid');
}
});
});
describe('a best place standing alone, and a trace too plain', () => {
const best = { lat: 12.9, lon: 43.6, explained: 0.71, heading: 65, fov: 54, tilt: 2, roll: -2 };
const ask = { trace: { known: false, within: [30, 65] }, who: { mode: 'ground' } };
const ring = (explained, metres = 100) => Array.from({ length: 8 }, (_, i) => ({ ...destination(best, i * 45, metres), explained }));
it('reads what the ground right round the best place explains, from enough points', () => {
expect(neighbourFit(best, ring(0.66))).toBeCloseTo(0.66, 6);
// farther points, or too few, say nothing
expect(neighbourFit(best, ring(0.2, 400))).toBeNull();
expect(neighbourFit(best, ring(0.2).slice(0, 3))).toBeNull();
});
it('says a lone spike where the ground round it explains far less, and nothing where it rises too', () => {
const lone = reliability({ verdict: 'match', places: [best], points: ring(0.18) }, { ask });
expect(lone).toMatchObject({ level: 'check', reasons: ['The ground 150 m around explains much less (18%): a lone spike'] });
expect(reliability({ verdict: 'match', places: [best], points: ring(0.66) }, { ask }).level).toBe('solid');
});
it('counts the turns of the trace across the picture, small wobbles left out', () => {
const x = Array.from({ length: 61 }, (_, i) => -1 + i / 30);
const wavy = { x, y: x.map((v) => 0.05 * Math.sin(v * 9)), half_width: 600 };
expect(traceTurns(wavy)).toBe(6);
const wobbly = { x, y: x.map((v, i) => 0.002 * (i % 2)), half_width: 600 };
expect(traceTurns(wobbly)).toBe(0);
// read from left to right whatever order the points came in
expect(traceTurns({ ...wavy, x: [...wavy.x].reverse(), y: [...wavy.y].reverse() })).toBe(6);
});
it('says when the trace turns too few times to name one place', () => {
const x = Array.from({ length: 41 }, (_, i) => -1 + i / 20);
const plain = { ...ask, trace: { ...ask.trace, x, y: x.map((v) => 0.1 * Math.cos(v * 3)), half_width: 600 } };
const told = reliability({ verdict: 'match', places: [best], points: [] }, { ask: plain });
// one rise and fall across the picture: a single turn
expect(told.reasons).toEqual(['The trace turns only 1 time: a plain shape fits many places']);
});
});
describe('the sun against the camera', () => {
it('keeps the sides in the menu order and asks with the sun only once a day and a side are said', () => {
expect(cleanSun({ date: '2024-06-21', start: '7:00', end: '19:30', sides: ['behind', 'ahead', 'up'] })).toEqual({
date: '2024-06-21',
start: '06:00',
end: '19:30',
sides: ['ahead', 'behind'],
});
expect(sunAsked({ date: '', sides: ['ahead'] })).toBeNull();
expect(sunAsked({ date: '2024-06-21', sides: [] })).toBeNull();
expect(sunAsked({ date: '2024-06-21', sides: ['left'] })).toEqual({ date: '2024-06-21', start: '06:00', end: '18:00', sides: ['left'] });
expect(SUN_SIDES.map((side) => side.id)).toEqual(['ahead', 'left', 'right', 'behind']);
});
it('draws any sectors as a fan', () => {
const from = { lat: 10, lon: 40 };
expect(fanOf(from, [{ centre: 180, half: 45 }], 5_000)).toHaveLength(1);
expect(ringsOf(from, [{ centre: 180, half: 45 }], 10_000).map((r) => r.metres)).toEqual([2_000, 5_000, 10_000]);
});
});
describe('where the eye stands', () => {
it('ticks grounds in the menu order, once each, and says them', () => {
expect(cleanStands(['plain', 'summit', 'plain', 'cliff'])).toEqual(['summit', 'plain']);
expect(toggleStand(['summit'], 'slope')).toEqual(['summit', 'slope']);
expect(toggleStand(['summit', 'slope'], 'summit')).toEqual(['slope']);
expect(standsText(['summit', 'slope'])).toBe('summit or ridge or slope');
expect(standsText([])).toBe('');
});
it('says what the grid keeps of the ground ticked, and the water left out', () => {
const preview = { total: 2400, kept: 640, kinds: { summit: 640, slope: 900, valley: 500, plain: 240, water: 120 } };
expect(groundText(preview, ['summit'])).toBe('Keeps 640 of 2,400 points (27%), 120 on water left out.');
expect(groundText({ ...preview, kept: 2280 }, [])).toBe('120 on water left out.');
expect(groundText({ ...preview, kinds: { ...preview.kinds, water: 0 } }, [])).toBe('');
expect(groundText(null, ['summit'])).toBe('');
// water ticked is searched, not left out
expect(groundText(preview, ['summit', 'water'])).toBe('Keeps 640 of 2,400 points (27%).');
expect(cleanStands(['water', 'plain'])).toEqual(['plain', 'water']);
});
it('shrinks the size said by what the ground leaves out, the filling-in with it', () => {
const estimated = { points: 1000, coarse: 800, most: 3400, step: 0.5 };
expect(withGround(estimated, { total: 800, kept: 200 })).toEqual({ points: 400, coarse: 800, most: 1000, step: 0.5 });
expect(withGround(estimated, null)).toBe(estimated);
expect(withGround(null, { total: 800, kept: 200 })).toBeNull();
});
});
describe('what the trace says before a search', () => {
it('reads which way the camera looks from where the skyline stands in the frame', () => {
// a portrait phone frame from a hilltop: the skyline 1.2 half widths up through a 51° lens asks about 30° down
const high = { y: [1.13, 1.2, 1.31], fov: 51, projection: 'camera' };
expect(lookingOf(high, 'ground')).toBe('down');
expect(lookingOf(high, 'drone')).toBeNull();
expect(lookingOf({ y: [0.05, 0.1, 0.2], fov: 51 }, 'ground')).toBeNull();
expect(lookingOf({ y: [-1.6, -1.5, -1.4], fov: 60 }, 'ground')).toBe('up');
expect(lookingOf({ y: [], fov: 51 })).toBeNull();
// a panorama reads its rows evenly: 0.4 half widths up a 60° strip is 12°, a whole one 30°
expect(lookingOf({ y: [0.3, 0.4, 0.5], fov: 60, projection: 'panorama' }, 'ground')).toBeNull();
expect(lookingOf({ y: [0.9, 1, 1.1], fov: 60, projection: 'panorama' }, 'ground')).toBe('down');
// the same height through a long lens is a small angle: 12° up a 24° frame stays well within the bounds
expect(lookingOf({ y: [0.9, 1, 1.1], fov: 24, projection: 'camera' }, 'ground')).toBeNull();
// a ridge stands over the horizon, so a skyline asking 17° down is offered already
expect(lookingOf({ y: [0.9, 1, 1.1], fov: 33.2 }, 'ground')).toBe('down');
});
it('says how wide a trace spans', () => {
expect(traceSpan({ x: [-1, 0, 1], fov: 60 })).toBeCloseTo(60, 6);
expect(traceSpan({ x: [-0.8, 0.76], fov: 125.78, projection: 'panorama' })).toBeCloseTo(98.1, 1);
expect(traceSpan({ x: [], fov: 60 })).toBe(0);
});
});
describe('how a kept search ended', () => {
it('says a search saved without running is not searched yet, quietly', () => {
expect(searchEnding({ status: 'saved' })).toBe('saved, not searched');
expect(searchTone({ status: 'saved' })).toBe('quiet');
expect(searchEnding({ status: 'cancelled' })).toBe('stopped');
expect(searchEnding({ status: 'done', best: { explained: 0.62 } })).toBe('best explains 62%');
});
});