mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
feat(vessels): key vessels by their source's stable id, and share a selected vessel
AIS Vessels are keyed by the id their live source gives, with the MMSI as an attribute: an MMSI can be shared, spoofed or reused, so two vessels with one MMSI are now two vessels. Looking a vessel up or selecting it by MMSI still finds it. A share link made while a vessel is selected opens that vessel. A UUID vessel id travels as 16 bytes in a new thing field (13). A shared thing that is not reporting now says so in a sentence per kind, with its id (ICAO, NORAD, MMSI or vessel UUID) on a second line.
This commit is contained in:
1 parent
57ff81f723
commit
cbbf55cacd
74 files changed
+2481
-586
No files matched your search
@@ -8,6 +8,11 @@
|
||||
* getTrack(reference, { signal }). References are opaque to consumers.
|
||||
* Snapshots describe coverage and completeness independently of freshness.
|
||||
* Records contain observation data only, with no scene objects or transport data.
|
||||
* Every record has a stable `id` (a non-empty string) that keys it across
|
||||
* snapshots. A vessel record's `id` is whatever its source gives, such as a
|
||||
* provider id; its `mmsi` is an optional attribute ('' or absent when
|
||||
* unknown), never its key, since vessels can share an MMSI. A source that
|
||||
* only has MMSIs uses the MMSI as the id.
|
||||
*
|
||||
* A source may also declare a timeline (see readSnapshotTimeline): it can
|
||||
* answer a snapshot at a given time, so the layer follows the world clock.
|
||||
@@ -155,8 +160,9 @@ export function httpError(response, source) {
|
||||
* malformed: `{ coverage(), stepMs, subscribe? }`. `coverage()` returns the
|
||||
* span `{start, end}` (epoch ms) the source can answer a snapshot for, or
|
||||
* null while it does not know yet; `stepMs` is the spacing of its snapshots;
|
||||
* the optional `subscribe(listener)` tells of a change in coverage and
|
||||
* returns the unsubscribe.
|
||||
* the optional `subscribe(listener)` tells of a change in coverage, or of a
|
||||
* better answer for a time already answered (a paused layer then loads the
|
||||
* time shown again), and returns the unsubscribe.
|
||||
* @param {object|null|undefined} source
|
||||
* @returns {{coverage: () => ({start: number, end: number}|null),
|
||||
* stepMs: number, subscribe: ((listener: () => void) => () => void)|null}|null}
|
||||
|
||||
@@ -9,6 +9,7 @@ import {
|
||||
openSkySnapshot,
|
||||
readsbSnapshot,
|
||||
readSnapshotTimeline,
|
||||
vesselSnapshot,
|
||||
} from './index.js';
|
||||
|
||||
const now = 1800000000000;
|
||||
@@ -196,6 +197,7 @@ test('vessel identity, opaque reference and heading/course remain distinct, unkn
|
||||
'opaque-reference',
|
||||
);
|
||||
assert.equal(row.id, '123456789');
|
||||
assert.equal(row.mmsi, '123456789');
|
||||
assert.equal(row.reference, 'opaque-reference');
|
||||
assert.equal(row.headingDeg, 45);
|
||||
assert.equal(row.courseDeg, 60);
|
||||
@@ -525,3 +527,62 @@ test('a source declares a timeline only with a coverage reader and a positive st
|
||||
stop();
|
||||
assert.equal(listeners.length, 0);
|
||||
});
|
||||
|
||||
test('vessel snapshots key rows by the id idFor gives; the MMSI is an attribute', () => {
|
||||
const at = { lat: 30, lon: -97 };
|
||||
const rows = [
|
||||
{ uuid: 'hull-a', mmsi: '123456789', ...at },
|
||||
{ uuid: 'hull-b', mmsi: '123456789', ...at },
|
||||
{ uuid: 'hull-c', mmsi: 'not-an-mmsi', ...at },
|
||||
{ uuid: 'hull-a', mmsi: '123456789', ...at },
|
||||
];
|
||||
const keyed = vesselSnapshot(
|
||||
{ rows },
|
||||
{ idFor: (row) => row.uuid || row.mmsi },
|
||||
);
|
||||
assert.deepEqual(
|
||||
keyed.records.map(({ id, mmsi, reference }) => [id, mmsi, reference]),
|
||||
[
|
||||
['hull-a', '123456789', 'hull-a'],
|
||||
['hull-b', '123456789', 'hull-b'],
|
||||
['hull-c', '', 'hull-c'],
|
||||
],
|
||||
);
|
||||
assert.equal(keyed.rejectedCount, 1, 'a repeated id is one vessel');
|
||||
|
||||
// AISStream rows have only MMSIs: one MMSI is one vessel, as before.
|
||||
const ais = vesselSnapshot({ rows });
|
||||
assert.deepEqual(
|
||||
ais.records.map(({ id, mmsi, reference }) => [id, mmsi, reference]),
|
||||
[
|
||||
['123456789', '123456789', '123456789'],
|
||||
['not-an-mmsi', '', 'not-an-mmsi'],
|
||||
],
|
||||
);
|
||||
const referenced = vesselSnapshot(
|
||||
{ rows: rows.slice(0, 1) },
|
||||
{ idFor: (row) => row.uuid, referenceFor: (row) => `track:${row.uuid}` },
|
||||
);
|
||||
assert.equal(referenced.records[0].reference, 'track:hull-a');
|
||||
});
|
||||
|
||||
test('a vessel with no name is not named by its id; a ten-digit MMSI is an MMSI', () => {
|
||||
const at = { lat: 30, lon: -97 };
|
||||
const [unnamed, longMmsi, named] = vesselSnapshot(
|
||||
{
|
||||
rows: [
|
||||
{ uuid: 'f00dcafe-0000-0000-0000-000000000001', ...at },
|
||||
{ uuid: 'hull-x', mmsi: '1234567890', ...at },
|
||||
{ uuid: 'hull-y', mmsi: '244123456', name: 'EVER GIVEN', ...at },
|
||||
],
|
||||
},
|
||||
{ idFor: (row) => row.uuid },
|
||||
).records;
|
||||
assert.equal(unnamed.name, '');
|
||||
assert.equal(unnamed.mmsi, '');
|
||||
assert.deepEqual(
|
||||
[longMmsi.mmsi, longMmsi.name],
|
||||
['1234567890', '1234567890'],
|
||||
);
|
||||
assert.equal(named.name, 'EVER GIVEN');
|
||||
});
|
||||
+47
-10
@@ -1,18 +1,41 @@
|
||||
import { coordinates, epoch, finite, LiveSourceError } from './contract.js';
|
||||
|
||||
/** AIS positions are sea-surface observations; heading and course are distinct. */
|
||||
export function normalizeVesselObservation(row, reference = null) {
|
||||
const id = String(row?.mmsi || row?.input_identifier || '').trim();
|
||||
/** An MMSI is up to ten digits (AIS carries it in 30 bits); anything else a
|
||||
* row names it is not one. */
|
||||
const MMSI_PATTERN = /^\d{1,10}$/;
|
||||
|
||||
/** The row's MMSI when it carries one that looks like an MMSI, else ''. */
|
||||
function vesselMmsi(row) {
|
||||
const text = String(row?.mmsi ?? '').trim();
|
||||
return MMSI_PATTERN.test(text) ? text : '';
|
||||
}
|
||||
|
||||
/** A row's stable id when its source names none: its MMSI or identifier. */
|
||||
function defaultVesselId(row) {
|
||||
return String(row?.mmsi || row?.input_identifier || '');
|
||||
}
|
||||
|
||||
/**
|
||||
* AIS positions are sea-surface observations; heading and course are distinct.
|
||||
* `id` is the vessel's key; an MMSI is not one (vessels share numbers and a
|
||||
* number can move to another hull), so `mmsi` is an attribute, '' when the
|
||||
* row has none. A row with no id of its own is keyed by its MMSI.
|
||||
*/
|
||||
export function normalizeVesselObservation(row, reference = null, id = null) {
|
||||
const key = String(id ?? defaultVesselId(row)).trim();
|
||||
const latitude = finite(row?.lat),
|
||||
longitude = finite(row?.lon);
|
||||
if (!id || !coordinates(latitude, longitude)) return null;
|
||||
if (!key || !coordinates(latitude, longitude)) return null;
|
||||
const mmsi = vesselMmsi(row);
|
||||
const speedKts = finite(row.speed);
|
||||
return {
|
||||
id,
|
||||
reference: reference ?? id,
|
||||
id: key,
|
||||
mmsi,
|
||||
reference: reference ?? key,
|
||||
latitude,
|
||||
longitude,
|
||||
name: String(row.name || row.input_name || id),
|
||||
// A source's own id is not a name: a vessel with none is unnamed.
|
||||
name: String(row.name || row.input_name || mmsi || defaultVesselId(row)),
|
||||
imo: String(row.imo || ''),
|
||||
type: String(row.type_specific || row.type || ''),
|
||||
destination: String(row.destination || ''),
|
||||
@@ -26,12 +49,21 @@ export function normalizeVesselObservation(row, reference = null) {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* A vessel snapshot from a `{ rows }` payload. `idFor(row)` gives a row's
|
||||
* stable id (its MMSI or identifier by default); rows are deduped by that id,
|
||||
* so two vessels sharing an MMSI stay two vessels. A source whose rows carry
|
||||
* an id of their own passes it, such as `idFor: (row) => row.uuid || row.mmsi`.
|
||||
* `referenceFor(row)` gives the reference its track is asked for by; the id
|
||||
* by default.
|
||||
*/
|
||||
export function vesselSnapshot(
|
||||
payload,
|
||||
{
|
||||
source = 'AISStream',
|
||||
coverage = 'received AIS positions',
|
||||
referenceFor = (row) => String(row.mmsi || row.input_identifier || ''),
|
||||
idFor = defaultVesselId,
|
||||
referenceFor = null,
|
||||
} = {},
|
||||
) {
|
||||
if (!Array.isArray(payload?.rows))
|
||||
@@ -40,8 +72,13 @@ export function vesselSnapshot(
|
||||
const records = [],
|
||||
ids = new Set();
|
||||
for (const row of rows) {
|
||||
const record = normalizeVesselObservation(row);
|
||||
if (record) record.reference = referenceFor(row);
|
||||
const record = normalizeVesselObservation(
|
||||
row,
|
||||
null,
|
||||
row && typeof row === 'object' ? idFor(row) : null,
|
||||
);
|
||||
// A row's track is asked for by its id unless the source says otherwise.
|
||||
if (record && referenceFor) record.reference = referenceFor(row);
|
||||
if (record && !ids.has(record.id)) {
|
||||
records.push(record);
|
||||
ids.add(record.id);
|
||||
|
||||
Reference in new issue
Block a user