A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.
JavaScript 3d-globecesiumflight-trackinggeospatialgeospatial-intelligencegisosintphotogrammetrysatellite-trackingspatial-intelligencewebglworldview
/**
* Byte-level primitives for the compact share-view format: base64url text,
* protobuf-style varints, and a tag-length-value reader and writer.
*
* Pure: no DOM, no Cesium, no platform buffers. Every integrity failure is a
* {@link ShareWireError} with a stable `reason`, so the view codec can turn it
* into a rejected link instead of an exception at app start.
*/
/** Wire types. Field numbers and their wire types are permanent. */
export const WIRE_VARINT = 0;
export const WIRE_FIXED64 = 1;
export const WIRE_LEN = 2;
export const WIRE_FIXED32 = 5;
/** Field numbers stay inside protobuf's range so tags fit in five bytes. */
export const MAX_FIELD_NUMBER = 2 ** 29 - 1;
const MAX_VARINT_BYTES = 8; // 56 bits covers every safe integer.
/** A malformed or out-of-bounds payload. `reason` is a stable code. */
export class ShareWireError extends Error {
constructor(reason, detail = '') {
super(detail ? `${reason}: ${detail}` : reason);
this.name = 'ShareWireError';
this.reason = reason;
}
}
const BASE64URL =
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
const BASE64URL_INDEX = new Map(
[...BASE64URL].map((char, index) => [char, index]),
);
/** Unpadded base64url text for `bytes`. */
export function encodeBase64Url(bytes) {
let out = '';
for (let i = 0; i < bytes.length; i += 3) {
const a = bytes[i];
const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
const triple = (a << 16) | (b << 8) | c;
out += BASE64URL[(triple >> 18) & 63] + BASE64URL[(triple >> 12) & 63];
if (i + 1 < bytes.length) out += BASE64URL[(triple >> 6) & 63];
if (i + 2 < bytes.length) out += BASE64URL[triple & 63];
}
return out;
}
/**
* Bytes for unpadded base64url text. Rejects padding, foreign characters, an
* impossible length and non-zero trailing bits, so every payload has exactly
* one spelling.
*/
export function decodeBase64Url(text) {
if (typeof text !== 'string' || text.length === 0)
throw new ShareWireError('empty');
if (text.length % 4 === 1) throw new ShareWireError('bad-base64');
const bytes = new Uint8Array(Math.floor((text.length * 3) / 4));
let buffer = 0;
let bits = 0;
let out = 0;
for (const char of text) {
const value = BASE64URL_INDEX.get(char);
if (value === undefined) throw new ShareWireError('bad-base64');
buffer = ((buffer << 6) | value) & 0xffffff;
bits += 6;
if (bits >= 8) {
bits -= 8;
bytes[out++] = (buffer >> bits) & 0xff;
}
}
if (bits > 0 && (buffer & ((1 << bits) - 1)) !== 0)
throw new ShareWireError('bad-base64', 'non-zero trailing bits');
return bytes;
}
/**
* CRC-8 (polynomial x⁸ + x² + x + 1, 0x07; initial value 0; no reflection;
* no final XOR) of `bytes`. A degree-8 CRC detects every error burst of up to
* 8 bits, so any one mistyped base64url character (6 bits) is caught.
*/
export function crc8(bytes) {
let crc = 0;
for (const byte of bytes) {
crc ^= byte;
for (let bit = 0; bit < 8; bit += 1)
crc = crc & 0x80 ? ((crc << 1) ^ 0x07) & 0xff : (crc << 1) & 0xff;
}
return crc;
}
/** Map a signed integer onto the unsigned varint space (0,-1,1,-2 → 0,1,2,3). */
export function zigzag(value) {
return value >= 0 ? value * 2 : -value * 2 - 1;
}
/** Inverse of {@link zigzag}. */
export function unzigzag(value) {
return value % 2 === 0 ? value / 2 : -(value + 1) / 2;
}
/** Largest magnitude a zigzag field can carry without losing precision. */
export const MAX_ZIGZAG_MAGNITUDE = Math.floor(Number.MAX_SAFE_INTEGER / 2);
/** Append-only byte sink with protobuf-style field helpers. */
export class WireWriter {
constructor() {
this.bytes = [];
}
varint(value) {
if (!Number.isSafeInteger(value) || value < 0)
throw new RangeError(`varint out of range: ${value}`);
let rest = value;
while (rest >= 0x80) {
this.bytes.push((rest % 0x80) | 0x80);
rest = Math.floor(rest / 0x80);
}
this.bytes.push(rest);
return this;
}
tag(field, wireType) {
if (!Number.isInteger(field) || field < 1 || field > MAX_FIELD_NUMBER)
throw new RangeError(`field number out of range: ${field}`);
return this.varint(field * 8 + wireType);
}
uintField(field, value) {
return this.tag(field, WIRE_VARINT).varint(value);
}
sintField(field, value) {
if (!Number.isSafeInteger(value) || Math.abs(value) > MAX_ZIGZAG_MAGNITUDE)
throw new RangeError(`signed value out of range: ${value}`);
return this.tag(field, WIRE_VARINT).varint(zigzag(value));
}
bytesField(field, bytes) {
this.tag(field, WIRE_LEN).varint(bytes.length);
for (const byte of bytes) this.bytes.push(byte);
return this;
}
/** ASCII-only text; every share-view string is drawn from ASCII grammars. */
textField(field, text) {
return this.bytesField(field, asciiBytes(text));
}
finish() {
return Uint8Array.from(this.bytes);
}
}
/** Printable-ASCII bytes for `text`; anything else is a programming error. */
export function asciiBytes(text) {
const bytes = [];
for (let i = 0; i < text.length; i += 1) {
const code = text.charCodeAt(i);
if (code < 0x20 || code > 0x7e)
throw new RangeError('share-view text must be printable ASCII');
bytes.push(code);
}
return bytes;
}
/** Printable-ASCII text from bytes; anything else is a malformed payload. */
export function asciiText(bytes) {
let out = '';
for (const byte of bytes) {
if (byte < 0x20 || byte > 0x7e) throw new ShareWireError('bad-text');
out += String.fromCharCode(byte);
}
return out;
}
/** Bounds-checked cursor over one message (or one packed blob). */
export class WireReader {
constructor(bytes, start = 0, end = bytes.length) {
this.bytes = bytes;
this.pos = start;
this.end = end;
}
get done() {
return this.pos >= this.end;
}
/** One canonical varint no larger than Number.MAX_SAFE_INTEGER. */
varint() {
let value = 0;
let scale = 1;
for (let count = 0; count < MAX_VARINT_BYTES; count += 1) {
if (this.pos >= this.end) throw new ShareWireError('truncated');
const byte = this.bytes[this.pos++];
value += (byte & 0x7f) * scale;
if ((byte & 0x80) === 0) {
// A zero final byte after a continuation is an overlong spelling.
if (count > 0 && byte === 0)
throw new ShareWireError('non-canonical-varint');
if (!Number.isSafeInteger(value))
throw new ShareWireError('varint-overflow');
return value;
}
scale *= 0x80;
}
throw new ShareWireError('varint-overflow');
}
svarint() {
return unzigzag(this.varint());
}
/** The next field's number and wire type, rejecting reserved wire types. */
tag() {
const key = this.varint();
const field = Math.floor(key / 8);
const wireType = key % 8;
if (field < 1 || field > MAX_FIELD_NUMBER)
throw new ShareWireError('bad-field-number');
if (
wireType !== WIRE_VARINT &&
wireType !== WIRE_FIXED64 &&
wireType !== WIRE_LEN &&
wireType !== WIRE_FIXED32
)
throw new ShareWireError('bad-wire-type', String(wireType));
return { field, wireType };
}
/** A length-delimited body as a sub-reader over the same bytes. */
lengthDelimited() {
const length = this.varint();
if (length > this.end - this.pos)
throw new ShareWireError('truncated', 'length exceeds payload');
const reader = new WireReader(this.bytes, this.pos, this.pos + length);
this.pos += length;
return reader;
}
/** Remaining bytes of this reader as a fresh array. */
rest() {
const out = this.bytes.slice(this.pos, this.end);
this.pos = this.end;
return out;
}
/** Skip one value of `wireType`, so newer fields cost older decoders nothing. */
skip(wireType) {
if (wireType === WIRE_VARINT) this.varint();
else if (wireType === WIRE_LEN) this.lengthDelimited();
else {
const size = wireType === WIRE_FIXED64 ? 8 : 4;
if (size > this.end - this.pos) throw new ShareWireError('truncated');
this.pos += size;
}
}
}