@geoblocks/cesium-walk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-present, camptocamp SA
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# Cesium Walk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package provides a camera mode for CesiumJS that lets the user walk around the scene
+with the keyboard or a gamepad. The camera is kept at a fixed height above the terrain.
+
+## Controls
+
+| Action | Keyboard | Gamepad (standard mapping) |
+|---|---|---|
+| Walk | W, A, S, D or the arrows | left stick |
+| Sprint, forward | Shift, held | Cross / A (button 0), held |
+| Jump | Space | Square / X (button 2) |
+
+The keys are matched by their position (`event.code`), so other keyboard layouts walk with the
+keys in the same place.
+
+These are the default bindings, `WALK_BINDINGS`, read with [cesium-input](../cesium-input). The walker
+reads its intent from `walkMode.input` on each tick, `{move: {x, y}, sprint, jump}`, so the controls can
+be remapped, or come from anywhere else, while the walk is not active:
+
+```javascript
+import Controls from '@geoblocks/cesium-input';
+import CesiumWalk, {WALK_BINDINGS} from '@geoblocks/cesium-walk';
+
+// J jumps instead of Space
+walkMode.input = new Controls({...WALK_BINDINGS, jump: {type: 'button', keys: ['KeyJ'], buttons: [2]}});
+// touch controls, an AI, a replay: `move` no longer than 1, x right and y forward
+walkMode.input = {read: () => ({move: touchStick.vector, sprint: false, jump: touchButton.tapped})};
+```
+
+## Installation
+
+```bash
+npm i --save @geoblocks/cesium-walk
+```
+
+## Demo
+
+[Demo](https://geoblocks.github.io/cesium-helpers/cesium-walk.html)
+
+## Usage
+
+```javascript
+import {Viewer} from '@cesium/engine';
+import CesiumWalk from '@geoblocks/cesium-walk';
+
+const viewer = new Viewer(...);
+// speed in meters per second, height above the terrain in meters
+const walkMode = new CesiumWalk(viewer, 1.6, 2.0);
+
+// ...
+walkMode.active = true;
+```
+
+`walkMode.sprintSpeed` (default three times the speed) and `walkMode.jumpSpeed` (default 4 m/s)
+can be changed at any time, as can these, all off or as on Earth by default:
+
+- `walkMode.gravity`, in m/s² (default 9.81): the Moon's 1.62, or a game's snappier jumps.
+- `walkMode.acceleration`, in m/s² (default `Infinity`, at once): how fast the walker reaches its
+  speed, stops and turns.
+- `walkMode.stepHeight`, in meters (default `Infinity`, always followed): the deepest drop of the
+  ground stepped down; off a deeper one, a ledge or a roof, the walker falls.
+
+In the air, jumping or falling, the walker keeps its height when the ground changes under it, and lands
+on the ground it meets.
+`walkMode.sprinting` tells whether the walker is sprinting. Set `walkMode.headBob = true` for the camera to bob at each step and dip on landing, as in GTA 5's
+first person. Set `walkMode.collision = true` for the walker to stop at the obstacles in view at eye
+height (buildings, trees, any opaque 3D tiles or primitives) and to slide along them; walking backward or
+sideways, the obstacles out of view do not stop it. Translucent primitives, of an alpha below 0.995, are
+not obstacles. The obstacles come from [cesium-obstacles](../cesium-obstacles), read in the depth
+of the last frame, which makes the CPU wait for the GPU. For a world known on the CPU, set
+`walkMode.obstacleAhead` to a function returning the obstacle ahead in a direction, `{point, normal}`
+with the normal toward the walker, or `undefined`: a ray cast stops the walker in every direction,
+without waiting.
+
+The walker stands on the terrain by default. To walk on something else, a model's floors, stairs and
+tunnels, set `walkMode.groundHeight` to a function returning the ground height in meters above the
+ellipsoid at a `Cartographic`, or `undefined` while unknown.
+
+## Walking on a mesh
+
+`@geoblocks/cesium-walk/walk-mesh.js` makes triangles you know on the CPU, a building's floors, stairs and
+walls, into both what is seen and what is walked on, with no wait for the GPU:
+
+```javascript
+import CesiumWalk from '@geoblocks/cesium-walk';
+import {createWalkMesh, walkOn} from '@geoblocks/cesium-walk/walk-mesh.js';
+
+import {Group} from '@geoblocks/cesium-walk/mesh-builder.js';
+
+// groups of triangles of one color each, in meters, z up, in the frame of a model matrix
+const floor = new Group([0.8, 0.8, 0.8, 1]);
+floor.polygon([[0, 0], [10, 0], [10, 6], [0, 6]], [], () => 0);
+const walls = new Group([0.9, 0.9, 0.85, 1]);
+walls.box(0, 0, 0, 10, 0.2, 2.5);
+const mesh = await createWalkMesh([floor.walkGroup, walls.walkGroup], modelMatrix);
+viewer.scene.primitives.add(mesh.primitive);
+
+const walkMode = new CesiumWalk(viewer);
+// stand on the highest floor below the knees, climb steps up to 0.4 m, stop at the walls 0.5 m ahead
+walkOn(walkMode, mesh, {eye: 1.6, step: 0.4, reach: 0.5});
+```
+
+A group can be walked on and not seen (`show: false`), seen and not walked on (`collide: false`), cast no
+shadow (`shadows: false`), glow (`emissive`), carry texture coordinates for a custom shader (`uv`,
+`customShader`) or a baked light's atlas (`lightmap`). The faces flatter than 60° are floors, the others
+walls. `Group` (`mesh-builder.js`) builds the groups face by face: `face`, `polygon` (with holes), `sides`, `box`;
+`charts: true` records each face, to lay them out in an atlas. `mesh.floorBelow(x, y, z)` and `mesh.raycast(origin, direction, maxDistance)` answer in the
+mesh's frame and on the globe.

package/cesium-walk.js

@@ -0,0 +1,384 @@
+import {Cartesian3, Math as CesiumMath} from "@cesium/core";
+import Controls from "@geoblocks/cesium-input";
+import {ObstacleProbe, blockedStep} from "@geoblocks/cesium-obstacles";
+
+// in seconds: a frame after a backgrounded tab must not walk or fall far
+const MAX_DELTA = 0.1;
+// the head bob: a dip of DIP meters at each step of STEP_LENGTH meters, twice as deep when sprinting,
+// and of LANDING meters when landing from a jump; both settle in about BOB_TIME seconds
+const STEP_LENGTH = 0.8;
+const DIP = 0.03;
+const LANDING = 0.15;
+const BOB_TIME = 0.15;
+// in meters: nearer its height, the camera stays, so that a walker standing still renders no frame
+const SETTLED = 1e-3;
+
+// the default bindings: W, A, S, D or the arrows to walk, Shift to sprint and Space to jump; on a gamepad, the
+// left stick, at any speed and in any direction, Cross to sprint and Square to jump, as in GTA 5. Keys by
+// event.code, so that other keyboard layouts walk with the keys in the same place
+/** @satisfies {Record<string, import("@geoblocks/cesium-input").Binding>} */
+export const WALK_BINDINGS = {
+  move: {type: "vector", keys: {up: ["KeyW", "ArrowUp"], down: ["KeyS", "ArrowDown"], left: ["KeyA", "ArrowLeft"], right: ["KeyD", "ArrowRight"]}, stick: "left"},
+  sprint: {type: "button", keys: ["ShiftLeft", "ShiftRight"], buttons: [0]},
+  jump: {type: "button", keys: ["Space"], buttons: [2]},
+};
+
+/** @typedef {{move: {x: number, y: number}, sprint: boolean, jump: boolean}} WalkIntent */
+
+// the camera controller's settings off while walking: its navigation, and its collision detection, which lifts
+// the camera onto the 3D tiles under it, a roof or a coarse tile still loading over the street, whenever the
+// camera moves; the walk keeps its own height
+const CONTROLLER_SETTINGS = /** @type {const} */ (["enableTranslate", "enableZoom", "enableRotate", "enableTilt", "enableCollisionDetection"]);
+
+const normalScratch = new Cartesian3();
+const forwardScratch = new Cartesian3();
+const stepScratch = new Cartesian3();
+const allowedScratch = new Cartesian3();
+const targetScratch = new Cartesian3();
+const changeScratch = new Cartesian3();
+
+/**
+ * One step of a jump or a fall under gravity.
+ * @param {number} offset Height above the walk height, in meters.
+ * @param {number} velocity Upward speed, in meters per second.
+ * @param {number} dt Seconds.
+ * @param {number} gravity In meters per second squared.
+ * @return {[number, number]} The next offset and velocity, [0, 0] once landed.
+ */
+function jumpStep(offset, velocity, dt, gravity) {
+  const next = velocity - gravity * dt;
+  const height = offset + ((velocity + next) / 2) * dt;
+  return height <= 0 && next <= 0 ? [0, 0] : [height, next];
+}
+
+/**
+ * Whether a jump starts: on a new press only, so that holding the button does not jump again on landing.
+ * @param {boolean} pressed
+ * @param {boolean} wasPressed
+ * @param {boolean} grounded
+ * @return {boolean}
+ */
+function jumpStart(pressed, wasPressed, grounded) {
+  return pressed && !wasPressed && grounded;
+}
+
+export default class CesiumWalk {
+  /**
+   * @param {import('@cesium/engine').CesiumWidget} viewer
+   * @param {number} [speed=1.6] Walk speed in meters per second.
+   * @param {number} [height=2.0] Height of the camera above the terrain.
+   */
+  constructor(viewer, speed = 1.6, height = 2.0) {
+    /**
+     * @type {import('@cesium/engine').CesiumWidget}
+     */
+    this.viewer = viewer;
+
+    /**
+     * @type {number}
+     */
+    this.speed = speed;
+
+    /**
+     * Speed while sprinting, in meters per second.
+     * @type {number}
+     */
+    this.sprintSpeed = 3 * speed;
+
+    /**
+     * Upward speed at the start of a jump, in meters per second.
+     * @type {number}
+     */
+    this.jumpSpeed = 4;
+
+    /**
+     * The gravity of jumps and falls, in meters per second squared.
+     * @type {number}
+     */
+    this.gravity = 9.81;
+
+    /**
+     * How fast the walker reaches its speed, stops and turns, in meters per second squared; at once by
+     * default.
+     * @type {number}
+     */
+    this.acceleration = Infinity;
+
+    /**
+     * The deepest drop of the ground the walker steps down, in meters: deeper, off a ledge or a roof, it
+     * falls. By default it follows the ground whatever the drop.
+     * @type {number}
+     */
+    this.stepHeight = Infinity;
+
+    /**
+     * @type {number}
+     */
+    this.height = height;
+
+    /**
+     * @type {boolean}
+     */
+    this.active_ = false;
+
+    /**
+     * @type {number}
+     */
+    this.lastTick_ = 0;
+
+    /**
+     * Where the walker's intent comes from, read on each tick: {move: {x, y}, sprint, jump}, move no longer
+     * than 1, x right and y forward. The keyboard and the first gamepad by default, with WALK_BINDINGS; any
+     * object with a read() method otherwise: touch controls, an AI, a replay. The walk turns its active on
+     * and off with its own: replace it while the walk is not active.
+     * @type {{read(): WalkIntent, active?: boolean}}
+     */
+    this.input = new Controls(WALK_BINDINGS);
+
+    // the walker's velocity, level, on the globe
+    this.velocity_ = new Cartesian3();
+
+    // the ground under the walker on the last tick, which it keeps its height above while in the air
+    /** @type {number | undefined} */
+    this.ground_ = undefined;
+
+    // the jump or the fall: height above the walk height and upward speed; whether the jump input was down
+    // last tick
+    this.jumpOffset_ = 0;
+    this.jumpVelocity_ = 0;
+    this.jumpHeld_ = false;
+
+    /**
+     * Whether the camera bobs at each step and dips on landing, as in GTA 5's first person.
+     * @type {boolean}
+     */
+    this.headBob = false;
+
+    /**
+     * Whether the walker stops at the obstacles in view at eye height: opaque 3D tiles or primitives.
+     * @type {boolean}
+     */
+    this.collision = false;
+
+    this.obstacleProbe_ = new ObstacleProbe(viewer.scene);
+
+    /**
+     * The obstacle ahead of the walker in a direction, a point of its plane and its normal toward the walker,
+     * if any; asked for each step while collision is on. By default the obstacles in view, read in the depth
+     * of the last frame, which waits for the GPU; for a world known on the CPU, a ray cast in every direction.
+     * @type {(toward: Cartesian3, key: string) => import('@geoblocks/cesium-obstacles').Obstacle | undefined}
+     */
+    this.obstacleAhead = (toward, key) => this.obstacleProbe_.ahead(toward, key);
+
+    /**
+     * The height of the ground under a position, in meters above the ellipsoid, or undefined when unknown
+     * yet. The terrain by default; a model's floors otherwise, for a walker on several levels.
+     * @type {(position: import('@cesium/core').Cartographic) => number | undefined}
+     */
+    this.groundHeight = position => viewer.scene.globe.getHeight(position);
+
+    // whether the walker sprinted on the last tick
+    this.sprinting_ = false;
+
+    // the camera controller's settings before walking
+    /** @type {Partial<Record<typeof CONTROLLER_SETTINGS[number], boolean>>} */
+    this.controllerSettings_ = {};
+
+    // the head bob: how deep, 0 standing to 2 sprinting, along the steps; the landing dip, 0 to 1
+    this.bob_ = 0;
+    this.stepPhase_ = 0;
+    this.landing_ = 0;
+
+    this.handleTickFunction_ = this.handleTick_.bind(this);
+  }
+
+  get active() {
+    return this.active_;
+  }
+
+  /**
+   * Whether the walker is sprinting.
+   * @return {boolean}
+   */
+  get sprinting() {
+    return this.active_ && this.sprinting_;
+  }
+
+  set active(active) {
+    if (active === this.active_) {
+      return;
+    }
+    this.active_ = active;
+    const controller = this.viewer.scene.screenSpaceCameraController;
+    if (this.active_) {
+      for (const setting of CONTROLLER_SETTINGS) {
+        this.controllerSettings_[setting] = controller[setting];
+        controller[setting] = false;
+      }
+      this.lastTick_ = performance.now();
+      this.input.active = true;
+      this.viewer.clock.onTick.addEventListener(this.handleTickFunction_);
+      this.clampCameraToTerrain_();
+    } else {
+      this.input.active = false;
+      this.viewer.clock.onTick.removeEventListener(this.handleTickFunction_);
+      this.jumpOffset_ = 0;
+      this.jumpVelocity_ = 0;
+      this.ground_ = undefined;
+      Cartesian3.clone(Cartesian3.ZERO, this.velocity_);
+      this.bob_ = 0;
+      this.landing_ = 0;
+      Object.assign(controller, this.controllerSettings_);
+    }
+  }
+
+  handleTick_() {
+    const timestamp = performance.now();
+    const deltaTime = Math.min((timestamp - this.lastTick_) / 1000, MAX_DELTA);
+    this.lastTick_ = timestamp;
+
+    const {move, sprint, jump} = this.input.read();
+    let forward = move.y;
+    let right = move.x;
+    // walking diagonally is not faster
+    const magnitude = Math.hypot(forward, right);
+    if (magnitude > 1) {
+      forward /= magnitude;
+      right /= magnitude;
+    }
+
+    const grounded = this.jumpOffset_ === 0 && this.jumpVelocity_ === 0;
+    if (jumpStart(jump, this.jumpHeld_, grounded)) {
+      this.jumpVelocity_ = this.jumpSpeed;
+    }
+    this.jumpHeld_ = jump;
+    const airborne = this.jumpOffset_ > 0 || this.jumpVelocity_ > 0;
+
+    const moving = forward !== 0 || right !== 0;
+    // forward, no more sideways than diagonally, as in GTA 5
+    this.sprinting_ = sprint && forward > 0 && forward >= Math.abs(right);
+    const stopped = Cartesian3.equals(this.velocity_, Cartesian3.ZERO);
+    if (!moving && stopped && !airborne && this.bob_ === 0 && this.landing_ === 0) {
+      // standing: only the terrain refining under the walker moves it
+      this.clampCameraToTerrain_();
+      return;
+    }
+
+    const camera = this.viewer.camera;
+    const speed = this.sprinting_ ? this.sprintSpeed : this.speed;
+    // walk along the view direction projected onto the ground plane,
+    // so that looking down does not push the camera into the terrain
+    const normal = this.surfaceNormal_();
+    const along = Cartesian3.multiplyByScalar(
+      normal,
+      Cartesian3.dot(camera.direction, normal),
+      forwardScratch
+    );
+    Cartesian3.subtract(camera.direction, along, along);
+    const level = Cartesian3.magnitude(along) > CesiumMath.EPSILON6;
+    if (level) {
+      Cartesian3.normalize(along, along);
+    }
+    // the velocity, toward the intended one as fast as the acceleration allows
+    const target = Cartesian3.multiplyByScalar(camera.right, right * speed, targetScratch);
+    if (level) {
+      Cartesian3.add(target, Cartesian3.multiplyByScalar(along, forward * speed, changeScratch), target);
+    }
+    const change = Cartesian3.subtract(target, this.velocity_, changeScratch);
+    const needed = Cartesian3.magnitude(change);
+    const allowed = this.acceleration * deltaTime;
+    if (needed <= allowed) {
+      Cartesian3.clone(target, this.velocity_);
+    } else {
+      Cartesian3.add(this.velocity_, Cartesian3.multiplyByScalar(change, allowed / needed, change), this.velocity_);
+    }
+    const forwardSpeed = level ? Cartesian3.dot(this.velocity_, along) : 0;
+    const rightSpeed = Cartesian3.dot(this.velocity_, camera.right);
+    if (forwardSpeed !== 0) {
+      this.step_(along, forwardSpeed * deltaTime, "forward");
+    }
+    if (rightSpeed !== 0) {
+      this.step_(camera.right, rightSpeed * deltaTime, "right");
+    }
+    if (airborne) {
+      [this.jumpOffset_, this.jumpVelocity_] = jumpStep(this.jumpOffset_, this.jumpVelocity_, deltaTime, this.gravity);
+      if (this.headBob && this.jumpOffset_ === 0) {
+        this.landing_ = 1;
+      }
+    }
+    // the head bob, which settles once turned off
+    const ease = 1 - Math.exp(-deltaTime / BOB_TIME);
+    const bob = this.headBob && moving && !airborne ? (this.sprinting_ ? 2 : 1) : 0;
+    this.bob_ += (bob - this.bob_) * ease;
+    this.landing_ -= this.landing_ * ease;
+    // the last thousandth in one step, so that the camera stops moving
+    if (bob === 0 && this.bob_ < 1e-3) {
+      this.bob_ = 0;
+    }
+    if (this.landing_ < 1e-3) {
+      this.landing_ = 0;
+    }
+    this.stepPhase_ += (Cartesian3.magnitude(this.velocity_) * deltaTime / STEP_LENGTH) * Math.PI;
+    this.clampCameraToTerrain_();
+  }
+
+  /**
+   * Moves the camera a step, stopping at obstacles or sliding along them.
+   * @param {Cartesian3} direction The unit direction of the step, level.
+   * @param {number} step The length of the step, negative backward, in meters.
+   * @param {string} kind Which steps these are, for the obstacle looked for last time.
+   */
+  step_(direction, step, kind) {
+    const camera = this.viewer.camera;
+    const toward = Cartesian3.multiplyByScalar(direction, Math.sign(step), stepScratch);
+    const obstacle = this.collision ? this.obstacleAhead(toward, `${kind}${Math.sign(step)}`) : undefined;
+    const allowed = blockedStep(toward, Math.abs(step), camera.positionWC, obstacle, allowedScratch);
+    if (allowed.length > 0) {
+      camera.move(allowed.direction, allowed.length);
+    }
+  }
+
+  clampCameraToTerrain_() {
+    const camera = this.viewer.camera;
+    const terrainHeight = this.groundHeight(camera.positionCartographic);
+    if (terrainHeight === undefined) {
+      // ground not loaded yet at this position
+      return;
+    }
+    if (this.ground_ !== undefined) {
+      // in the air, or off a drop deeper than a step, the walker keeps its height and falls the rest
+      const drop = this.ground_ - terrainHeight;
+      if (this.jumpOffset_ > 0 || this.jumpVelocity_ !== 0 || drop > this.stepHeight) {
+        this.jumpOffset_ += drop;
+        if (this.jumpOffset_ <= 0) {
+          // on the ground again: landed, or lifted by the ground while still going up
+          this.jumpOffset_ = 0;
+          if (this.jumpVelocity_ <= 0) {
+            this.jumpVelocity_ = 0;
+            if (this.headBob) {
+              this.landing_ = 1;
+            }
+          }
+        }
+      }
+    }
+    this.ground_ = terrainHeight;
+    const cameraHeight = camera.positionCartographic.height;
+
+    // move along the surface normal, not the camera up vector, which is
+    // tilted when the camera is pitched
+    const bob = DIP * this.bob_ * Math.abs(Math.sin(this.stepPhase_)) + LANDING * this.landing_;
+    const offset = terrainHeight + this.height + this.jumpOffset_ - bob - cameraHeight;
+    if (Math.abs(offset) > SETTLED) {
+      camera.move(this.surfaceNormal_(), offset);
+    }
+  }
+
+  /**
+   * @return {import('@cesium/core').Cartesian3} The ellipsoid surface normal at the camera position.
+   */
+  surfaceNormal_() {
+    const scene = this.viewer.scene;
+    return scene.globe.ellipsoid.geodeticSurfaceNormal(scene.camera.position, normalScratch);
+  }
+}

package/mesh-builder.js

@@ -0,0 +1,109 @@
+import {Cartesian2, PolygonPipeline} from "@cesium/core";
+
+// Triangles of one color, built face by face, for createWalkMesh (walk-mesh.js).
+
+/**
+ * @typedef {object} Chart A face's place among a group's vertices, for laying it out in an atlas.
+ * @property {number} start Its first vertex.
+ * @property {number} count Its vertices.
+ * @property {number[]} normal Its normal, not of unit length.
+ */
+
+/** The normal of a flat ring of corners, by Newell's method, of any length. */
+function newell(/** @type {number[][]} */ corners) {
+  const n = [0, 0, 0];
+  corners.forEach(([x, y, z], i) => {
+    const [nx, ny, nz] = corners[(i + 1) % corners.length];
+    n[0] += (y - ny) * (z + nz);
+    n[1] += (z - nz) * (x + nx);
+    n[2] += (x - nx) * (y + ny);
+  });
+  return n;
+}
+
+export class Group {
+  /**
+   * Triangles of one color, in meters, z up.
+   * @param {number[]} color Linear, and its alpha.
+   * @param {{charts?: boolean} & Record<string, any>} [options] The walk group's (show, collide, shadows, emissive,
+   *     uv, customShader, ...), passed on; charts: each face recorded, for an atlas.
+   */
+  constructor(color, {charts = false, ...options} = {}) {
+    this.color = color;
+    this.options = options;
+    /** @type {number[]} */
+    this.positions = [];
+    /** @type {number[]} */
+    this.indices = [];
+    /** @type {Chart[] | undefined} */
+    this.charts = charts ? [] : undefined;
+  }
+
+  /**
+   * A planar convex face, its corners in order.
+   * @param {...number[]} corners [x, y, z]
+   */
+  face(...corners) {
+    const first = this.positions.length / 3;
+    corners.forEach((corner) => this.positions.push(...corner));
+    for (let i = 1; i + 1 < corners.length; i++) {
+      this.indices.push(first, first + i, first + i + 1);
+    }
+    this.charts?.push({start: first, count: corners.length, normal: newell(corners)});
+  }
+
+  /**
+   * A flat polygon with holes, its height at each corner.
+   * @param {number[][]} outline [x, y]
+   * @param {number[][][]} holes
+   * @param {(x: number, y: number) => number} z
+   */
+  polygon(outline, holes, z) {
+    const points = [outline, ...holes].flat();
+    /** @type {number[]} */
+    const starts = [];
+    let start = outline.length;
+    for (const hole of holes) {
+      starts.push(start);
+      start += hole.length;
+    }
+    const first = this.positions.length / 3;
+    points.forEach(([x, y]) => this.positions.push(x, y, z(x, y)));
+    PolygonPipeline.triangulate(points.map(([x, y]) => new Cartesian2(x, y)), starts).forEach((i) => this.indices.push(first + i));
+    this.charts?.push({start: first, count: points.length, normal: newell(outline.map(([x, y]) => [x, y, z(x, y)]))});
+  }
+
+  /**
+   * The faces of a ring between two heights.
+   * @param {number[][]} ring [x, y]
+   * @param {number} z0
+   * @param {number} z1
+   */
+  sides(ring, z0, z1) {
+    ring.forEach((a, i) => {
+      const b = ring[(i + 1) % ring.length];
+      this.face([...a, z0], [...b, z0], [...b, z1], [...a, z1]);
+    });
+  }
+
+  /**
+   * An axis-aligned box.
+   * @param {number} x0
+   * @param {number} y0
+   * @param {number} z0
+   * @param {number} x1
+   * @param {number} y1
+   * @param {number} z1
+   */
+  box(x0, y0, z0, x1, y1, z1) {
+    this.sides([[x0, y0], [x1, y0], [x1, y1], [x0, y1]], z0, z1);
+    this.face([x0, y0, z1], [x1, y0, z1], [x1, y1, z1], [x0, y1, z1]);
+    this.face([x0, y0, z0], [x1, y0, z0], [x1, y1, z0], [x0, y1, z0]);
+  }
+
+  /** The group for createWalkMesh: its color, vertices and triangles, its options, its charts if recorded. */
+  get walkGroup() {
+    return {color: this.color, vertices: new Float32Array(this.positions), triangles: new Uint32Array(this.indices), ...this.options,
+      ...(this.charts ? {charts: this.charts} : {})};
+  }
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@geoblocks/cesium-walk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geoblocks/cesium-helpers/",
+    "directory": "packages/cesium-walk"
+  },
+  "main": "cesium-walk.js",
+  "module": "cesium-walk.js",
+  "sideEffects": false,
+  "exports": {
+    ".": "./cesium-walk.js",
+    "./walk-mesh.js": "./walk-mesh.js",
+    "./mesh-builder.js": "./mesh-builder.js"
+  },
+  "files": [
+    "cesium-walk.js",
+    "walk-mesh.js",
+    "mesh-builder.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@geoblocks/cesium-input": "^0.1.0",
+    "@geoblocks/cesium-obstacles": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@cesium/core": ">=0.1.0",
+    "@cesium/engine": ">=10"
+  }
+}

package/walk-mesh.js

@@ -0,0 +1,443 @@
+import {Cartesian3, Cartographic, Ellipsoid, Matrix4} from "@cesium/core";
+import {Axis, Model, PrimitiveCollection, ShadowMode} from "@cesium/engine";
+
+// Triangles to walk on, in meters, z up, in the frame of a model matrix: their models, and the floors and
+// walls a walker meets, without reading the depth, which waits for the GPU.
+
+// the ground's cells, in meters
+const CELL = 2;
+// the faces flatter than this, of the cosine of their slope, are floors, stairs and ramps
+const FLOOR = 0.5;
+
+const originScratch = new Cartesian3();
+const directionScratch = new Cartesian3();
+const upScratch = new Cartesian3();
+const rayScratch = new Cartesian3();
+const rayOriginScratch = new Cartesian3();
+const kneesScratch = new Cartographic();
+const floorScratch = new Cartesian3();
+const floorCartographicScratch = new Cartographic();
+
+/**
+ * @typedef {object} WalkGroup Triangles of one color.
+ * @property {number[]} color The base color, linear, and its alpha: translucent below 1.
+ * @property {Float32Array} vertices x, y, z, in meters, z up.
+ * @property {Uint32Array} triangles
+ * @property {boolean} [show] false: walked on, not seen (an invisible edge).
+ * @property {boolean} [collide] false: seen, not walked on (the battens, the water).
+ * @property {boolean} [shadows] false: casts no shadow (the glass, the water).
+ * @property {number} [emissive] The share of its color it gives off: the light indoors, which Cesium does not
+ *     bounce off the walls.
+ * @property {boolean} [uv] Whether its vertices carry their x and y as texture coordinates, in meters, for a
+ *     shader drawing on the floors.
+ * @property {Float32Array} [lightmap] Its vertices' coordinates in a baked light's atlas, u and v each, written as
+ *     the second texture coordinates.
+ * @property {import("@cesium/engine").CustomShader} [customShader]
+ */
+
+/**
+ * The flat shaded model of the triangles, untextured, in glTF's y up, quantized (KHR_mesh_quantization):
+ * the positions in 16 bits, scaled back to meters by the node; the normals in 8 bits; each vertex padded to
+ * 4 bytes, 12 in all, as against 24 in floats. Exported for the tests.
+ * @param {Float32Array} vertices
+ * @param {Uint32Array} triangles
+ * @param {number[]} color
+ * @param {number} emissive
+ * @param {boolean} uv Whether to give the vertices their x and y as texture coordinates, in floats.
+ * @param {Float32Array | undefined} lightmap The vertices' second texture coordinates, in floats, if any.
+ * @return {ArrayBuffer} The binary glTF.
+ */
+export function toGlb(vertices, triangles, color, emissive, uv, lightmap) {
+  const count = triangles.length;
+  // the extent of the map, in glTF's axes
+  const toGltf = (/** @type {number} */ v) => [vertices[v], vertices[v + 2], -vertices[v + 1]];
+  const low = [Infinity, Infinity, Infinity];
+  const high = [-Infinity, -Infinity, -Infinity];
+  for (let v = 0; v < vertices.length; v += 3) {
+    toGltf(v).forEach((value, axis) => {
+      low[axis] = Math.min(low[axis], value);
+      high[axis] = Math.max(high[axis], value);
+    });
+  }
+  // the node maps -32767..32767 back to the widest extent, the same on every axis, which leaves the
+  // normals as they are
+  const translation = low.map((value, axis) => (value + high[axis]) / 2);
+  // a single point: any step keeps it at the node's translation
+  const step = Math.max(...low.map((value, axis) => high[axis] - value)) / 65534 || 1;
+  const scale = [step, step, step];
+  const positions = new Int16Array(count * 4);
+  const normals = new Int8Array(count * 4);
+  const texCoords = new Float32Array(uv ? count * 2 : 0);
+  const lightmapCoords = new Float32Array(lightmap ? count * 2 : 0);
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < count; i += 3) {
+    const corners = [0, 1, 2].map(k => toGltf(triangles[i + k] * 3));
+    const [a, b, c] = corners.map(([x, y, z]) => new Cartesian3(x, y, z));
+    const normal = Cartesian3.cross(Cartesian3.subtract(b, a, new Cartesian3()), Cartesian3.subtract(c, a, new Cartesian3()), new Cartesian3());
+    if (Cartesian3.magnitudeSquared(normal) > 0) {
+      Cartesian3.normalize(normal, normal);
+    }
+    corners.forEach((corner, k) => {
+      const quantized = corner.map((value, axis) => Math.round((value - translation[axis]) / step));
+      positions.set(quantized, (i + k) * 4);
+      normals.set([normal.x, normal.y, normal.z].map(n => Math.round(n * 127)), (i + k) * 4);
+      for (let axis = 0; axis < 3; axis++) {
+        min[axis] = Math.min(min[axis], quantized[axis]);
+        max[axis] = Math.max(max[axis], quantized[axis]);
+      }
+      if (uv) {
+        const v = triangles[i + k] * 3;
+        texCoords.set([vertices[v], vertices[v + 1]], (i + k) * 2);
+      }
+      if (lightmap) {
+        const v = triangles[i + k];
+        lightmapCoords.set([lightmap[v * 2], lightmap[v * 2 + 1]], (i + k) * 2);
+      }
+    });
+  }
+  // the float attributes after the positions and normals, each its own buffer view
+  const floats = /** @type {[string, Float32Array][]} */ ([...(uv ? [['TEXCOORD_0', texCoords]] : []), ...(lightmap ? [['TEXCOORD_1', lightmapCoords]] : [])]);
+  const floatsLength = floats.reduce((n, [, array]) => n + array.byteLength, 0);
+  let floatOffset = positions.byteLength + normals.byteLength;
+  const json = new TextEncoder().encode(JSON.stringify({
+    asset: {version: '2.0'},
+    extensionsUsed: ['KHR_mesh_quantization', ...(emissive > 1 ? ['KHR_materials_emissive_strength'] : [])],
+    extensionsRequired: ['KHR_mesh_quantization'],
+    scene: 0,
+    scenes: [{nodes: [0]}],
+    nodes: [{mesh: 0, translation, scale}],
+    meshes: [{primitives: [{attributes: {POSITION: 0, NORMAL: 1, ...Object.fromEntries(floats.map(([name], k) => [name, 2 + k]))}, material: 0}]}],
+    materials: [{
+      pbrMetallicRoughness: {baseColorFactor: color, metallicFactor: 0, roughnessFactor: 1},
+      // glTF caps the factor at 1, the strength carries the rest
+      emissiveFactor: color.slice(0, 3).map(c => Math.min(Math.max(c * Math.min(emissive, 1), 0), 1)),
+      ...(emissive > 1 ? {extensions: {KHR_materials_emissive_strength: {emissiveStrength: emissive}}} : {}),
+      doubleSided: true,
+      ...(color[3] < 1 ? {alphaMode: 'BLEND'} : {}),
+    }],
+    buffers: [{byteLength: positions.byteLength + normals.byteLength + floatsLength}],
+    bufferViews: [
+      {buffer: 0, byteOffset: 0, byteLength: positions.byteLength, byteStride: 8, target: 34962},
+      {buffer: 0, byteOffset: positions.byteLength, byteLength: normals.byteLength, byteStride: 4, target: 34962},
+      ...floats.map(([, array]) => {
+        const view = {buffer: 0, byteOffset: floatOffset, byteLength: array.byteLength, target: 34962};
+        floatOffset += array.byteLength;
+        return view;
+      }),
+    ],
+    accessors: [
+      {bufferView: 0, componentType: 5122, count, type: 'VEC3', min, max},
+      {bufferView: 1, componentType: 5120, normalized: true, count, type: 'VEC3'},
+      ...floats.map((_, k) => ({bufferView: 2 + k, componentType: 5126, count, type: 'VEC2'})),
+    ],
+  }));
+  const jsonLength = Math.ceil(json.length / 4) * 4;
+  const binLength = positions.byteLength + normals.byteLength + floatsLength;
+  const glb = new ArrayBuffer(12 + 8 + jsonLength + 8 + binLength);
+  const view = new DataView(glb);
+  view.setUint32(0, 0x46546c67, true);
+  view.setUint32(4, 2, true);
+  view.setUint32(8, glb.byteLength, true);
+  view.setUint32(12, jsonLength, true);
+  view.setUint32(16, 0x4e4f534a, true);
+  new Uint8Array(glb, 20, jsonLength).fill(0x20).set(json);
+  view.setUint32(20 + jsonLength, binLength, true);
+  view.setUint32(24 + jsonLength, 0x004e4942, true);
+  new Int16Array(glb, 28 + jsonLength, count * 4).set(positions);
+  new Int8Array(glb, 28 + jsonLength + positions.byteLength, count * 4).set(normals);
+  let offset = 28 + jsonLength + positions.byteLength + normals.byteLength;
+  for (const [, array] of floats) {
+    new Float32Array(glb, offset, array.length).set(array);
+    offset += array.byteLength;
+  }
+  return glb;
+}
+
+/**
+ * @param {WalkGroup[]} groups
+ * @param {Matrix4} modelMatrix From the triangles' frame to the globe.
+ */
+export async function createWalkMesh(groups, modelMatrix) {
+  // a single point, or nothing, has nothing to draw
+  const visible = groups.filter(group => group.show !== false && group.triangles.length > 0 &&
+    group.vertices.some((value, k) => value !== group.vertices[k % 3]));
+  const urls = visible.map(group => URL.createObjectURL(new Blob([toGlb(group.vertices, group.triangles, group.color, group.emissive ?? 0, group.uv ?? false, group.lightmap)], {type: 'model/gltf-binary'})));
+  const loaded = await Promise.allSettled(visible.map(async (group, k) => {
+    // with glTF's y up only: Cesium would also turn the model's +z to +x, a quarter turn off the frame's axes
+    const model = await Model.fromGltfAsync({
+      url: urls[k],
+      modelMatrix,
+      forwardAxis: Axis.X,
+      shadows: group.shadows === false ? ShadowMode.RECEIVE_ONLY : ShadowMode.ENABLED,
+      ...(group.customShader ? {customShader: group.customShader} : {}),
+    });
+    model.readyEvent.addEventListener(() => URL.revokeObjectURL(urls[k]));
+    model.errorEvent.addEventListener(() => URL.revokeObjectURL(urls[k]));
+    return model;
+  }));
+  // in the groups' order
+  const primitive = new PrimitiveCollection();
+  for (const result of loaded) {
+    if (result.status === 'fulfilled') {
+      primitive.add(result.value);
+    }
+  }
+  const failed = loaded.find(result => result.status === 'rejected');
+  if (failed) {
+    primitive.destroy();
+    urls.forEach(url => URL.revokeObjectURL(url));
+    throw failed.reason;
+  }
+
+  // the groups walked on as one: their vertices one after the other, their triangles renumbered
+  const colliding = groups.filter(group => group.collide !== false);
+  const vertices = new Float32Array(colliding.reduce((n, group) => n + group.vertices.length, 0));
+  const triangles = new Uint32Array(colliding.reduce((n, group) => n + group.triangles.length, 0));
+  let vertexOffset = 0;
+  let triangleOffset = 0;
+  for (const group of colliding) {
+    vertices.set(group.vertices, vertexOffset);
+    for (let k = 0; k < group.triangles.length; k++) {
+      triangles[triangleOffset + k] = group.triangles[k] + vertexOffset / 3;
+    }
+    vertexOffset += group.vertices.length;
+    triangleOffset += group.triangles.length;
+  }
+  const toLocal = Matrix4.inverse(modelMatrix, new Matrix4());
+  // the normals' matrix, the inverse transpose
+  const toNormal = Matrix4.transpose(toLocal, new Matrix4());
+
+  // the triangles, and the floors among them, by the cells they overlap
+  /** @type {Map<string, number[]>} */
+  const cells = new Map();
+  /** @type {Map<string, number[]>} */
+  const allCells = new Map();
+  const isFloor = new Uint8Array(triangles.length / 3);
+  const vertex = (/** @type {number} */ index) => vertices.subarray(index * 3, index * 3 + 3);
+  const add = (/** @type {Map<string, number[]>} */ map, /** @type {string} */ key, /** @type {number} */ i) => {
+    const list = map.get(key);
+    if (list) {
+      list.push(i);
+    } else {
+      map.set(key, [i]);
+    }
+  };
+  for (let i = 0; i < triangles.length; i += 3) {
+    const [a, b, c] = [vertex(triangles[i]), vertex(triangles[i + 1]), vertex(triangles[i + 2])];
+    const nx = (b[1] - a[1]) * (c[2] - a[2]) - (b[2] - a[2]) * (c[1] - a[1]);
+    const ny = (b[2] - a[2]) * (c[0] - a[0]) - (b[0] - a[0]) * (c[2] - a[2]);
+    const nz = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+    isFloor[i / 3] = Math.abs(nz) >= FLOOR * Math.hypot(nx, ny, nz) ? 1 : 0;
+    for (let x = Math.floor(Math.min(a[0], b[0], c[0]) / CELL); x <= Math.floor(Math.max(a[0], b[0], c[0]) / CELL); x++) {
+      for (let y = Math.floor(Math.min(a[1], b[1], c[1]) / CELL); y <= Math.floor(Math.max(a[1], b[1], c[1]) / CELL); y++) {
+        const key = `${x},${y}`;
+        add(allCells, key, i);
+        if (isFloor[i / 3]) {
+          add(cells, key, i);
+        }
+      }
+    }
+  }
+
+  /**
+   * The highest floor at a position of the frame, not above it.
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   * @return {number | undefined} Its height, in meters.
+   */
+  const floorBelow = (x, y, z) => {
+    let highest;
+    for (const i of cells.get(`${Math.floor(x / CELL)},${Math.floor(y / CELL)}`) ?? []) {
+      const a = triangles[i] * 3, b = triangles[i + 1] * 3, c = triangles[i + 2] * 3;
+      const ux = vertices[b] - vertices[a], uy = vertices[b + 1] - vertices[a + 1];
+      const vx = vertices[c] - vertices[a], vy = vertices[c + 1] - vertices[a + 1];
+      const d = ux * vy - vx * uy;
+      if (d === 0) {
+        continue;
+      }
+      const s = ((x - vertices[a]) * vy - vx * (y - vertices[a + 1])) / d;
+      const t = (ux * (y - vertices[a + 1]) - (x - vertices[a]) * uy) / d;
+      if (s < 0 || t < 0 || s + t > 1) {
+        continue;
+      }
+      const height = vertices[a + 2] + s * (vertices[b + 2] - vertices[a + 2]) + t * (vertices[c + 2] - vertices[a + 2]);
+      if (height <= z && (highest === undefined || height > highest)) {
+        highest = height;
+      }
+    }
+    return highest;
+  };
+
+  // the ray each triangle was last tested against, so that a triangle over several cells is tested once
+  const tested = new Uint32Array(triangles.length / 3);
+  let ray = 0;
+  /**
+   * The nearest triangle along a ray, in meters, by Möller and Trumbore's test, through the cells the
+   * ray crosses, nearest first.
+   * @param {Cartesian3} o The origin.
+   * @param {Cartesian3} d The unit direction.
+   * @param {number} far The longest distance.
+   * @param {boolean} walls Whether to skip the floors.
+   * @return {{distance: number, triangle: number} | undefined}
+   */
+  const nearestHit = (o, d, far, walls) => {
+    ray++;
+    let best;
+    let x = Math.floor(o.x / CELL);
+    let y = Math.floor(o.y / CELL);
+    const stepX = Math.sign(d.x);
+    const stepY = Math.sign(d.y);
+    // the distances along the ray to the next cell borders, and between borders
+    let nextX = stepX === 0 ? Infinity : ((x + (stepX > 0 ? 1 : 0)) * CELL - o.x) / d.x;
+    let nextY = stepY === 0 ? Infinity : ((y + (stepY > 0 ? 1 : 0)) * CELL - o.y) / d.y;
+    const deltaX = stepX === 0 ? Infinity : CELL / Math.abs(d.x);
+    const deltaY = stepY === 0 ? Infinity : CELL / Math.abs(d.y);
+    let entry = 0;
+    while (entry <= far) {
+      const exit = Math.min(nextX, nextY, far);
+      for (const i of allCells.get(`${x},${y}`) ?? []) {
+        if (tested[i / 3] === ray || (walls && isFloor[i / 3])) {
+          continue;
+        }
+        tested[i / 3] = ray;
+        const a = triangles[i] * 3, b = triangles[i + 1] * 3, c = triangles[i + 2] * 3;
+        const e1x = vertices[b] - vertices[a], e1y = vertices[b + 1] - vertices[a + 1], e1z = vertices[b + 2] - vertices[a + 2];
+        const e2x = vertices[c] - vertices[a], e2y = vertices[c + 1] - vertices[a + 1], e2z = vertices[c + 2] - vertices[a + 2];
+        const px = d.y * e2z - d.z * e2y, py = d.z * e2x - d.x * e2z, pz = d.x * e2y - d.y * e2x;
+        const det = e1x * px + e1y * py + e1z * pz;
+        if (Math.abs(det) < 1e-9) {
+          continue;
+        }
+        const sx = o.x - vertices[a], sy = o.y - vertices[a + 1], sz = o.z - vertices[a + 2];
+        const u = (sx * px + sy * py + sz * pz) / det;
+        if (u < 0 || u > 1) {
+          continue;
+        }
+        const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;
+        const v = (d.x * qx + d.y * qy + d.z * qz) / det;
+        if (v < 0 || u + v > 1) {
+          continue;
+        }
+        const t = (e2x * qx + e2y * qy + e2z * qz) / det;
+        if (t >= 0 && t <= far && (!best || t < best.distance)) {
+          best = {distance: t, triangle: i};
+        }
+      }
+      // a hit within this cell is the nearest; one beyond it may still be beaten in the next cells
+      if (best && best.distance <= exit) {
+        return best;
+      }
+      if (exit >= far) {
+        return best;
+      }
+      entry = exit;
+      if (nextX < nextY) {
+        x += stepX;
+        nextX += deltaX;
+      } else {
+        y += stepY;
+        nextY += deltaY;
+      }
+    }
+    return best;
+  };
+
+  return {
+    primitive,
+    floorBelow,
+    /**
+     * The first surface along a ray on the globe.
+     * @param {Cartesian3} origin
+     * @param {Cartesian3} direction A unit vector.
+     * @param {number} maxDistance In meters.
+     * @param {{walls?: boolean}} [options] walls: skip the floors, stairs and ramps, which the walker climbs.
+     * @return {{position: Cartesian3, normal: Cartesian3, distance: number} | undefined} Where the
+     *     ray stops, the surface's normal toward the ray's origin, and the distance in meters.
+     */
+    raycast: (origin, direction, maxDistance, {walls = false} = {}) => {
+      const o = Matrix4.multiplyByPoint(toLocal, origin, originScratch);
+      const d = Matrix4.multiplyByPointAsVector(toLocal, direction, directionScratch);
+      // the frame's units in a meter along the ray, should the matrix scale
+      const perMeter = Cartesian3.magnitude(d);
+      Cartesian3.divideByScalar(d, perMeter, d);
+      const hit = nearestHit(o, d, maxDistance * perMeter, walls);
+      if (!hit) {
+        return undefined;
+      }
+      const position = Matrix4.multiplyByPoint(modelMatrix, Cartesian3.add(o, Cartesian3.multiplyByScalar(d, hit.distance, rayScratch), rayScratch), new Cartesian3());
+      const i = hit.triangle;
+      const [a, b, c] = [vertex(triangles[i]), vertex(triangles[i + 1]), vertex(triangles[i + 2])];
+      const e1 = new Cartesian3(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+      const e2 = new Cartesian3(c[0] - a[0], c[1] - a[1], c[2] - a[2]);
+      const normal = Matrix4.multiplyByPointAsVector(toNormal, Cartesian3.cross(e1, e2, e1), new Cartesian3());
+      Cartesian3.normalize(normal, normal);
+      if (Cartesian3.dot(normal, direction) > 0) {
+        Cartesian3.negate(normal, normal);
+      }
+      return {position, normal, distance: Cartesian3.distance(origin, position)};
+    },
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {Cartesian3} [result]
+     * @return {Cartesian3} A position of the frame on the globe.
+     */
+    position: (x, y, z, result = new Cartesian3()) => Matrix4.multiplyByPoint(modelMatrix, Cartesian3.fromElements(x, y, z, result), result),
+    /**
+     * @param {Cartesian3} position
+     * @param {Cartesian3} [result]
+     * @return {Cartesian3} A position on the globe in the frame.
+     */
+    local: (/** @type {Cartesian3} */ position, result = new Cartesian3()) => Matrix4.multiplyByPoint(toLocal, position, result),
+  };
+}
+
+/**
+ * The heights above the floor the walls are looked for at: the knees, the waist and the eyes.
+ * @param {number} eye
+ * @param {number} step
+ * @return {number[]} In meters, from the lowest.
+ */
+export function rayHeights(eye, step) {
+  return [step + 0.05, (step + eye) / 2, eye];
+}
+
+/**
+ * Walks a CesiumWalk on a mesh: it stands on the highest floor below its knees, up the stairs, under the
+ * arches, else on what it stood on before (the terrain); the walls ahead stop it, from rays cast at the knees,
+ * the waist and the eyes, the floors and stairs left to the ground below, in every direction.
+ * @param {import('./cesium-walk.js').default} walk
+ * @param {Awaited<ReturnType<typeof createWalkMesh>>} mesh
+ * @param {{eye: number, step: number, reach: number}} options In meters: the eyes above the floor, the
+ *     highest step, how far ahead the walls are looked for.
+ */
+export function walkOn(walk, mesh, {eye, step, reach}) {
+  const camera = walk.viewer.scene.camera;
+  const fallback = walk.groundHeight;
+  const heights = rayHeights(eye, step);
+  const walls = {walls: true};
+  walk.obstacleAhead = toward => {
+    const eyes = camera.positionWC;
+    const up = Ellipsoid.WGS84.geodeticSurfaceNormal(eyes, upScratch);
+    let nearest;
+    for (const height of heights) {
+      const origin = Cartesian3.add(eyes, Cartesian3.multiplyByScalar(up, height - eye, rayOriginScratch), rayOriginScratch);
+      const hit = mesh.raycast(origin, toward, reach, walls);
+      if (hit && (!nearest || hit.distance < nearest.distance)) {
+        nearest = hit;
+      }
+    }
+    return nearest && {point: nearest.position, normal: nearest.normal};
+  };
+  walk.groundHeight = cartographic => {
+    const knees = Cartographic.clone(cartographic, kneesScratch);
+    knees.height -= eye - step;
+    const {x, y, z} = mesh.local(Cartographic.toCartesian(knees, Ellipsoid.WGS84, floorScratch), floorScratch);
+    const floor = mesh.floorBelow(x, y, z);
+    return floor === undefined ? fallback(cartographic) :
+      Cartographic.fromCartesian(mesh.position(x, y, floor, floorScratch), Ellipsoid.WGS84, floorCartographicScratch).height;
+  };
+}