mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +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
@@ -59,6 +59,12 @@ export const SHARE_VIEW_FOLLOW_OFFSET_DEFAULT = Object.freeze({
|
||||
pitch: -35,
|
||||
});
|
||||
|
||||
/**
|
||||
* The follow range a thing view can carry, in whole metres: 1 to this (the
|
||||
* codec clamps to the same bound).
|
||||
*/
|
||||
export const SHARE_VIEW_FOLLOW_RANGE_MAX_M = 1e8;
|
||||
|
||||
const EARTH_RADIUS_M = 6_371_000;
|
||||
const RAD = Math.PI / 180;
|
||||
|
||||
@@ -114,6 +120,27 @@ function enuBasis(lat, lon) {
|
||||
|
||||
const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
|
||||
|
||||
/**
|
||||
* The follow offset that puts the camera at `camera` (lat, lon, alt) while
|
||||
* following an entity at `fix`: the inverse of {@link followCameraFor}, on
|
||||
* the same sphere, in whole metres and degrees. Null when the camera is not
|
||||
* above the entity's local horizontal (a view from below it, or through the
|
||||
* earth, has no follow offset), or is at the entity.
|
||||
*/
|
||||
export function followOffsetFor(fix, camera) {
|
||||
const at = toEcef(fix.lat, fix.lon, fix.alt);
|
||||
const from = toEcef(camera.lat, camera.lon, camera.alt);
|
||||
const basis = enuBasis(fix.lat, fix.lon);
|
||||
const delta = [0, 1, 2].map((i) => from[i] - at[i]);
|
||||
const local = {
|
||||
east: dot(delta, basis.east),
|
||||
north: dot(delta, basis.north),
|
||||
up: dot(delta, basis.up),
|
||||
};
|
||||
if (!(local.up > 0)) return null;
|
||||
return followOffsetFromEnu(local);
|
||||
}
|
||||
|
||||
/**
|
||||
* Where the camera sits while following an entity at `fix` from `offset`,
|
||||
* and how it looks back at the entity, on a sphere of radius 6 371 000 m. A
|
||||
|
||||
+60
-5
@@ -62,7 +62,9 @@ import {
|
||||
export {
|
||||
SHARE_VIEW_ENTITY_KINDS,
|
||||
SHARE_VIEW_FOLLOW_OFFSET_DEFAULT,
|
||||
SHARE_VIEW_FOLLOW_RANGE_MAX_M,
|
||||
followCameraFor,
|
||||
followOffsetFor,
|
||||
followOffsetFromEnu,
|
||||
followOffsetToEnu,
|
||||
} from './follow.js';
|
||||
@@ -387,8 +389,9 @@ const fieldNumber = (key) => FIELD_BY_KEY.get(key).number;
|
||||
|
||||
/**
|
||||
* Fields inside the thing message (top-level field 13). Permanent. Fields 1–4
|
||||
* are the entity ids, one per SHARE_VIEW_ENTITY_KINDS code; exactly one is
|
||||
* present. The follow offset and the last-known fix are flat fields here, not
|
||||
* are the entity ids, one per SHARE_VIEW_ENTITY_KINDS code, and field 13 is a
|
||||
* vessel id that is a UUID, as its 16 bytes; exactly one of them is present.
|
||||
* The follow offset and the last-known fix are flat fields here, not
|
||||
* sub-messages, to save their tag and length bytes.
|
||||
*/
|
||||
export const SHARE_VIEW_THING_FIELDS = Object.freeze({
|
||||
@@ -400,8 +403,17 @@ export const SHARE_VIEW_THING_FIELDS = Object.freeze({
|
||||
alt: 10, // sint metres, its last-known altitude
|
||||
ageS: 11, // sint, seconds the fix predates the created-at time (field 8)
|
||||
observedAt: 12, // epoch, when the fix was taken; only without a created-at
|
||||
vesselUuid: 13, // LEN, 16 bytes: a vessel id that is a UUID
|
||||
});
|
||||
|
||||
/**
|
||||
* A vessel id that is a UUID, as a source's stable id may be: lowercase,
|
||||
* dashed. It travels as its 16 bytes (thing field 13), not as text.
|
||||
*/
|
||||
export const SHARE_VIEW_UUID_GRAMMAR =
|
||||
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
|
||||
const UUID_BYTES = 16;
|
||||
|
||||
/** The default of a field or flag for a view in `style`. */
|
||||
function defaultOf(entry, style) {
|
||||
if (entry.default !== BY_STYLE) return entry.default;
|
||||
@@ -490,7 +502,10 @@ function normalizeEntityId(entry, value) {
|
||||
: typeof value === 'string'
|
||||
? value.trim().toLowerCase()
|
||||
: null;
|
||||
if (raw === null || !TRACKING_ID_GRAMMAR.test(raw)) return null;
|
||||
if (raw === null) return null;
|
||||
// A vessel's source may key it by a UUID, longer than the id grammar.
|
||||
if (entry.kind === 'vessel' && SHARE_VIEW_UUID_GRAMMAR.test(raw)) return raw;
|
||||
if (!TRACKING_ID_GRAMMAR.test(raw)) return null;
|
||||
if (entry.kind === 'satellite' && !/^[1-9]\d{0,14}$/.test(raw)) return null;
|
||||
return raw;
|
||||
}
|
||||
@@ -795,6 +810,31 @@ const REGISTRY_BY_TOKEN = new Map(
|
||||
const charNumber = (char) => LAYER_STATE_TOKEN_ALPHABET.indexOf(char);
|
||||
const CANONICAL_INTEGER = /^(0|-?[1-9]\d{0,14})$/;
|
||||
|
||||
/** The 16 bytes of a UUID in SHARE_VIEW_UUID_GRAMMAR. */
|
||||
function uuidBytes(id) {
|
||||
const hex = id.replaceAll('-', '');
|
||||
return Array.from({ length: UUID_BYTES }, (_, i) =>
|
||||
Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16),
|
||||
);
|
||||
}
|
||||
|
||||
/** The lowercase dashed UUID that `bytes` spell. */
|
||||
function uuidText(bytes) {
|
||||
const hex = Array.from(bytes, (byte) =>
|
||||
byte.toString(16).padStart(2, '0'),
|
||||
).join('');
|
||||
return [
|
||||
hex.slice(0, 8),
|
||||
hex.slice(8, 12),
|
||||
hex.slice(12, 16),
|
||||
hex.slice(16, 20),
|
||||
hex.slice(20),
|
||||
].join('-');
|
||||
}
|
||||
|
||||
const isVesselUuid = (entry, id) =>
|
||||
entry.kind === 'vessel' && SHARE_VIEW_UUID_GRAMMAR.test(id);
|
||||
|
||||
function writeEntityId(writer, entry, id) {
|
||||
const field = entry.code;
|
||||
if (entry.idForm === 'hex24' && /^[0-9a-f]{6}$/.test(id))
|
||||
@@ -895,7 +935,8 @@ function encodeThing(writer, view, state) {
|
||||
const f = SHARE_VIEW_THING_FIELDS;
|
||||
const d = SHARE_VIEW_FOLLOW_OFFSET_DEFAULT;
|
||||
const thing = new WireWriter();
|
||||
writeEntityId(thing, entry, view.entity.id);
|
||||
const uuid = isVesselUuid(entry, view.entity.id);
|
||||
if (!uuid) writeEntityId(thing, entry, view.entity.id);
|
||||
const { range, heading, pitch } = view.offset;
|
||||
if (range !== d.range) thing.uintField(f.range, range);
|
||||
if (heading !== d.heading) thing.sintField(f.heading, signedAngle(heading));
|
||||
@@ -914,6 +955,8 @@ function encodeThing(writer, view, state) {
|
||||
} else if (observed !== null)
|
||||
thing.sintField(f.observedAt, epochSeconds(observed));
|
||||
}
|
||||
// Fields go in ascending order, so the UUID id (field 13) comes last.
|
||||
if (uuid) thing.bytesField(f.vesselUuid, uuidBytes(view.entity.id));
|
||||
writer.bytesField(fieldNumber('thing'), thing.finish());
|
||||
}
|
||||
|
||||
@@ -1063,7 +1106,9 @@ const TOP_LEVEL_WIRE_TYPES = new Map(
|
||||
const THING_WIRE_TYPES = new Map([
|
||||
...SHARE_VIEW_ENTITY_KINDS.map((e) => [e.code, [WIRE_VARINT, WIRE_LEN]]),
|
||||
...Object.values(SHARE_VIEW_THING_FIELDS).map((n) => [n, [WIRE_VARINT]]),
|
||||
[SHARE_VIEW_THING_FIELDS.vesselUuid, [WIRE_LEN]],
|
||||
]);
|
||||
const VESSEL_ENTRY = SHARE_VIEW_ENTITY_KINDS.find((e) => e.kind === 'vessel');
|
||||
|
||||
const unz = unzigzag;
|
||||
const CLOSED_ENUMS = new Set(['detectionMode', 'detectionAllocation']);
|
||||
@@ -1258,8 +1303,18 @@ function decodeThing(reader, createdAtS, unknown) {
|
||||
? followCameraFor(lastKnown, normalizeFollowOffset(offset))
|
||||
: null;
|
||||
const present = SHARE_VIEW_ENTITY_KINDS.filter((e) => fields.has(e.code));
|
||||
if (present.length > 1)
|
||||
const uuid = fields.get(F.vesselUuid);
|
||||
if (present.length + (uuid ? 1 : 0) > 1)
|
||||
throw new ShareWireError('duplicate-field', 'thing entity id');
|
||||
if (uuid) {
|
||||
const bytes = uuid.len.rest();
|
||||
if (bytes.length !== UUID_BYTES)
|
||||
throw new ShareWireError('bad-length', 'thing vessel id');
|
||||
return {
|
||||
camera,
|
||||
view: thingView(VESSEL_ENTRY.kind, uuidText(bytes), offset, lastKnown),
|
||||
};
|
||||
}
|
||||
const entry = present[0];
|
||||
if (!entry) {
|
||||
// A newer app's entity kind uses a thing field this decoder skipped.
|
||||
|
||||
@@ -43,14 +43,17 @@ import {
|
||||
BY_STYLE,
|
||||
SHARE_VIEW_FLAGS,
|
||||
SHARE_VIEW_FOLLOW_OFFSET_DEFAULT,
|
||||
SHARE_VIEW_FOLLOW_RANGE_MAX_M,
|
||||
SHARE_VIEW_STYLE_DEFAULTS,
|
||||
SHARE_VIEW_LAYER_OPTION_ABSENT,
|
||||
SHARE_VIEW_PANELS,
|
||||
SHARE_VIEW_STYLE_PARAMS,
|
||||
SHARE_VIEW_THING_FIELDS,
|
||||
createDefaultShareViewState,
|
||||
decodeShareView,
|
||||
encodeShareView,
|
||||
followCameraFor,
|
||||
followOffsetFor,
|
||||
followOffsetFromEnu,
|
||||
followOffsetToEnu,
|
||||
layerTokenFromNumber,
|
||||
@@ -149,6 +152,7 @@ function randomState(random) {
|
||||
String(int(100000000, 999999999)),
|
||||
'002442000',
|
||||
'tmp-7',
|
||||
'0770e3ca-b896-c307-f499-4f9df2b8f86b',
|
||||
])
|
||||
: pick(random, [
|
||||
int(0, 0xffffff).toString(16).padStart(6, '0'),
|
||||
@@ -1359,3 +1363,211 @@ test('the world time is written only away from live, and may lie ahead', () => {
|
||||
encodeShareView({ sharedAtMs: NOW_MS }).length,
|
||||
);
|
||||
});
|
||||
|
||||
/* ---------------- vessel ids that are UUIDs ---------------- */
|
||||
|
||||
const VESSEL_UUID = '0770e3ca-b896-c307-f499-4f9df2b8f86b';
|
||||
const VESSEL_FIX = {
|
||||
lat: 51.9301,
|
||||
lon: 4.0512,
|
||||
alt: 47,
|
||||
observedAtMs: NOW_MS - 30_000,
|
||||
};
|
||||
const VESSEL_OFFSET = { range: 3200, heading: 20, pitch: -30 };
|
||||
const vesselView = (id, extra = {}) => ({
|
||||
view: {
|
||||
kind: 'thing',
|
||||
entity: { kind: 'vessel', id },
|
||||
offset: VESSEL_OFFSET,
|
||||
lastKnown: VESSEL_FIX,
|
||||
},
|
||||
sharedAtMs: NOW_MS,
|
||||
...extra,
|
||||
});
|
||||
|
||||
/** A thing message's bytes, wrapped as a whole payload's code. */
|
||||
function thingCode(write) {
|
||||
const thing = new WireWriter();
|
||||
write(thing);
|
||||
const writer = new WireWriter();
|
||||
writer.bytes.push(1);
|
||||
writer.bytesField(13, thing.finish());
|
||||
return hashOf(writer.finish());
|
||||
}
|
||||
|
||||
test('a vessel id that is a UUID travels as its 16 bytes and round-trips', () => {
|
||||
assert.equal(SHARE_VIEW_THING_FIELDS.vesselUuid, 13);
|
||||
const code = assertRoundTrip(vesselView(VESSEL_UUID));
|
||||
const { state } = decodeOk(code);
|
||||
assert.deepEqual(state.view.entity, { kind: 'vessel', id: VESSEL_UUID });
|
||||
// Upper case is the same id: the decoder gives it back lowercase.
|
||||
assert.equal(
|
||||
decodeOk(encodeShareView(vesselView(VESSEL_UUID.toUpperCase()))).state.view
|
||||
.entity.id,
|
||||
VESSEL_UUID,
|
||||
);
|
||||
// 16 bytes and a two-byte tag and length, not 36 characters of text.
|
||||
const aircraft = encodeShareView({
|
||||
...vesselView('a1b2c3'),
|
||||
view: {
|
||||
...vesselView('a1b2c3').view,
|
||||
entity: { kind: 'aircraft', id: 'a1b2c3' },
|
||||
},
|
||||
});
|
||||
assert.equal(aircraft.length, 44);
|
||||
assert.equal(code.length, 62);
|
||||
assert.equal(
|
||||
payloadBytes(code).length - payloadBytes(aircraft).length,
|
||||
18 - 5,
|
||||
'the id costs 18 bytes where an ICAO address costs 5',
|
||||
);
|
||||
// The id field comes last, after the fix, in ascending order.
|
||||
const bytes = payloadBytes(code);
|
||||
assert.deepEqual(
|
||||
[...bytes.slice(-18)],
|
||||
[
|
||||
0x6a,
|
||||
16,
|
||||
...VESSEL_UUID.replaceAll('-', '')
|
||||
.match(/../g)
|
||||
.map((h) => parseInt(h, 16)),
|
||||
],
|
||||
);
|
||||
// A UUID form is only a vessel's: other kinds keep the id grammar.
|
||||
for (const kind of ['aircraft', 'military_aircraft', 'satellite'])
|
||||
assert.deepEqual(
|
||||
normalizeShareViewState({
|
||||
view: { kind: 'thing', entity: { kind, id: VESSEL_UUID } },
|
||||
}).view,
|
||||
{ kind: 'place' },
|
||||
);
|
||||
// Near-UUIDs are not UUIDs, and are longer than the id grammar allows.
|
||||
for (const id of [VESSEL_UUID.replaceAll('-', '') + '0', `${VESSEL_UUID}0`])
|
||||
assert.deepEqual(
|
||||
normalizeShareViewState({
|
||||
view: { kind: 'thing', entity: { kind: 'vessel', id } },
|
||||
}).view,
|
||||
{ kind: 'place' },
|
||||
);
|
||||
});
|
||||
|
||||
test('MMSI and short text vessel ids, and links made before UUIDs, are unchanged', () => {
|
||||
// Codes written before vessel ids could be UUIDs.
|
||||
const before = {
|
||||
'AUCAn8wYahkYoPH_rgEogBkwKDg7QIqyP0iA-QRQXlg8Ag': '366999712',
|
||||
AUCAn8wYah4aCTAwMjQ0MjAwMCiAGTAoODtAirI_SID5BFBeWDyl: '002442000',
|
||||
};
|
||||
for (const [code, id] of Object.entries(before)) {
|
||||
assert.equal(encodeShareView(vesselView(id)), code);
|
||||
const { state } = decodeOk(code);
|
||||
assert.deepEqual(state.view, {
|
||||
kind: 'thing',
|
||||
entity: { kind: 'vessel', id },
|
||||
offset: VESSEL_OFFSET,
|
||||
lastKnown: VESSEL_FIX,
|
||||
});
|
||||
}
|
||||
// A camera-only vessel view with a short text id, as before.
|
||||
const tmp = 'ARCgnAEYwLgCagcaBXRtcC03GQ';
|
||||
assert.equal(
|
||||
encodeShareView({
|
||||
lat: 1,
|
||||
lon: 2,
|
||||
view: { kind: 'thing', entity: { kind: 'vessel', id: 'tmp-7' } },
|
||||
}),
|
||||
tmp,
|
||||
);
|
||||
assert.equal(decodeOk(tmp).state.view.entity.id, 'tmp-7');
|
||||
});
|
||||
|
||||
test('a UUID vessel id with another id, or of the wrong length, is malformed', () => {
|
||||
const uuid = VESSEL_UUID.replaceAll('-', '')
|
||||
.match(/../g)
|
||||
.map((h) => parseInt(h, 16));
|
||||
const reason = (code) => decodeShareView(code, { nowMs: NOW_MS }).reason;
|
||||
// Two entity ids: the UUID and an MMSI, or an aircraft's address.
|
||||
assert.equal(
|
||||
reason(thingCode((t) => t.uintField(3, 366999712).bytesField(13, uuid))),
|
||||
'duplicate-field',
|
||||
);
|
||||
assert.equal(
|
||||
reason(thingCode((t) => t.uintField(1, 0xa1b2c3).bytesField(13, uuid))),
|
||||
'duplicate-field',
|
||||
);
|
||||
assert.equal(
|
||||
reason(thingCode((t) => t.bytesField(13, uuid).bytesField(13, uuid))),
|
||||
'duplicate-field',
|
||||
);
|
||||
for (const bytes of [uuid.slice(0, 15), [...uuid, 0], []])
|
||||
assert.equal(
|
||||
reason(thingCode((t) => t.bytesField(13, bytes))),
|
||||
'bad-length',
|
||||
);
|
||||
// The field is LEN only.
|
||||
assert.equal(
|
||||
reason(thingCode((t) => t.uintField(13, 5))),
|
||||
'wire-type-mismatch',
|
||||
);
|
||||
// The 16 bytes alone are a vessel; any bytes spell a UUID.
|
||||
assert.deepEqual(
|
||||
decodeOk(thingCode((t) => t.bytesField(13, new Array(16).fill(0xff)))).state
|
||||
.view.entity,
|
||||
{ kind: 'vessel', id: 'ffffffff-ffff-ffff-ffff-ffffffffffff' },
|
||||
);
|
||||
});
|
||||
|
||||
test('a decoder that predates UUID vessel ids opens the view at its derived camera', () => {
|
||||
// Such a decoder skips thing field 13 as it skips any unknown field: the
|
||||
// same payload with the id under a field this decoder does not know.
|
||||
const bytes = [...payloadBytes(encodeShareView(vesselView(VESSEL_UUID)))];
|
||||
const at = bytes.length - 18;
|
||||
assert.equal(bytes[at], 0x6a);
|
||||
bytes[at] = 0xf2; // field 30, LEN
|
||||
bytes.splice(at + 1, 0, 0x01);
|
||||
// The thing message grew by a byte: its own length too.
|
||||
const thingLength = bytes.indexOf(0x6a) + 1;
|
||||
bytes[thingLength] += 1;
|
||||
const result = decodeOk(hashOf(bytes));
|
||||
assert.equal(result.fallback, 'unknown-entity-kind');
|
||||
assert.deepEqual(result.state.view, { kind: 'place' });
|
||||
const camera = followCameraFor(VESSEL_FIX, VESSEL_OFFSET);
|
||||
assert.equal(result.state.lat, Math.round(camera.lat * 1e4) / 1e4);
|
||||
assert.equal(result.state.lon, Math.round(camera.lon * 1e4) / 1e4);
|
||||
});
|
||||
|
||||
test('the follow offset for a camera is the inverse of followCameraFor', () => {
|
||||
const fix = { lat: 51.9301, lon: 4.0512, alt: 47 };
|
||||
for (const offset of [
|
||||
{ range: 3200, heading: 20, pitch: -30 },
|
||||
{ range: 250, heading: 300, pitch: -5 },
|
||||
{ range: 80_000, heading: 135, pitch: -70 },
|
||||
{ range: 2_000_000, heading: 0, pitch: -89 },
|
||||
])
|
||||
assert.deepEqual(
|
||||
followOffsetFor(fix, followCameraFor(fix, offset)),
|
||||
offset,
|
||||
);
|
||||
// The codec carries ranges up to the bound a subject is checked against.
|
||||
const far = {
|
||||
range: SHARE_VIEW_FOLLOW_RANGE_MAX_M + 5,
|
||||
heading: 0,
|
||||
pitch: -35,
|
||||
};
|
||||
assert.equal(
|
||||
normalizeShareViewState({
|
||||
view: { kind: 'thing', entity: { kind: 'vessel', id: '1' }, offset: far },
|
||||
}).view.offset.range,
|
||||
SHARE_VIEW_FOLLOW_RANGE_MAX_M,
|
||||
);
|
||||
// A camera below the entity's horizontal, or at it, has no offset.
|
||||
assert.equal(
|
||||
followOffsetFor(fix, { lat: 51.95, lon: 4.0512, alt: 40 }),
|
||||
null,
|
||||
);
|
||||
assert.equal(followOffsetFor(fix, fix), null);
|
||||
// Far round the curve of the earth at low height: below its horizon.
|
||||
assert.equal(
|
||||
followOffsetFor(fix, { lat: 53.9, lon: 4.0512, alt: 1000 }),
|
||||
null,
|
||||
);
|
||||
});
|
||||
Reference in new issue
Block a user