// 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]);
});