creating-globe-tours

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Globe Tours

创建地球飞行游览

Overview

概述

Coordinate Camera, Entity, and Clock MCP servers to create narrated flyover tours with multiple stops.

Core principle: A tour is a sequence of camera movements with optional annotations at each stop.

Critical distinction — Marker vs. Viewpoint:

The marker (label, billboard, point) goes at the actual location coordinates.
The camera flies to a viewpoint — a position offset from the marker so the marker and its surroundings are clearly visible.
Never fly the camera directly to the marker coordinates. If you do, the camera lands on top of the marker and the user can't see it. Instead, position the camera at a distance and altitude that frames the marker well.

协调Camera、Entity和Clock MCP服务器，创建带旁白的多站点飞行游览。

核心原则： 游览是一系列相机移动序列，每个站点可添加可选注释。

关键区别——标记点（Marker）与视点（Viewpoint）：

标记点（标签、广告牌、点）放置在实际位置坐标处。
相机会飞往视点——一个偏离标记点的位置，以便清晰看到标记点及其周边环境。
绝对不要让相机直接飞往标记点坐标。如果这样做，相机将停在标记点上方，用户无法看到它。相反，应将相机定位在能很好框住标记点的距离和高度处。

When to Use

适用场景

User wants to "show" multiple locations in sequence
Building a presentation or demo with geographic stops
Creating a guided walkthrough of an area
"Take me on a tour of..." or "fly through these places"

When NOT to use:

Single location fly-to (just use camera_fly_to directly)
Animating an entity along a route (use animating-journey-routes skill)
Time-based playback (use time-lapse-visualizations skill)

用户想要按顺序“展示”多个地点
构建带地理站点的演示或示例
创建某区域的导览式漫游
“带我游览...”或“飞越这些地方”的需求

不适用场景：

单个地点的飞行（直接使用camera_fly_to即可）
沿路线动画实体（使用animating-journey-routes技能）
基于时间的回放（使用time-lapse-visualizations技能）

Planning Checklist

规划清单

Workflow

工作流程

mermaid

flowchart TB
    A[Gather stop list] --> B[Resolve coordinates]
    B -->|geolocation_search if needed| C[For each stop]
    C --> D[Add label at marker position<br/>entity_add_label]
    D --> E[Calculate viewpoint<br/>offset from marker]
    E --> F[Fly to VIEWPOINT<br/>camera_fly_to]
    F --> G[Orbit?<br/>camera_start_orbit]
    G --> H[Wait/delay]
    H --> I{More stops?}
    I -->|yes| C
    I -->|no| J[End tour]

mermaid

flowchart TB
    A[Gather stop list] --> B[Resolve coordinates]
    B -->|geolocation_search if needed| C[For each stop]
    C --> D[Add label at marker position<br/>entity_add_label]
    D --> E[Calculate viewpoint<br/>offset from marker]
    E --> F[Fly to VIEWPOINT<br/>camera_fly_to]
    F --> G[Orbit?<br/>camera_start_orbit]
    G --> H[Wait/delay]
    H --> I{More stops?}
    I -->|yes| C
    I -->|no| J[End tour]

Viewpoint Positioning

视点定位

When flying to a tour stop, you need TWO positions:

Marker position — where the label/entity is placed (at or near the actual location)
Camera viewpoint — where the camera flies to (offset so the marker is visible and framed well)

飞往游览站点时，你需要两个位置：

标记点位置——标签/实体的放置位置（位于或接近实际地点）
相机视点——相机飞往的位置（偏离标记点，确保标记点可见且框选效果良好）

How to Calculate a Good Viewpoint

如何计算合适的视点

Marker Type	Camera Offset Strategy
City/landmark	Place camera 0.01–0.05° away in lat/lon, 500–2000m altitude, pitch down 20–40° toward marker
Region/area	Place camera 0.1–0.5° away, 5000–20000m altitude, pitch down 30–50°
Building/POI	Place camera 0.005–0.01° away, 200–800m altitude, pitch down 25–45°

Rules of thumb:

Altitude: Higher camera = wider context. A good starting point is 3–5× the height of the tallest feature at the stop.
Lateral offset: Shift the camera slightly (south is a good default preference) so the marker appears in the upper portion of the frame, which feels natural.
Heading: Point the camera toward the marker. If the camera is south of the marker, heading ≈ 0° (north). If east, heading ≈ 270° (west). Calculate based on relative position.
Pitch: Tilt down toward the marker. Values of -25° to -45° work well for most stops. Steeper pitch (-50° to -70°) for overhead/map-like views.

标记点类型	相机偏移策略
城市/地标	将相机放置在经纬度偏移0.01–0.05°处，高度500–2000米，向下倾斜20–40°朝向标记点
区域/地区	将相机放置在经纬度偏移0.1–0.5°处，高度5000–20000米，向下倾斜30–50°
建筑/兴趣点（POI）	将相机放置在经纬度偏移0.005–0.01°处，高度200–800米，向下倾斜25–45°

经验法则：

高度： 相机位置越高，视野越广。一个好的起点是站点最高特征高度的3-5倍。
横向偏移： 轻微移动相机（向南是默认偏好），使标记点出现在画面上部，这样更符合视觉习惯。
朝向： 相机朝向标记点。如果相机在标记点南侧，朝向≈0°（北）；如果在东侧，朝向≈270°（西）。根据相对位置计算。
倾斜角度： 向下朝向标记点。大多数站点使用-25°至-45°的角度。更陡的倾斜角度（-50°至-70°）适用于俯视/地图式视图。

Example: Marker at Eiffel Tower

示例：埃菲尔铁塔标记点

Marker position:  { longitude: 2.2945,  latitude: 48.8584, height: 350 }
Camera viewpoint: { longitude: 2.2945,  latitude: 48.845,  height: 1200 }
                                                   ^^^^^^ offset south
Camera orientation: { heading: 0, pitch: -35, roll: 0 }
                                   ^^^^^^^^^^ looking down toward marker

The camera is ~1.5 km south and 1200m up, looking north and slightly down — giving a clear view of the tower and its label.

标记点位置:  { longitude: 2.2945,  latitude: 48.8584, height: 350 }
相机视点: { longitude: 2.2945,  latitude: 48.845,  height: 1200 }
                                                   ^^^^^^ 向南偏移
相机朝向: { heading: 0, pitch: -35, roll: 0 }
                                   ^^^^^^^^^^ 向下朝向标记点

相机位于标记点以南约1.5公里、1200米高空，朝北并略微向下——可以清晰看到铁塔及其标签。

Quick Reference

快速参考

Position Format (All Tools)

位置格式（所有工具）

json

{
  "longitude": -74.0060,
  "latitude": 40.7128,
  "height": 1000
}

Note: Longitude first, then latitude. Height in meters.

json

{
  "longitude": -74.0060,
  "latitude": 40.7128,
  "height": 1000
}

注意： 先写经度，再写纬度。高度单位为米。

Color Format (Entity Tools)

颜色格式（Entity工具）

json

{
  "red": 1.0,
  "green": 0.0,
  "blue": 0.0,
  "alpha": 1.0
}

Note: Values 0-1, not 0-255.

json

{
  "red": 1.0,
  "green": 0.0,
  "blue": 0.0,
  "alpha": 1.0
}

注意： 值范围为0-1，而非0-255。

Camera Easing Functions

相机缓动函数

Effect	Easing	Use For
Smooth professional	QUADRATIC_IN_OUT	Most tours
Dramatic arrival	CUBIC_IN	Hero locations
Gentle float	SINUSOIDAL_OUT	Scenic views
Quick snap	LINEAR_NONE	Fast transitions

效果	缓动方式	适用场景
流畅专业	QUADRATIC_IN_OUT	大多数游览
戏剧性到达	CUBIC_IN	核心地标
平缓浮动	SINUSOIDAL_OUT	风景视图
快速切换	LINEAR_NONE	快速过渡

Recommended Durations

Distance	Duration
Same city	2-3 seconds
Regional (100km)	4-5 seconds
Continental	6-8 seconds
Global	10+ seconds

距离	时长
同城	2-3秒
区域级（100公里）	4-5秒
洲际	6-8秒
全球	10+秒

Orbit Settings

环绕设置

Effect	Speed (rad/s)	Direction
Slow dramatic	0.002	counterclockwise
Standard showcase	0.005	counterclockwise
Quick spin	0.01	clockwise

Orbit rules:

```
camera_start_orbit
```
orbits from the current camera state. It preserves the existing position, heading, pitch, and range.
NEVER call
camera_look_at_transform
before
camera_start_orbit
unless the user explicitly asks to change their viewing angle.
```
camera_look_at_transform
```
resets the camera orientation, which destroys the user's current view.
If the user says "rotate" or "orbit," just call
```
camera_start_orbit
```
directly. That's it. Do not reposition or reorient the camera first.

效果	速度（弧度/秒）	方向
缓慢戏剧性	0.002	逆时针
标准展示	0.005	逆时针
快速旋转	0.01	顺时针

环绕规则：

```
camera_start_orbit
```
从当前相机状态开始环绕。它会保留现有的位置、朝向、倾斜角度和范围。
除非用户明确要求改变视角，否则绝对不要在
camera_start_orbit
之前调用
camera_look_at_transform
。
```
camera_look_at_transform
```
会重置相机朝向，破坏用户当前的视图。
如果用户说“旋转”或“环绕”，直接调用
```
camera_start_orbit
```
即可。无需先重新定位或调整相机朝向。

Example Tour Sequence

示例游览序列

javascript

// 1. Search for location (returns coordinates)
geolocation_search({ query: "Eiffel Tower, Paris" })
// Returns: { longitude: 2.2945, latitude: 48.8584, ... }

// 2. Add label at the ACTUAL location
entity_add_label({
  position: { longitude: 2.2945, latitude: 48.8584, height: 350 },
  label: {
    text: "Eiffel Tower",
    font: "24pt sans-serif",
    fillColor: { red: 1, green: 1, blue: 1, alpha: 1 },
    outlineColor: { red: 0, green: 0, blue: 0, alpha: 1 },
    outlineWidth: 2,
    style: "FILL_AND_OUTLINE"
  },
  id: "tour-label-paris"
})

// 3. Fly camera to a VIEWPOINT — NOT to the marker itself!
//    Camera is offset south of the marker and elevated, looking
//    north and downward so the Eiffel Tower label is clearly visible.
camera_fly_to({
  destination: { longitude: 2.2945, latitude: 48.845, height: 1200 },
  orientation: { heading: 0, pitch: -35, roll: 0 },
  duration: 5,
  easingFunction: "QUADRATIC_IN_OUT"
})

// 4. Start orbit (after fly_to completes)
camera_start_orbit({
  speed: 0.005,
  direction: "counterclockwise"
})

// 5. Wait, then stop orbit
camera_stop_orbit()

// 6. Continue to next stop...

// 7. Cleanup when done
entity_remove({ entityId: "tour-label-paris" })

javascript

// 1. 搜索地点（返回坐标）
geolocation_search({ query: "Eiffel Tower, Paris" })
// 返回: { longitude: 2.2945, latitude: 48.8584, ... }

// 2. 在实际位置添加标签
entity_add_label({
  position: { longitude: 2.2945, latitude: 48.8584, height: 350 },
  label: {
    text: "Eiffel Tower",
    font: "24pt sans-serif",
    fillColor: { red: 1, green: 1, blue: 1, alpha: 1 },
    outlineColor: { red: 0, green: 0, blue: 0, alpha: 1 },
    outlineWidth: 2,
    style: "FILL_AND_OUTLINE"
  },
  id: "tour-label-paris"
})

// 3. 飞往视点——不要直接飞往标记点！
// 相机位于标记点南侧并升高，朝北向下看，以便清晰看到埃菲尔铁塔标签。
camera_fly_to({
  destination: { longitude: 2.2945, latitude: 48.845, height: 1200 },
  orientation: { heading: 0, pitch: -35, roll: 0 },
  duration: 5,
  easingFunction: "QUADRATIC_IN_OUT"
})

// 4. 开始环绕（在fly_to完成后）
camera_start_orbit({
  speed: 0.005,
  direction: "counterclockwise"
})

// 5. 等待后停止环绕
camera_stop_orbit()

// 6. 继续下一个站点...

// 7. 完成后清理
entity_remove({ entityId: "tour-label-paris" })

Common Mistakes

常见错误

Mistake	Fix
Camera flies to marker coords	Offset the camera so the marker is IN VIEW, not under the camera. See Viewpoint Positioning above.
Using `camera_look_at_transform` before orbit	Just call `camera_start_orbit` directly — it preserves the current view. `camera_look_at_transform` resets the camera angle.
Coordinates reversed	Use longitude first: `{ longitude, latitude, height }`
Colors as hex strings	Use object: `{ red: 1, green: 0, blue: 0, alpha: 1 }`
Flying too fast	Increase duration for long distances
Orbit won't stop	Call camera_stop_orbit() explicitly
Labels not visible	Check height is above terrain, increase font size
Forgetting cleanup	Track entity IDs and call entity_remove

错误	修复方案
相机飞往标记点坐标	偏移相机位置，使标记点在视野内，而非相机正下方。请参阅上方的视点定位部分。
在环绕前调用 `camera_look_at_transform`	直接调用 `camera_start_orbit` 即可——它会保留当前视图。 `camera_look_at_transform` 会重置相机角度。
坐标顺序颠倒	先写经度： `{ longitude, latitude, height }`
使用十六进制字符串表示颜色	使用对象格式： `{ red: 1, green: 0, blue: 0, alpha: 1 }`
飞行速度过快	长距离飞行时增加时长
环绕无法停止	显式调用camera_stop_orbit()
标签不可见	检查高度是否高于地形，增大字体大小
忘记清理	跟踪实体ID并调用entity_remove

Multi-Server Coordination

多服务器协调

Server	Role in Tours
Camera	fly_to, start_orbit, stop_orbit, set_view
Entity	add_label, add_billboard, add_point, remove
Clock	Set time-of-day for lighting effects
Geolocation	search to resolve place names

服务器	在游览中的作用
Camera	fly_to、start_orbit、stop_orbit、set_view
Entity	add_label、add_billboard、add_point、remove
Clock	设置时间段以实现光照效果
Geolocation	搜索解析地点名称

Red Flags

注意事项

Using the same coordinates for both the marker and the camera destination — the camera must be offset to a viewpoint
Calling
camera_look_at_transform
before
camera_start_orbit
— this destroys the user's current camera angle; just call orbit directly
Starting tour without knowing all stop coordinates
Not testing fly_to durations (too fast = disorienting)
Leaving orbit running when moving to next stop
Forgetting the globe is 3D (consider altitude and pitch)

标记点和相机目标使用相同坐标——相机必须偏移到视点位置
在
camera_start_orbit
之前调用
camera_look_at_transform
——这会破坏用户当前的相机角度；直接调用环绕即可
未获取所有站点坐标就开始游览
未测试fly_to时长（速度过快会导致眩晕）
移动到下一个站点时仍保持环绕状态
忘记地球是3D的（考虑高度和倾斜角度）

creating-globe-tours

Original

Translation

Creating Globe Tours

创建地球飞行游览

Overview

概述

When to Use

适用场景

Planning Checklist

规划清单

Workflow

工作流程

Viewpoint Positioning

视点定位

How to Calculate a Good Viewpoint

如何计算合适的视点

Example: Marker at Eiffel Tower

示例：埃菲尔铁塔标记点

Quick Reference

快速参考

Position Format (All Tools)

位置格式（所有工具）

Color Format (Entity Tools)

颜色格式（Entity工具）

Camera Easing Functions

相机缓动函数

Recommended Durations

推荐时长

Orbit Settings

环绕设置

Example Tour Sequence

示例游览序列

Common Mistakes

常见错误

Multi-Server Coordination

多服务器协调

Red Flags

注意事项