From 7ba15deb5e46c43a577291b9bafe80b7f53f9753 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 14 Nov 2026 02:03:26 -0800 Subject: [PATCH] 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. --- src/render/cesium/draw.js | 12 +++- src/render/cesium/gpuIcons.js | 10 +++- src/render/cesium/harness.js | 1 + src/render/conformance/checks/ports.js | 76 ++++++++++++++++++++++++++ src/render/contract/draw.d.ts | 11 +++- src/render/stub/index.js | 15 +++-- 6 files changed, 113 insertions(+), 12 deletions(-) diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index c8384a864..39a008369 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -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) && diff --git a/src/render/cesium/gpuIcons.js b/src/render/cesium/gpuIcons.js index 53289ff9b..fd4af1f80 100644 --- a/src/render/cesium/gpuIcons.js +++ b/src/render/cesium/gpuIcons.js @@ -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, diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index a14cfd05e..30b3b7c89 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -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', diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index b0ef99b5f..69ac29764 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -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', diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index c9f414ef6..2c85d2fec 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -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 }; diff --git a/src/render/stub/index.js b/src/render/stub/index.js index eee2d54d0..8a852e36d 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -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);