diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 26928eae2..ed549dd71 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -5658,7 +5658,7 @@ request viewbox and continues searching without that geographic preference. - UTILITIES ▸ **Draw** turns the globe into a whiteboard drawn by hand. Pick a shape (icon buttons for Area, Line and Pin) and a colour swatch for the next shape, click the vertices on the real world, and finish. **Keyboard contract, live only while Draw is on and never while you are typing in another field:** Enter finishes the shape (as does a double-click, and the two cannot both submit it — the session is replaced before the annotate call is awaited); Backspace removes the last vertex; Esc cancels the shape in progress, and a second Esc — Esc on an empty session — leaves draw mode. **Clear** wipes the board (the shape in progress and every placed mark), so removing marks does not require the console or the microphone. - **Drawn shapes are listed under Draw like Import's files** (`src/ui/views/panels/DrawMarkList.vue`, rows worded by `presentDrawMarks` in `src/annotations/drawMarks.js`): one row per hand-drawn mark (`manual: true`; voice marks are not listed) with its colour swatch, its name, and show/hide, fly-to and remove. The draw tool publishes the rows with the rest of its controls and answers the row actions (`renameDrawMark`, `recolorDrawMark`, `toggleDrawMark`, `flyToDrawMark`, `removeDrawMark`) through the display store; it republishes on the engine's `onChange`, so a voice clear or an expiry updates the list. Rows are keyed and updated in place: a board change never takes a name being typed (the field keeps its draft while focused) or the button under a click. The name is saved on Enter or on leaving the field, once; Esc restores it, before anything else and with the row's colours open too. Both keep focus in the field, so neither drops it to the page or leaves Draw. The swatch opens the five colours right after it (shown at the end of the row), with the current colour focused; the arrows, Home and End try another, and a click or Esc closes them and returns focus to the swatch. Both colour groups (the next shape's and a row's) are one `DrawSwatches` radio group with a single tab stop, coloured from `DRAW_COLOR_CSS`; on touch screens each dot answers a 24 px target. An unnamed shape shows its kind, and an unnamed line its length; a renamed line keeps its length (`Ridge walk — 950 m`). **Hidden** keeps a mark on the board at alpha 0, and the world renderer takes every one of its entities out (`show = false`), so no material that keeps its own colour (the line's flowing stroke) still paints it; the screen renderer does not project a hidden callout, so it cannot push a visible label aside; `fly_route` skips a hidden route; and with every mark hidden the annotations render hold is released. **Fly to** is an immediate navigation (`runImmediateNavigation('drawing', …)`), like Import's: Cockpit refuses it and a running orbit, follow or track lets go first. A line is framed by its whole path, across the antimeridian too. -- Runtime entry: `createApplicationTools` (`src/app/tools.js`, behind the `src/standalone/tools.js` shim) calls `initDrawTool({ viewer, annotations, navigation, publish, connect })` after `initAnnotations` and defers its `destroy()`, so disposing the shell returns every DOM listener, the pointer subscriptions, the preview draw sets, the borrowed click actions and the `window.__gevDrawTool` handle. The live preview (a dashed rubber band and a dot per vertex) is two sets on the renderer's draw port, so the tool no longer reaches Cesium; the rubber band follows each move's `pickPosition`, the dispatcher's sensor-corrected pick-buffer point, as clicks do. Its controls are Vue views in the UTILITIES panel (`DrawControls.vue`, `DrawMarkList.vue`) that render what the tool publishes to the display store and call its actions. That handle (`setActive`, `setShape`, `addVertex(lon, lat)`, `finish`, `cancel`, `clearAll`, `marks`, `setColor`, `diagnostics`) is the no-mouse test seam. +- Runtime entry: `createApplicationTools` (`src/app/tools.js`, behind the `src/standalone/tools.js` shim) calls `initDrawTool({ viewer, annotations, navigation, publish, connect })` after `initAnnotations` and defers its `destroy()`, so disposing the shell returns every DOM listener, the pointer subscriptions, the preview draw sets, the borrowed click actions and the `window.__gevDrawTool` handle. The live preview (a dashed rubber band, dashed behind the surface too through the line's `depthFailDash`, and a dot per vertex) is two sets on the renderer's draw port, so the tool no longer reaches Cesium; the rubber band follows each move's `pickPosition`, the dispatcher's sensor-corrected pick-buffer point, as clicks do. Its controls are Vue views in the UTILITIES panel (`DrawControls.vue`, `DrawMarkList.vue`) that render what the tool publishes to the display store and call its actions. That handle (`setActive`, `setShape`, `addVertex(lon, lat)`, `finish`, `cancel`, `clearAll`, `marks`, `setColor`, `diagnostics`) is the no-mouse test seam. - Contract: a finished shape is submitted through the SAME `annotationEngine.annotate()` the voice agent uses, with geometry supplied and `manual: true` (`type: area` + `ring`, `type: route` + `path`, `type: pin` + coordinates). `resolveSpec` short-circuits manual specs (`resolveManualSpec`) so no geocoder, Places or Overpass call is made. A drawn area is a real (not synthesized) outline and drapes solid; a drawn line is a `route` with `mode: 'manual'`, labelled with its length and never a travel time; a pin is a point. Drawn marks therefore render with the whiteboard look, persist, appear in `.list()`, and clear with `clear_annotations` / `.clear()`. A drawn shape is never merged with another as a duplicate: every one is drawn on purpose, and every one is unnamed until its row names it, so two pins dropped close together are two pins. - **A vertex is a lon/lat, and the mark is DRAPED.** Clicks are picked through `pickWorldFromScreen` — one of two scene helpers the annotation resolver factory (`src/annotations/resolver.js`) exposes alongside `sampleGroundHeight`, so the app has ONE depth-aware pick cascade rather than a second written beside it — which returns the height the pick landed on as well as the coordinate, so the live preview hangs on the roof or hillside under the pointer instead of sinking to sea level. The world renderer draws areas and routes with `clampToGround`, so the height is dropped at finish in one place (`finishSpec`) rather than being carried downstream and discarded silently: what you get is the outline you drew, lying on the surface beneath it. - **Draped marks classify onto `ClassificationType.BOTH`** — terrain AND 3D tiles — not onto 3D tiles alone. With only `CESIUM_3D_TILE`, every area fill, area outline, route and arrow rendered to nothing on a keyless boot, where Cesium's own globe carries Esri/OSM imagery and there are no tiles to classify against; the labels appeared and the geometry did not. That hit spoken annotations exactly as hard as hand-drawn ones. `scripts/qa-draw-tool.mjs` counts the mark's own colour in the rendered frame before and after a shape is finished, on a keyed AND a keyless server, so "the board says there is a mark" can no longer pass for "the mark is on screen". diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index aac2d9cb4..7afc09214 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -42,6 +42,9 @@ optional, so a renderer written before it still conforms: target's east-north-up frame, or the identity. `setView` keeps that frame while it places a world pose. A share link's follow offset is re-expressed in it, satellites included. +- A line item's `depthFailDash` (`{ length, pattern16? }`) dashes the parts + behind the surface in `depthFailColor`, as the Draw tool's rubber band is. + A renderer that predates it draws those parts solid. The renderer itself (`renderer.d.ts`) adds capture, pixel reads, settling, resize, context loss and `destroy`. `common.d.ts` holds the shared shapes diff --git a/src/annotations/drawTool.js b/src/annotations/drawTool.js index aaaa50171..488497c6e 100644 --- a/src/annotations/drawTool.js +++ b/src/annotations/drawTool.js @@ -184,7 +184,9 @@ export function initDrawTool({ color: withAlpha(cssColor(PREVIEW[color] || PREVIEW.primary), 0.9), length: 16, }, + // Dashed behind the surface too, as the band in front of it is. depthFailColor: withAlpha(cssColor(PREVIEW.primary), 0.35), + depthFailDash: { length: 16 }, }, ]); }; diff --git a/src/annotations/drawToolBehaviour.test.mjs b/src/annotations/drawToolBehaviour.test.mjs index b9d227ed5..ba6e66543 100644 --- a/src/annotations/drawToolBehaviour.test.mjs +++ b/src/annotations/drawToolBehaviour.test.mjs @@ -448,6 +448,7 @@ test('the rubber band follows the pointer, closes an area and takes the chosen c [139 / 255, 233 / 255, 1, 0.35], 'behind the surface it stays the primary colour, as before', ); + assert.deepEqual(band().depthFailDash, { length: 16 }, 'and dashed there'); assert.equal(band().style.kind, 'dash'); assert.equal(band().style.length, 16); assert.equal(band().widthPx, 3); diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 04a2a20ed..34f2d086e 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -1281,7 +1281,14 @@ export function createCesiumDraw({ depthFailAppearance: new Cesium.PolylineMaterialAppearance({ material: lineMaterial( record, - { kind: 'solid', color: item.depthFailColor }, + item.depthFailDash + ? { + kind: 'dash', + color: item.depthFailColor, + length: item.depthFailDash.length, + pattern16: item.depthFailDash.pattern16, + } + : { kind: 'solid', color: item.depthFailColor }, reveal, ), }), @@ -1488,6 +1495,10 @@ export function createCesiumDraw({ item.clampTo, item.style, item.depthFailColor, + // A dash is drawn only with a depth-fail colour, the same in any key order. + item.depthFailColor && item.depthFailDash + ? [item.depthFailDash.length, item.depthFailDash.pattern16] + : null, // Segment colours and shows change in place. item.segmentColors != null, item.segmentShow != null, diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 3adebd2b0..363f3c54d 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -2892,6 +2892,58 @@ test('a line with a depth-fail colour draws it behind the surface, and moves in assert.equal(scene.added.length, 0); })); +test('a depth-fail dash dashes the parts behind the surface, in the depth-fail colour', () => + withImageClasses(() => { + const { scene, draw } = drawOver(); + const set = draw.lines({ id: 'band' }); + const band = (extra = {}) => ({ + id: 'band', + positions: [ + Cesium.Cartesian3.fromDegrees(0, 0, 100), + Cesium.Cartesian3.fromDegrees(0.01, 0.01, 100), + ], + widthPx: 3, + mode: 'geodesic', + style: { kind: 'dash', color: [1, 1, 0, 0.9], length: 16 }, + depthFailColor: [0, 1, 1, 0.35], + depthFailDash: { length: 16 }, + ...extra, + }); + set.set([band()]); + const host = scene.added[0]; + const deep = host.get(1).get(0); + const hidden = deep.depthFailAppearance.material; + assert.equal(hidden.type, 'PolylineDash'); + assert.ok( + Cesium.Color.equals( + hidden.uniforms.color, + new Cesium.Color(0, 1, 1, 0.35), + ), + ); + assert.equal(hidden.uniforms.dashLength, 16); + assert.equal(hidden.uniforms.dashPattern, 255, 'the default pattern'); + // A move keeps the dash; its fields in another order are the same look. + set.upsert([band({ depthFailDash: { length: 16 } })]); + assert.equal(scene.added[0], host, 'not rebuilt'); + assert.equal( + host.get(1).get(0).depthFailAppearance.material.type, + 'PolylineDash', + ); + set.upsert([band({ depthFailDash: { pattern16: 0xf0f0, length: 8 } })]); + const patterned = scene.added[0].get(1).get(0).depthFailAppearance.material; + assert.equal(patterned.uniforms.dashPattern, 0xf0f0); + assert.equal(patterned.uniforms.dashLength, 8); + const again = scene.added[0]; + set.upsert([band({ depthFailDash: { length: 8, pattern16: 0xf0f0 } })]); + assert.equal(scene.added[0], again, 'the same dash in another order'); + // Without it the hidden parts are solid; the change is a new look. + set.upsert([band({ depthFailDash: undefined })]); + assert.notEqual(scene.added[0], host, 'rebuilt'); + const solid = scene.added[0].get(1).get(0).depthFailAppearance.material; + assert.equal(solid.type, 'Color'); + set.dispose(); + })); + test('a draped flow line still drawing while its rebuilds build keeps flowing', () => withImageClasses(() => { const { scene, draw, frame } = drawOver(); diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index a59debed3..f34b8cd21 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -41,6 +41,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.drillPick', 'draw.icons.distance', 'draw.icons.update', + 'draw.lines.depthFailDash', 'draw.lines.styles', 'draw.lines.drape', 'draw.lines.segments', diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index 4aeb08b22..6f83e8ae9 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -1348,6 +1348,36 @@ export function portChecks() { set.dispose(); }, ), + check( + 'draw.lines.depthFailDash', + 'a line dashed behind the surface draws, moves in place and changes back to solid', + async (h, r) => { + await overAustin(h, r); + const lines = r.draw.lines({ id: 'conf:line-dash' }); + const at = (dLon, height) => + h.toEcef({ lon: AUSTIN.lon + dLon, lat: AUSTIN.lat, height }); + const band = (height, extra = {}) => ({ + id: 'band', + positions: [at(-0.002, 50), at(0.002, height)], + widthPx: 3, + mode: 'geodesic', + style: { kind: 'dash', color: [1, 1, 0, 0.9], length: 16 }, + depthFailColor: [0, 1, 1, 0.35], + depthFailDash: { length: 16 }, + ...extra, + }); + lines.set([band(-200)]); + await drawn(h, r); + equal(lines.size(), 1, 'held'); + lines.upsert([band(-100)]); + await drawn(h, r); + equal(lines.size(), 1, 'moved in place, not added'); + lines.upsert([band(-100, { depthFailDash: undefined })]); + await drawn(h, r); + equal(lines.size(), 1, 'solid behind the surface again'); + lines.dispose(); + }, + ), check( 'draw.lines.styles', 'flow lines draw draped and in space, and a line with a depth-fail colour moves every frame, without stopping the frame or picks', diff --git a/src/render/contract/contract.test.mjs b/src/render/contract/contract.test.mjs index 015f191d8..12e7e09e1 100644 --- a/src/render/contract/contract.test.mjs +++ b/src/render/contract/contract.test.mjs @@ -178,6 +178,12 @@ test('members added to version 0 later are optional, each behind its capability' // A renderer written before an addition still conforms without it. assert.equal(PORTS.globe.isGlobeVisible, 'globeVisibility'); assert.equal(PORTS.camera.followFrame, 'followFrame'); + // Item fields added later are optional too. + const optional = (shape, field) => + Object.fromEntries( + members(checker.getTypeAtLocation(declared(shape).name)), + )[field]; + assert.equal(optional('LineItem', 'depthFailDash'), true); }); test('the shape check names what is missing and what a capability does not allow', () => { diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index 6700214ba..9aa52e5bb 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -229,6 +229,13 @@ export interface LineItem { style: LineStyle; /** Colour where the line is behind the surface; `null` hides those parts. */ depthFailColor?: Color | null; + /** + * Dash the parts behind the surface, in `depthFailColor`, as a `dash` + * style's `length` and `pattern16` dash a line. Omitted, they are solid; a + * renderer that predates it draws them solid too. Ignored without a + * `depthFailColor`, and on draped lines, which are never behind it. + */ + depthFailDash?: { length: number; pattern16?: number }; /** Per-segment colours; changing them does not rebuild the line. */ segmentColors?: Color[]; segmentShow?: boolean[];