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
14.1 KB
Raw Blame
/**
 * What a measure on the map reads, apart from the map.
 *
 * A measure is points clicked on the map, open (a line) or closed (an area).
 * A line of two points can also be *used as* something: a range ring round A,
 * a view cone from A toward B, a shadow from an object's foot at A to its tip
 * at B, or the reach of a viewshed from A. One gesture and then a choice,
 * rather than a tool per question: each of those is a distance and a bearing
 * from a point, and drawing one is the same two clicks whatever it is for.
 *
 * Everything here is arithmetic over plain data (`{ points, closed, use,
 * rings, aperture }`), so the readings, the words on the map and the copied
 * text are read off a test (measures.test.js).
 */
import { bearingBetween } from './horizon/geometry.js';
import {
  angleAt,
  centroid,
  cone,
  crossing,
  destination,
  formatArea,
  formatBearing,
  formatDistance,
  formatHeight,
  haversine,
  midway,
  pathLength,
  perimeter,
  polygonArea,
} from './measure.js';

/** What a line of two points can be used as, in the order the panel offers them. */
export const USES = [
  { id: 'ring', label: 'Ring', title: 'Circles round A, as wide as the line' },
  { id: 'cone', label: 'Cone', title: 'What a camera at A facing B takes in' },
  { id: 'shadow', label: 'Shadow', title: 'A shadow from a foot at A to its tip at B: how tall, and the hour' },
  { id: 'viewshed', label: 'Viewshed', title: 'The ground in sight from A, out as far as B' },
];

/** How many rings a range can carry, and how wide a cone opens by default. */
export const MAX_RINGS = 5;
export const APERTURE = 60;

/** A fresh measure, starting at one point. */
export function newMeasure(id, at) {
  return { id, points: [{ lat: at.lat, lon: at.lon }], closed: false, use: null, rings: 1, aperture: APERTURE };
}

/** A line of exactly two points: the one shape with a bearing and a use. */
export function isPair(measure) {
  return Boolean(measure) && !measure.closed && measure.points.length === 2;
}

/** Each straight piece of a measure, closing back to the start for an area. */
export function legs(measure) {
  const points = measure.closed ? [...measure.points, measure.points[0]] : measure.points;
  return points.slice(1).map((to, i) => {
    const from = points[i];
    return { from, to, length: haversine(from, to), bearing: bearingBetween(from, to) };
  });
}

/** The length and bearing of a line of two points, and the bearing back. */
export function pairReading(measure) {
  const [a, b] = measure.points;
  const toward = bearingBetween(a, b);
  return { length: haversine(a, b), bearing: toward, back: bearingBetween(b, a) };
}

/**
 * The measure in one line, for the status bar and the list: an area's size, a
 * line's length, and for a line of two points its bearing or what it is used
 * as. Empty while a measure is one point short of meaning anything.
 */
export function headline(measure, units) {
  const { points } = measure;
  if (points.length < 2) return '';
  if (measure.closed) return points.length >= 3 ? formatArea(polygonArea(points), units) : '';
  if (points.length > 2) return formatDistance(pathLength(points), units);
  const { length, bearing } = pairReading(measure);
  if (measure.use === 'ring') return `Radius ${formatDistance(length, units)}`;
  if (measure.use === 'cone') return `${Math.round(measure.aperture)}° cone · ${formatDistance(length, units)}`;
  return `${formatDistance(length, units)} · ${formatBearing(bearing)}`;
}

/**
 * The words written on the map beside a measure: each leg's length and
 * bearing at its middle, the whole length at the end of a line of several
 * legs, the angle at each inner corner of a line, and an area's size in its
 * middle. Rings say their radius on their edge, clear of the line.
 *
 * A leg's label carries its two ends, and a corner's angle its two
 * neighbours, so whoever places them can set them off the line on screen, or
 * leave a leg's out where the leg is too short to hold it.
 */
export function labels(measure, units) {
  const { points } = measure;
  if (points.length < 2) return [];
  const out = legs(measure).map((leg, i) => ({
    id: `leg-${i}`,
    kind: 'leg',
    at: midway(leg.from, leg.to),
    text: `${formatDistance(leg.length, units)} · ${formatBearing(leg.bearing)}`,
    from: leg.from,
    to: leg.to,
  }));
  if (measure.closed && points.length >= 3) {
    out.push({ id: 'area', kind: 'area', at: centroid(points), text: formatArea(polygonArea(points), units) });
  }
  if (!measure.closed && points.length > 2) {
    out.push({ id: 'total', kind: 'total', at: points.at(-1), text: formatDistance(pathLength(points), units), around: [points.at(-2)] });
    for (let i = 1; i < points.length - 1; i++) {
      const deg = angleAt(points[i - 1], points[i], points[i + 1]);
      out.push({ id: `angle-${i}`, kind: 'angle', at: points[i], text: `${Math.round(deg)}°`, around: [points[i - 1], points[i + 1]] });
    }
  }
  if (isPair(measure) && measure.use === 'ring' && measure.rings > 1) {
    const { length, bearing } = pairReading(measure);
    for (let k = 2; k <= measure.rings; k++) {
      out.push({
        id: `ring-${k}`,
        kind: 'ring',
        at: destination(points[0], bearing + 90, length * k),
        text: formatDistance(length * k, units),
      });
    }
  }
  return out;
}

/** The shapes a line's use adds round it: rings, or a cone. */
export function useShapes(measure) {
  if (!isPair(measure)) return [];
  const [a] = measure.points;
  const { length, bearing } = pairReading(measure);
  if (measure.use === 'ring') {
    const count = Math.max(1, Math.min(MAX_RINGS, Math.round(measure.rings) || 1));
    return Array.from({ length: count }, (_, i) => ({ kind: 'circle', at: a, radiusM: length * (i + 1) }));
  }
  if (measure.use === 'cone') return [{ kind: 'polygon', points: cone(a, bearing, measure.aperture, length) }];
  return [];
}

/** How wide a cone is where it reaches B: the side a camera there would frame. */
export function coneWidth(measure) {
  const { length } = pairReading(measure);
  return 2 * length * Math.tan(((Math.min(179, measure.aperture) / 2) * Math.PI) / 180);
}

/** Two crossings closer than this are one, and a crossing at a shared end is no crossing. */
const SAME_POINT_M = 0.5;

/**
 * Where the lines of different measures cross. Two bearings drawn from two
 * places meet at what both point at, so a crossing is marked and named rather
 * than left for the eye to find.
 */
export function crossings(measures) {
  const lines = measures.filter((m) => !m.closed && m.points.length >= 2);
  const found = [];
  for (let i = 0; i < lines.length; i++) {
    for (let j = i + 1; j < lines.length; j++) {
      const ends = [lines[i].points[0], lines[i].points.at(-1), lines[j].points[0], lines[j].points.at(-1)];
      for (const one of legs(lines[i])) {
        for (const other of legs(lines[j])) {
          const at = crossing(one.from, one.to, other.from, other.to);
          if (!at || ends.some((end) => haversine(end, at) < SAME_POINT_M)) continue;
          if (found.some((seen) => haversine(seen.at, at) < SAME_POINT_M)) continue;
          found.push({ at, between: [lines[i].id, lines[j].id] });
        }
      }
    }
  }
  return found;
}

/**
 * The stretches of a profile's line its eye sees and does not, each as the
 * points to draw it through. Neighbouring stretches share their meeting point,
 * so the line is drawn whole in two colours.
 */
export function sightRuns(profile) {
  const seen = profile?.sight?.seen;
  if (!seen?.length) return [];
  const runs = [];
  let current = null;
  seen.forEach((value, i) => {
    const point = { lat: profile.lat[i], lon: profile.lon[i] };
    if (current?.seen === value) {
      current.points.push(point);
      return;
    }
    current = { seen: value, points: current ? [current.points.at(-1), point] : [point] };
    runs.push(current);
  });
  return runs.filter((run) => run.points.length >= 2);
}

/**
 * A viewshed's answer (`/api/terrain/viewshed`) as one shape to fill.
 *
 * Each stretch of a ray in sight is a wedge as wide as the ray's share of the
 * turn, so neighbouring rays tile the ground. Wedges of neighbouring rays that
 * overlap are chained into one outline, out along their far edges and back
 * along their near ones: a thousand wedges side by side would each have their
 * edges smoothed, and the ground in sight would read as a striped fan.
 */
export function viewshedGeometry(answer) {
  const centre = { lat: answer.lat, lon: answer.lon };
  const half = answer.step_deg / 2;
  const strips = [];
  let open = [];
  answer.runs.forEach((run, ray) => {
    const azimuth = ray * answer.step_deg;
    const next = [];
    for (let k = 0; k + 1 < run.length; k += 2) {
      const [near, far] = [run[k], run[k + 1]];
      if (!(far > near)) continue;
      const wedge = { azimuth, near, far };
      // the strip this wedge carries on: one whose last wedge it overlaps, not yet carried on by another
      const strip = open.find((one) => !one.carried && near < one.last.far && one.last.near < far);
      if (strip) {
        strip.wedges.push(wedge);
        strip.last = wedge;
        strip.carried = true;
        next.push(strip);
      } else {
        const fresh = { wedges: [wedge], last: wedge, carried: true };
        strips.push(fresh);
        next.push(fresh);
      }
    }
    for (const strip of next) strip.carried = false;
    open = next;
  });
  const at = (azimuth, metres) => (metres > 0 ? destination(centre, azimuth, metres) : centre);
  const coordinates = strips.map(({ wedges }) => {
    const outer = wedges.flatMap((w) => [at(w.azimuth - half, w.far), at(w.azimuth + half, w.far)]);
    const inner = [...wedges].reverse().flatMap((w) => [at(w.azimuth + half, w.near), at(w.azimuth - half, w.near)]);
    const ring = [...outer, ...inner];
    return [[...ring, ring[0]].map((point) => [point.lon, point.lat])];
  });
  return { type: 'MultiPolygon', coordinates };
}

const METRES_PER = { m: 1, km: 1000, ft: 0.3048, mi: 1609.344, nm: 1852 };

/** The unit a typed distance is read in when it names none, for the analyst's units. */
export function fieldUnit(metres, units) {
  if (units === 'nautical') return 'nm';
  if (units === 'imperial') return metres < METRES_PER.mi ? 'ft' : 'mi';
  return metres < 1000 ? 'm' : 'km';
}

/** A distance written into a field in `unit`: no more decimals than the unit needs. */
export function fieldValue(metres, unit) {
  const value = metres / METRES_PER[unit];
  const short = unit === 'm' || unit === 'ft';
  const decimals = short ? (value >= 100 ? 0 : 1) : 3;
  return String(Number(value.toFixed(decimals)));
}

/**
 * A distance as somebody types it, in metres: "2.5", "2,5 km", "800 m",
 * "1.2 mi", "3 NM", "500 ft". A bare number is in `unit`. Null for anything
 * else, and for nothing at all.
 */
export function parseDistance(text, unit) {
  const typed = String(text ?? '').trim().toLowerCase().replace(',', '.');
  const match = typed.match(/^(\d+(?:\.\d+)?|\.\d+)\s*(m|km|ft|mi|nm)?$/);
  if (!match) return null;
  const metres = Number(match[1]) * METRES_PER[match[2] ?? unit];
  return metres > 0 ? metres : null;
}

/**
 * The measure as text to paste into notes: what it reads, then where it is,
 * with the ground and the answer of its use when they are known. `coords`
 * writes a point the way the analyst's coordinates read everywhere else.
 */
export function summary(measure, units, { coords, ground = null, shadow = null, viewshed = null } = {}) {
  const { points } = measure;
  const at = (point) => coords(point.lat, point.lon);
  const lines = [];
  if (measure.closed) {
    lines.push(`Area ${formatArea(polygonArea(points), units)}, perimeter ${formatDistance(perimeter(points), units)}`);
    lines.push(`Corners: ${points.map(at).join('; ')}`);
    return lines.join('\n');
  }
  if (!isPair(measure)) {
    lines.push(`Distance ${formatDistance(pathLength(points), units)} over ${points.length - 1} legs`);
    lines.push(`Through: ${points.map(at).join('; ')}`);
    return lines.join('\n');
  }
  const { length, bearing, back } = pairReading(measure);
  lines.push(`Distance ${formatDistance(length, units)}, bearing ${formatBearing(bearing, 1)} (back ${formatBearing(back, 1)})`);
  lines.push(`From ${at(points[0])} to ${at(points[1])}`);
  if (ground?.corners?.length === 2) {
    const [from, to] = ground.corners;
    lines.push(`Ground ${formatHeight(from, units)} to ${formatHeight(to, units)} (${signed(to - from, units)})`);
  }
  if (ground?.sight) lines.push(sightSentence(ground.sight, units));
  if (measure.use === 'ring') {
    const count = Math.max(1, measure.rings);
    lines.push(`Rings every ${formatDistance(length, units)}, out to ${formatDistance(length * count, units)}`);
  }
  if (measure.use === 'cone') {
    lines.push(`Cone ${Math.round(measure.aperture)}° wide, ${formatDistance(coneWidth(measure), units)} across at B`);
  }
  if (measure.use === 'shadow' && shadow) lines.push(shadowSentence(shadow, units));
  if (measure.use === 'viewshed' && viewshed) {
    lines.push(`Viewshed: ${Math.round(viewshed.share * 100)}% of the ground within ${formatDistance(viewshed.radius_m, units)} in sight`);
  }
  return lines.join('\n');
}

/** A rise or a fall with its sign, in the analyst's height unit. */
export function signed(metres, units) {
  const text = formatHeight(Math.abs(metres), units);
  return `${metres >= 0 ? '+' : '−'}${text}`;
}

/** Whether B is in sight from A, as one sentence. */
function sightSentence(sight, units) {
  return sight.visible
    ? 'B is in sight from A'
    : `B is out of sight from A: ground in the way at ${formatDistance(sight.blocked_at_m, units)}`;
}

/** A shadow's answer (`/api/geo/shadow`) as one sentence, or why it has none. */
export function shadowSentence(shadow, units) {
  const [first, second] = shadow.moments ?? [];
  if (!first) return `No hour of ${shadow.date} casts this shadow`;
  const clock = (moment) => moment.local.slice(11, 16);
  const height = `About ${formatHeight(first.height_m, units)} tall`;
  const when = `sun at ${formatBearing(first.sun_azimuth)}, ${first.sun_altitude.toFixed(1)}° up at ${clock(first)} ${first.abbreviation}`;
  const also = second ? `, or ${formatHeight(second.height_m, units)} at ${clock(second)}` : '';
  return `${height} (${when}${also})`;
}