Keep bounded imagery off Cesium's base layer and pins on drawn 3D tiles

Cesium treats the first imagery layer shown on the globe as its base
layer and stretches that layer's edge texels over the whole globe. With
no base map under it, a KMZ ground overlay turned the whole globe its
edge colour. The Cesium imagery adapter now keeps a floor under an
engine layer that covers less than the globe (a bounded rectangle, or
Web Mercator tiles, which stop at ±85.05°) whenever that layer would
otherwise be the base layer. The floor is one transparent pixel over the
globe at alpha 0, so Cesium draws nothing of it. It is placed when the
adapter adds or changes a layer, and again at each scene preUpdate,
before Cesium picks the base layer. When base imagery lies under the
layer, which is the app's normal state, there is no floor. A bounded
layer now draws only inside its rectangle, as the contract says.

When the globe is not the drawn surface, the import display now clamps
ground pins to the drawn scene, as Cesium's import did whenever the
globe was hidden. Before, it did this only for the map's own 3D tiles.
Each height query now leaves out the point sets of every imported file
on the engine, not only the file's own sets: Cesium's import kept all
imported pins out of height queries, so a higher pin from another file
never became the ground. The display also gives a footprint with its
points at the heights they are drawn at, and flying to a file frames
pins on raised tiles as Cesium did. Cesium's import clamped visible pins
with clampToHeightMostDetailed, which loads the finest tiles. The
display samples the tiles drawn now and samples them again after the
camera stops and while tiles load.

The KML reader's parity test against KmlDataSource now includes the
large-file QA's style case: a shared style with point, line and polygon
parts, inline overrides of each part, and named styles and an inline
StyleMap pair that are alike. The reader matches Cesium there.

QA scripts:
- qa-geo-import moves the camera over the files before it reads which
  pins show. Ground pins are hidden only beyond the horizon.
- qa-geo-import-large compares clamped pins by longitude and latitude.
  Cesium keeps a clamped billboard at its file height, while the import
  draws its pins on the sampled ground.
- qa-geo-import-regressions gives its 3D-tiles fixture a non-zero
  tileset geometricError, because Cesium never draws a tileset whose own
  error is 0. Its XYZ check now waits for the import to sample the ground
  again once the globe's tiles have loaded.

Known differences that remain: a KMZ ground overlay is now imagery, so
ground fills draw over it where the old ground rectangle drew over them;
right after an import on ellipsoid terrain, pins can sit on the coarse
globe mesh until the ground is sampled again.

The full unit suite and the boundary, format and coupling checks pass.
In the browser, keyless: qa-geo-import, qa-geo-import-large and
qa-navara-geo-import pass; qa-geo-import-regressions fails only its
portrait-flight check, which also fails before the refactor.
This commit is contained in:
German Khokhlov committed 2026-11-07 14:11:03 +04:00
1 parent f4b83a3a31
commit 910d693b94
12 files changed
+390 -61

No files matched your search

+37 -7
View File
@@ -13,11 +13,15 @@
// ignored the depth test;
// - ground overlays: one image imagery layer each over its rectangle.
// Nothing is pickable: an imported file has no card. Ground heights under
// the points come from engine.surface, sampled again by refreshGround().
// the points come from engine.surface, sampled again by refreshGround():
// the terrain where the globe is drawn, else (3D tiles) the scene drawn
// under a low camera, never an imported point (as Cesium's import kept its
// pins out of height queries).
import * as geo from '../geo/index.js';
import { normalizeGroundItem } from '../globe/ground.js';
import { composeIcon } from './geoImportPins.js';
import { recordFootprint } from './geoImportRecords.js';
const POLYGON_ORDER = 0;
const LINE_ORDER = 1;
@@ -31,6 +35,13 @@ const HORIZON_LIFT_M = 2000;
const CLAMP_TILES_BELOW_M = 250_000;
const BATCH = 256;
let serial = 0;
// Each engine's imported point sets, left out of each other's ground.
const pointSets = new WeakMap();
const pointSetsOf = (engine) => {
let sets = pointSets.get(engine);
if (!sets) pointSets.set(engine, (sets = new Set()));
return sets;
};
const imageFromUrl = async (url) => {
const image = new Image();
@@ -79,6 +90,7 @@ const lookKey = (icon, depth) =>
* @returns {Promise<{ report: { drawn: number, undrawn: number,
* kinds: Object<string, number> }, setShow: (visible: boolean) => void,
* refreshGround: (signal?: AbortSignal) => Promise<void>,
* footprint: () => Array<[number, number, number]>,
* destroy: () => void }>}
*/
export async function drawImportedFile(
@@ -111,7 +123,10 @@ export async function drawImportedFile(
for (const set of groundSets.splice(0)) set.destroy();
for (const line of lines.splice(0)) line.destroy();
for (const layer of layers.splice(0)) layer.destroy();
for (const look of looks.values()) look.set?.destroy();
for (const look of looks.values()) {
pointSetsOf(engine).delete(look.set);
look.set?.destroy();
}
looks.clear();
}
@@ -281,6 +296,7 @@ export async function drawImportedFile(
: {}),
},
});
pointSetsOf(engine).add(look.set);
drawn += look.pins.length;
}),
);
@@ -294,16 +310,15 @@ export async function drawImportedFile(
}
request();
// Where heights come from now: the terrain, or the 3D tiles under a low
// camera when they are the drawn surface.
// Where heights come from now: the terrain, or the scene drawn under a
// low camera when the globe is not (3D tiles).
function heightContext() {
const surface = engine.surface;
const tiles =
engine.imagery?.surface?.() === 'tiles' &&
(engine.imagery?.surface?.() ?? 'globe') !== 'globe' &&
surface.clampToHeightSupported &&
engine.camera.height() < CLAMP_TILES_BELOW_M;
const exclude = [...looks.values()].map((look) => look.set).filter(Boolean);
return { surface, tiles, exclude };
return { surface, tiles, exclude: [...pointSetsOf(engine)] };
}
// The ground under a pin, falling back to the last known one.
@@ -414,6 +429,21 @@ export async function drawImportedFile(
syncCull();
request();
},
/**
* What the file covers (recordFootprint), its points at the heights
* they draw at: on the ground sampled under them.
*/
footprint() {
const out = recordFootprint({ ...records, points: [] });
for (const look of looks.values())
for (const pin of look.pins)
out.push([
pin.lon,
pin.lat,
pin.height ?? (pin.ground ?? 0) + pin.offset,
]);
return out;
},
/** Sample the ground under the points again (a map or the terrain changed). */
async refreshGround(signal) {
const total = [...looks.values()].reduce((n, l) => n + l.pins.length, 0);
+50
View File
@@ -182,6 +182,56 @@ for (const make of GROUND_HARNESSES) {
},
);
displayTest(
'off the globe, ground pins sit on the scene drawn, never on an imported point',
async ({ engine, viewer, pins }) => {
// 3D tiles under a low camera: the globe is not drawn.
if (viewer) {
viewer.scene.globe.show = false;
viewer.scene.clampToHeightSupported = true;
} else engine.imagery.surface = () => 'tiles';
engine.camera.height = () => 1000;
const excluded = [];
engine.surface.clampToHeight = (position, exclude) => {
excluded.push(exclude);
const at = geo.cartographic.fromCartesian(position);
return geo.cartesian3.fromRadians(at.longitude, at.latitude, 2000);
};
const ground = await drawImportedFile(
engine,
geoJsonRecords({ type: 'Point', coordinates: [1, 2] }, '#39d0ff'),
{ createCanvas },
);
const raised = geoJsonRecords(
{ type: 'Point', coordinates: [1, 2, 5000] },
'#39d0ff',
);
raised.points[0].altitude = 'absolute';
const high = await drawImportedFile(engine, raised, { createCanvas });
const height = () =>
Math.round(
geo.cartographic.fromCartesian(pins[0].items[0].position).height,
);
assert.equal(height(), 2000);
assert.deepEqual(
ground.footprint().map((p) => p.map(Math.round)),
[[1, 2, 2000]],
'a flight frames the pin where it draws',
);
await ground.refreshGround();
assert.equal(height(), 2000);
assert.deepEqual(
new Set(excluded.at(-1)),
new Set(pins.map(({ set }) => set)),
"another file's point is not ground",
);
high.destroy();
await ground.refreshGround();
assert.deepEqual(excluded.at(-1), [pins[0].set]);
ground.destroy();
},
);
displayTest(
'fills keep holes, raised outlines and plain overlays',
async ({ engine, set }) => {
+24
View File
@@ -108,6 +108,29 @@ const STYLED = kml(`
<Placemark><name>deduplicated a</name><styleUrl>#a</styleUrl><LineString><coordinates>3,3 4,4</coordinates></LineString></Placemark>
<Placemark><name>deduplicated b</name><styleUrl>#b</styleUrl><LineString><coordinates>4,4 5,5</coordinates></LineString></Placemark>`);
// 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(`
<Style id="base"><IconStyle><heading>25</heading><scale>1.2</scale></IconStyle>
<LineStyle><color>ffdd6600</color><width>7</width></LineStyle>
<PolyStyle><color>6600ddff</color><fill>1</fill><outline>0</outline></PolyStyle></Style>
<Placemark><name>shared point</name><styleUrl>#base</styleUrl>
<Style><IconStyle><scale>0.6</scale><color>ff00dd66</color></IconStyle></Style>
<Point><coordinates>-122.49,37.77,0</coordinates></Point></Placemark>
<Placemark><name>shared line</name><styleUrl>#base</styleUrl>
<Style><LineStyle><width>3</width></LineStyle></Style>
<LineString><coordinates>-122.50,37.77,0 -122.49,37.77,0</coordinates></LineString></Placemark>
<Placemark><name>shared polygon</name><styleUrl>#base</styleUrl>
<Style><PolyStyle><outline>1</outline></PolyStyle></Style>
<Polygon><outerBoundaryIs><LinearRing><coordinates>-122.50,37.77,0 -122.49,37.77,0 -122.49,37.78,0 -122.50,37.77,0</coordinates></LinearRing></outerBoundaryIs></Polygon></Placemark>
<Style id="named-a"><IconStyle><scale>0.8</scale></IconStyle></Style>
<Style id="named-b"><IconStyle><scale>0.8</scale></IconStyle></Style>
<StyleMap id="paired"><Pair><key>normal</key><Style><IconStyle><scale>0.8</scale></IconStyle></Style></Pair></StyleMap>
<Placemark><name>named-a</name><styleUrl>#named-a</styleUrl><Point><coordinates>-122.49,37.77,0</coordinates></Point></Placemark>
<Placemark><name>named-b</name><styleUrl>#named-b</styleUrl><Point><coordinates>-122.49,37.77,0</coordinates></Point></Placemark>
<Placemark><name>paired</name><styleUrl>#paired</styleUrl><Point><coordinates>-122.49,37.77,0</coordinates></Point></Placemark>`);
/** A document as the import prepares it for reading. */
function prepared(text) {
const doc = parseXml(text, 'KML');
@@ -303,6 +326,7 @@ function ourReading(text) {
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);