@expofp/wayfinding 3.38.0 → 3.39.1

package/dist/createWayfinding.d.ts

@@ -22,6 +22,18 @@ export interface WayfindingConfig {
     readonly layers: WayfindingLayers;
     /** Plan GPS calibration; the snap and reroute thresholds are derived from it. */
     readonly gpsConfig?: GpsConfig;
+    /**
+     * Draws every icon facing the camera, through `ImageDef.screenSpace`. Set it when the plan
+     * renders in 3D, together with the `overlay` option of `initWayfindingLayers`.
+     *
+     * An icon then keeps its plan anchor and the on-screen size `onScale` gives it, and stands up to
+     * face the viewer. Two costs come with that. It takes {@link IconConfig.cardinalSnap} out of
+     * use, because the renderer owns a screen-space def's orientation and ignores a roll rule on
+     * one. It also changes what {@link IconConfig.rotation} turns about, from the plan's normal to
+     * the screen's, so an icon whose rotation carries a plan heading points at a screen direction
+     * instead.
+     */
+    readonly screenSpaceIcons?: boolean;
     readonly onTransitionClick?: (point: TransitionPointDef) => void;
     /** Fired when the route changes. `bounds.isEmpty()` detects an empty/cleared route. */
     readonly onRouteUpdate?: (lines: readonly RouteLine[], bounds: Box) => void;

package/dist/createWayfinding.js

@@ -4,7 +4,9 @@ import { createWayfindingRuntime, } from './runtime/index.js';
 export function createWayfinding(config) {
     const { dataSource, renderer: rendererPort, iconProvider, floorContext, layers, gpsConfig, } = config;
     const engine = createWayfindingEngine(dataSource);
-    const renderer = createWayfindingRenderer(rendererPort, layers);
+    const renderer = createWayfindingRenderer(rendererPort, layers, {
+        screenSpaceIcons: config.screenSpaceIcons,
+    });
     const snapThresholdMeters = getThresholdOrDefault(gpsConfig?.snapThreshold, SNAP_THRESHOLD_METERS);
     const snapThreshold = getThresholdFromMetersToSvg({
         thresholdInMeters: snapThresholdMeters,

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  */
 export type { GpsConfig, Wayfinding, WayfindingConfig } from './createWayfinding.js';
 export { createWayfinding } from './createWayfinding.js';
-export type { WayfindingLayers } from './renderer/index.js';
+export type { WayfindingLayerOptions, WayfindingLayers } from './renderer/index.js';
 export { initWayfindingLayers, resolveWayfindingLayers } from './renderer/index.js';
 export type { GraphDataSource } from './core/index.js';
 export type { IconConfig, RendererPort } from './renderer/index.js';

package/dist/index.js

@@ -10,7 +10,7 @@ export { initWayfindingLayers, resolveWayfindingLayers } from './renderer/index.
 // route endpoint so the runtime renders that point as the live position.
 export { CURRENT_POSITION_POINT_ID } from './runtime/index.js';
 // Pure routing helper: orders waypoints for the shortest visiting sequence
-// (nearest-neighbour + 2-opt). Stateless and instance-free, so callers can plan
+// (nearest-neighbor + 2-opt). Stateless and instance-free, so callers can plan
 // multi-stop routes before a wayfinding instance exists (e.g. the SDK
 // `getOptimizedRoutes`).
 export { optimizeWaypointOrder } from './core/routing/optimizeWaypointOrder.js';

package/dist/renderer/createWayfindingRenderer.js

@@ -14,7 +14,7 @@ const DEFAULT_COLORS = {
 export function createWayfindingRenderer(port, layers, config = {}) {
     const colors = { ...DEFAULT_COLORS, ...config.colors };
     const layerManager = createLayerManager(port);
-    const iconManager = createIconManager(layerManager, port, layers);
+    const iconManager = createIconManager(layerManager, port, layers, config.screenSpaceIcons);
     const trailManager = createTrailManager(layerManager, layers.trail);
     const routeLineManager = createRouteLineManager(layerManager, colors, port, layers);
     const wfRenderer = {

package/dist/renderer/iconManager.d.ts

@@ -36,7 +36,8 @@ export interface IconManager {
  * @param layerManager - Tracks what changed.
  * @param port - The host's roll rule and commit.
  * @param layers - The icon layers to place into.
+ * @param screenSpace - Whether every icon faces the camera rather than lying on the plan.
  * @returns The manager.
  */
-export declare function createIconManager(layerManager: LayerManager, port: RendererPort, layers: Pick<WayfindingLayers, 'icons' | 'currentPosition'>): IconManager;
+export declare function createIconManager(layerManager: LayerManager, port: RendererPort, layers: Pick<WayfindingLayers, 'icons' | 'currentPosition'>, screenSpace?: boolean): IconManager;
 //# sourceMappingURL=iconManager.d.ts.map

package/dist/renderer/iconManager.js

@@ -25,9 +25,10 @@ export function rescaleIcon(def, pixelSize) {
  * @param layerManager - Tracks what changed.
  * @param port - The host's roll rule and commit.
  * @param layers - The icon layers to place into.
+ * @param screenSpace - Whether every icon faces the camera rather than lying on the plan.
  * @returns The manager.
  */
-export function createIconManager(layerManager, port, layers) {
+export function createIconManager(layerManager, port, layers, screenSpace = false) {
     const icons = new Map();
     const iconKeysByName = new Map();
     const keyToName = new Map();
@@ -65,6 +66,10 @@ export function createIconManager(layerManager, port, layers) {
     }
     function createIcon(iconKey, name, cfg, rotation = cfg.rotation) {
         const layer = layerFor(cfg);
+        // The caller's own answer wins where it gave one. An icon whose rotation carries a plan bearing
+        // opts out, because a screen-space def spins about the screen's normal and would point at a
+        // fixed screen direction instead.
+        const facesCamera = cfg.screenSpace ?? screenSpace;
         layerManager.touchLayer(layer);
         // Size zero on purpose: an icon's size is only expressible in terms of the current pixel size, and
         // `rescaleIcon` is its one writer. The renderer lays a def out as it registers, hidden or not, so
@@ -75,8 +80,11 @@ export function createIconManager(layerManager, port, layers) {
             hidden: cfg.hidden ?? false,
             dim: cfg.dimmed ? 1 : 0,
             origin: cfg.origin,
+            screenSpace: facesCamera,
         };
-        if (cfg.cardinalSnap)
+        // A screen-space icon already stands up to face the viewer, so it has no readability to keep
+        // through a quarter turn. Its own billboarding is what a cardinal snap would be for.
+        if (cfg.cardinalSnap && !facesCamera)
             port.attachCardinalSnap(def);
         def.onScale = ({ pixelSize }) => rescaleIcon(def, pixelSize);
         layer.children.push(def);

package/dist/renderer/index.d.ts

@@ -1,5 +1,5 @@
 export { createWayfindingRenderer } from './createWayfindingRenderer.js';
-export type { WayfindingLayers } from './layers.js';
+export type { WayfindingLayerOptions, WayfindingLayers } from './layers.js';
 export { initWayfindingLayers, resolveWayfindingLayers } from './layers.js';
 export type { IconConfig, RendererPort, WayfindingRenderer } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/renderer/layers.d.ts

@@ -6,6 +6,20 @@ import type { ImageDef, LayerDef, LineDef } from '@expofp/renderer';
  * images and lines cannot share one. Which layers exist and how they stack among themselves is this
  * package's business; where the block sits in a scene is the host's.
  */
+/** How the host wants the block built. */
+export interface WayfindingLayerOptions {
+    /**
+     * Draws the whole block above 3D content, through `LayerDef.overlay`.
+     *
+     * Set it when the plan renders in 3D. A route runs along the floor, so a booth volume standing
+     * between it and a tilted camera hides it. The overlay tier turns depth testing off for the
+     * block and draws it after every plan-tier layer, which is the case the tier exists for.
+     *
+     * Set on the block alone, because `overlay` accumulates down the layer tree. Every layer inside
+     * inherits it, and none of them can opt back out.
+     */
+    readonly overlay?: boolean;
+}
 export interface WayfindingLayers {
     /** Dot trail between an off-graph anchor and the route. */
     readonly trail: LayerDef<ImageDef>;
@@ -23,9 +37,10 @@ export interface WayfindingLayers {
  *
  * Mount it wherever wayfinding belongs in the scene — the route has to draw over the pathway layers
  * (efp #1206). `createWayfinding` finds it there and fills it.
+ * @param options - How to build the block. See {@link WayfindingLayerOptions}.
  * @returns The block to mount.
  */
-export declare function initWayfindingLayers(): LayerDef<LayerDef>;
+export declare function initWayfindingLayers(options?: WayfindingLayerOptions): LayerDef<LayerDef>;
 /**
  * Finds the mounted block in a scene and hands back the layers inside it, so a host that mounted
  * the block needs to carry nothing but its scene.

package/dist/renderer/layers.js

@@ -11,9 +11,10 @@ const CURRENT_POSITION_LAYER_NAME = 'wf-current-position';
  *
  * Mount it wherever wayfinding belongs in the scene — the route has to draw over the pathway layers
  * (efp #1206). `createWayfinding` finds it there and fills it.
+ * @param options - How to build the block. See {@link WayfindingLayerOptions}.
  * @returns The block to mount.
  */
-export function initWayfindingLayers() {
+export function initWayfindingLayers(options = {}) {
     const trail = { name: TRAIL_LAYER_NAME, children: [] };
     const lines = { name: LINES_LAYER_NAME, children: [] };
     const linesAnimated = { name: LINES_ANIMATED_LAYER_NAME, children: [] };
@@ -29,6 +30,9 @@ export function initWayfindingLayers() {
         // Once for the block, which the children inherit: a search dims the venue behind the route,
         // never the route.
         dim: 0,
+        // Once for the block as well, and for the same reason. `overlay` accumulates down the tree, so
+        // the five layers above inherit it and none of them can drop back to the plan tier.
+        overlay: options.overlay,
     };
 }
 /**

package/dist/renderer/types.d.ts

@@ -55,11 +55,35 @@ export interface IconConfig {
      * Set at first setIcon for an icon key; ignored on subsequent updates.
      */
     readonly cardinalSnap?: boolean;
+    /**
+     * Overrides {@link WayfindingRendererConfig.screenSpaceIcons} for this icon alone.
+     *
+     * Pass `false` where {@link rotation} carries a plan bearing, such as the position arrow's device
+     * heading or a kiosk's facing. A screen-space def spins about the screen's normal rather than the
+     * plan's, so such an icon would point at a fixed screen direction instead of at the bearing it
+     * was given. Leave it unset for an icon whose rotation means nothing, which is most of them.
+     *
+     * Set at first setIcon for an icon key, as {@link origin} and {@link cardinalSnap} are. A later
+     * call that changes it is ignored unless the canvas changes too, which rebuilds the def.
+     */
+    readonly screenSpace?: boolean;
     readonly onClick?: () => void;
 }
 export interface WayfindingRendererConfig {
     /** Optional color overrides; defaults applied if omitted. */
     readonly colors?: Partial<RouteColors>;
+    /**
+     * Draws every icon facing the camera, through `ImageDef.screenSpace`.
+     *
+     * Set it when the plan renders in 3D. An icon keeps its plan anchor and the on-screen size
+     * `onScale` gives it, and stands up to face the viewer instead of lying on the floor.
+     *
+     * This takes {@link IconConfig.cardinalSnap} out of use, because billboarding is already what
+     * that rule was for. It also changes what {@link IconConfig.rotation} turns about, from the
+     * plan's normal to the screen's, so an icon whose rotation carries a plan bearing opts out
+     * through {@link IconConfig.screenSpace}.
+     */
+    readonly screenSpaceIcons?: boolean;
 }
 /**
  * WayfindingRenderer — generic ImageDef/LineDef renderer for wayfinding visuals.

package/dist/runtime/positionView.js

@@ -14,6 +14,11 @@ export function createPositionView({ renderer, iconProvider, }) {
                 x: input.x,
                 y: input.y,
                 rotation,
+                // The arrow points along the device's own heading, which is a direction in the venue, so it
+                // stays flat on the plan and turns with it. A screen-space def spins about the screen's
+                // normal and would hold one screen direction whatever the plan is turned to. The
+                // headingless dot has no direction to lose, so it takes the renderer's own setting.
+                screenSpace: hasHeading ? false : undefined,
                 hidden,
                 dimmed: hidden,
                 origin: [0.5, 0.5],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/wayfinding",
-  "version": "3.38.0",
+  "version": "3.39.1",
   "type": "module",
   "description": "ExpoFP SDK internal: framework-neutral wayfinding (routing, snapping, scene rendering)",
   "homepage": "https://developer.expofp.com/",
@@ -34,12 +34,12 @@
   "dependencies": {
     "ngraph.graph": "^19.1.0",
     "tslib": "^2.3.0",
-    "@expofp/geometry": "3.38.0"
+    "@expofp/geometry": "3.39.1"
   },
   "peerDependencies": {
-    "@expofp/renderer": "3.38.0"
+    "@expofp/renderer": "3.39.1"
   },
   "devDependencies": {
-    "@expofp/renderer": "3.38.0"
+    "@expofp/renderer": "3.39.1"
   }
 }