Scale, fade and show icons by eye distance

Cesium icon sets now draw an item's scaleByDistance, fadeByDistance and
displayRange, as point sets already draw their curves, and drop them again
when a restyle in place leaves them out. An empty display range shows the
icon nowhere; a curve whose far end is not past its near one is left out
rather than refused mid-update. Cesium eases between a curve's ends rather
than interpolating linearly, as it always has for points.

The reference renderer now scales an item's pick size by its distance curve
and leaves out items faded or scaled to nothing, and the draw.icons.distance
conformance check covers all three fields.
This commit is contained in:
Sameh Khamis committed 2026-11-06 22:25:07 -08:00
1 parent 1aa280b43f
commit ee6b9e49aa
5 files changed
+147 -6

No files matched your search

+25 -3
View File
@@ -70,9 +70,15 @@ const classificationOf = (clampTo = 'both') =>
tiles: Cesium.ClassificationType.CESIUM_3D_TILE, tiles: Cesium.ClassificationType.CESIUM_3D_TILE,
})[clampTo] ?? Cesium.ClassificationType.BOTH; })[clampTo] ?? Cesium.ClassificationType.BOTH;
/** A distance curve as Cesium's, or undefined. */ /**
* A distance curve as Cesium's, or undefined. Cesium's curves hold the same
* end values but ease between them (not linearly, as the contract's do):
* points and icons draw them as Cesium's own entities always have. A curve
* whose far end is not past its near one is left out.
*/
const nearFarOf = (curve) => const nearFarOf = (curve) =>
curve // One that ends where it starts is no curve, which Cesium refuses.
curve && curve.far > curve.near
? new Cesium.NearFarScalar( ? new Cesium.NearFarScalar(
curve.near, curve.near,
curve.nearValue, curve.nearValue,
@@ -81,6 +87,18 @@ const nearFarOf = (curve) =>
) )
: undefined; : undefined;
/** Whether a `displayRange` shows anything: `[near, far)` is not empty. */
const displayable = (range) => !range || range[1] > range[0];
/**
* A `displayRange` as Cesium's, or undefined for none (or an empty one).
* Cesium still shows an item at exactly its far distance.
*/
const displayConditionOf = (range) =>
range && displayable(range)
? new Cesium.DistanceDisplayCondition(range[0], range[1])
: undefined;
/** Cesium's point blending for a set's `blend`. */ /** Cesium's point blending for a set's `blend`. */
const pointBlendOf = (blend) => const pointBlendOf = (blend) =>
({ ({
@@ -445,7 +463,11 @@ export function createCesiumDraw({ scene, report }) {
verticalOrigin: ANCHORS[item.anchor ?? 'center'], verticalOrigin: ANCHORS[item.anchor ?? 'center'],
disableDepthTestDistance: item.disableDepthTest ?? 0, disableDepthTestDistance: item.disableDepthTest ?? 0,
heightReference: heightReferenceOf(item.height, record.spec.clampTo), heightReference: heightReferenceOf(item.height, record.spec.clampTo),
show: item.show !== false, // An empty range shows it nowhere.
show: item.show !== false && displayable(item.displayRange),
scaleByDistance: nearFarOf(item.scaleByDistance),
translucencyByDistance: nearFarOf(item.fadeByDistance),
distanceDisplayCondition: displayConditionOf(item.displayRange),
// The defaults, so a restyle in place puts back what an item dropped. // The defaults, so a restyle in place puts back what an item dropped.
rotation: 0, rotation: 0,
alignedAxis: Cesium.Cartesian3.ZERO, alignedAxis: Cesium.Cartesian3.ZERO,
+54
View File
@@ -1399,3 +1399,57 @@ test('an icon set is built anew where changing it in place would draw out of ord
assert.equal(scene.added[0].length, 0); assert.equal(scene.added[0].length, 0);
set.dispose(); set.dispose();
}); });
test('icons scale, fade and show by eye distance, and drop the curves in place', () => {
const scene = fakeScene();
const part = createCesiumDraw({
scene,
report: (error) => assert.fail(error),
});
const set = part.port.icons({ id: 'icons:distance' });
const icon = (extra = {}) => ({
id: 'a',
pos: { lon: 0, lat: 0 },
image: 'a.png',
size: [8, 8],
...extra,
});
set.set([
icon({
scaleByDistance: { near: 1e3, nearValue: 1.5, far: 1e6, farValue: 0.5 },
fadeByDistance: { near: 2e3, nearValue: 1, far: 2e6, farValue: 0 },
displayRange: [10, 5e6],
}),
]);
const [host] = scene.added;
const a = host.get(0);
assert.ok(
Cesium.NearFarScalar.equals(
a.scaleByDistance,
new Cesium.NearFarScalar(1e3, 1.5, 1e6, 0.5),
),
);
assert.ok(
Cesium.NearFarScalar.equals(
a.translucencyByDistance,
new Cesium.NearFarScalar(2e3, 1, 2e6, 0),
),
);
assert.equal(a.distanceDisplayCondition.near, 10);
assert.equal(a.distanceDisplayCondition.far, 5e6);
set.upsert([icon()]);
assert.equal(host.get(0), a, 'changed in place');
assert.equal(a.scaleByDistance, undefined);
assert.equal(a.translucencyByDistance, undefined);
assert.equal(a.distanceDisplayCondition, undefined);
set.upsert([
icon({
scaleByDistance: { near: 5, nearValue: 1, far: 5, farValue: 2 },
}),
]);
assert.equal(a.scaleByDistance, undefined, 'no curve: left out');
set.upsert([icon({ displayRange: [100, 100] })]);
assert.equal(a.show, false, 'an empty range shows it nowhere');
set.dispose();
});
+1
View File
@@ -36,6 +36,7 @@ export const CESIUM_CHECKS = new Set([
'draw.atlas', 'draw.atlas',
'draw.clampState', 'draw.clampState',
'draw.drillPick', 'draw.drillPick',
'draw.icons.distance',
'draw.icons.update', 'draw.icons.update',
'draw.ids', 'draw.ids',
'draw.models', 'draw.models',
+45
View File
@@ -1221,6 +1221,51 @@ export function portChecks() {
set.dispose(); set.dispose();
}, },
), ),
check(
'draw.icons.distance',
'icons scale, fade and show by eye distance',
async (h, r) => {
await overAustin(h, r);
const set = r.draw.icons({ id: 'conf:icons-distance' });
const pos = h.toEcef({ ...AUSTIN, height: 0 });
const icon = (extra = {}) => ({
id: 'one',
pos,
image: DOT,
size: [16, 16],
...extra,
});
set.set([icon()]);
await drawn(h, r);
await settled(r);
const s = r.query.project(pos);
ok(s, 'the icon projects');
const at = (dx) => r.query.pick(s.x + dx, s.y);
const mine = (hit) => hit?.set === 'conf:icons-distance';
ok(mine(at(0)) && !mine(at(20)), 'drawn at its size');
// The eye is 2 km off: held at the curve's near value.
const curve = (value) => ({
near: 1e4,
nearValue: value,
far: 1e7,
farValue: value,
});
set.upsert([icon({ scaleByDistance: curve(4) })]);
await drawn(h, r);
await settled(r);
ok(mine(at(20)), 'scaled up by distance: picked 20 px off');
set.upsert([icon({ fadeByDistance: curve(0) })]);
await drawn(h, r);
ok(!mine(at(0)), 'faded out by distance: not drawn');
set.upsert([icon({ displayRange: [0, 100] })]);
await drawn(h, r);
ok(!mine(at(0)), 'out of its display range: not drawn');
set.upsert([icon({ displayRange: [0, 1e6] })]);
await drawn(h, r);
ok(mine(at(0)), 'in its display range: drawn');
set.dispose();
},
),
check( check(
'draw.columns', 'draw.columns',
'column updates are rows: sized, picked, removed', 'column updates are rows: sized, picked, removed',
+22 -3
View File
@@ -65,6 +65,14 @@ const KNOBS = Object.freeze([
{ key: 'targetFps', kind: 'number', min: 0, max: 240, default: 0, cost: 0.2 }, { key: 'targetFps', kind: 'number', min: 0, max: 240, default: 0, cost: 0.2 },
]); ]);
/** A distance curve's value at `distance`: held past each end. */
function nearFarValue(curve, distance) {
if (distance <= curve.near) return curve.nearValue;
if (distance >= curve.far) return curve.farValue;
const t = (distance - curve.near) / (curve.far - curve.near);
return curve.nearValue + (curve.farValue - curve.nearValue) * t;
}
function uncaught(error) { function uncaught(error) {
if (typeof globalThis.reportError === 'function') if (typeof globalThis.reportError === 'function')
globalThis.reportError(error); globalThis.reportError(error);
@@ -562,20 +570,31 @@ export function createStubRenderer(options = {}) {
if (item.show === false || item.pickable === false) continue; if (item.show === false || item.pickable === false) continue;
const p = itemPosition(set, item); const p = itemPosition(set, item);
if (!p || isOccluded(p)) continue; if (!p || isOccluded(p)) continue;
if (item.displayRange) {
const distance = magnitude(sub(p, eye().position)); const distance = magnitude(sub(p, eye().position));
if (item.displayRange) {
const [nearM, farM] = item.displayRange; const [nearM, farM] = item.displayRange;
if (distance < nearM || distance >= farM) continue; if (distance < nearM || distance >= farM) continue;
} }
// Faded out entirely, it is not drawn.
if (
item.fadeByDistance &&
nearFarValue(item.fadeByDistance, distance) <= 0
)
continue;
const s = project(p); const s = project(p);
if (!s) continue; if (!s) continue;
const pixel = item.pixelSize ?? item.marker?.pixelSize ?? 10; const pixel = item.pixelSize ?? item.marker?.pixelSize ?? 10;
const size = item.pickProxy?.size ?? const size = item.pickProxy?.size ??
item.size ?? item.size ??
item.marker?.size ?? [pixel, pixel]; item.marker?.size ?? [pixel, pixel];
const scale = item.scaleByDistance
? nearFarValue(item.scaleByDistance, distance)
: 1;
// Scaled to nothing, it is not drawn.
if (scale <= 0) continue;
if ( if (
Math.abs(s.x - x) <= size[0] / 2 + halfW && Math.abs(s.x - x) <= (size[0] * scale) / 2 + halfW &&
Math.abs(s.y - y) <= size[1] / 2 + halfH Math.abs(s.y - y) <= (size[1] * scale) / 2 + halfH
) )
hits.push({ hits.push({
set: setId, set: setId,