feat(render): an icon's offset may scale with it, and an axis-turned icon turns by its rotation too

The contract gains offsetScalesByDistance: the pixel offset grows and
shrinks with scaleByDistance, as Cesium's pixelOffsetScaleByDistance does
with the same curve. rotationMode 'axis' now also turns by rotation, as a
Cesium billboard with an aligned axis and a rotation does. Cesium draws
both on its billboards; its GPU icons take the rotation and refuse a
scaled offset; the stub picks both. New conformance check
draw.icons.offsetTurn.
This commit is contained in:
Sameh Khamis committed 2026-11-14 02:03:26 -08:00
1 parent c99c577b3e
commit 7ba15deb5e
6 files changed
+113 -12

No files matched your search

+10 -2
View File
@@ -1356,6 +1356,10 @@ export function createCesiumDraw({
// An empty range shows it nowhere.
show: item.show !== false && displayable(item.displayRange),
scaleByDistance: nearFarOf(item.scaleByDistance),
// Its offset shrinks with it, as Cesium's KML icons' did.
pixelOffsetScaleByDistance: item.offsetScalesByDistance
? nearFarOf(item.scaleByDistance)
: undefined,
translucencyByDistance: nearFarOf(item.fadeByDistance),
distanceDisplayCondition: displayConditionOf(item.displayRange),
// The defaults, so a restyle in place puts back what an item dropped.
@@ -1367,9 +1371,11 @@ export function createCesiumDraw({
item.pixelOffset?.y ?? 0,
),
};
if (item.rotationMode === 'screen') look.rotation = item.rotation ?? 0;
if (item.rotationMode === 'screen' || item.rotationMode === 'axis')
look.rotation = item.rotation ?? 0;
// Its up turned along the axis on screen, as Cesium's own aligned
// billboards stand; an axis of zero length stands upright.
// billboards stand, then by its rotation; an axis of zero length stands
// upright.
if (item.rotationMode === 'axis' && item.alignedAxis) {
const { x = 0, y = 0, z = 0 } = item.alignedAxis;
const axis = new Cesium.Cartesian3(x, y, z);
@@ -1413,6 +1419,7 @@ export function createCesiumDraw({
show: item.show,
displayRange: item.displayRange ? [...item.displayRange] : undefined,
scaleByDistance: curve(item.scaleByDistance),
offsetScalesByDistance: item.offsetScalesByDistance,
fadeByDistance: curve(item.fadeByDistance),
rotationMode: item.rotationMode,
rotation: item.rotation,
@@ -1466,6 +1473,7 @@ export function createCesiumDraw({
style.show === item.show &&
sameList(style.displayRange, item.displayRange) &&
sameCurve(style.scaleByDistance, item.scaleByDistance) &&
style.offsetScalesByDistance === item.offsetScalesByDistance &&
sameCurve(style.fadeByDistance, item.fadeByDistance) &&
style.rotationMode === item.rotationMode &&
(item.rotationMode === 'screen' || style.rotation === item.rotation) &&
+7 -3
View File
@@ -240,6 +240,8 @@ export function createGpuIcons({
const refuse = (what) => {
throw new Error(`the Cesium renderer's GPU icons have no ${what}`);
};
if (item.offsetScalesByDistance && nonZero(item.pixelOffset))
refuse('pixel offsets scaled by distance');
// What a row reads from its extras texture, which WebGL 1 has not.
if (scene.context?.webgl2 === false) {
if (item.height !== undefined && item.height !== 'absolute')
@@ -447,10 +449,12 @@ export function createGpuIcons({
set.setAnchor(row, ANCHORS[item.anchor] ?? 0);
set.setRotation(
row,
item.rotationMode === 'screen' ? (item.rotation ?? 0) : 0,
item.rotationMode === 'screen' || item.rotationMode === 'axis'
? (item.rotation ?? 0)
: 0,
);
// Its up along the axis, as a billboard's; one of zero length
// stands upright.
// Its up along the axis, as a billboard's, then turned by its
// rotation; one of zero length stands upright.
const {
x = 0,
y = 0,
+1
View File
@@ -62,6 +62,7 @@ export const CESIUM_CHECKS = new Set([
'draw.icons.cluster',
'draw.icons.distance',
'draw.icons.images',
'draw.icons.offsetTurn',
'draw.icons.update',
'draw.lines.depthFail',
'draw.lines.settled',
+76
View File
@@ -1981,6 +1981,82 @@ export function portChecks() {
set.dispose();
},
),
check(
'draw.icons.offsetTurn',
'an icon offset shrinks with it when it says so, and one turned by an axis turns by its rotation too',
async (h, r) => {
await overAustin(h, r);
const set = r.draw.icons({ id: 'conf:icons-offset-turn' });
const pos = h.toEcef({ ...AUSTIN, height: 0 });
const icon = (extra = {}) => ({
id: 'one',
pos,
image: DOT,
size: [16, 16],
...extra,
});
const show = async (extra) => {
set.set([icon(extra)]);
await drawn(h, r);
await settled(r);
await drawn(h, r);
};
await show();
const s = r.query.project(pos);
ok(s, 'the icon projects');
const mine = (x, y) =>
r.query
.drillPick(x, y)
.some(
(hit) => hit.set === 'conf:icons-offset-turn' && hit.id === 'one',
);
// The eye is 2 km off: held at the curve's near value, half size.
const half = { near: 1e4, nearValue: 0.5, far: 1e7, farValue: 0.5 };
const offset = { x: 40, y: 0 };
await show({ scaleByDistance: half, pixelOffset: offset });
ok(
mine(s.x + 40, s.y) && !mine(s.x + 20, s.y),
'halved by distance, its offset is not',
);
await show({
scaleByDistance: half,
pixelOffset: offset,
offsetScalesByDistance: true,
});
ok(
mine(s.x + 20, s.y) && !mine(s.x + 40, s.y),
'halved by distance with its offset',
);
// Looking north, an up along east turns it a quarter clockwise; a
// quarter turn counter-clockwise on screen lays it down again.
const east = h.toEcef({
lon: AUSTIN.lon + 0.01,
lat: AUSTIN.lat,
height: 0,
});
const alignedAxis = {
x: east.x - pos.x,
y: east.y - pos.y,
z: east.z - pos.z,
};
await show({ size: [64, 8], rotationMode: 'axis', alignedAxis });
ok(
mine(s.x, s.y + 24) && !mine(s.x + 24, s.y),
'its up along east stands it up',
);
await show({
size: [64, 8],
rotationMode: 'axis',
alignedAxis,
rotation: Math.PI / 2,
});
ok(
mine(s.x + 24, s.y) && !mine(s.x, s.y + 24),
'then a quarter turn on screen lays it down',
);
set.dispose();
},
),
check(
'draw.motion.look',
'moving icons draw offset, anchored, turned, clamped, faded and ranged as icons do',
+9 -2
View File
@@ -192,14 +192,21 @@ export interface IconItem extends Placed {
/**
* `screen`: upright on screen, rotated by `rotation`;
* `course`: rotated on screen along `course` (or the motion's course);
* `axis`: rotated about `alignedAxis`.
* `axis`: its up along `alignedAxis` as projected on screen, then
* rotated by `rotation`.
*/
rotationMode?: 'screen' | 'course' | 'axis';
/** Radians counter-clockwise on screen, for `rotationMode: 'screen'`. */
/**
* Radians counter-clockwise on screen, for `rotationMode: 'screen'` and
* `'axis'`.
*/
rotation?: number;
/** ECEF axis for `rotationMode: 'axis'`. */
alignedAxis?: Vec3;
/** CSS pixels, y down. */
pixelOffset?: ScreenXY;
/** `pixelOffset` grows and shrinks with `scaleByDistance`, as the icon does. */
offsetScalesByDistance?: boolean;
anchor?: 'center' | 'bottom' | 'top';
/** Swap to `near` when drawn larger than `switchPx`. */
imageLod?: { near: ImageRef; switchPx: number };
+10 -5
View File
@@ -1146,15 +1146,20 @@ export function createStubRenderer(options = {}) {
let dy = y - cy;
if (set.kind === 'icons') {
const lift = { bottom: 1, top: -1 }[item.anchor] ?? 0;
cx += item.pixelOffset?.x ?? 0;
// Its offset shrinks with it when it says so.
const offsetScale = item.offsetScalesByDistance ? scale : 1;
cx += (item.pixelOffset?.x ?? 0) * offsetScale;
cy +=
(item.pixelOffset?.y ?? 0) -
(item.pixelOffset?.y ?? 0) * offsetScale -
(lift * (item.size?.[1] ?? 0) * scale) / 2;
dx = x - cx;
dy = y - cy;
// Turned counter-clockwise on screen (its up along the axis
// as projected there): the pick turned back.
let turn = item.rotationMode === 'screen' ? (item.rotation ?? 0) : 0;
// as projected there, then by its rotation): the pick turned back.
let turn =
item.rotationMode === 'screen' || item.rotationMode === 'axis'
? (item.rotation ?? 0)
: 0;
const axis = item.rotationMode === 'axis' ? item.alignedAxis : null;
if (
axis &&
@@ -1164,7 +1169,7 @@ export function createStubRenderer(options = {}) {
add(p, normalize(vec(axis.x ?? 0, axis.y ?? 0, axis.z ?? 0))),
);
if (tip && (tip.x !== s.x || tip.y !== s.y))
turn = Math.atan2(-(tip.x - s.x), -(tip.y - s.y));
turn += Math.atan2(-(tip.x - s.x), -(tip.y - s.y));
}
if (turn !== 0) {
const c = Math.cos(turn);