// The KML reader against Cesium's KmlDataSource, the reference it replaces: // the same sanitized documents read by both give the same pins, lines, // polygons and overlays with the same styles. Cesium stays a test // dependency here only. import '../testSupport/registerDom.mjs'; import test from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; import { deduplicateKmlStyles, loadGeoFile, parseXml, sanitizeKmlDocument, } from './geoFileImport.js'; import { kmlColor, readKmlRecords } from './geoImportKml.js'; // happy-dom's getElementsByTagNameNS('*', name) finds nothing in a parsed // XML document; KmlDataSource queries every element through it. function byNamespace(namespace, localName) { return [...this.getElementsByTagName('*')].filter( (el) => (localName === '*' || el.localName === localName) && (namespace === '*' || el.namespaceURI === namespace), ); } const probe = new DOMParser().parseFromString('', 'application/xml'); for (const node of [probe, probe.documentElement]) for (let p = Object.getPrototypeOf(node); p; p = Object.getPrototypeOf(p)) if (Object.hasOwn(p, 'getElementsByTagNameNS')) { p.getElementsByTagNameNS = byNamespace; break; } const TRAP = 'gev-qa-trap.invalid'; const PNG = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=='; const kml = (body) => ` ${body}`; // scripts/qa-geo-import.mjs's KML, with a packed icon and overlay as in its KMZ. const QA = kml(` https://${TRAP}/link.kml QA KML pin#s <img src="https://${TRAP}/balloon.png"> 2019-01-01T00:00:00Z2019-01-02T00:00:00Z -122.47,37.77,0 QA palette pin#palette -122.48,37.771,0 QA moving 2019-01-01T00:00:00Z2019-01-01T01:00:00Z -122.49 37.767 0-122.475 37.772 0 QA split tracks -122.50 37.767 0-122.49 37.768 0 -122.47 37.771 0-122.46 37.772 0 QA remote stylehttps://${TRAP}/styles.kml#x -122.50,37.766 -122.46,37.772 ${PNG} 37.7737.76-122.46-122.47`); // Styles and geometries the import keeps, each the way KML allows. const STYLED = kml(` normal#red highlight#pin normal default pin1,1 styled pin#pin1,2,50 fraction#fracabsolute1,3,500 inset#insetrelativeToGround11,4,80 hidden icon#none1,5 mapped line#map0,0 1,1 2,1 inline map line#inlineMap0,0 1,0 override#red 0,1 1,2 air line#redabsolute0,2,100 1,3,200 relative line0relativeToGround0,3,10 1,4,20 wall#red1absolute0,4,100 1,5,100 ring0,0 1,0 1,1 0,0 filled#red 0,0 2,0 2,2 0,2 0,0 0.5,0.5 1,0.5 1,1 0.5,0.5 hollow raised#hollowabsolute 3,0,10 4,0,10 4,1,10 3,0,10 plain5,0 6,0 6,1 5,0 multi#red 7,7 7,7 8,8 7,0 8,0 8,1 7,0 in folder#red9,9 80ffffff${PNG} 1110-17917915 ff0000ff13121312 deduplicated a#a3,3 4,4 deduplicated b#b4,4 5,5`); // scripts/qa-geo-import-large.mjs's style check: one shared style with // point, line and polygon parts, each placemark overriding one part inline, // and named styles and an inline StyleMap pair that are alike. const SHARED = kml(` shared point#base -122.49,37.77,0 shared line#base -122.50,37.77,0 -122.49,37.77,0 shared polygon#base -122.50,37.77,0 -122.49,37.77,0 -122.49,37.78,0 -122.50,37.77,0 normal named-a#named-a-122.49,37.77,0 named-b#named-b-122.49,37.77,0 paired#paired-122.49,37.77,0`); /** A document as the import prepares it for reading. */ function prepared(text) { const doc = parseXml(text, 'KML'); sanitizeKmlDocument(doc); deduplicateKmlStyles(doc); return doc; } // To 1e-6, and -0 as 0. const round = (v) => v === undefined ? undefined : Math.round(v * 1e6) / 1e6 + 0; const rgba = (c) => c && [c.red, c.green, c.blue, c.alpha].map(round); const lonLatH = (cartesian) => { const c = Cesium.Cartographic.fromCartesian(cartesian); return [ Cesium.Math.toDegrees(c.longitude), Cesium.Math.toDegrees(c.latitude), c.height, ].map((v) => Math.round(v * 1e4) / 1e4 + 0); }; const roundPosition = (p) => p.map((v) => Math.round(v * 1e4) / 1e4 + 0); const HEIGHT_MODE = { [Cesium.HeightReference.CLAMP_TO_GROUND]: 'ground', [Cesium.HeightReference.RELATIVE_TO_GROUND]: 'relative', [Cesium.HeightReference.NONE]: 'absolute', }; /** What Cesium's KmlDataSource draws of a document, as comparable data. */ async function cesiumReading(text) { const previous = Cesium.PinBuilder.prototype.fromColor; Cesium.PinBuilder.prototype.fromColor = (color, size) => ({ pin: rgba(color), pinSize: size, }); try { const ds = await Cesium.KmlDataSource.load(prepared(text), { clampToGround: true, }); const now = Cesium.JulianDate.now(); const value = (property) => property?.getValue?.(now); const out = { points: [], lines: [], polygons: [], overlays: [], walls: 0 }; for (const entity of ds.entities.values) { const billboard = entity.billboard; const image = value(billboard?.image); if (billboard && entity.position && image) { const offset = value(billboard.pixelOffset); const rotation = value(billboard.rotation); const region = value(billboard.imageSubRegion); out.points.push({ name: entity.name, position: lonLatH(value(entity.position)), altitude: HEIGHT_MODE[value(billboard.heightReference)], image: image.pin ? image : { url: image.url ?? String(image) }, scale: round(value(billboard.scale) ?? 1), color: rgba(value(billboard.color)) ?? [1, 1, 1, 1], offset: offset ? [offset.x, offset.y].map(round) : [0, 0], rotation: round(rotation ?? 0), subRegion: region ? [region.x, region.y, region.width, region.height] : undefined, size: [value(billboard.width), value(billboard.height)], }); } if (entity.polyline) { const ground = value(entity.polyline.clampToGround) === true; out.lines.push({ name: entity.name, positions: value(entity.polyline.positions).map((p) => { const [lon, lat, h] = lonLatH(p); return ground ? [lon, lat] : [lon, lat, h]; }), ground, color: rgba(value(entity.polyline.material)?.color) ?? rgba(entity.polyline.material?.color?.getValue(now)) ?? [ 1, 1, 1, 1, ], width: value(entity.polyline.width) ?? 1, }); } if (entity.wall) out.walls += 1; if (entity.polygon) { const polygon = entity.polygon; const hierarchy = value(polygon.hierarchy); const raised = value(polygon.perPositionHeight) === true; const ring = (positions) => positions.map((p) => { const [lon, lat, h] = lonLatH(p); return raised ? [lon, lat, h] : [lon, lat]; }); const fill = value(polygon.fill) ?? true; const outline = value(polygon.outline) ?? false; out.polygons.push({ name: entity.name, rings: [ ring(hierarchy.positions), ...hierarchy.holes.map((h) => ring(h.positions)), ], raised, fill: fill ? (rgba(polygon.material?.color?.getValue(now)) ?? [1, 1, 1, 1]) : null, outline: outline ? { color: rgba(value(polygon.outlineColor)) ?? [1, 1, 1, 1], widthPx: value(polygon.outlineWidth) ?? 1, } : null, }); } if (entity.rectangle) { const r = value(entity.rectangle.coordinates); const material = entity.rectangle.material; const url = material?.image?.getValue(now); out.overlays.push({ rectangle: [r.west, r.south, r.east, r.north].map((v) => round(Cesium.Math.toDegrees(v)), ), url: url ? (url.url ?? String(url)) : null, color: rgba(material?.color?.getValue(now)) ?? rgba(material?.getValue?.(now)?.color) ?? [1, 1, 1, 1], rotation: round( Cesium.Math.toDegrees(value(entity.rectangle.rotation) ?? 0), ), }); } } return out; } finally { Cesium.PinBuilder.prototype.fromColor = previous; } } /** The reader's records of a document, in the same comparable form. */ function ourReading(text) { const records = readKmlRecords(prepared(text)); return { points: records.points.map(({ name, position, altitude, icon }) => ({ name, position: roundPosition(position), altitude, image: icon.image.pin ? { pin: icon.image.pin.map(round), pinSize: icon.image.pinSize } : icon.image, scale: round(icon.scale ?? 1), color: (icon.color ?? [1, 1, 1, 1]).map(round), offset: (icon.offsetPx ?? [0, 0]).map(round), rotation: round(icon.rotation ?? 0), subRegion: icon.subRegion, size: [icon.widthPx, icon.heightPx], })), lines: records.lines.map(({ name, positions, ground, color, widthPx }) => ({ name, positions: positions.map((p) => ground ? roundPosition(p).slice(0, 2) : roundPosition(p), ), ground, color: color.map(round), width: widthPx, })), polygons: records.polygons.map( ({ name, rings, raised, fill, outline }) => ({ name, rings: rings.map((ring) => ring.map((p) => raised ? roundPosition(p) : roundPosition(p).slice(0, 2), ), ), raised, fill: fill && fill.map(round), outline: outline && { color: outline.color.map(round), widthPx: outline.widthPx, }, }), ), overlays: records.overlays.map( ({ rectangle: r, url, color, rotation }) => ({ rectangle: [r.west, r.south, r.east, r.north].map(round), url, // Cesium's transparent image material caps the alpha at 0.99, as the // display's imagery alpha does. color: (url ? [...color.slice(0, 3), Math.min(0.99, color[3])] : color ).map(round), rotation: round(rotation), }), ), walls: records.undrawn.wall ?? 0, }; } for (const [name, text] of [ ['the QA file', QA], ['styles, altitudes, multigeometries and overlays', STYLED], ['shared styles with inline overrides, named and paired', SHARED], ]) { test(`KML records match Cesium's reading: ${name}`, async () => { const cesium = await cesiumReading(text); const ours = ourReading(text); assert.deepEqual(ours.points, cesium.points); // Cesium draws a wall's outline where the reader draws its top edge as // a line; every other line is the same. assert.deepEqual( ours.lines.filter((line) => line.name !== 'wall'), cesium.lines, ); assert.equal(ours.walls, cesium.walls); assert.deepEqual(ours.polygons, cesium.polygons); assert.deepEqual(ours.overlays, cesium.overlays); }); } test('the QA file reads to pins, ground lines and a packed overlay, with nothing remote', () => { const records = readKmlRecords(prepared(QA)); assert.deepEqual( records.points.map(({ name, icon }) => [name, Boolean(icon.image.pin)]), [ ['QA KML pin', false], // A blocked palette icon falls back to Cesium's yellow pin. ['QA palette pin', true], ], ); assert.deepEqual( records.lines.map(({ name, ground, positions }) => [ name, ground, positions.length, ]), [ ['QA moving', true, 2], ['QA split tracks', true, 2], ['QA split tracks', true, 2], ['QA remote style', true, 2], ], ); assert.equal(records.overlays.length, 1); assert.ok(!JSON.stringify(records).includes(TRAP)); // No time survives: a dated placemark draws for all time. assert.ok(!/2019/.test(JSON.stringify(records))); }); test('extruded polygons and quads are counted as undrawn', () => { const records = readKmlRecords( prepared( kml(`1absolute 0,0,9 1,0,9 1,1,9 0,0,9 ${PNG}0,0 1,0 1,1 0,1`), ), ); assert.deepEqual(records.undrawn, { extruded: 1, latLonQuad: 1 }); assert.equal(records.polygons[0].raised, true); }); test('KML colours are aabbggrr; a random colour stays within its channels', () => { assert.deepEqual(kmlColor('7f00ff00'), [0, 1, 0, 127 / 255]); assert.equal(kmlColor(' '), undefined); const [red, green, blue, alpha] = kmlColor('ff0000ff', true); assert.ok(red >= 0 && red <= 1 && green === 0 && blue === 0 && alpha === 1); }); test('a KML file loads to records with its name, count and outside content removed', async () => { const loaded = await loadGeoFile(new File([QA], 'remote-bits.kml')); assert.equal(loaded.format, 'kml'); assert.equal(loaded.entityCount, 7); assert.ok(loaded.removed > 0); assert.equal(loaded.records.points[0].name, 'QA KML pin'); loaded.revoke(); }); test('GroundOverlay retains altitude and altitude mode for drawing diagnostics', () => { const records = readKmlRecords( parseXml( kml( `1000absolute0101`, ), ), ); assert.equal(records.overlays[0].altitude, 1000); assert.equal(records.overlays[0].altitudeMode, 'absolute'); }); test('GroundOverlay keeps drawOrder, including negatives and the default', () => { const records = readKmlRecords( prepared( kml( [10, -2, null, 10] .map( (order) => ` ${order === null ? '' : `${order}`} 0101 `, ) .join(''), ), ), ); assert.deepEqual( records.overlays.map((overlay) => overlay.drawOrder), [10, -2, 0, 10], ); }); test('KML polygons discard degenerate holes and retain valid ones', () => { const records = readKmlRecords( prepared( kml(` 0,0 2,0 2,2 0,2 0,0 1,1 1.1,1.1 1,1 1,1 1.1,1.1 1,1 1.1,1.1 0.5,0.5 0.6,0.5 0.6,0.6 0.5,0.5 `), ), ); assert.equal(records.polygons[0].rings.length, 2); assert.deepEqual(records.polygons[0].rings[1][0], [0.5, 0.5, 0]); });