Files
gods-eye-view/src/data/geoImportKml.js
T
German Khokhlov 97c4dc76ce Move scene effects and imported geometry behind the globe contract
Move Cesium viewer, map, sky, projection, trail and sonar internals into
its engine. Drive styles, bloom, sharpening and contact sonar through
engine.render. Count camera-input suspensions across all three engines
and migrate the feature callers. Preserve Cesium's effects and input
behaviour; fix transit lens clicks on Cesium and make zero sharpening on
Navara disable sharpening, as it does on Cesium.

Parse imported files into plain records and draw them through movers,
lines, ground and imagery on both engines. Follow Cesium's KML style
precedence, preserve local KMZ images and frame the drawable records.
Open overlays use imagery when the engine has no native map-overlay API.
Run every imported-display case on fake and headless Cesium engines.

The shared import path retains these known differences from Cesium's old
DataSources: wall fills, extruded prisms and gx:LatLonQuad are undrawn;
raised polygon fills drape while outlines retain altitude; GroundOverlay
rotation, altitude and RGB tint are not applied; rhumb lines become great
circles. Ground heights use the loaded surface synchronously instead of
waiting for most-detailed sampling. Supported KMZ ground overlays now
draw on Navara too. Document the limits rather than claiming full parity.

Combine batches B and C because their disjoint path manifests cannot
place the shared boundary and format files in a later commit while
keeping B independently valid. This combined commit owns the shared
docs, package boundaries, format scope, locale catalogs and coupling
baseline. Remove five obsolete import strings from all eleven catalogs.
Make the load-time source scan include new files and skip deleted paths
so the same checks work before and after recording the moves.

Coupling: Navara renderer lines fall from 1695 to 1294, Cesium import
files from 25 to 9, viewer lines from 1177 to 1026, SDK loads from 4 to 3
and engine-name lines from 62 to 42. No count grows.

The full unit suite and the boundary, format and coupling checks pass.
Browser validation remains to be run.

Browser checks to run
GOOGLE_MAPS_API_KEY= CESIUM_ION_TOKEN= npm run dev -- --port 4291
node scripts/qa-contract-suite.mjs http://localhost:4291
node scripts/qa-navara-visual-styles.mjs http://localhost:4291
node scripts/qa-navara-bloom.mjs http://localhost:4291
node scripts/qa-navara-sonar.mjs http://localhost:4291
QA_BASE_URL=http://localhost:4291 node scripts/qa-visual-effects.mjs
QA_BASE_URL=http://localhost:4291 node scripts/qa-zoom-out-guard.mjs
node scripts/qa-sky-model-lighting.mjs --url http://localhost:4291
node scripts/qa-geo-import.mjs http://localhost:4291
node scripts/qa-geo-import-regressions.mjs http://localhost:4291
node scripts/qa-geo-import-large.mjs http://localhost:4291
node scripts/qa-navara-geo-import.mjs http://localhost:4291

Use the keyless server for every check. Photoreal-only cases remain
unverified; do not enable paid tiles to run them.
2026-11-07 12:45:21 +04:00

411 lines
14 KiB
JavaScript

// A sanitized KML document (src/data/geoFileImport.js: no network links,
// remote images, models, descriptions or times, tracks as their recorded
// lines) read into the import's plain records (src/data/geoImportRecords.js)
// the way Cesium's KmlDataSource read it, without Cesium: the same shared,
// inline and StyleMap styles and their precedence, the same defaults (a
// yellow map pin, white lines and fills), billboards of 32 px with KML's
// distance scale and hot spot, ground lines for clamped and tessellated
// paths, lines in the air for absolute and relative ones, and ground
// overlays as image rectangles. Labels are not drawn (the import never
// drew them); walls and extruded polygons are counted in `undrawn`.
import { emptyRecords, importFeatureName } from './geoImportRecords.js';
// KmlDataSource's billboard: 32 px, scaled by camera distance.
const BILLBOARD_SIZE = 32;
const BILLBOARD_SCALE_BY_DISTANCE = Object.freeze([
2414016, 1.0, 1.6093e7, 0.1,
]);
// Its pin where no icon is given: Cesium.Color.YELLOW, drawn at 64 px.
const DEFAULT_PIN = Object.freeze({
pin: Object.freeze([1, 1, 0, 1]),
pinSize: 64,
});
const WHITE = Object.freeze([1, 1, 1, 1]);
const GEOMETRY = new Set([
'Point',
'LineString',
'LinearRing',
'Polygon',
'MultiGeometry',
'Model',
'Track',
'MultiTrack',
]);
/** 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 first = (el, localName) => childrenNamed(el, localName)[0];
/** A child's trimmed text, or undefined without the child. */
const textOf = (el, localName) => {
const child = first(el, localName);
return child ? child.textContent.trim() : undefined;
};
const numberOf = (el, localName) => {
const value = Number.parseFloat(textOf(el, localName));
return Number.isFinite(value) ? value : undefined;
};
const booleanOf = (el, localName) => {
const value = textOf(el, localName);
return value === undefined
? undefined
: value === '1' || /^true$/i.test(value);
};
/**
* A KML colour (aabbggrr) as rgba in 0..1, or undefined; `random`
* (colorMode random) draws each non-zero channel at random up to its
* value, as Cesium does, on every read.
*/
export function kmlColor(value, random = false) {
const text = String(value ?? '')
.trim()
.replace(/^#/, '');
if (!text) return undefined;
const channel = (at) => Number.parseInt(text.substring(at, at + 2), 16) / 255;
const [alpha, blue, green, red] = [0, 2, 4, 6].map(channel);
const pick = (v) => (random && v > 0 ? Math.random() * v : v);
return [pick(red), pick(green), pick(blue), alpha];
}
const colorOf = (el, localName) =>
kmlColor(textOf(el, localName), textOf(el, 'colorMode') === 'random');
/** One coordinate tuple; Google Earth reads what is missing as 0. */
function tuple(text) {
const [lon = 0, lat = 0, height = 0] = String(text ?? '')
.split(',')
.map((v) => Number.parseFloat(v))
.map((v) => (Number.isFinite(v) ? v : 0));
return [lon, lat, height];
}
const coordinates = (el) =>
el ? (el.textContent.match(/\S+/g) ?? []).map(tuple) : [];
/** Where a geometry sits, from its altitude modes (Cesium's reading). */
function altitudeOf(geometry) {
const modes = childrenNamed(geometry, 'altitudeMode');
const isGx = (el) => /google\.com\/kml\/ext/.test(el.namespaceURI || '');
const mode = modes.find((el) => !isGx(el))?.textContent.trim();
const gx = modes.find(isGx)?.textContent.trim();
if (mode === 'absolute') return 'absolute';
if (mode === 'relativeToGround') return 'relative';
if (!mode || mode === 'clampToGround')
return gx === 'relativeToSeaFloor' && !mode ? 'relative' : 'ground';
return gx === 'relativeToSeaFloor' ? 'relative' : 'ground';
}
// A style as KmlDataSource builds it on an entity: `icon` (its billboard),
// `line` (its polyline) and `poly` (its polygon); a property left undefined
// is filled by a merged style.
function applyStyle(styleEl, target) {
for (const node of childrenNamed(styleEl, 'IconStyle')) {
const iconEl = first(node, 'Icon');
const href = textOf(iconEl, 'href');
const icon = (target.icon ??= {});
// Blank <Icon> tags mean no icon at all.
icon.image = href ? { url: href } : iconEl ? false : undefined;
icon.scale = numberOf(node, 'scale');
icon.color = colorOf(node, 'color');
const region = ['x', 'y', 'w', 'h'].map((key) => numberOf(iconEl, key));
if (region.some((v) => v !== undefined))
icon.subRegion = region.map((v) => v ?? 0);
const heading = numberOf(node, 'heading');
// Google Earth reads a heading of 0 as none.
if (heading !== undefined && heading !== 0)
icon.rotation = (-heading * Math.PI) / 180;
const offset = hotSpotOffset(first(node, 'hotSpot'), icon.scale ?? 1);
if (offset) icon.offsetPx = offset;
}
for (const node of childrenNamed(styleEl, 'LineStyle'))
target.line = {
width: numberOf(node, 'width'),
color: colorOf(node, 'color'),
};
for (const node of childrenNamed(styleEl, 'PolyStyle')) {
const poly = (target.poly ??= { outline: true, outlineColor: WHITE });
poly.color = colorOf(node, 'color') ?? poly.color;
poly.fill = booleanOf(node, 'fill') ?? poly.fill;
poly.outline = booleanOf(node, 'outline') ?? poly.outline;
}
}
/** A KML hot spot as Cesium's billboard pixel offset (+y down), or null. */
function hotSpotOffset(el, scale) {
if (!el) return null;
const read = (name) => {
const value = Number.parseFloat(el.getAttribute(name));
return Number.isFinite(value) ? value : undefined;
};
const x = read('x');
const y = read('y');
let dx;
let dy;
if (x !== undefined) {
const unit = el.getAttribute('xunits');
if (unit === 'pixels') dx = -x * scale;
else if (unit === 'insetPixels') dx = (x - BILLBOARD_SIZE) * scale;
else if (unit === 'fraction') dx = -x * BILLBOARD_SIZE * scale;
dx = (dx ?? Number.NaN) + BILLBOARD_SIZE * 0.5 * scale;
}
if (y !== undefined) {
const unit = el.getAttribute('yunits');
if (unit === 'pixels') dy = y * scale;
else if (unit === 'insetPixels') dy = (-y + BILLBOARD_SIZE) * scale;
else if (unit === 'fraction') dy = y * BILLBOARD_SIZE * scale;
dy = (dy ?? Number.NaN) - BILLBOARD_SIZE * 0.5 * scale;
}
if (dx === undefined && dy === undefined) return null;
const finite = (v) => (Number.isFinite(v) ? v : 0);
return [finite(dx), finite(dy)];
}
const cloneStyle = (style) => ({
icon: style.icon && { ...style.icon },
line: style.line && { ...style.line },
poly: style.poly && { ...style.poly },
});
/** Entity.merge: what `target` leaves undefined comes from `source`. */
function mergeStyle(target, source) {
if (!source) return target;
for (const key of ['icon', 'line', 'poly']) {
if (!source[key]) continue;
if (!target[key]) target[key] = { ...source[key] };
else
for (const [name, value] of Object.entries(source[key]))
target[key][name] ??= value;
}
return target;
}
/** The document's shared styles by '#id', as KmlDataSource collects them. */
function sharedStyles(doc) {
const styles = new Map();
const all = [...doc.getElementsByTagName('*')];
for (const el of all) {
if (el.localName !== 'Style') continue;
const id = el.getAttribute('id');
if (id === null || styles.has(`#${id}`)) continue;
const style = {};
applyStyle(el, style);
styles.set(`#${id}`, style);
}
for (const el of all) {
if (el.localName !== 'StyleMap') continue;
const id = el.getAttribute('id');
if (id === null) continue;
for (const pair of childrenNamed(el, 'Pair')) {
if (textOf(pair, 'key') !== 'normal' || styles.has(`#${id}`)) continue;
const style = {};
const url = textOf(pair, 'styleUrl');
if (url !== undefined)
mergeStyle(style, styles.get(url.startsWith('#') ? url : `#${url}`));
else {
const inline = first(pair, 'Style');
if (inline) applyStyle(inline, style);
}
styles.set(`#${id}`, style);
}
}
return styles;
}
/** A placemark's final style: its last inline style, then its styleUrl. */
function placemarkStyle(placemark, styles) {
const lookup = (url) => styles.get(url) ?? styles.get(`#${url}`);
const result = {};
const inline = [...(placemark.childNodes || [])]
.filter(
(el) =>
el.nodeType === 1 &&
(el.localName === 'Style' || el.localName === 'StyleMap'),
)
.at(-1);
if (inline?.localName === 'Style') applyStyle(inline, result);
else if (inline)
for (const pair of childrenNamed(inline, 'Pair')) {
if (textOf(pair, 'key') !== 'normal') continue;
const url = textOf(pair, 'styleUrl');
if (url !== undefined) mergeStyle(result, lookup(url));
else {
const style = first(pair, 'Style');
if (style) applyStyle(style, result);
}
}
const external = textOf(placemark, 'styleUrl');
if (external !== undefined) mergeStyle(result, lookup(external));
return result;
}
/** The polyline Cesium draws for a style: its colour (white) and width (1). */
const lineLook = (style) => ({
color: style.line?.color ?? WHITE,
widthPx: style.line?.width ?? 1,
});
function readGeometry(geometry, style, name, records) {
const kind = geometry.localName;
if (kind === 'MultiGeometry') {
for (const child of geometry.childNodes || [])
if (child.nodeType === 1 && GEOMETRY.has(child.localName))
readGeometry(child, style, name, records);
return;
}
const altitude = altitudeOf(geometry);
const extrude = booleanOf(geometry, 'extrude') === true;
if (kind === 'Point') {
const [position = [0, 0, 0]] = coordinates(first(geometry, 'coordinates'));
const icon = style.icon ?? {};
if (icon.image !== false)
records.points.push({
name,
position,
altitude,
icon: {
image: icon.image || DEFAULT_PIN,
widthPx: BILLBOARD_SIZE,
heightPx: BILLBOARD_SIZE,
scale: icon.scale,
color: icon.color,
offsetPx: icon.offsetPx,
subRegion: icon.subRegion,
rotation: icon.rotation,
scaleByDistance: BILLBOARD_SCALE_BY_DISTANCE,
},
});
// A drop line from an extruded point down to the ellipsoid.
if (extrude && altitude !== 'ground')
records.lines.push({
name,
positions: [position, [position[0], position[1], 0]],
ground: false,
...lineLook(style),
});
return;
}
if (kind === 'LineString' || kind === 'LinearRing') {
const positions = coordinates(first(geometry, 'coordinates'));
if (positions.length < 2) return;
const tessellate = booleanOf(geometry, 'tessellate') === true;
if (altitude !== 'ground' && extrude) {
// A wall; its outline's top edge draws as the path.
records.undrawn.wall = (records.undrawn.wall ?? 0) + 1;
records.lines.push({
name,
positions,
ground: false,
...lineLook(style),
});
} else if (altitude === 'ground' && tessellate)
records.lines.push({ name, positions, ground: true, ...lineLook(style) });
else
records.lines.push({
name,
positions:
altitude === 'ground'
? positions.map(([lon, lat]) => [lon, lat, 0])
: positions,
ground: false,
...lineLook(style),
});
return;
}
if (kind === 'Polygon') {
const ringOf = (boundary) =>
coordinates(first(first(boundary, 'LinearRing'), 'coordinates'));
const outer = ringOf(first(geometry, 'outerBoundaryIs'));
if (!outer.length) return;
const holes = childrenNamed(geometry, 'innerBoundaryIs')
.flatMap((boundary) =>
childrenNamed(boundary, 'LinearRing').map((ring) =>
coordinates(first(ring, 'coordinates')),
),
)
.filter((ring) => ring.length);
const poly = style.poly ?? { outline: true, outlineColor: WHITE };
const raised = altitude !== 'ground';
if (raised && extrude)
records.undrawn.extruded = (records.undrawn.extruded ?? 0) + 1;
records.polygons.push({
name,
rings: [outer, ...holes],
raised,
fill: poly.fill === false ? null : (poly.color ?? WHITE),
outline:
poly.outline === false
? null
: {
color: style.line
? (style.line.color ?? WHITE)
: (poly.outlineColor ?? WHITE),
widthPx: style.line?.width ?? 1,
},
});
}
// A Model or a Track left by the sanitizer has nothing to draw.
}
function readGroundOverlay(el, records) {
const name = importFeatureName(textOf(el, 'name'));
const color = colorOf(el, 'color') ?? WHITE;
const quad = first(el, 'LatLonQuad');
if (quad) {
records.undrawn.latLonQuad = (records.undrawn.latLonQuad ?? 0) + 1;
return;
}
const box = first(el, 'LatLonBox');
if (!box) return;
// Cesium's negativePiToPi and latitude clamp.
const lon = (v = 0) =>
v >= -180 && v <= 180 ? v : ((((v + 180) % 360) + 360) % 360) - 180;
const lat = (v = 0) => Math.max(-90, Math.min(90, v));
const rectangle = {
west: lon(numberOf(box, 'west')),
south: lat(numberOf(box, 'south')),
east: lon(numberOf(box, 'east')),
north: lat(numberOf(box, 'north')),
};
if (!(rectangle.north > rectangle.south)) return;
const url = textOf(first(el, 'Icon'), 'href') || null;
records.overlays.push({
name,
url,
rectangle,
color,
rotation: numberOf(box, 'rotation') ?? 0,
});
}
/**
* Read a sanitized KML document into records, placemarks and ground
* overlays in document order.
* @param {Document} doc
* @returns {import('./geoImportRecords.js').ImportedRecords}
*/
export function readKmlRecords(doc) {
const records = emptyRecords();
const styles = sharedStyles(doc);
for (const el of doc.getElementsByTagName('*')) {
if (el.localName === 'GroundOverlay') {
readGroundOverlay(el, records);
continue;
}
if (el.localName !== 'Placemark') continue;
const name = importFeatureName(textOf(el, 'name'));
const style = cloneStyle(placemarkStyle(el, styles));
// Only a placemark's first geometry draws.
const geometry = [...(el.childNodes || [])].find(
(child) => child.nodeType === 1 && GEOMETRY.has(child.localName),
);
if (geometry) readGeometry(geometry, style, name, records);
}
return records;
}