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
/** Session-local geodata loading with bounded geometry and local-only file references. */
import * as Cesium from 'cesium';
import { createImportImageBudget } from './geoImportImages.js';
import { createImportedPins } from './geoImportPins.js';
import { msg } from '../i18n/marker.js';
/** Largest file accepted, in bytes. */
const MAX_IMPORT_BYTES = 50 * 1024 * 1024;
/** Largest total a KMZ may inflate to — a zip bomb stops here. */
const MAX_KMZ_INFLATED_BYTES = 120 * 1024 * 1024;
/** Most files on the globe at once. */
export const MAX_IMPORTED_FILES = 12;
/** Most entities one file may create before it is refused. */
export const MAX_IMPORT_ENTITIES = 20_000;
/** Most vertices (points of every line, ring and marker) in one file. */
export const MAX_IMPORT_POSITIONS = 250_000;
/** Most normalized style definitions and local image links in one KML/KMZ. */
const MAX_KML_LINKS = 2_000;
/** Longest plain-text name kept from a file's features. */
const MAX_IMPORT_NAME_LENGTH = 120;
/** What the file picker offers. */
export const GEO_FILE_ACCEPT = '.geojson,.json,.kml,.kmz,.gpx';
const GEOJSON_TYPES = new Set([
'FeatureCollection',
'Feature',
'Point',
'MultiPoint',
'LineString',
'MultiLineString',
'Polygon',
'MultiPolygon',
'GeometryCollection',
]);
const KMZ_IMAGE_TYPES = Object.freeze({
png: 'image/png',
jpg: 'image/jpeg',
jpeg: 'image/jpeg',
gif: 'image/gif',
webp: 'image/webp',
bmp: 'image/bmp',
});
// External content and metadata the session-local import does not use.
const KML_REMOVED_ELEMENTS = new Set([
'NetworkLink',
'NetworkLinkControl',
'ScreenOverlay',
'PhotoOverlay',
'Model',
'Tour',
'description',
'BalloonStyle',
'Snippet',
'ExtendedData',
'TimeSpan',
'TimeStamp',
'LookAt',
'Camera',
'visibility',
'viewRefreshMode',
'viewFormat',
'httpQuery',
]);
/**
* An error whose message is meant for the person who chose the file. The
* message stays English; `template` and `values`, when given, let the UI show
* it in the active language.
*/
export class GeoImportError extends Error {
constructor(message, template = message, values = {}) {
super(message);
this.name = 'GeoImportError';
this.template = template;
this.values = values;
}
}
/**
* The format of a file, from its name first and its first bytes second.
* @param {string} name File name.
* @param {Uint8Array} [head] The first bytes of the file.
* @returns {'geojson'|'kml'|'kmz'|'gpx'|null}
*/
export function detectGeoFileFormat(name, head) {
const ext = /\.([a-z0-9]+)$/i.exec(String(name || ''))?.[1]?.toLowerCase();
if (ext === 'geojson') return 'geojson';
if (ext === 'kml' || ext === 'kmz' || ext === 'gpx') return ext;
if (!head?.length) return ext === 'json' ? 'geojson' : null;
if (
head[0] === 0x50 &&
head[1] === 0x4b &&
head[2] === 0x03 &&
head[3] === 0x04
)
return 'kmz';
const text = new TextDecoder()
.decode(head.subarray(0, 1024))
.replace(/^/, '')
.trimStart();
if (text.startsWith('{')) return 'geojson';
if (text.startsWith('<')) {
if (/<kml[\s>]/i.test(text)) return 'kml';
if (/<gpx[\s>]/i.test(text)) return 'gpx';
}
return ext === 'json' ? 'geojson' : null;
}
/**
* A short, printable name for the list: the file name without control
* characters, cut to 60 characters.
* @param {string} name
* @returns {string}
*/
export function importDisplayName(name) {
const clean = String(name || '')
.replace(/[\u0000-\u001f\u007f]/g, '')
.trim();
if (!clean) return 'Imported file';
return clean.length > 60 ? `${clean.slice(0, 57)}…` : clean;
}
/**
* Parse and check GeoJSON text. Throws `GeoImportError` for anything that is
* not a GeoJSON object.
* @param {string} text
* @returns {object}
*/
export function parseGeoJsonText(text) {
let value;
try {
value = JSON.parse(String(text).replace(/^/, ''));
} catch {
throw new GeoImportError(msg('That file is not valid JSON.'));
}
if (!value || typeof value !== 'object' || !GEOJSON_TYPES.has(value.type))
throw new GeoImportError(msg('That JSON file is not GeoJSON.'));
if (value.type === 'FeatureCollection' && !Array.isArray(value.features))
throw new GeoImportError(
msg('That FeatureCollection has no features list.'),
);
return value;
}
/**
* Count features and vertices in a parsed GeoJSON object without recursion
* limits or array spreading, stopping as soon as a limit is passed.
* @param {object} geojson
* @param {{maxFeatures?: number, maxPositions?: number, maxEntities?: number}} [limits]
* @returns {{features: number, positions: number, entities: number,
* over: ''|'features'|'positions'|'entities'}}
*/
export function countGeoJsonGeometry(
geojson,
{
maxFeatures = MAX_IMPORT_ENTITIES,
maxPositions = MAX_IMPORT_POSITIONS,
maxEntities = MAX_IMPORT_ENTITIES,
} = {},
) {
let features = ['Feature', 'FeatureCollection'].includes(geojson?.type)
? 0
: 1;
let positions = 0;
let entities = 0;
const result = (over = '') => ({ features, positions, entities, over });
const stack = [geojson];
while (stack.length) {
const node = stack.pop();
if (!node || typeof node !== 'object') continue;
if (node.type === 'FeatureCollection') {
const list = Array.isArray(node.features) ? node.features : [];
for (let i = 0; i < list.length; i++) {
if (list[i]?.type !== 'Feature')
throw new GeoImportError(
msg('Every GeoJSON feature must have type Feature.'),
);
stack.push(list[i]);
}
continue;
}
if (node.type === 'Feature') {
features += 1;
if (features > maxFeatures) return result('features');
if (node.geometry == null) {
entities += 1;
if (entities > maxEntities) return result('entities');
}
stack.push(node.geometry);
continue;
}
if (node.type === 'GeometryCollection') {
const list = node.geometries;
if (!Array.isArray(list))
throw new GeoImportError(msg('That GeoJSON has invalid geometries.'));
for (let i = 0; i < list.length; i++) {
if (!list[i] || ['Feature', 'FeatureCollection'].includes(list[i].type))
throw new GeoImportError(
msg('That GeoJSON contains an unsupported geometry.'),
);
stack.push(list[i]);
}
continue;
}
const depth = {
Point: 0,
MultiPoint: 1,
LineString: 1,
MultiLineString: 2,
Polygon: 2,
MultiPolygon: 3,
}[node.type];
if (depth !== undefined) {
// Multipart geometries create one Cesium entity per component, even
// when the document wraps them in just one Feature.
entities += node.type.startsWith('Multi')
? Array.isArray(node.coordinates)
? node.coordinates.length
: 0
: 1;
if (entities > maxEntities) return result('entities');
// Walk the coordinate arrays iteratively: a position is an array whose
// first item is a number.
const coords = [[node.coordinates, depth]];
while (coords.length) {
const [c, remaining] = coords.pop();
if (!Array.isArray(c))
throw new GeoImportError(
msg('That GeoJSON has invalid coordinates.'),
);
if (remaining === 0) {
if (
c.length < 2 ||
c.length > 3 ||
!c.every(Number.isFinite) ||
Math.abs(c[0]) > 180 ||
Math.abs(c[1]) > 90 ||
(c.length === 3 && Math.abs(c[2]) > 1_000_000)
)
throw new GeoImportError(
msg('That GeoJSON has invalid coordinates.'),
);
positions += 1;
if (positions > maxPositions) return result('positions');
} else
for (let i = 0; i < c.length; i++) coords.push([c[i], remaining - 1]);
}
} else
throw new GeoImportError(
msg('That GeoJSON contains an unsupported geometry.'),
);
}
return result();
}
/** The refusal for a file over a size limit, in the person's terms. */
function overLimitError({ over, features }) {
if (over === 'entities')
return new GeoImportError(
`That file creates more than ${MAX_IMPORT_ENTITIES.toLocaleString()} map objects (the limit).`,
msg('That file creates more than {limit} map objects (the limit).'),
{ limit: MAX_IMPORT_ENTITIES.toLocaleString() },
);
if (over === 'links')
return new GeoImportError(
`That file has more than ${MAX_KML_LINKS.toLocaleString()} style definitions and image links after cleanup (the limit).`,
msg(
'That file has more than {limit} style definitions and image links after cleanup (the limit).',
),
{ limit: MAX_KML_LINKS.toLocaleString() },
);
if (over === 'features')
return new GeoImportError(
`That file has more than ${MAX_IMPORT_ENTITIES.toLocaleString()} features (the limit).`,
msg('That file has more than {limit} features (the limit).'),
{ limit: MAX_IMPORT_ENTITIES.toLocaleString() },
);
const limit = MAX_IMPORT_POSITIONS.toLocaleString();
if (features)
return new GeoImportError(
`That file has more than ${limit} points (the limit) across ${features.toLocaleString()} features.`,
msg(
'That file has more than {limit} points (the limit) across {features} features.',
),
{ limit, features: features.toLocaleString() },
);
return new GeoImportError(
`That file has more than ${limit} points (the limit).`,
msg('That file has more than {limit} points (the limit).'),
{ limit },
);
}
// The import uses WGS84 ground footprints and a short name only. Remove
// loader-sensitive metadata before Cesium allocates properties or entity IDs.
function prepareGeoJson(geojson) {
const stack = [geojson];
while (stack.length) {
const node = stack.pop();
if (!node) continue;
delete node.crs;
delete node.id;
if (node.type === 'FeatureCollection') {
for (const feature of node.features) stack.push(feature);
} else if (node.type === 'Feature') {
const name = importFeatureName(node.properties?.name);
node.properties = name ? { name } : {};
stack.push(node.geometry);
} else if (node.type === 'GeometryCollection') {
for (const geometry of node.geometries) stack.push(geometry);
} else {
const coords = [node.coordinates];
while (coords.length) {
const value = coords.pop();
if (typeof value[0] === 'number') value.length = 2;
else for (const child of value) coords.push(child);
}
}
}
}
/** Inflate raw-deflate bytes with the platform's stream, stopping at `maxBytes`. */
async function inflateRaw(bytes, maxBytes) {
const stream = new Blob([bytes])
.stream()
.pipeThrough(new DecompressionStream('deflate-raw'));
const reader = stream.getReader();
const chunks = [];
let total = 0;
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
total += value.length;
if (total > maxBytes)
throw new GeoImportError(
msg('That KMZ unpacks to more than the import limit.'),
);
chunks.push(value);
}
} catch (error) {
await reader.cancel().catch(() => {});
if (error instanceof GeoImportError) throw error;
throw new GeoImportError(
msg('That KMZ is damaged and could not be unpacked.'),
);
}
const out = new Uint8Array(total);
let at = 0;
for (const chunk of chunks) {
out.set(chunk, at);
at += chunk.length;
}
return out;
}
/**
* Read the entries of a zip archive (stored or deflated; no encryption, no
* ZIP64). Directory entries are skipped.
* @param {Uint8Array} bytes The whole archive.
* @param {{maxInflatedBytes?: number}} [options]
* @returns {Promise<Map<string, Uint8Array>>} Entry path → contents.
*/
export async function readZipEntries(
bytes,
{ maxInflatedBytes = MAX_KMZ_INFLATED_BYTES } = {},
) {
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
const fail = (message = msg('That KMZ is not a readable zip archive.')) => {
throw new GeoImportError(message);
};
// End of central directory: 22 bytes plus a comment of up to 64 KiB.
let eocd = -1;
for (
let i = bytes.length - 22;
i >= Math.max(0, bytes.length - 22 - 0xffff);
i--
) {
if (view.getUint32(i, true) === 0x06054b50) {
eocd = i;
break;
}
}
if (eocd < 0) fail();
const count = view.getUint16(eocd + 10, true);
const dirSize = view.getUint32(eocd + 12, true);
let at = view.getUint32(eocd + 16, true);
if (count === 0xffff || at === 0xffffffff || at + dirSize > eocd)
fail(msg('That KMZ uses a zip format this import does not read.'));
const entries = new Map();
const names = new TextDecoder();
let inflated = 0;
for (let n = 0; n < count; n++) {
if (at + 46 > bytes.length || view.getUint32(at, true) !== 0x02014b50)
fail();
const flags = view.getUint16(at + 8, true);
const method = view.getUint16(at + 10, true);
const compressed = view.getUint32(at + 20, true);
const size = view.getUint32(at + 24, true);
const nameLength = view.getUint16(at + 28, true);
const extraLength = view.getUint16(at + 30, true);
const commentLength = view.getUint16(at + 32, true);
const local = view.getUint32(at + 42, true);
const name = names.decode(bytes.subarray(at + 46, at + 46 + nameLength));
at += 46 + nameLength + extraLength + commentLength;
if (name.endsWith('/')) continue;
if (flags & 0x1) fail(msg('That KMZ is encrypted.'));
if (compressed === 0xffffffff || size === 0xffffffff)
fail(msg('That KMZ uses a zip format this import does not read.'));
if (local + 30 > bytes.length || view.getUint32(local, true) !== 0x04034b50)
fail();
const start =
local +
30 +
view.getUint16(local + 26, true) +
view.getUint16(local + 28, true);
if (start + compressed > bytes.length) fail();
const data = bytes.subarray(start, start + compressed);
let contents;
if (method === 0) contents = data;
else if (method === 8)
contents = await inflateRaw(data, maxInflatedBytes - inflated);
else
fail(
msg('That KMZ uses a compression method this import does not read.'),
);
inflated += contents.length;
if (inflated > maxInflatedBytes)
fail(msg('That KMZ unpacks to more than the import limit.'));
entries.set(name, contents);
}
return entries;
}
/**
* The KML document inside a KMZ: `doc.kml` when present, else the first
* `.kml` entry nearest the archive root.
* @param {Map<string, Uint8Array>} entries
* @returns {string|null} Entry path.
*/
export function kmzMainDocument(entries) {
if (entries.has('doc.kml')) return 'doc.kml';
const kml = [...entries.keys()]
.filter((name) => /\.kml$/i.test(name))
.sort(
(a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b),
);
return kml[0] ?? null;
}
/**
* Resolve a KMZ-relative href to an entry path, or null.
* @param {string} href As written in the KML.
* @param {string} base The KML entry's path.
* @param {Map<string, Uint8Array>} entries
* @returns {string|null}
*/
export function resolveKmzPath(href, base, entries) {
const raw = String(href || '').trim();
if (!raw || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('//'))
return null;
let decoded;
try {
decoded = decodeURIComponent(raw.split(/[?#]/)[0]);
} catch {
return null;
}
const parts = base.split('/').slice(0, -1);
for (const part of decoded.replace(/\\/g, '/').split('/')) {
if (!part || part === '.') continue;
if (part === '..') parts.pop();
else parts.push(part);
}
const path = parts.join('/');
return entries.has(path) ? path : null;
}
/** MIME type for a KMZ image entry, or null when it is not an image we serve. */
export function kmzImageType(path) {
const ext = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase();
return KMZ_IMAGE_TYPES[ext] ?? null;
}
const elementsNamed = (doc, localName) =>
[...doc.getElementsByTagName('*')].filter((el) => el.localName === localName);
/**
* A `resolveLocal` for `sanitizeKmlDocument`: the blob URL of an image packed
* in the KMZ, or null. Each entry gets one blob and one URL however many
* hrefs name it, so repeated icons don't copy (and decode) the image again.
* @param {Map<string, Uint8Array>} entries
* @param {string} main Path of the KMZ's KML document.
* @param {(url: string) => void} onUrl Called once per new URL (to revoke later).
* @param {(blob: Blob) => string} [createUrl]
* @returns {(href: string) => string|null}
*/
export function kmzImageResolver(
entries,
main,
onUrl,
createUrl = (blob) => URL.createObjectURL(blob),
) {
const urls = new Map();
return (href) => {
const path = resolveKmzPath(href, main, entries);
const type = path && kmzImageType(path);
if (!type) return null;
let url = urls.get(path);
if (!url) {
url = createUrl(new Blob([entries.get(path)], { type }));
urls.set(path, url);
onUrl(url);
}
return url;
};
}
/**
* Strip everything from a parsed KML document that would make the page reach
* outside the file. `resolveLocal(href)` returns a URL for an image packed in
* the same KMZ (or null); every other href is removed, so icons fall back to
* Cesium's default pin and a ground overlay without a local image is dropped.
* @param {Document} doc
* @param {(href: string) => string|null} [resolveLocal]
* @returns {{removed: number}} How many elements were taken out.
*/
export function sanitizeKmlDocument(doc, resolveLocal = () => null) {
let removed = 0;
const drop = (el) => {
if (el.parentNode) {
el.parentNode.removeChild(el);
removed += 1;
}
};
// One snapshot and pass, rather than rescanning the whole XML tree for
// every discarded element type. Strip unused metadata before the loader
// constructs descriptions, availability intervals and camera objects.
for (const el of [...doc.getElementsByTagName('*')])
if (
KML_REMOVED_ELEMENTS.has(el.localName) ||
el.localName in Object.prototype
)
drop(el);
else if (!['Style', 'StyleMap'].includes(el.localName))
el.removeAttribute('id');
for (const href of elementsNamed(doc, 'href')) {
const value = (href.textContent || '').trim();
if (!value) continue;
const local = resolveLocal(value);
if (local) href.textContent = local;
else if (/^data:image\/(png|jpeg|gif|webp|bmp);/i.test(value)) continue;
else {
const icon = href.parentNode;
const overlay = icon?.parentNode;
if (overlay?.localName === 'GroundOverlay') {
drop(overlay);
continue;
}
// An empty Icon explicitly hides the billboard in Cesium. Remove the
// blocked icon definition so the loader supplies its local default pin.
// Authored empty Icons (with no blocked href) still mean no marker.
drop(
icon?.localName === 'Icon' && icon.parentNode?.localName === 'IconStyle'
? icon
: href,
);
}
}
for (const styleUrl of elementsNamed(doc, 'styleUrl')) {
const value = (styleUrl.textContent || '').trim();
if (!value.startsWith('#')) drop(styleUrl);
else styleUrl.textContent = value;
}
for (const pair of elementsNamed(doc, 'Pair'))
if (
!childText(pair, 'key') ||
(!childrenNamed(pair, 'styleUrl').length &&
!childrenNamed(pair, 'Style').length)
)
drop(pair);
// Draw recorded KML paths as their original static vertices. Letting the
// loader build time-dynamic tracks would expand each into thousands of
// interpolated points later and exceed the checked geometry budget.
for (const track of elementsNamed(doc, 'Track')) {
const line = doc.createElementNS(
'http://www.opengis.net/kml/2.2',
'LineString',
);
const coordinates = doc.createElementNS(
'http://www.opengis.net/kml/2.2',
'coordinates',
);
const recordedCoordinates = childrenNamed(track, 'coord').map((coord) =>
coord.textContent.trim().split(/\s+/).join(','),
);
coordinates.textContent = recordedCoordinates.join(' ');
line.appendChild(coordinates);
for (const mode of childrenNamed(track, 'altitudeMode'))
line.appendChild(mode.cloneNode(true));
track.parentNode?.replaceChild(line, track);
}
for (const tracks of elementsNamed(doc, 'MultiTrack')) {
const geometry = doc.createElementNS(
'http://www.opengis.net/kml/2.2',
'MultiGeometry',
);
for (const line of childrenNamed(tracks, 'LineString'))
geometry.appendChild(line);
tracks.parentNode?.replaceChild(geometry, tracks);
}
for (const line of [
...elementsNamed(doc, 'LineString'),
...elementsNamed(doc, 'LinearRing'),
]) {
const mode = childText(line, 'altitudeMode');
if (
!mode ||
mode === 'clampToGround' ||
mode === 'clampToSeaFloor' ||
!childrenNamed(line, 'tessellate').length
) {
let tessellate = childrenNamed(line, 'tessellate')[0];
if (!tessellate) {
tessellate = doc.createElementNS(
'http://www.opengis.net/kml/2.2',
'tessellate',
);
line.appendChild(tessellate);
}
tessellate.textContent = '1';
}
}
return { removed };
}
/** Child elements of `el` with this local name (any namespace). */
const childrenNamed = (el, localName) => {
const out = [];
const kids = el?.childNodes || [];
for (let i = 0; i < kids.length; i++)
if (kids[i].nodeType === 1 && kids[i].localName === localName)
out.push(kids[i]);
return out;
};
const childText = (el, localName) =>
(childrenNamed(el, localName)[0]?.textContent || '').trim();
/**
* Share identical styles before the loader builds their graphics. Inline
* overrides stay inline StyleMaps, so an existing styleUrl still supplies
* properties the override leaves unset. Named references are redirected.
* Random-color styles remain unchanged; duplicate IDs
* keep the loader's original precedence instead of being rewritten.
* @param {Document} doc Sanitized KML.
* @param {{serializeStyle?: Function, maxStyles?: number}} [options]
* @returns {number} Number of original style blocks replaced.
*/
export function deduplicateKmlStyles(
doc,
{ serializeStyle, maxStyles = MAX_KML_LINKS } = {},
) {
const serializer = serializeStyle ? null : new XMLSerializer();
const serialize =
serializeStyle || ((el) => serializer.serializeToString(el));
const groups = new Map();
const usedIds = new Set();
const duplicateIds = new Set();
for (const el of doc.getElementsByTagName('*')) {
const id = el.getAttribute('id');
if (id !== null) {
if (usedIds.has(id)) duplicateIds.add(id);
usedIds.add(id);
}
}
for (const style of elementsNamed(doc, 'Style')) {
if (
elementsNamed(style, 'colorMode').some(
(el) => el.textContent.trim() === 'random',
)
)
continue;
const template = style.cloneNode(true);
template.removeAttribute('id');
const key = serialize(template);
let group = groups.get(key);
if (!group) {
group = { template, nodes: [] };
groups.set(key, group);
if (groups.size > maxStyles) throw overLimitError({ over: 'links' });
}
group.nodes.push(style);
}
const redirects = new Map();
let replaced = 0;
let serial = 0;
let container;
for (const { template, nodes } of groups.values()) {
if (
nodes.length < 2 ||
nodes.some((el) => duplicateIds.has(el.getAttribute('id')))
)
continue;
const ns = template.namespaceURI || 'http://www.opengis.net/kml/2.2';
if (!container) {
const root = doc.documentElement;
container =
root.localName === 'Document'
? root
: childrenNamed(root, 'Document')[0];
if (!container) {
container = doc.createElementNS(ns, 'Document');
while (root.firstChild) container.appendChild(root.firstChild);
root.appendChild(container);
}
}
let id;
do {
id = `gev-import-style-${++serial}`;
} while (usedIds.has(id));
usedIds.add(id);
template.setAttribute('id', id);
container.appendChild(template);
for (const style of nodes) {
const originalId = style.getAttribute('id');
if (originalId !== null) redirects.set(originalId, id);
let reference;
if (style.parentNode.localName === 'Pair') {
reference = doc.createElementNS(ns, 'styleUrl');
reference.textContent = `#${id}`;
} else {
reference = doc.createElementNS(ns, 'StyleMap');
for (const state of ['normal', 'highlight']) {
const pair = doc.createElementNS(ns, 'Pair');
const key = doc.createElementNS(ns, 'key');
key.textContent = state;
const url = doc.createElementNS(ns, 'styleUrl');
url.textContent = `#${id}`;
pair.appendChild(key);
pair.appendChild(url);
reference.appendChild(pair);
}
}
style.parentNode.replaceChild(reference, style);
replaced += 1;
}
}
for (const url of elementsNamed(doc, 'styleUrl')) {
const value = url.textContent.trim();
const id = value.startsWith('#') && redirects.get(value.slice(1));
if (id) url.textContent = `#${id}`;
}
return replaced;
}
/**
* Count placemarks and vertices in a parsed KML document before Cesium reads
* it: every `<coordinates>` tuple and every `gx:coord`, plus normalized
* style definitions and distinct image `<href>` values (`links`).
* Inline StyleMaps are references, not additional shared style definitions.
* @param {Document} doc
* @returns {{features: number, entities: number, positions: number, links: number,
* over: ''|'features'|'entities'|'positions'|'links'}}
*/
export function countKmlGeometry(
doc,
{
maxFeatures = MAX_IMPORT_ENTITIES,
maxEntities = MAX_IMPORT_ENTITIES,
maxPositions = MAX_IMPORT_POSITIONS,
maxLinks = MAX_KML_LINKS,
} = {},
) {
let features = 0;
let entities = 0;
let positions = 0;
let links = 0;
const imageLinks = new Set();
const result = (over) => ({ features, entities, positions, links, over });
const geometryNames = new Set([
'Point',
'LineString',
'LinearRing',
'Polygon',
'Track',
'MultiTrack',
'MultiGeometry',
'Model',
]);
for (const el of doc.getElementsByTagName('*')) {
const name = el.localName;
if (
['north', 'south', 'east', 'west', 'rotation', 'altitude'].includes(name)
) {
const value = Number(el.textContent);
const limit = ['north', 'south'].includes(name)
? 90
: name === 'altitude'
? 1_000_000
: 360;
if (
!el.textContent.trim() ||
!Number.isFinite(value) ||
Math.abs(value) > limit
)
throw new GeoImportError(msg('That KML has invalid geometry bounds.'));
}
// Cesium creates entities for folders, a parent for every placemark, and
// a child for each geometry in a MultiGeometry, including nested containers.
if (
name === 'Placemark' ||
name === 'Folder' ||
name === 'GroundOverlay' ||
(geometryNames.has(name) &&
['MultiGeometry', 'MultiTrack'].includes(el.parentNode?.localName))
) {
entities += 1;
if (entities > maxEntities) return result('entities');
}
if (
name === 'Style' ||
(name === 'StyleMap' && el.getAttribute('id') !== null)
) {
links += 1;
if (links > maxLinks) return result('links');
} else if (name === 'href') {
const href = el.textContent.trim();
if (!imageLinks.has(href)) {
imageLinks.add(href);
links += 1;
if (links > maxLinks) return result('links');
}
} else if (name === 'Placemark') {
features += 1;
if (features > maxFeatures) return result('features');
} else if (name === 'coordinates') {
const text = el.textContent || '';
for (const match of text.matchAll(/\S+/g)) {
checkKmlPosition(match[0].split(','));
positions += 1;
if (positions > maxPositions) return result('positions');
}
} else if (name === 'coord') {
checkKmlPosition(el.textContent.trim().split(/\s+/));
positions += 1;
if (positions > maxPositions) return result('positions');
}
}
return result('');
}
function checkKmlPosition(tuple) {
const numbers = tuple.map(Number);
if (
tuple.length < 2 ||
tuple.length > 3 ||
tuple.some((v) => !v.trim()) ||
!numbers.every(Number.isFinite) ||
Math.abs(numbers[0]) > 180 ||
Math.abs(numbers[1]) > 90 ||
(numbers.length === 3 && Math.abs(numbers[2]) > 1_000_000)
)
throw new GeoImportError(msg('That KML has invalid coordinates.'));
}
/**
* Read a parsed GPX document into GeoJSON: waypoints become points, each
* route a line and each track one MultiLineString with a line per `<trkseg>`
* (segment breaks are gaps in the recording and stay gaps). Only names are
* kept, and no times, so a dated track draws without a clock. Throws
* `GeoImportError` past the size limits.
* @param {Document} doc
* @returns {object} A FeatureCollection.
*/
export function gpxToGeoJson(
doc,
{
maxFeatures = MAX_IMPORT_ENTITIES,
maxPositions = MAX_IMPORT_POSITIONS,
} = {},
) {
const root = doc.documentElement;
if (root?.localName !== 'gpx')
throw new GeoImportError(msg('That GPX file has no <gpx> document.'));
const features = [];
let positions = 0;
const point = (el) => {
const rawLat = el.getAttribute('lat');
const rawLon = el.getAttribute('lon');
if (rawLat == null || rawLon == null || !rawLat.trim() || !rawLon.trim())
return null;
const lat = Number(rawLat);
const lon = Number(rawLon);
if (
!Number.isFinite(lat) ||
!Number.isFinite(lon) ||
Math.abs(lat) > 90 ||
Math.abs(lon) > 180
)
return null;
positions += 1;
if (positions > maxPositions)
throw overLimitError({
over: 'positions',
features: features.length,
positions,
});
return [lon, lat];
};
const add = (name, geometry) => {
if (features.length >= maxFeatures)
throw overLimitError({
over: 'features',
features: features.length + 1,
positions,
});
features.push({
type: 'Feature',
properties: name ? { name } : {},
geometry,
});
};
for (const wpt of childrenNamed(root, 'wpt')) {
const at = point(wpt);
if (at) add(childText(wpt, 'name'), { type: 'Point', coordinates: at });
}
for (const rte of childrenNamed(root, 'rte')) {
const line = [];
for (const pt of childrenNamed(rte, 'rtept')) {
const at = point(pt);
if (at) line.push(at);
}
if (line.length >= 2)
add(childText(rte, 'name'), { type: 'LineString', coordinates: line });
}
for (const trk of childrenNamed(root, 'trk')) {
const lines = [];
for (const seg of childrenNamed(trk, 'trkseg')) {
const line = [];
for (const pt of childrenNamed(seg, 'trkpt')) {
const at = point(pt);
if (at) line.push(at);
}
if (line.length >= 2) lines.push(line);
}
if (lines.length)
add(childText(trk, 'name'), {
type: 'MultiLineString',
coordinates: lines,
});
}
return { type: 'FeatureCollection', features };
}
/** A feature name as short plain text (no control characters), or undefined. */
export function importFeatureName(value) {
const text = String(value ?? '')
.replace(/[\u0000-\u001f\u007f]/g, ' ')
.replace(/\s+/g, ' ')
.trim();
if (!text) return undefined;
return text.length > MAX_IMPORT_NAME_LENGTH
? `${text.slice(0, MAX_IMPORT_NAME_LENGTH - 1)}…`
: text;
}
/**
* Make every entity of an imported data source inert: no description,
* balloon, extended data or properties, no native label, and a name that is
* short plain text. Generated pin canvases share a data URL so Cesium uploads
* each image once, rather than allocating a texture entry for every entity.
* Returns how many entities were touched.
* @param {{entities: {values: object[]}}} dataSource
* @returns {number}
*/
export function scrubImportedEntities(dataSource) {
const collection = dataSource?.entities;
const list = collection?.values || [];
const images = new Map();
collection?.suspendEvents?.();
try {
for (let i = 0; i < list.length; i++) {
const entity = list[i];
let name;
try {
name = importFeatureName(
typeof entity.name === 'string' ? entity.name : undefined,
);
} catch {
name = undefined;
}
entity.name = name;
entity.description = undefined;
entity.label = undefined;
entity.properties = undefined;
if (entity.kml && typeof entity.kml === 'object') entity.kml = undefined;
if (
entity.billboard?.heightReference?.getValue?.() ===
Cesium.HeightReference.CLAMP_TO_GROUND
)
entity.billboard.disableDepthTestDistance = Number.POSITIVE_INFINITY;
const property = entity.billboard?.image;
if (property?.isConstant === false) continue;
const image = property?.getValue?.();
if (image?.tagName === 'CANVAS') {
let url = images.get(image);
if (!url) {
url = image.toDataURL();
images.set(image, url);
}
entity.billboard.image = url;
}
}
} finally {
collection?.resumeEvents?.();
}
return list.length;
}
/**
* Take time out of an imported data source so adding it cannot move the app's
* shared clock: the data source reports no clock (the viewer adopts the clock
* of every added source that has one), every entity is available for all
* time. KML tracks have already become their original static vertices in
* `sanitizeKmlDocument`, so no sampled-position fallback is needed here.
* @param {object} dataSource
* @returns {object} The same data source.
*/
export function detachImportedTime(dataSource) {
Object.defineProperty(dataSource, 'clock', {
configurable: true,
enumerable: false,
get: () => undefined,
set: () => {},
});
const list = dataSource?.entities?.values || [];
for (let i = 0; i < list.length; i++) {
const entity = list[i];
entity.availability = undefined;
}
return dataSource;
}
/** Repair only the first KML opening tag, scanning its delimiter once. */
export function repairKmlRootNamespaces(value, what = 'KML') {
const text = String(value);
// Skip XML comments and processing instructions without treating their
// literal '<kml' text as an opening root tag.
let start = 0;
for (;;) {
start = text.indexOf('<', start);
if (start < 0) return text;
if (text.slice(start, start + 9).toUpperCase() === '<!DOCTYPE') {
let quote = null;
let subsetDepth = 0;
let end = start + 9;
for (; end < text.length; end++) {
const char = text[end];
if (quote) {
if (char === quote) quote = null;
} else if (char === '"' || char === "'") quote = char;
else if (char === '<' && text.startsWith('<!--', end)) {
// Comments and processing instructions inside the internal subset
// carry no declaration syntax; jump past them as a whole.
const skip = text.indexOf('-->', end + 4);
if (skip < 0) return text;
end = skip + 2;
} else if (char === '<' && text.startsWith('<?', end)) {
const skip = text.indexOf('?>', end + 2);
if (skip < 0) return text;
end = skip + 1;
} else if (char === '[') subsetDepth++;
else if (char === ']') subsetDepth--;
else if (char === '>' && subsetDepth === 0) break;
}
if (end === text.length) return text;
start = end + 1;
continue;
}
const close = text.startsWith('<!--', start)
? '-->'
: text.startsWith('<?', start)
? '?>'
: null;
if (!close) break;
const end = text.indexOf(close, start + 2);
if (end < 0) return text; // The XML parser reports an unterminated preamble.
start = end + close.length;
}
const match = /^<kml\b/i.exec(text.slice(start, start + 5));
if (!match) return text;
let quote = null;
let end = -1;
for (let index = start + match[0].length; index < text.length; index++) {
const char = text[index];
if (char === '<') break; // Raw '<' is invalid even inside an XML attribute.
if (quote) {
if (char === quote) quote = null;
} else if (char === '"' || char === "'") {
quote = char;
} else if (char === '>') {
end = index + 1;
break;
}
}
if (end < 0)
throw new GeoImportError(
`That ${what} file is not valid XML.`,
msg('That {format} file is not valid XML.'),
{ format: what },
);
// Walk the root's attributes in order so quoted values are never read as
// declarations. Anything the walk cannot tokenize is kept verbatim for the
// XML parser to judge.
const seen = new Set();
const attribute = /(\s+)([^\s=/>"']+)\s*=\s*("[^"]*"|'[^']*')/y;
let position = start + match[0].length;
let root = text.slice(start, position);
for (;;) {
attribute.lastIndex = position;
const found = attribute.exec(text);
if (!found || attribute.lastIndex > end) break;
position = attribute.lastIndex;
const prefix = /^xmlns:([\w.-]+)$/.exec(found[2])?.[1];
if (prefix && seen.has(prefix)) continue;
if (prefix) seen.add(prefix);
root += found[0];
}
root += text.slice(position, end);
if (!seen.has('xsi') && /[<\s]xsi:/.test(text))
root = root.replace(
/(\/?)>$/,
' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"$1>',
);
return text.slice(0, start) + root + text.slice(end);
}
/** Parse KML or GPX with the shared namespace repairs and XML validation. */
export function parseXml(text, what) {
// Match the namespace repairs Cesium applies to ordinary exported KML.
if (what !== 'GPX') text = repairKmlRootNamespaces(text, what);
const doc = new DOMParser().parseFromString(
String(text).replace(/^/, ''),
'application/xml',
);
if (doc.getElementsByTagName('parsererror').length)
throw new GeoImportError(
`That ${what} file is not valid XML.`,
msg('That {format} file is not valid XML.'),
{ format: what },
);
return doc;
}
/** Decode XML bytes, honouring a UTF-16 byte-order mark. */
export function decodeXml(bytes) {
const encoding =
bytes[0] === 0xff && bytes[1] === 0xfe
? 'utf-16le'
: bytes[0] === 0xfe && bytes[1] === 0xff
? 'utf-16be'
: 'utf-8';
return new TextDecoder(encoding).decode(bytes);
}
function checkLocalImages(doc, entries = new Map(), main = '') {
const charge = createImportImageBudget();
const checked = new Set();
for (const href of elementsNamed(doc, 'href')) {
const value = href.textContent.trim();
if (checked.has(value)) continue;
checked.add(value);
const path = resolveKmzPath(value, main, entries);
try {
if (path && kmzImageType(path)) charge(path, entries.get(path));
else if (/^data:image\/(png|jpeg|gif|webp|bmp);/i.test(value)) {
const comma = value.indexOf(',');
const header = value.slice(0, comma);
const body = value.slice(comma + 1);
const raw = /;base64$/i.test(header)
? atob(body)
: decodeURIComponent(body);
charge(
value,
Uint8Array.from(raw, (c) => c.charCodeAt(0)),
);
}
} catch {
throw new GeoImportError(
msg(
'That file has an unreadable image or exceeds the 16-megapixel image limit.',
),
);
}
}
}
// Cesium also processes KML in deferred tasks; an exception there does not
// reject its load promise. Keep a failed file from blocking the serial queue.
async function loadKml(doc, viewer, signal) {
let removeError;
try {
return await boundedImport(
Promise.race([
Cesium.KmlDataSource.load(doc, {
camera: viewer.scene.camera,
canvas: viewer.scene.canvas,
clampToGround: true,
}),
new Promise((_, reject) => {
const failed = () => {
reject(new GeoImportError(msg('That KML could not be read.')));
};
globalThis.addEventListener?.('error', failed);
removeError = () => globalThis.removeEventListener?.('error', failed);
}),
]),
signal,
);
} finally {
removeError?.();
}
}
// Resolve a static file's ground pins in batches before they are visualized.
// Per-billboard CLAMP_TO_GROUND subscriptions scale poorly on large imports.
const groundPins = new WeakMap();
async function settleGroundPins(dataSource, viewer, signal) {
let pins = groundPins.get(dataSource);
if (!pins) {
pins = [];
for (const entity of dataSource.entities.values) {
const reference = entity.billboard?.heightReference?.getValue?.();
if (
reference === Cesium.HeightReference.CLAMP_TO_GROUND ||
reference === Cesium.HeightReference.RELATIVE_TO_GROUND
) {
const position = entity.position?.getValue?.(Cesium.JulianDate.now());
if (!position) continue;
const cartographic = Cesium.Cartographic.fromCartesian(position);
if (!cartographic)
throw new GeoImportError(
msg('That file has invalid point coordinates.'),
);
pins.push({
entity,
original: position,
cartographic,
offset:
reference === Cesium.HeightReference.RELATIVE_TO_GROUND
? cartographic.height
: 0,
});
entity.billboard.heightReference = Cesium.HeightReference.NONE;
entity.billboard.disableDepthTestDistance = Number.POSITIVE_INFINITY;
}
}
groundPins.set(dataSource, pins);
}
for (let at = 0; at < pins.length; at += 256) {
signal?.throwIfAborted();
const batch = pins.slice(at, at + 256);
const positions = batch.map(
({ cartographic: c }) =>
new Cesium.Cartographic(c.longitude, c.latitude, 0),
);
const mesh =
viewer.scene?.globe?.show === false &&
viewer.scene?.clampToHeightSupported;
// A coarse rendered ellipsoid mesh can report a height kilometres below
// zero. Its provider's exact height is zero even while a 3D map hides it;
// a buried starting point can make the downward mesh ray miss the surface.
const ellipsoid =
viewer.terrainProvider instanceof Cesium.EllipsoidTerrainProvider;
for (let i = 0; i < positions.length; i++) {
const sampled = ellipsoid
? 0
: viewer.scene?.globe?.getHeight?.(positions[i]);
positions[i].height = mesh
? (batch[i].groundHeight ??
Math.max(0, Number.isFinite(sampled) ? sampled : 0))
: Number.isFinite(sampled)
? sampled
: batch[i].groundHeight || 0;
}
const points = positions.map((c) =>
Cesium.Cartesian3.fromRadians(c.longitude, c.latitude, c.height),
);
const height = viewer.camera?.positionCartographic?.height;
if (mesh && Number.isFinite(height) && height < 250_000) {
const rectangle = viewer.camera.computeViewRectangle?.();
const indices = [];
for (let i = 0; i < positions.length; i++)
if (rectangle && Cesium.Rectangle.contains(rectangle, positions[i]))
indices.push(i);
if (indices.length) {
const resolved = await boundedImport(
viewer.scene.clampToHeightMostDetailed(
indices.map((i) => {
const c = positions[i];
return Cesium.Cartesian3.fromRadians(
c.longitude,
c.latitude,
Math.max(0, c.height),
);
}),
),
signal,
);
for (let i = 0; i < indices.length; i++)
if (resolved[i]) points[indices[i]] = resolved[i];
}
}
signal?.throwIfAborted();
for (let i = 0; i < batch.length; i++) {
const item = batch[i];
const c = points[i] && Cesium.Cartographic.fromCartesian(points[i]);
if (!c)
throw new GeoImportError(
msg(
'Ground heights are not available for that file. Try again when the map has loaded.',
),
);
item.groundHeight = c.height;
c.height += item.offset;
item.entity.position =
Math.abs(c.height - item.cartographic.height) < 1e-6
? item.original
: Cesium.Cartesian3.fromRadians(c.longitude, c.latitude, c.height);
}
if (at + batch.length < pins.length)
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
async function boundedImport(promise, signal) {
let timer, abort;
try {
signal?.throwIfAborted();
return await Promise.race([
promise,
new Promise((_, reject) => {
abort = () => reject(signal.reason);
signal?.addEventListener('abort', abort, { once: true });
timer = setTimeout(
() =>
reject(new GeoImportError(msg('That file took too long to read.'))),
60_000,
);
}),
]);
} finally {
clearTimeout(timer);
signal?.removeEventListener('abort', abort);
}
}
/**
* Load a ground footprint, retaining explicit KML altitude modes. Call mount after
* adding the source; revoke owns pin and blob cleanup.
* @param {File|Blob & {name?: string}} file
* @param {{viewer: Cesium.Viewer, color?: string}} options `color` is a CSS color.
* @returns {Promise<{dataSource: Cesium.DataSource, name: string,
* format: string, entityCount: number, removed: number, mount: Function, revoke: Function}>}
*/
export async function loadGeoFile(
file,
{ viewer, color = '#39d0ff', signal } = {},
) {
signal = signal
? AbortSignal.any([signal, AbortSignal.timeout(60_000)])
: AbortSignal.timeout(60_000);
signal?.throwIfAborted();
if (!file || !Number.isFinite(file.size))
throw new GeoImportError(msg('Nothing to import.'));
if (file.size > MAX_IMPORT_BYTES)
throw new GeoImportError(
`That file is larger than ${MAX_IMPORT_BYTES / 1024 / 1024} MiB.`,
msg('That file is larger than {size} MiB.'),
{ size: MAX_IMPORT_BYTES / 1024 / 1024 },
);
let bytes = new Uint8Array(await boundedImport(file.arrayBuffer(), signal));
const format = detectGeoFileFormat(file.name, bytes.subarray(0, 1024));
if (!format)
throw new GeoImportError(
msg('Only GeoJSON, KML, KMZ and GPX files can be imported.'),
);
const stroke = Cesium.Color.fromCssColorString(color);
const urls = [];
let pins;
const revoke = () => {
pins?.destroy();
urls.splice(0).forEach((url) => URL.revokeObjectURL(url));
};
const name = importDisplayName(file.name);
let dataSource;
let removed = 0;
try {
if (format === 'geojson' || format === 'gpx') {
let geojson;
if (format === 'gpx') {
geojson = gpxToGeoJson(parseXml(decodeXml(bytes), 'GPX'));
} else {
geojson = parseGeoJsonText(new TextDecoder().decode(bytes));
}
const size = countGeoJsonGeometry(geojson);
if (size.over) throw overLimitError(size);
if (!size.positions)
throw new GeoImportError(msg('That file has nothing to draw.'));
prepareGeoJson(geojson);
bytes = null;
dataSource = await boundedImport(
Cesium.GeoJsonDataSource.load(geojson, {
clampToGround: true,
stroke,
fill: stroke.withAlpha(0.25),
strokeWidth: 3,
markerColor: stroke,
// No HTML description table is built from the file's properties.
describe: () => undefined,
}),
signal,
);
} else {
let text;
let entries;
let main;
let resolveLocal = () => null;
if (format === 'kmz') {
entries = await readZipEntries(bytes);
main = kmzMainDocument(entries);
if (!main)
throw new GeoImportError(msg('That KMZ holds no KML document.'));
text = decodeXml(entries.get(main));
resolveLocal = kmzImageResolver(entries, main, (url) => urls.push(url));
} else {
text = decodeXml(bytes);
}
const doc = parseXml(text, format.toUpperCase());
text = null;
bytes = null;
// Bound geometry before transformations, then count the styles and
// image links that survive sanitizing and sharing repeated styles.
const size = countKmlGeometry(doc, { maxLinks: Infinity });
if (size.over) throw overLimitError(size);
checkLocalImages(doc, entries, main);
removed = sanitizeKmlDocument(doc, resolveLocal).removed;
entries?.clear();
deduplicateKmlStyles(doc);
const normalizedSize = countKmlGeometry(doc);
if (normalizedSize.over) throw overLimitError(normalizedSize);
dataSource = await loadKml(doc, viewer, signal);
}
} catch (error) {
revoke();
if (error instanceof GeoImportError) throw error;
throw new GeoImportError(
`That ${format.toUpperCase()} file could not be read.`,
msg('That {format} file could not be read.'),
{ format: format.toUpperCase() },
);
}
const entityCount = dataSource.entities.values.length;
if (entityCount > MAX_IMPORT_ENTITIES) {
revoke();
throw new GeoImportError(
`That file has ${entityCount.toLocaleString()} map objects; the limit is ${MAX_IMPORT_ENTITIES.toLocaleString()}.`,
msg('That file has {count} map objects; the limit is {limit}.'),
{
count: entityCount.toLocaleString(),
limit: MAX_IMPORT_ENTITIES.toLocaleString(),
},
);
}
const now = Cesium.JulianDate.now();
const drawable = dataSource.entities.values.some(
(e) =>
e.billboard?.image?.getValue(now) ||
e.point ||
e.rectangle ||
e.polyline?.positions?.getValue(now)?.length >= 2 ||
e.wall?.positions?.getValue(now)?.length >= 2 ||
e.polygon?.hierarchy?.getValue(now)?.positions?.length >= 3,
);
if (!drawable) {
revoke();
throw new GeoImportError(msg('That file has nothing to draw.'));
}
scrubImportedEntities(dataSource);
try {
await settleGroundPins(dataSource, viewer, signal);
} catch (error) {
revoke();
throw error instanceof GeoImportError
? error
: new GeoImportError(
msg('Ground heights could not be read. Try that file again.'),
);
}
// Keep the clock invariant explicit even though unused KML dates have
// already been stripped and all supported geometries are static.
detachImportedTime(dataSource);
try {
pins = createImportedPins(dataSource, viewer);
} catch {
revoke();
throw new GeoImportError(msg('That file has invalid point graphics.'));
}
// The display name travels beside the data source (the file name, not
// anything the document says about itself).
return {
dataSource,
name,
format,
entityCount,
removed,
revoke,
mount: () => pins.mount(),
refreshGround: (refreshSignal) =>
settleGroundPins(
dataSource,
viewer,
refreshSignal
? AbortSignal.any([refreshSignal, AbortSignal.timeout(15_000)])
: AbortSignal.timeout(15_000),
).then(() => pins.sync()),
};
}