@ifc-lite/viewer 1.21.0 → 1.22.0

package/src/lib/geo/cesium-bridge.ts

@@ -28,9 +28,13 @@
 import proj4 from 'proj4';
 import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
 import type { CoordinateInfo } from '@ifc-lite/geometry';
-import { resolveProjection } from './reproject';
-import { resolveTerrainElevation } from './terrain-elevation';
-import { getEffectiveHorizontalScale } from './effective-georef';
+import { computeModelCenterInIfcMeters, resolveProjection } from './reproject';
+import {
+  resolveTerrainElevationDetailed,
+  type ResolveTerrainElevationOptions,
+  type TerrainElevationSample,
+} from './terrain-elevation';
+import { getEffectiveHorizontalScale } from './geo-scale';
 
 export interface GeodesicPosition {
   longitude: number;
@@ -61,11 +65,65 @@ export interface CesiumBridge {
   queryTerrainHeight(
     Cesium: typeof import('cesium'),
     viewer: InstanceType<typeof import('cesium').Viewer>,
-  ): Promise<number | null>;
+    options?: ResolveTerrainElevationOptions,
+  ): Promise<TerrainElevationSample | null>;
 
   viewerToGeodetic(vx: number, vy: number, vz: number): GeodesicPosition | null;
 }
 
+export interface CesiumModelOriginInfo extends GeodesicPosition {
+  longitude: number;
+  latitude: number;
+  height: number;
+  ifcOriginHeight: number;
+  easting: number;
+  northing: number;
+  horizontalScale: number;
+}
+
+export async function computeCesiumModelOrigin(
+  mapConversion: MapConversion,
+  projectedCRS: ProjectedCRS,
+  coordinateInfo?: CoordinateInfo,
+  lengthUnitScale = 1,
+  placementHeightOverride?: number,
+): Promise<CesiumModelOriginInfo | null> {
+  const projDef = await resolveProjection(projectedCRS);
+  if (!projDef) return null;
+
+  const absc = mapConversion.xAxisAbscissa ?? 1.0;
+  const ordi = mapConversion.xAxisOrdinate ?? 0.0;
+  const center = computeModelCenterInIfcMeters(coordinateInfo);
+  const mapScale = projectedCRS.mapUnitScale ?? lengthUnitScale;
+  const horizontalScale = getEffectiveHorizontalScale(
+    mapConversion.scale,
+    mapScale,
+    lengthUnitScale,
+  );
+  const easting = mapConversion.eastings * mapScale
+    + horizontalScale * (absc * center.ifcX - ordi * center.ifcY);
+  const northing = mapConversion.northings * mapScale
+    + horizontalScale * (ordi * center.ifcX + absc * center.ifcY);
+  const ifcOriginHeight = mapConversion.orthogonalHeight * mapScale + center.ifcZ;
+  const height = placementHeightOverride ?? ifcOriginHeight;
+
+  try {
+    const [lon, lat] = proj4(projDef, 'WGS84', [easting, northing]);
+    if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+    return {
+      longitude: lon,
+      latitude: lat,
+      height,
+      ifcOriginHeight,
+      easting,
+      northing,
+      horizontalScale,
+    };
+  } catch {
+    return null;
+  }
+}
+
 export async function createCesiumBridge(
   mapConversion: MapConversion,
   projectedCRS: ProjectedCRS,
@@ -87,57 +145,34 @@ export async function createCesiumBridge(
   const ordi = mapConversion.xAxisOrdinate ?? 0.0;
   const rotAngle = Math.atan2(ordi, absc);
 
-  const shift = coordinateInfo?.originShift ?? { x: 0, y: 0, z: 0 };
-  const rtc = coordinateInfo?.wasmRtcOffset;
-  const rtcYup = rtc
-    ? { x: rtc.x, y: rtc.z, z: -rtc.y }
-    : { x: 0, y: 0, z: 0 };
-
   const bounds = coordinateInfo?.originalBounds;
   const modelVX = bounds ? (bounds.min.x + bounds.max.x) / 2 : 0;
   const modelVY = bounds ? (bounds.min.y + bounds.max.y) / 2 : 0;
   const modelVZ = bounds ? (bounds.min.z + bounds.max.z) / 2 : 0;
 
-  // ── Compute model origin in WGS84 ──
-  const owx = modelVX + shift.x + rtcYup.x;
-  const owy = modelVY + shift.y + rtcYup.y;
-  const owz = modelVZ + shift.z + rtcYup.z;
-  // Viewer Y-up → IFC Z-up
-  const oIfcX = owx;
-  const oIfcY = -owz;
-  const oIfcZ = owy;
-  // Geometry coordinates (oIfcX/Y/Z) are already in metres (the geometry engine
-  // converts from the IFC file's native unit during extraction). MapConversion
-  // values use the unit from IfcProjectedCRS.MapUnit; fall back to project unit.
-  const mapScale = projectedCRS.mapUnitScale ?? lengthUnitScale;
-  // IfcMapConversion.Scale bridges project length unit → map unit (e.g. 0.001
-  // for mm→m). Geometry is already in metres, so the effective horizontal
-  // scale is (Scale * mapUnitScale) / lengthUnitScale — see issue #595.
-  const hScale = getEffectiveHorizontalScale(mapConversion.scale, mapScale, lengthUnitScale);
-  const oEasting = mapConversion.eastings * mapScale + hScale * (absc * oIfcX - ordi * oIfcY);
-  const oNorthing = mapConversion.northings * mapScale + hScale * (ordi * oIfcX + absc * oIfcY);
-  const ifcOHeight = mapConversion.orthogonalHeight * mapScale + oIfcZ;
-  // The actual altitude used for the enuToEcef origin. When the caller
-  // pre-computes a terrain-clamped placement, we honour it so the bridge,
-  // model matrix, and camera frame are all built around the SAME altitude
-  // from the start — no post-load shifting required.
-  const oHeight = placementHeightOverride ?? ifcOHeight;
-
-  let originLon: number, originLat: number;
-  try {
-    const [lon, lat] = proj4(projDef, 'WGS84', [oEasting, oNorthing]);
-    if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
-    originLon = lon;
-    originLat = lat;
-  } catch {
-    return null;
-  }
-
+  const shift = coordinateInfo?.originShift ?? { x: 0, y: 0, z: 0 };
+  const rtc = coordinateInfo?.wasmRtcOffset;
+  const rtcYup = rtc
+    ? { x: rtc.x, y: rtc.z, z: -rtc.y }
+    : { x: 0, y: 0, z: 0 };
+  const origin = await computeCesiumModelOrigin(
+    mapConversion,
+    projectedCRS,
+    coordinateInfo,
+    lengthUnitScale,
+    placementHeightOverride,
+  );
+  if (!origin) return null;
   const modelOrigin: GeodesicPosition = {
-    longitude: originLon,
-    latitude: originLat,
-    height: oHeight,
+    longitude: origin.longitude,
+    latitude: origin.latitude,
+    height: origin.height,
   };
+  const hScale = origin.horizontalScale;
+  const mapScale = projectedCRS.mapUnitScale ?? lengthUnitScale;
+  const oHeight = origin.height;
+  const originLon = origin.longitude;
+  const originLat = origin.latitude;
 
   // ── Build the viewer→ENU 3x3 rotation matrix ──
   // This converts a DELTA vector from viewer space to ENU.
@@ -301,8 +336,9 @@ export async function createCesiumBridge(
   function queryTerrainHeight(
     Cesium: typeof import('cesium'),
     viewer: InstanceType<typeof import('cesium').Viewer>,
-  ): Promise<number | null> {
-    return resolveTerrainElevation(Cesium, viewer, originLat, originLon);
+    options: ResolveTerrainElevationOptions = {},
+  ): Promise<TerrainElevationSample | null> {
+    return resolveTerrainElevationDetailed(Cesium, viewer, originLat, originLon, options);
   }
 
   function viewerToGeodetic(vx: number, vy: number, vz: number): GeodesicPosition | null {

package/src/lib/geo/cesium-placement.test.ts

@@ -0,0 +1,244 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  closestYOnVerticalLineFromRay,
+  computeCesiumPlacement,
+  computeIfcOriginHeight,
+  computeOrthogonalHeightForBaseAltitude,
+  getMapUnitScale,
+  intersectRayWithHorizontalPlane,
+  mapUnitsToMeters,
+  metersToMapUnits,
+  projectedDeltaToViewerDelta,
+  shouldPreferOrthometricTerrain,
+  viewerDeltaToProjectedDelta,
+} from './cesium-placement.js';
+
+describe('cesium placement helpers', () => {
+  it('falls back to the project length unit when mapUnitScale is absent', () => {
+    assert.strictEqual(getMapUnitScale(undefined, 0.001), 0.001);
+    assert.strictEqual(getMapUnitScale({ mapUnitScale: 1 }, 0.001), 1);
+  });
+
+  it('converts between metres and map units using ProjectedCRS.mapUnitScale', () => {
+    const usFoot = { mapUnitScale: 0.3048006096 };
+    assert.strictEqual(mapUnitsToMeters(10, usFoot, 1), 3.048006096);
+    assert.strictEqual(
+      metersToMapUnits(3.048006096, usFoot, 1),
+      10,
+    );
+  });
+
+  it('prefers orthometric terrain when a vertical datum is present', () => {
+    assert.strictEqual(shouldPreferOrthometricTerrain({ verticalDatum: 'EPSG:8357' }), true);
+    assert.strictEqual(shouldPreferOrthometricTerrain({ verticalDatum: '$' }), false);
+    assert.strictEqual(shouldPreferOrthometricTerrain({ verticalDatum: '' }), false);
+    assert.strictEqual(shouldPreferOrthometricTerrain(undefined), false);
+  });
+
+  it('computes terrain-clamped placement and clip plane from storey anchor', () => {
+    const placement = computeCesiumPlacement({
+      coordinateInfo: {
+        originShift: { x: 0, y: 0, z: 0 },
+        originalBounds: {
+          min: { x: 0, y: -3, z: 0 },
+          max: { x: 10, y: 9, z: 10 },
+        },
+        shiftedBounds: {
+          min: { x: 0, y: -3, z: 0 },
+          max: { x: 10, y: 9, z: 10 },
+        },
+        hasLargeCoordinates: false,
+      },
+      projectedCRS: { verticalDatum: 'EPSG:8357' },
+      ifcOriginHeight: 244,
+      terrainHeight: 245,
+      storeyElevations: new Map([[1, -3], [2, 0], [3, 3]]),
+    });
+
+    assert.strictEqual(placement.clampAnchorY, 0);
+    assert.strictEqual(placement.anchorOffset, 3);
+    assert.strictEqual(placement.placementHeight, 248);
+    assert.strictEqual(placement.terrainClipY, 0);
+    assert.strictEqual(placement.preferOrthometricTerrain, true);
+  });
+
+  it('preserves authored OrthogonalHeight when it is already above terrain', () => {
+    const placement = computeCesiumPlacement({
+      ifcOriginHeight: 244,
+      terrainHeight: 195.4,
+    });
+
+    assert.strictEqual(placement.placementHeight, 244);
+    assert.strictEqual(placement.terrainClipY, -48.599999999999994);
+  });
+
+  it('computes OrthogonalHeight from target base altitude with shift and RTC', () => {
+    const orthogonalHeight = computeOrthogonalHeightForBaseAltitude({
+      coordinateInfo: {
+        originShift: { x: 0, y: 2, z: 0 },
+        originalBounds: {
+          min: { x: 0, y: -1, z: 0 },
+          max: { x: 10, y: 11, z: 10 },
+        },
+        shiftedBounds: {
+          min: { x: 0, y: -1, z: 0 },
+          max: { x: 10, y: 11, z: 10 },
+        },
+        hasLargeCoordinates: false,
+        wasmRtcOffset: { x: 0, y: 0, z: 3 },
+      },
+      projectedCRS: { mapUnitScale: 0.3048 },
+      lengthUnitScale: 1,
+      storeyElevations: new Map([[1, 0]]),
+      targetBaseAltitude: 245,
+    });
+
+    assert.strictEqual(orthogonalHeight, 787.4);
+  });
+
+  it('computes the IFC origin height from OrthogonalHeight and model center', () => {
+    const height = computeIfcOriginHeight(
+      { orthogonalHeight: 12 },
+      { mapUnitScale: 0.5 },
+      {
+        originShift: { x: 0, y: 3, z: 0 },
+        originalBounds: {
+          min: { x: 0, y: 2, z: 0 },
+          max: { x: 10, y: 8, z: 10 },
+        },
+        shiftedBounds: {
+          min: { x: 0, y: 2, z: 0 },
+          max: { x: 10, y: 8, z: 10 },
+        },
+        hasLargeCoordinates: false,
+      },
+      1,
+    );
+
+    assert.strictEqual(height, 14);
+  });
+
+  it('converts viewer XY drag deltas into projected map deltas', () => {
+    const projected = viewerDeltaToProjectedDelta(
+      2,
+      -1,
+      { xAxisAbscissa: 1, xAxisOrdinate: 0, scale: 1 },
+      { mapUnitScale: 1 },
+      1,
+    );
+
+    assert.deepStrictEqual(projected, { eastings: 2, northings: 1 });
+  });
+
+  it('converts projected map deltas back to viewer drag deltas', () => {
+    const viewer = projectedDeltaToViewerDelta(
+      2,
+      1,
+      { xAxisAbscissa: 1, xAxisOrdinate: 0, scale: 1 },
+      { mapUnitScale: 1 },
+      1,
+    );
+
+    assert.deepStrictEqual(viewer, { x: 2, z: -1 });
+  });
+
+  it('intersects a downward ray with a horizontal plane at the expected point', () => {
+    const hit = intersectRayWithHorizontalPlane(
+      { origin: { x: 5, y: 10, z: -3 }, direction: { x: 0, y: -1, z: 0 } },
+      0,
+    );
+    assert.deepStrictEqual(hit, { x: 5, y: 0, z: -3 });
+  });
+
+  it('intersects an oblique ray with a horizontal plane consistently for two cursor samples', () => {
+    // Two parallel rays separated by a known horizontal offset should map to
+    // hit points separated by the same offset on the plane. This is the
+    // invariant the placement gizmo relies on for stable XY drag at any
+    // camera angle.
+    const direction = { x: 0.4, y: -0.6, z: 0.5 };
+    const hitA = intersectRayWithHorizontalPlane(
+      { origin: { x: 0, y: 12, z: 0 }, direction },
+      0,
+    );
+    const hitB = intersectRayWithHorizontalPlane(
+      { origin: { x: 1, y: 12, z: 2 }, direction },
+      0,
+    );
+    assert.ok(hitA && hitB);
+    assert.strictEqual(Math.round((hitB.x - hitA.x) * 1e6) / 1e6, 1);
+    assert.strictEqual(Math.round((hitB.z - hitA.z) * 1e6) / 1e6, 2);
+  });
+
+  it('rejects rays that are parallel to the horizontal plane', () => {
+    const hit = intersectRayWithHorizontalPlane(
+      { origin: { x: 0, y: 5, z: 0 }, direction: { x: 1, y: 0, z: 0 } },
+      0,
+    );
+    assert.strictEqual(hit, null);
+  });
+
+  it('rejects rays whose intersection lies behind the origin', () => {
+    // Ray going up, plane below origin: t < 0.
+    const hit = intersectRayWithHorizontalPlane(
+      { origin: { x: 0, y: 5, z: 0 }, direction: { x: 0, y: 1, z: 0 } },
+      0,
+    );
+    assert.strictEqual(hit, null);
+  });
+
+  it('returns the cursor-aligned Y on a vertical line for an oblique ray', () => {
+    // Ray that passes exactly through (anchorX, 7, anchorZ) — the closest
+    // point on the vertical axis is the same point, so Y = 7.
+    const anchorX = 4;
+    const anchorZ = -2;
+    const target = { x: anchorX, y: 7, z: anchorZ };
+    const origin = { x: 0, y: 0, z: 0 };
+    const dx = target.x - origin.x;
+    const dy = target.y - origin.y;
+    const dz = target.z - origin.z;
+    const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    const direction = { x: dx / len, y: dy / len, z: dz / len };
+    const y = closestYOnVerticalLineFromRay({ origin, direction }, anchorX, anchorZ);
+    assert.ok(y !== null);
+    assert.ok(Math.abs((y as number) - 7) < 1e-9);
+  });
+
+  it('preserves vertical drag amount when cursor moves up by a known screen offset', () => {
+    // Two rays that pass through points (anchorX, y1, anchorZ) and
+    // (anchorX, y2, anchorZ) on the vertical line: returned Y values must
+    // equal y1 and y2 exactly — the basis of frame-rate-independent height
+    // dragging at oblique camera angles.
+    const anchorX = 0;
+    const anchorZ = 0;
+    const origin = { x: 6, y: 0, z: 4 };
+
+    const aim = (y: number) => {
+      const dx = anchorX - origin.x;
+      const dy = y - origin.y;
+      const dz = anchorZ - origin.z;
+      const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      return { origin, direction: { x: dx / len, y: dy / len, z: dz / len } };
+    };
+
+    const y1 = closestYOnVerticalLineFromRay(aim(2), anchorX, anchorZ);
+    const y2 = closestYOnVerticalLineFromRay(aim(9), anchorX, anchorZ);
+    assert.ok(y1 !== null && y2 !== null);
+    assert.ok(Math.abs((y1 as number) - 2) < 1e-9);
+    assert.ok(Math.abs((y2 as number) - 9) < 1e-9);
+  });
+
+  it('rejects vertical rays for closest-Y-on-line (degenerate)', () => {
+    const y = closestYOnVerticalLineFromRay(
+      { origin: { x: 0, y: 10, z: 0 }, direction: { x: 0, y: -1, z: 0 } },
+      0,
+      0,
+    );
+    assert.strictEqual(y, null);
+  });
+});

package/src/lib/geo/cesium-placement.ts

@@ -0,0 +1,231 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import type { CoordinateInfo } from '@ifc-lite/geometry';
+import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
+
+import { findClampAnchorY } from './clamp-anchor';
+import { computeModelCenterInIfcMeters } from './reproject';
+import { getEffectiveHorizontalScale } from './geo-scale';
+
+export function getMapUnitScale(
+  projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
+  lengthUnitScale: number,
+): number {
+  const mapUnitScale = projectedCRS?.mapUnitScale;
+  if (typeof mapUnitScale === 'number' && mapUnitScale > 0) return mapUnitScale;
+  return lengthUnitScale > 0 ? lengthUnitScale : 1;
+}
+
+export function mapUnitsToMeters(
+  value: number,
+  projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
+  lengthUnitScale: number,
+): number {
+  return value * getMapUnitScale(projectedCRS, lengthUnitScale);
+}
+
+export function metersToMapUnits(
+  value: number,
+  projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
+  lengthUnitScale: number,
+): number {
+  return value / getMapUnitScale(projectedCRS, lengthUnitScale);
+}
+
+export function shouldPreferOrthometricTerrain(
+  projectedCRS: Pick<ProjectedCRS, 'verticalDatum'> | undefined,
+): boolean {
+  const verticalDatum = projectedCRS?.verticalDatum?.trim();
+  return Boolean(verticalDatum && verticalDatum !== '$');
+}
+
+export interface CesiumPlacementInput {
+  coordinateInfo?: CoordinateInfo;
+  projectedCRS?: Pick<ProjectedCRS, 'verticalDatum'> | Pick<ProjectedCRS, 'mapUnitScale'> & Pick<ProjectedCRS, 'verticalDatum'>;
+  ifcOriginHeight: number;
+  terrainHeight: number | null;
+  storeyElevations?: Map<number, number>;
+}
+
+export interface CesiumPlacementResult {
+  clampAnchorY: number;
+  minY: number;
+  modelCenterY: number;
+  anchorOffset: number;
+  ifcOriginHeight: number;
+  placementHeight: number;
+  terrainClipY: number | null;
+  preferOrthometricTerrain: boolean;
+}
+
+export function computeCesiumPlacement({
+  coordinateInfo,
+  projectedCRS,
+  ifcOriginHeight,
+  terrainHeight,
+  storeyElevations,
+}: CesiumPlacementInput): CesiumPlacementResult {
+  const bounds = coordinateInfo?.originalBounds;
+  const modelCenterY = bounds ? (bounds.min.y + bounds.max.y) / 2 : 0;
+  const minY = bounds?.min.y ?? 0;
+  const clampAnchorY = findClampAnchorY(bounds, storeyElevations);
+  const anchorOffset = modelCenterY - clampAnchorY;
+  const terrainPlacementHeight = terrainHeight !== null
+    ? terrainHeight + anchorOffset
+    : null;
+  const placementHeight = terrainPlacementHeight !== null
+    ? Math.max(ifcOriginHeight, terrainPlacementHeight)
+    : ifcOriginHeight;
+
+  return {
+    clampAnchorY,
+    minY,
+    modelCenterY,
+    anchorOffset,
+    ifcOriginHeight,
+    placementHeight,
+    terrainClipY: terrainHeight !== null
+      ? terrainHeight - placementHeight + modelCenterY
+      : null,
+    preferOrthometricTerrain: shouldPreferOrthometricTerrain(projectedCRS),
+  };
+}
+
+export interface OrthogonalHeightForBaseAltitudeInput {
+  coordinateInfo?: CoordinateInfo;
+  projectedCRS?: Pick<ProjectedCRS, 'mapUnitScale'>;
+  lengthUnitScale: number;
+  storeyElevations?: Map<number, number>;
+  targetBaseAltitude: number;
+}
+
+export function computeOrthogonalHeightForBaseAltitude({
+  coordinateInfo,
+  projectedCRS,
+  lengthUnitScale,
+  storeyElevations,
+  targetBaseAltitude,
+}: OrthogonalHeightForBaseAltitudeInput): number {
+  const bounds = coordinateInfo?.originalBounds;
+  const anchorY = findClampAnchorY(bounds, storeyElevations);
+  const shiftY = coordinateInfo?.originShift?.y ?? 0;
+  // RTC offset is stored in IFC Z-up; viewer-Y aligns to its Z component.
+  const rtcYupY = coordinateInfo?.wasmRtcOffset?.z ?? 0;
+  const orthogonalHeightMeters = targetBaseAltitude - shiftY - rtcYupY - anchorY;
+
+  return Math.round(
+    metersToMapUnits(orthogonalHeightMeters, projectedCRS, lengthUnitScale) * 100,
+  ) / 100;
+}
+
+export function computeIfcOriginHeight(
+  mapConversion: Pick<MapConversion, 'orthogonalHeight'>,
+  projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
+  coordinateInfo: CoordinateInfo | undefined,
+  lengthUnitScale: number,
+): number {
+  const mapScale = getMapUnitScale(projectedCRS, lengthUnitScale);
+  return mapConversion.orthogonalHeight * mapScale + computeModelCenterInIfcMeters(coordinateInfo).ifcZ;
+}
+
+export function viewerDeltaToProjectedDelta(
+  deltaX: number,
+  deltaZ: number,
+  mapConversion: Pick<MapConversion, 'xAxisAbscissa' | 'xAxisOrdinate' | 'scale'>,
+  projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
+  lengthUnitScale: number,
+): { eastings: number; northings: number } {
+  const mapScale = getMapUnitScale(projectedCRS, lengthUnitScale);
+  const hScale = getEffectiveHorizontalScale(
+    mapConversion.scale,
+    mapScale,
+    lengthUnitScale,
+  );
+  const abscissa = mapConversion.xAxisAbscissa ?? 1;
+  const ordinate = mapConversion.xAxisOrdinate ?? 0;
+  const eastMeters = hScale * (abscissa * deltaX + ordinate * deltaZ);
+  const northMeters = hScale * (ordinate * deltaX - abscissa * deltaZ);
+
+  return {
+    eastings: metersToMapUnits(eastMeters, projectedCRS, lengthUnitScale),
+    northings: metersToMapUnits(northMeters, projectedCRS, lengthUnitScale),
+  };
+}
+
+export interface Ray3 {
+  origin: { x: number; y: number; z: number };
+  direction: { x: number; y: number; z: number };
+}
+
+/**
+ * Intersect a ray with the horizontal plane y = planeY. Returns null when the
+ * ray is (near-)parallel to the plane or the hit lies behind the ray origin.
+ *
+ * Used by the placement gizmo's XY drag: a stable horizontal drag plane
+ * through the gizmo anchor avoids the projection-Jacobian instability of
+ * linearised screen-axis approximations, which blow up to "huge jumps" at
+ * oblique camera angles when the gizmo plane is near-edge-on to the camera.
+ */
+export function intersectRayWithHorizontalPlane(
+  ray: Ray3,
+  planeY: number,
+): { x: number; y: number; z: number } | null {
+  const dirY = ray.direction.y;
+  if (!Number.isFinite(dirY) || Math.abs(dirY) < 1e-6) return null;
+  const t = (planeY - ray.origin.y) / dirY;
+  if (!Number.isFinite(t) || t < 0) return null;
+  return {
+    x: ray.origin.x + ray.direction.x * t,
+    y: planeY,
+    z: ray.origin.z + ray.direction.z * t,
+  };
+}
+
+/**
+ * Find the Y-coordinate on the vertical line (anchorX, *, anchorZ) closest
+ * to a ray. Returns null when the ray's horizontal component vanishes (the
+ * ray is parallel to the vertical line — no meaningful "grab" point).
+ *
+ * Used by the placement gizmo's height drag so the slider tracks the cursor
+ * accurately at any camera tilt, instead of linearising screen-space pixels
+ * per metre.
+ */
+export function closestYOnVerticalLineFromRay(
+  ray: Ray3,
+  anchorX: number,
+  anchorZ: number,
+): number | null {
+  const dx = ray.direction.x;
+  const dz = ray.direction.z;
+  const horiz = dx * dx + dz * dz;
+  if (!Number.isFinite(horiz) || horiz < 1e-12) return null;
+  const s = (dx * (anchorX - ray.origin.x) + dz * (anchorZ - ray.origin.z)) / horiz;
+  return ray.origin.y + s * ray.direction.y;
+}
+
+export function projectedDeltaToViewerDelta(
+  eastingsDelta: number,
+  northingsDelta: number,
+  mapConversion: Pick<MapConversion, 'xAxisAbscissa' | 'xAxisOrdinate' | 'scale'>,
+  projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
+  lengthUnitScale: number,
+): { x: number; z: number } {
+  const mapScale = getMapUnitScale(projectedCRS, lengthUnitScale);
+  const hScale = getEffectiveHorizontalScale(
+    mapConversion.scale,
+    mapScale,
+    lengthUnitScale,
+  );
+  const abscissa = mapConversion.xAxisAbscissa ?? 1;
+  const ordinate = mapConversion.xAxisOrdinate ?? 0;
+  const eastMeters = mapUnitsToMeters(eastingsDelta, projectedCRS, lengthUnitScale);
+  const northMeters = mapUnitsToMeters(northingsDelta, projectedCRS, lengthUnitScale);
+  const denom = Math.max((abscissa * abscissa + ordinate * ordinate) * hScale, 1e-12);
+
+  return {
+    x: (abscissa * eastMeters + ordinate * northMeters) / denom,
+    z: (ordinate * eastMeters - abscissa * northMeters) / denom,
+  };
+}