@bimangle/cesium-tool-tour

v1.0.0

Published

8 days ago

A Cesium plugin providing first-person scene tour navigation with keyboard, mouse and virtual joystick support.

0High
0Medium
0Low

bimangle.liu

cesium tour roam navigate first-person 3dtiles bimangle

@bimangle/cesium-tool-tour

A Cesium plugin providing first-person scene tour (漫游导航) navigation.
适用于 Cesium 三维场景的第一人称漫游导航插件。

Supports keyboard + mouse (Pointer Lock) mode and a virtual joystick panel mode for touch devices.
支持键鼠模式（Pointer Lock）和触控友好的虚拟摇杆模式。

Features / 功能特性

Keyboard mode — WASD + QE movement, mouse look via Pointer Lock
键盘模式：WASD + QE 移动，鼠标通过 Pointer Lock 控制视角
Virtual joystick mode — on-screen WASDQE buttons + draggable joystick; works on touch devices without interfering with Cesium native gestures
虚拟摇杆模式：屏幕按键 + 可拖拽摇杆，适合触控设备且不干扰 Cesium 原生操作
Step distance — 0.001 / 0.01 / 0.1 / 1.0 m per keypress (default 1.0 m)
移动步距：0.001 / 0.01 / 0.1 / 1.0 m（默认 1.0 m）
Hold-key acceleration — continuous movement at 30× step distance/s after 300 ms hold
按住加速：持续按住 300 ms 后以 30 倍步距/秒连续移动
Mouse wheel — scroll up to move forward, scroll down to move backward (5× step distance per notch)
鼠标滚轮：向上滚前进，向下滚后退，每格 5 倍步距
Double-click to advance — double-click a scene object to fly halfway toward it; camera faces the target
双击推进：双击场景中的目标点，镜头朝目标点平滑飞行到中点处
Fly / Horizontal mode — choose whether W/S follows camera pitch or stays on the horizontal plane
飞行 / 水平模式：W/S 可沿相机方向或仅在水平面移动
Bilingual UI — Chinese (zh-*) or English based on navigator.language
双语界面：根据 navigator.language 自动切换中文或英文
Integrates with cesium-tool-measure — automatically cancels active measurement when tour mode starts
与测量插件协同：漫游激活时自动取消正在进行的测量

Installation / 安装

NPM

npm install @bimangle/cesium-tool-tour

CDN

<!-- Cesium must be loaded first / 必须先加载 Cesium -->
<script src="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Widgets/widgets.css" rel="stylesheet">

<!-- Then include cesium-ui and cesium-tool-tour / 再引入 cesium-ui 和 cesium-tool-tour -->
<script src="https://unpkg.com/@bimangle/cesium-ui/dist/cesium-ui.js"></script>
<script src="https://unpkg.com/@bimangle/cesium-tool-tour/dist/cesium-tool-tour.js"></script>

Quick Start / 快速开始

Browser (CDN)

<!DOCTYPE html>
<html>
<head>
  <script src="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Cesium.js"></script>
  <link href="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
  <script src="https://unpkg.com/@bimangle/cesium-ui/dist/cesium-ui.js"></script>
  <script src="https://unpkg.com/@bimangle/cesium-tool-tour/dist/cesium-tool-tour.js"></script>
  <style>
    html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; }
  </style>
</head>
<body>
  <div id="cesiumContainer"></div>
  <script>
    const viewer = new Cesium.Viewer('cesiumContainer');

    // One line — cesium-ui is initialized automatically.
    // 一行接入，cesium-ui 会自动初始化。
    viewer.extend(ToolTourMixin);

    // Access the instance / 访问实例
    // viewer.toolTour  → ToolTour instance
  </script>
</body>
</html>

NPM / ES Modules

import * as Cesium from 'cesium';
import { ToolTourMixin } from '@bimangle/cesium-tool-tour';

const viewer = new Cesium.Viewer('cesiumContainer');

// One line — cesium-ui is initialized automatically.
// 一行接入，cesium-ui 会自动初始化。
viewer.extend(ToolTourMixin);

// Access the instance / 访问实例
// viewer.toolTour  → ToolTour instance

To customize the toolbar position / 自定义工具栏位置：

viewer.extend(ToolTourMixin, {
    uiOptions: {
        position:              'top-left',
        direction:             'vertical',
        notificationPosition:  'bottom-right',
        panelCascadeDirection: 'right',
    }
});

To co-exist with the measure plugin / 与测量插件共存：

viewer.extend(ToolMeasureMixin);
viewer.extend(ToolTourMixin);  // shares the same toolbar / 共享同一工具栏

Controls / 操作说明

Keyboard mode / 键鼠模式

| Key / 按键 | Action / 动作 | |------------|---------------| | W / ↑ | Move forward / 向前 | | S / ↓ | Move backward / 向后 | | A / ← | Move left / 向左 | | D / → | Move right / 向右 | | Q / PageUp | Move up / 向上 | | E / PageDown | Move down / 向下 | | Mouse move | Rotate view (Pointer Lock) / 旋转视角（Pointer Lock）| | Left-drag | Rotate view (degraded mode) / 旋转视角（降级模式）| | Scroll wheel ↑ | Move forward / 向前移动 | | Scroll wheel ↓ | Move backward / 向后移动 | | Left double-click | Fly halfway to target / 飞向目标中点 | | Esc | Exit tour mode / 退出漫游 |

Click ▶ Start Tour / ▶ 开始漫游 in the panel, then move the mouse to look around.
点击面板中的 ▶ 开始漫游 按钮后，移动鼠标控制视角。

Virtual joystick mode / 虚拟摇杆模式

Check Virtual Joystick / 虚拟摇杆 in the panel. Controls are immediately available:
勾选面板中的 虚拟摇杆 选项，控件立即可用：

WASDQE buttons — same movement as keyboard / 与键盘相同的移动操作
Joystick pad — drag to rotate the camera view / 拖拽旋转视角
Cesium native pan / orbit gestures remain fully active outside the panel / 面板外 Cesium 原生操作不受影响

API

// viewer.extend() — recommended entry point (idempotent)
// viewer.extend() — 推荐的初始化方式（幂等）
viewer.extend(ToolTourMixin);
viewer.extend(ToolTourMixin, options);  // with options / 带配置项

// Direct class usage / 直接使用类
const tool = new ToolTour(viewer, options);

// Access via viewer property (set by Mixin)
// 通过 viewer 属性访问（由 Mixin 设置）
viewer.toolTour.activate();    // Enter keyboard mode / 进入键鼠模式
viewer.toolTour.deactivate();  // Exit keyboard mode / 退出键鼠模式
viewer.toolTour.destroy();     // Full cleanup / 完整销毁

Options / 配置项

| Option | Type | Default | Description | |--------|------|---------|-------------| | uiOptions | object | {} | Passed to CesiumUIMixin if cesiumUI not yet initialised / 若 cesiumUI 尚未初始化时传入 |

Technical Notes / 技术说明

Mouse input / 鼠标输入

Mouse look is handled via Cesium.ScreenSpaceEventHandler bound to the scene canvas, which operates inside Cesium's own event pipeline and is unaffected by stopPropagation or pointer capture from other elements.
鼠标视角通过绑定在 canvas 上的 Cesium.ScreenSpaceEventHandler 处理，工作在 Cesium 自身事件管道内，不受外部 stopPropagation 影响。

Pointer Lock mode: cursor is hidden, MOUSE_MOVE delta is used directly.
Degraded mode (Pointer Lock denied / iframe): left-button drag (LEFT_DOWN → MOUSE_MOVE → LEFT_UP) controls view rotation.

Mouse wheel / 滚轮前进后退

The WHEEL event from ScreenSpaceEventHandler is used. Scroll up (positive delta) = move forward; scroll down = move backward. Each standard notch (120 units) moves stepDist × 5.
通过 ScreenSpaceEventHandler 的 WHEEL 事件处理滚轮输入。向上滚（正值）为前进，向下滚为后退，每格移动 stepDist × 5。

Double-click advance / 双击推进

Double-clicking in keyboard mode picks the 3-D scene position under the cursor (scene.pickPosition → fallback to globe.pick) and flies the camera to the midpoint between its current position and the picked point. The camera is oriented to face the target throughout the flight. If nothing is picked (sky), the action is ignored.
双击时拾取光标下方的三维坐标，镜头平滑飞行到当前位置与目标点的中间处，飞行期间镜头保持面向目标点。点击天空时忽略。

Keyboard mode implementation / 键鼠模式实现

Calls canvas.requestPointerLock() to enable unlimited mouse movement
调用 canvas.requestPointerLock() 实现无限制鼠标移动
Disables viewer.scene.screenSpaceCameraController (all axes) while active, restores on exit
激活时禁用 screenSpaceCameraController，退出时自动恢复原始状态
Listens for pointerlockchange to handle unexpected unlock (e.g. Alt+Tab)
监听 pointerlockchange 处理意外解锁（如 Alt+Tab）

Hold-key acceleration / 持续按键加速

keydown → immediate single move (stepDist)
          ↓ after 300 ms hold
          continuous: stepDist × 30 × Δt (m/s)
keyup   → stop

Implemented via a Map<code, { pressTime, singleFired }> polled on every clock.onTick frame.
通过 clock.onTick 每帧轮询 Map<code, { pressTime, singleFired }> 实现。

Pitch clamping / 俯仰角限制

Cesium's camera.pitch is read-only. Pitch is clamped to [-85°, +85°] by accumulating the applied lookUp delta in _pitchAccum and refusing to exceed the limits.
Cesium 的 camera.pitch 为只读，通过累积 lookUp 增量并限制在 [-85°, +85°] 内实现俯仰角钳制。

Horizontal mode / 水平模式

In horizontal mode, W/S/A/D movement direction is projected onto the local tangent plane using the ellipsoid geodetic surface normal at the camera position, so forward/backward/left/right movement is always parallel to the ground regardless of camera pitch.
水平模式下，WASD 移动方向通过椭球面法线投影到切平面，无论俯仰角如何，前后左右始终与地面平行。

Virtual joystick event isolation / 虚拟摇杆事件隔离

All pointer events inside the joystick area call stopPropagation() and preventDefault(), so they never reach Cesium's canvas event handlers.
摇杆区域内的所有 pointer 事件均调用 stopPropagation() 和 preventDefault()，不会传递到 Cesium 的 canvas 事件处理器。

CSS Class Reference / CSS 命名规范

All classes use the ba-ctt- prefix (ba = BimAngle, ctt = cesium-tool-tour).
所有 CSS 类名采用 ba-ctt- 前缀。

| Class | Purpose | |-------|---------| | .ba-ctt-panel | Sub-panel container | | .ba-ctt-panel--visible | Sub-panel visible state | | .ba-ctt-panel-header | Title bar (draggable) | | .ba-ctt-section | Config section block | | .ba-ctt-radio-group | Step-distance radio group | | .ba-ctt-mode-btn | View mode toggle button | | .ba-ctt-mode-btn--active | Active view mode button | | .ba-ctt-checkbox-row | Joystick toggle row | | .ba-ctt-start-btn | Start Tour button | | .ba-ctt-joystick-area | Expandable joystick section | | .ba-ctt-joystick-area--visible | Joystick section visible state | | .ba-ctt-vbtns | Virtual button grid | | .ba-ctt-vbtn | Individual virtual button | | .ba-ctt-vbtn--pressed | Virtual button pressed state | | .ba-ctt-vjoy-pad | Joystick outer pad | | .ba-ctt-vjoy-knob | Joystick inner knob | | .ba-ctt-vjoy-knob--active | Knob dragging state | | .ba-ctt-hud | HUD overlay bar (keyboard mode) | | .ba-ctt-hud--visible | HUD visible state |

Compatibility / 兼容性

CesiumJS ≥ 1.110.0
Chrome 90+, Firefox 88+, Edge 90+, Safari 15+
Pointer Lock API required for keyboard mode / 键鼠模式需要 Pointer Lock API 支持

Build / 构建

npm install
npm run build
# Output: dist/cesium-tool-tour.js

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@bimangle/cesium-tool-tour

Features / 功能特性

Installation / 安装

NPM

CDN

Quick Start / 快速开始

Browser (CDN)

NPM / ES Modules

Controls / 操作说明

Keyboard mode / 键鼠模式

Virtual joystick mode / 虚拟摇杆模式

API

Options / 配置项

Technical Notes / 技术说明

Mouse input / 鼠标输入

Mouse wheel / 滚轮前进后退

Double-click advance / 双击推进

Keyboard mode implementation / 键鼠模式实现

Hold-key acceleration / 持续按键加速

Pitch clamping / 俯仰角限制

Horizontal mode / 水平模式

Virtual joystick event isolation / 虚拟摇杆事件隔离

CSS Class Reference / CSS 命名规范

Compatibility / 兼容性

Build / 构建

License / 许可证