3D 区域浏览器：自定义指南

3D 区域探索器是一款解决方案，可让您以引人入胜的 3D 效果探索社区。该解决方案利用了 Google 的仿真 3D 图块、地点搜索、地点详情和 Autocomplete API。

开始使用：

使用托管的 3D Area Explorer Admin 应用

或

获取 API 密钥并从 GitHub 下载代码。

启用

• 仿真 3D 图块 API
• Places API

自定义体验

3D 区域探索器解决方案可高度可定制，让您能够根据客户转化历程量身定制体验。您可以使用界面上的控制台或使用 config.json 文件进行自定义。

准备好自定义了吗？具体步骤如下：

位置

通过调整 config.json 文件中的纬度和经度来定义体验的起点。

相机控制

您可以通过选择镜头的轨道类型（经典的圆形路径或有趣的正弦波）来控制您的旅程。

• 固定轨道：

  这是固定高度且围绕特定地图注点的圆形轨道。

  探索 Google 悉尼办事处，了解固定轨道的实际应用。

• Dynamic orbit：

  镜头沿正弦波轨迹围绕指定的地图注点平稳移动。这种独特的运动让观看者可以从不同的高度和角度观察地图注点，从而提供动态且沉浸式的视觉体验。

  探索埃菲尔铁塔，了解动态轨道的实际运行情况。

地图注点 (POI)：

• 确定您想要探索的地点类型，自定义您的探索。使用 config.json 中的 types 数组从博物馆、公园、学校等中进行选择。
• 通过调整 density 参数，设置所显示的地图注点数量上限。
• 修改 searchRadius (in meters) 以包含附近的隐藏宝石或专注于特定区域。
• 您可以使用 speed (in revolutions per minute) 参数设置为相机选择的移动速度。

预加载探索：深入了解网址自定义

借助 3D 区域探索器，您可以通过网址自定义功能来预定义探索。这样便无需进行手动配置，从而简化用户体验。

创建完美的网址：

只需将特定参数附加到区域浏览器网址，即可预设位置和其他设置。例如：

https://{base-url}/#location.coordinates.lat=40.7424396&location.coordinates.lng=-74.0061439

此网址将起点设置为指定的经纬度，即刻将您传送到所选位置。可用参数：

• location.coordinates.lat：所选位置的纬度。
• location.coordinates.lng：所选位置的经度。
• poi.types：要显示的地图注点类型的逗号分隔列表。
• poi.density：所选的地图注点数量上限。
• poi.searchRadius：搜索附近地图注点时的半径。
• camera.speed：相机轨道速度。
• camera.orbitType：相机轨道类型（“fixed-orbit”或“dynamic-orbit”）。

网址自定义的优势：

• 通过预定义设置来简化用户体验。
• 与特定的预加载位置和地图注点共享目标历程。
• 在网站中无缝嵌入预配置的“区域探索器”体验。

通过利用网址自定义，您可以打造量身定制的体验，并邀请他人踏上精心策划的冒险之旅。

注意： 请尝试使用加载完毕的自定义网址： https://js-3d-area-explorer-demo-dev-t6a6o7lkja-uc.a.run.app/#camera.orbitType=fixed-orbit&camera.speed=2.2&poi.types=restaurant&poi.types=parking&poi.types=movie_theater&poi.types=bus_station&poi.density=40&poi.searchRadius=5100

进一步自定义

上一部分探讨了可通过界面或配置文件访问的调整。不过，还有几个其他内置参数可以修改，以进一步自定义应用。

如需进行这些高级自定义，您需要查看位于 src 目录下的 src/utils/cesium.js 文件中的代码。以下变量可以更改，以改变应用的外观和风格

摄像头高度

通过调整 CAMERA_HEIGHT 值，控制相机在飞向某个点时自身的位置高度。值越大，提供的全景视图越缩小；值越低，越接近该区域的详情

// Camera height (in meters) above the target when flying to a point.
const CAMERA_HEIGHT = 100;

• 设置：CAMERA_HEIGHT
• 默认值：100
• 说明：定义飞到某个点时镜头在目标位置上方的高度。
• 示例值：
  • 50：近景，突出细节。
  • 200：更全景。

相机倾斜度

镜头的初始倾斜度由 BASE_PITCH 定义。对于向下倾斜，使用负值；对于向上倾斜，使用正值。要为探索添加细微的动态运动，请更改 AUTO_ORBIT_PITCH_AMPLITUDE。

// Pitch 30 degrees downwards
const BASE_PITCH = -30;
// change the pitch by 10 degrees over time
const AUTO_ORBIT_PITCH_AMPLITUDE = 10;

• 设置：BASE_PITCH 和 AUTO_ORBIT_PITCH_AMPLITUDE
• 默认值：
  • BASE_PITCH：-30（向下倾斜 30 度）
  • AUTO_ORBIT_PITCH_AMPLITUDE：10（音高会随时间变化 10 度）

说明：相机倾斜度是指地图的可视倾斜度，以度为单位。这也称为“倾斜”。这些设置定义了镜头在自动旋转期间的初始倾斜度和动态倾斜度调整。

示例值：

• BASE_PITCH：0（水平摄像头）
• AUTO_ORBIT_PITCH_AMPLITUDE：0（无音调变化）

镜头范围和缩放

这些参数用于设置聚焦特定点时应用的缩放量。值越小，意味着缩放级别越近。

// Distance variation relative to initial range.
const RANGE_AMPLITUDE_RELATIVE = 0.55;

// Determines how much the camera should zoom in or out
const ZOOM_FACTOR = 20;

设置：RANGE_AMPLITUDE_RELATIVE 和 ZOOM_FACTOR

默认值：

• RANGE_AMPLITUDE_RELATIVE：0.55（相对距离变化）
• ZOOM_FACTOR：20（相机缩放比例）

说明：这些设置可定义相机移动期间的范围变化，以及用于近距离观察的缩放级别。

示例值：

• RANGE_AMPLITUDE_RELATIVE：1（全范围变体）
• ZOOM_FACTOR：10（缩放范围较小）

// Camera heading (rotation), pitch (tilt), and range (distance) for resetting view.
const CAMERA_OFFSET = {
  heading: 0, // No rotation offset.
  pitch: Cesium.Math.toRadians(BASE_PITCH),
  range: 800, // 800 meters from the center.
};

重置相机

当用户想要将相机重置到原始位置时，系统会使用 CAMERA_OFFSET 值。此设置包括朝向（旋转）、倾斜度（倾斜）和范围（相机与中心的距离）。

• 设置：CAMERA_OFFSET
• 默认值：
  • heading：0（无旋转偏移）
  • pitch：Cesium.Math.toRadians(-30)（向下倾斜 30 度）
  • range：800（距离中心 800 米）
• 说明：定义用于重置视图的相机朝向、倾斜度和范围。
• 示例值：
  • heading：45（度，西北视图）
  • range：1500 米（离中心更远）

起始坐标：

START_COORDINATES 用于定义镜头的初始经度、纬度和高度。这是探索的起点，因此请将其设置为您希望用户首先看到的区域。

// Default camera start position in longitude, latitude, and altitude.
const START_COORDINATES = {
  longitude: 0,
  latitude: 60,
  height: 15000000, // 15,000 km above the surface
};

• 设置：START_COORDINATES

• 默认值：

  • longitude：0
  • latitude：60
  • height：15000000（高于水面 15000 公里）

• 示例值：

  • longitude：-122.4934；latitude：37.7951（金门大桥）
  • height：2000（更接近的起始位置）

加载预定义的位置

config.json 中的 location 对象用于设置区域的中心。它是 Cesium 查看器中相机的初始视点。coordinates：定义您希望镜头首先平移到的位置的纬度 (lat) 和经度 (lng)。调整这些值可将相机设置为地球上的任意特定位置。

  {
  "location": {
    "coordinates": { "lat": null, "lng": null }
  },

此配置可让您启动 3D 地点导航器应用，并将其放大到您选择的特定位置。您可以使用 Google 的地理编码工具在 location 对象中指定某个地址或地点名称的经纬度坐标：

1. 访问地理编码工具。
2. 创建地理编码请求 点击“亲自试用”部分，然后在“地址”字段中输入您选择的位置。您可以指定地址、地点名称，甚至是地标。
3. 生成坐标 点击“生成”按钮提交您的请求。该工具将返回一个响应，其中包含有关该位置的各种信息，包括 geometry.location 部分下显示的其纬度和经度坐标。
4. 使用地理编码：从响应中复制检索到的纬度和经度值，并将其粘贴到配置中的 coordinates 对象中。

注意：以这种方式使用的地理编码必须遵循 Google Maps Platform 服务条款第 3.4 节中列出的条款，即：缓存时间不得超过 30 天，在此之后必须刷新。

此配置会使用地理编码工具自动确定 Google 总部（位于加利福尼亚州山景城）的坐标，并以镜头为中心来启动 3D 地点导航器应用。

注意 ：此方法可简化查找坐标的过程，减少手动识别的需要。借助它，您可以在配置中使用任意位置的地址或名称无缝探索任意位置。

高级自定义

您可以通过深入了解代码来进行其他自定义。以下部分介绍了一些选项

添加新的相机路径

该解决方案开箱即实现了两个不同的相机路径：

fixed-orbit" | "dynamic-orbit"

但如果您需要，可以创建新的镜头路径，您可以使用

calculateAutoOrbitFrame 函数中的 /src/utils/cesium.js。

如需在配置面板中使用这种新的路径计算方法，请参阅 demo/src/camera-settings.js. 中的实现

添加更多地点类型

可以在文件 demo/src/place-settings.js 中调整配置的地点类型列表。从第 4 行开始，演示中可用的地点类型。

如果您想在不更改演示来源的情况下使用特定地点类型，只需将其添加到 poi.types 下的 config.json 文件中即可

自定义样式 (css)

对于我们使用 CSS 变量的样式。所有主流浏览器都支持这些样式，因此可以集中更改一行内容并更新特定的 CSS 属性。我们的 CSS 变量在 src/main.css. 中定义。您可以在其中调整整个应用的颜色、字体设置以及内边距或外边距。

叠加其他数据

如需叠加其他数据，您需要更新 src/utils/cesium.js 文件，并参阅 Cesium 文档，了解如何向地球添加 GeoJSON 或其他地理引用数据。

移除配置部分

我们的 JavaScript 应用的配置文件包含三个主要部分：demo/src/[config-panel.js](config-panel.js): location、poi 和 camera。其中每个部分都为应用的不同方面提供了配置选项。开发者可以根据自己的特定需求自定义这些部分。

1.从配置中移除特定部分

• “位置信息”部分

如需移除 location 部分，请在代码中找到下面这行代码，然后添加注释或将其删除：

const locationConfig = { ...config.location, ...customConfig.location };

• 地图注点部分

如需移除 poi 部分，请在代码中找到下面这行代码，然后为其添加注解或将其删除：

const poiConfig = { ...config.poi, ...customConfig.poi };

• 相机部分

如需移除 camera 部分，请在代码中找到下面这行代码，然后为其添加注解或将其删除：

const cameraConfig = { ...config.camera, ...customConfig.camera };

2. 更新组合配置

移除某个部分后，必须更新组合的配置对象。该对象会将默认配置与任何自定义设置合并。从 combinedConfig 对象中移除相应的属性：

const combinedConfig = {
 location: { ...config.location, ...customConfig.location }, // Remove if location section is removed

 poi: { ...config.poi, ...customConfig.poi }, // Remove if poi section is removed
 camera: { ...config.camera, ...customConfig.camera }, // Remove if camera section is removed
};

3. 调整界面元素

如果移除某个部分还意味着移除相关的界面元素，请相应地更新 HTML 代码中的代码。例如，如果您想从管理控制台中删除相机速度等特定部分，则必须同时更新其 js 和 html 代码。

4. 移除“相机设置”部分

如需从界面中移除相机设置部分，请找到以下行，然后将其注释或删除：

const cameraSettingsSecgetCameraSettingsSection(cameraConfig);

移除位置信息版块摘要

const locationSection = await getLocationSettingsSection(locationConfig);

总结

在本文档中，我们探讨了区域探索器中提供的各种自定义选项，用于定制您的 3D 探索体验。通过修改相机行为、调整视觉倾斜度和更改缩放级别，您可以打造引人入胜的独特体验，展示您选择的设置和地图注点。

请务必尝试不同的配置并微调参数，以满足您的特定需求。利用自定义的强大功能，您可以打造沉浸式的个性化历程，从而吸引受众群体并将您的愿景变为现实。