feat(globe): dynamic lines on both engines

engine.lines.createLine({ id, widthPx, color, depthFailAlpha, dash
({ lengthPx, gapPx } | 'tactical'), arc ('none'|'geodesic'), modelMatrix,
pickId }) → a Line: setPositions (Cartesian3[] or a flat Float64Array),
setColor, setModelMatrix, show, destroy; lines.list() for QA. Options,
flat positions, geodesic densification (great circles of the geodetic
normals, height interpolated, one step per degree) and the registry are
engine-neutral (src/globe/lines.js); the fake engine keeps every line.

- Cesium: a Primitive of a PolylineGeometry (synchronous, rebuilt when
  the positions change) with a PolylineMaterialAppearance in an
  engine-owned collection; depthFailAlpha is depthFailAppearance with the
  alpha scaled; pixel dashes are PolylineDash (16-bit pattern); the
  tactical dash is the launches' selected-orbit shader under its own type
  (launches keep theirs until Task 15a moves them onto engine.lines).
- Navara: a public MeshDesc (transparent pass, unlit) holding a ribbon
  of one quad per segment, widened to CSS pixels in the vertex shader;
  a second copy drawn with GreaterDepth and the alpha scaled is the
  depth-fail part; dashes are cut in the fragment shader (pixels along
  the screen direction, or the tactical pattern over the fraction along
  the line); positions relative to the first point, the model matrix on
  the group. Geodesic arcs are densified on the CPU. Not pickable yet.
- The contract suite draws a three-point line on both engines: magenta
  along both segments, nothing off it, 1° east once turned by its model
  matrix, gone when hidden; a line 30 km under the ground shows only its
  depth-fail copy, dimmer than the line.

Main chunk 2,867,499 bytes (+7,197, +0.25 %: the Cesium lines).
This commit is contained in:
German Khokhlov committed 2026-10-16 17:24:36 +04:00
1 parent 0109097440
commit 86aa0bc9ba
16 files changed
+1380 -2

No files matched your search

+5
View File
@@ -10,6 +10,7 @@ import { createCesiumClock } from './clock.js';
import { createCesiumCredits } from './credits.js';
import { createCesiumFrames } from './frames.js';
import { createCesiumInput } from './input.js';
import { createCesiumLines } from './lines.js';
import { createCesiumMaps } from './maps.js';
import { createCesiumMovers } from './movers.js';
import { createCesiumPicker } from './picker.js';
@@ -46,6 +47,10 @@ export function createCesiumEngine(viewer, options = {}) {
projector: createCesiumProjector(viewer),
frames: createCesiumFrames(viewer),
clock: createCesiumClock(viewer, options),
lines: createCesiumLines(viewer, {
requestRender: (reason) => render.render.request(reason),
...(options.lineFactories ? { factories: options.lineFactories } : {}),
}),
movers: createCesiumMovers(viewer, {
requestRender: (reason) => render.render.request(reason),
...(options.moverFactories ? { factories: options.moverFactories } : {}),
+214
View File
@@ -0,0 +1,214 @@
// engine.lines on Cesium: each line is one Primitive of a PolylineGeometry
// (built synchronously, rebuilt when its positions change) with a
// PolylineMaterialAppearance, inside one engine-owned PrimitiveCollection
// added to the scene with the first line. depthFailAlpha adds Cesium's
// depthFailAppearance (the same material, its alpha scaled) for the part
// the scene hides; dashes in pixels are PolylineDash; the tactical dash is
// the launches' selected-orbit pattern along the whole line.
import * as Cesium from 'cesium';
import { createLineRegistry } from '../lines.js';
const TACTICAL_TYPE = 'GevLineTactical';
let tacticalRegistered = false;
// The launches' GevMissionOrbitTactical shader (layers/launches/
// orbitRendering.js), under the engine's own type until Task 15a moves
// launches onto engine.lines.
function registerTactical() {
if (tacticalRegistered) return;
new Cesium.Material({
fabric: {
type: TACTICAL_TYPE,
uniforms: { color: Cesium.Color.CYAN, groupCount: 4, dashCount: 100 },
source: `
czm_material czm_getMaterial(czm_materialInput materialInput) {
czm_material material = czm_getDefaultMaterial(materialInput);
float groupPosition = fract(materialInput.st.s * groupCount);
float markPosition = groupPosition * (dashCount + 1.0);
float markIndex = floor(markPosition);
float localPosition = fract(markPosition);
float centerDistance = abs(localPosition - 0.5);
float edge = max(fwidth(localPosition) * 1.35, 0.012);
float dashAlong = 1.0 - smoothstep(0.27 - edge, 0.27 + edge, centerDistance);
float dashAcross = 1.0 - smoothstep(0.12, 0.24, abs(materialInput.st.t - 0.5));
float dash = dashAlong * dashAcross;
float dotAlong = (localPosition - 0.5) / 0.32;
float dotAcross = (materialInput.st.t - 0.5) / 0.5;
float dot = 1.0 - smoothstep(0.78, 1.0, length(vec2(dotAlong, dotAcross)));
float isDot = 1.0 - step(0.5, markIndex);
float visible = mix(dash, dot, isDot);
material.diffuse = color.rgb;
material.emission = color.rgb * mix(0.07, 0.65, isDot);
material.alpha = color.a * visible * mix(0.58, 1.0, isDot);
return material;
}`,
},
});
tacticalRegistered = true;
}
/** PolylineDash's 16-bit pattern: the dash first, then the gap. */
export function dashPattern(lengthPx, gapPx) {
const on = Math.max(
1,
Math.min(16, Math.round((16 * lengthPx) / (lengthPx + gapPx))),
);
return (0xffff << (16 - on)) & 0xffff;
}
const toColor = ([r, g, b, a], alphaScale = 1) =>
new Cesium.Color(r, g, b, a * alphaScale);
/** The Cesium material type and uniforms of a line (pure, for tests). */
export function materialSpec(options, color, alphaScale = 1) {
const { dash } = options;
if (dash?.kind === 'pixels')
return {
type: 'PolylineDash',
uniforms: {
color: toColor(color, alphaScale),
gapColor: Cesium.Color.TRANSPARENT,
dashLength: dash.lengthPx + dash.gapPx,
dashPattern: dashPattern(dash.lengthPx, dash.gapPx),
},
};
if (dash?.kind === 'tactical')
return {
type: TACTICAL_TYPE,
uniforms: {
color: toColor(color, alphaScale),
groupCount: dash.groups,
dashCount: dash.dashes,
},
};
return { type: 'Color', uniforms: { color: toColor(color, alphaScale) } };
}
function cesiumMaterial({ type, uniforms }) {
if (type === TACTICAL_TYPE) registerTactical();
return Cesium.Material.fromType(type, uniforms);
}
const DEFAULT_FACTORIES = {
primitive: (options) => new Cesium.Primitive(options),
appearance: (spec) =>
new Cesium.PolylineMaterialAppearance({ material: cesiumMaterial(spec) }),
};
/**
* @param {Cesium.Viewer} viewer
* @param {{ requestRender?: (reason: string) => void, factories?: object }} [options]
* @returns {{ lines: import('../contract.js').GlobeLines, destroy: () => void }}
*/
export function createCesiumLines(
viewer,
{ requestRender = () => viewer.scene.requestRender(), factories = {} } = {},
) {
const make = { ...DEFAULT_FACTORIES, ...factories };
const { scene } = viewer;
let root = null;
const rootCollection = () => {
if (!root) {
root = new Cesium.PrimitiveCollection({ destroyPrimitives: true });
scene.primitives.add(root);
}
return root;
};
const registry = createLineRegistry((options) => {
rootCollection();
let color = options.color;
let modelMatrix = options.modelMatrix
? Cesium.Matrix4.fromArray(options.modelMatrix)
: Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY);
let shown = true;
let primitive = null;
let appearance = null;
let depthFail = null;
const drop = () => {
if (primitive) root.remove(primitive);
primitive = null;
};
return {
setPositions(flat) {
drop();
if (flat.length < 6) {
requestRender('lines');
return;
}
const positions = [];
for (let index = 0; index < flat.length; index += 3)
positions.push(
new Cesium.Cartesian3(
flat[index],
flat[index + 1],
flat[index + 2],
),
);
appearance = make.appearance(materialSpec(options, color));
depthFail =
options.depthFailAlpha > 0
? make.appearance(
materialSpec(options, color, options.depthFailAlpha),
)
: undefined;
primitive = make.primitive({
geometryInstances: new Cesium.GeometryInstance({
geometry: new Cesium.PolylineGeometry({
positions,
width: options.widthPx,
vertexFormat: Cesium.PolylineMaterialAppearance.VERTEX_FORMAT,
arcType:
options.arc === 'geodesic'
? Cesium.ArcType.GEODESIC
: Cesium.ArcType.NONE,
}),
id: options.pickId,
}),
appearance,
depthFailAppearance: depthFail,
modelMatrix: Cesium.Matrix4.clone(modelMatrix),
show: shown,
asynchronous: false,
});
root.add(primitive);
requestRender('lines');
},
setColor(rgba) {
color = rgba;
if (appearance) appearance.material.uniforms.color = toColor(rgba);
if (depthFail)
depthFail.material.uniforms.color = toColor(
rgba,
options.depthFailAlpha,
);
requestRender('lines');
},
setModelMatrix(matrix) {
modelMatrix = Cesium.Matrix4.fromArray(matrix);
if (primitive)
primitive.modelMatrix = Cesium.Matrix4.clone(modelMatrix);
requestRender('lines');
},
show(visible) {
shown = visible;
if (primitive) primitive.show = visible;
requestRender('lines');
},
destroy() {
drop();
requestRender('lines');
},
};
});
return {
lines: registry.lines,
destroy() {
registry.destroyAll();
if (root) {
scene.primitives.remove(root);
root = null;
}
},
};
}
+127
View File
@@ -0,0 +1,127 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { createCesiumLines, dashPattern } from './lines.js';
import { createFakeViewer } from './testing/fakeViewer.mjs';
function fakePrimitives() {
const made = [];
return {
made,
factories: {
primitive: (options) => {
const primitive = {
...options,
isDestroyed: () => false,
destroy() {
primitive.destroyed = true;
},
};
made.push(primitive);
return primitive;
},
appearance: (spec) => ({
material: { type: spec.type, uniforms: { ...spec.uniforms } },
}),
},
};
}
const points = [
{ x: 6_378_137, y: 0, z: 0 },
{ x: 6_378_137, y: 1000, z: 0 },
{ x: 6_378_137, y: 2000, z: 1000 },
];
test('a dash in pixels becomes PolylineDash with a 16-bit pattern', () => {
assert.equal(dashPattern(16, 16), 0xff00);
assert.equal(dashPattern(12, 4), 0xfff0);
assert.equal(dashPattern(1, 0), 0xffff);
});
test('positions build one polyline primitive; a change rebuilds it', () => {
const viewer = createFakeViewer();
const { factories, made } = fakePrimitives();
const renders = [];
const { lines, destroy } = createCesiumLines(viewer, {
factories,
requestRender: (reason) => renders.push(reason),
});
assert.equal(viewer.scene.primitives.length, 0, 'nothing at creation');
const line = lines.createLine({
id: 'trail',
widthPx: 3,
color: [1, 0, 0, 1],
depthFailAlpha: 0.4,
arc: 'geodesic',
pickId: 'trail-1',
});
assert.equal(viewer.scene.primitives.length, 1);
assert.equal(made.length, 0, 'no primitive without positions');
line.setPositions(points);
assert.equal(made.length, 1);
const [first] = made;
const geometry = first.geometryInstances.geometry;
assert.equal(geometry._width, 3);
assert.equal(geometry._arcType, Cesium.ArcType.GEODESIC);
assert.equal(geometry._positions.length, 3);
assert.equal(first.geometryInstances.id, 'trail-1');
assert.equal(first.asynchronous, false);
assert.ok(first.depthFailAppearance, 'the dimmer copy behind the scene');
assert.ok(
Cesium.Color.equals(
first.depthFailAppearance.material.uniforms.color,
new Cesium.Color(1, 0, 0, 0.4),
),
);
line.setPositions(points.slice(0, 2));
assert.equal(made.length, 2);
assert.equal(first.destroyed, true, 'the old primitive goes');
line.setColor([0, 1, 0, 1]);
assert.ok(
Cesium.Color.equals(
made[1].appearance.material.uniforms.color,
new Cesium.Color(0, 1, 0, 1),
),
);
const turn = Cesium.Matrix4.fromRotation(Cesium.Matrix3.fromRotationZ(0.5));
line.setModelMatrix(Cesium.Matrix4.toArray(turn));
assert.ok(Cesium.Matrix4.equals(made[1].modelMatrix, turn));
line.show(false);
assert.equal(made[1].show, false);
line.setPositions(points);
assert.equal(made[2].show, false, 'a rebuild keeps show and matrix');
assert.ok(Cesium.Matrix4.equals(made[2].modelMatrix, turn));
assert.ok(renders.length >= 4);
line.destroy();
assert.equal(made[2].destroyed, true);
destroy();
assert.equal(viewer.scene.primitives.length, 0);
});
test('dash kinds pick their materials', () => {
const viewer = createFakeViewer();
const { factories, made } = fakePrimitives();
const { lines } = createCesiumLines(viewer, { factories });
lines
.createLine({
id: 'd',
widthPx: 2,
color: [1, 1, 1, 1],
dash: { lengthPx: 12, gapPx: 4 },
})
.setPositions(points);
lines
.createLine({ id: 't', widthPx: 3, color: [0, 1, 1, 1], dash: 'tactical' })
.setPositions(points);
lines
.createLine({ id: 's', widthPx: 1, color: [1, 1, 1, 1] })
.setPositions(points);
assert.equal(made[0].appearance.material.type, 'PolylineDash');
assert.equal(made[0].appearance.material.uniforms.dashLength, 16);
assert.equal(made[0].appearance.material.uniforms.dashPattern, 0xfff0);
assert.equal(made[1].appearance.material.type, 'GevLineTactical');
assert.equal(made[1].appearance.material.uniforms.groupCount, 4);
assert.equal(made[2].appearance.material.type, 'Color');
assert.equal(made[2].depthFailAppearance, undefined);
});