Ground

let map = new Map({
  basemap: "tianditu-vector",
  ground: "world-elevation"
});

let map = new Map({
  basemap: "tianditu-vector",
  ground: "world-topobathymetry"
});

map.ground.surfaceColor = '#004C73';

map.ground.opacity = 0.4;

属性列表

属性详细说明

declaredClass Stringreadonly inherited

起始版本: GeoScene API for JavaScript 4.22

类名。类的名称声明格式为 geoscene.folder.className。

layers Collection<ElevationLayer>

高程图层的集合，用于定义构成地面的高程或地形。将高程图层添加到地面时，表面的地形变化将以 3D 形式呈现，就像它们在现实世界中一样。

当图层集合为空时，地面表面是平坦的。

示例代码:

// 添加世界高程服务到地面
let layer = new ElevationLayer({
  url: "//links.geoscene.cn/elevation3d/rest/services/WorldElevation3D/Terrain3D/ImageServer"
});
map.ground.layers.add(layer);

loaded Booleanreadonly

指示实例是否已加载。当true时，可以访问对象的属性。当地面的图层已完全创建但尚未加载时，将被视为已加载。

默认值:false

loadError Errorreadonly

如果在加载时发生错误，则返回 Error 对象。

默认值:null

loadStatus Stringreadonly

表示加载操作的状态。

值	描述
not-loaded	对象的资源尚未加载。
loading	对象的资源当前正在加载。
loaded	对象的资源已加载，未出现错误。
failed	无法加载对象的资源。有关更多详细信息，请参阅 loadError。

可选值:"not-loaded"|"loading"|"failed"|"loaded"

默认值:not-loaded

loadWarnings Object[]readonly

加载时发生的警告列表。

navigationConstraint Accessorautocast

起始版本: GeoScene API for JavaScript 4.22

指定相对于地面的用户导航约束。

Property:

type String 约束的类型。它可以是以下之一： 值 描述 stay-above 用户只能在地面上导航 none 用户可以在地表上方和下方导航 默认值: stay-above 可选值:"stay-above"|"none"

opacity Number

起始版本: GeoScene API for JavaScript 4.22

地面的不透明度，包括表面默认颜色和底图（不含参考图层）。此属性可用于透视地面效果。

默认值:1

surfaceColor Colorautocast

自动转换自 Object|Number[]|String

起始版本: GeoScene API for JavaScript 4.22

地面表面的颜色，显示在底图下方。如果此值为 null，则改为显示一个网格。颜色中的 Alpha 值将被忽略。使用不透明度属性可以控制地面的不透明度。

默认值:null

方法列表

方法详细说明

cancelLoad()

取消 load() 操作如果它已经在运行。

clone(){Ground}

深拷贝对象。

返回值:

类型	描述
Ground	调用此方法的 Ground 实例的深拷贝。

createElevationSampler(extent, options){Promise<ElevationSampler>}

起始版本: GeoScene API for JavaScript 4.22

通过查询地面图层中的高程数据并将其缓存，以便之后可以快速对值进行采样，从而为给定范围创建高程采样器。采样器使用具有可用数据的第一个图层中的高程数据。要从特定图层获取高程数据，请使用 ElevationLayer.createElevationSampler()。

参数:

规范:

extent Extent 创建采样器的范围。

options Object optional 其他采样器选项。 规范: demResolution Number|String optional 默认值: auto 控制从中对高程数据进行采样的水平分辨率（像元大小），以米为单位（默认为 auto）。有关更多详细信息,请参阅地面。 noDataValue Number optional 默认值: 0 没有可用数据时要使用的值。 signal AbortSignal optional 中止请求的中止信号。如果取消，则 promise 将 reject，并显示名为AbortError 。另请参阅中止控制器。

返回值:

类型	描述
Promise<ElevationSampler>	高程采样器。

destroy()

起始版本: GeoScene API for JavaScript 4.22

破坏地面及其图层。一旦 ground 被销毁，这些就不能再使用。要防止图层被破坏，请在调用。destroy()之前将其从地面上移除。

// 通过将它们从地面上移除来防止layer被破坏
const layers = ground.layers.removeAll();

// 销毁ground和任何剩余的相关资源
ground.destroy();

示例:

• Map.destroy()
• WebMap.destroy()
• WebScene.destroy()
• Basemap.destroy()
• Layer.destroy()
• PortalItem.destroy()

fromJSON(json){*}static

创建此类的新实例，并使用从 GeoScene 产品生成的 JSON 对象的值对其进行初始化。传递到输入参数中的json对象通常来自对 REST API 中的查询操作的响应或来自其他 GeoScene 产品的 toJSON() 方法。有关何时以及如何使用此功能的详细信息和示例，请参阅指南中的 使用 fromJSON() 主题。

参数:

json Object 实例的 JSON 表示形式，采用 GeoScene 格式。有关各种输入 JSON 对象的结构示例，请参阅GeoScene REST API 文档。

返回值:

类型	描述
*	返回一个该类的新实例。

isFulfilled(){Boolean}

isFulfilled() 可用于验证创建类的实例是否已完成(无论成功或失败)。 如果已完成，将会返回true。

返回值:

类型	描述
Boolean	指示创建类的实例是否已完成（无论成功或失败）。

isRejected(){Boolean}

isRejected() 可用于验证创建类的实例是否失败。 如果失败, 将会返回 true 。

返回值:

类型	描述
Boolean	指示是否已拒绝创建类的实例。

isResolved(){Boolean}

isResolved() 可用于验证创建类的实例是否成功。 如果成功, 将会返回 true 。

返回值:

类型	描述
Boolean	指示是否已解析创建类的实例。

load(signal){Promise}

加载此类引用的资源。如果视图是使用映射实例构造的，则此方法将自动对视图及其在 Map 中引用的所有资源执行。

开发人员在访问不会在 View 中加载的资源时，必须调用此方法。

该方法仅在首次调用资源时触发资源的加载。后续调用load()返回相同的承诺。

可以提供signal来停止对Loadable实例加载状态的关注。当信号中止时，实例不会停止其加载过程，只有 cancelLoad 可以中止它。

参数:

signal AbortSignal optional 可用于中止异步任务的信号对象。promise 将 reject 名为AbortError的错误，并在发出中止信号时命名为"错误"。有关如何构造可用于传递中止信号的控制器的详细信息，另请参阅中止控制器。

返回值:

类型	描述
Promise	在加载资源后返回。

loadAll(){Promise<Ground>}

起始版本: GeoScene API for JavaScript 4.22

加载与地面关联的所有外部可加载资源。对于地面，这将加载所有图层。

返回值:

类型	描述
Promise<Ground>	在加载所有可加载资源后 resolve。如果至少一个可加载资源无法加载，则 reject。

示例:

• load

示例代码:

// 加载所有资源，但如果其中一个或多个未能加载则忽略
ground.loadAll()
  .catch(function(error) {
    // 忽略任何失败资源
  })
  .then(function() {
    console.log("All loaded");
  });

queryElevation(geometry, options){Promise<ElevationQueryResult>}

Query the ground layer services for elevation values for the given geometry.

返回的结果包含几何的副本，其中 z 值从具有可用数据的第一个图层的高程数据中采样。 可以使用 demResolution 选项设置查询高程的分辨率。 在许多情况下，auto demResolution 可用于获取高质量的高程样本，而无需知道服务中数据的确切位置。 这对于组合来自多个来源的高程数据的服务（例如世界高程服务）特别有用。 如果需要更多控制或更高质量的样本，请使用 finest-contiguous 或固定的 {number} 分辨率。

参数:

规范:

geometry Point|Multipoint|Polyline 要采样的几何图形。

options Object optional 其他查询选项。 规范: demResolution Number|String optional 默认值: auto 控制从中对高程数据进行采样的水平分辨率（像元大小），以米为单位（默认为auto ）。有关不同设置的更多详细信息，请参阅下表。 demResolution 描述 auto 为输入几何的每个坐标自动选择适当的分辨率。当前实现将尝试使用最精细的可用分辨率，因为所需的磁贴请求总数不超过特定的最大数量（当前为 20）。请注意，这可能会导致从不同的分辨率对值进行采样。 finest-contiguous 从整个几何体中的最佳可用分辨率（像元大小）进行采样高程。 {number} 从最接近指定分辨率的分辨率（以米为单位）的样本高程。 returnSampleInfo Boolean optional 默认值: false 指示是否为每个采样坐标返回其他采样信息。 noDataValue Number optional 默认值: 0 没有可用数据时在生成的几何图形中显示的值。 signal AbortSignal optional 中止请求的中止信号。如果取消，则 promise 将 reject 名为AbortError 的错误。参阅中止控制器。

返回值:

类型	描述
Promise<ElevationQueryResult>	解析为具有采样几何图形、分辨率信息且无数据值的对象。

示例代码:

require(["geoscene/Map", "geoscene/geometry/Multipoint"], function(Map, Multipoint) {
  const map = new Map({
    ground: "world-elevation"
  });

  // 横跨珠穆朗玛峰山脊的各个点
  const points = [
     [ 86.9252, 27.9883 ],
     [ 86.9265, 27.9894 ],
     [ 86.9292, 27.9923 ],
     [ 86.9324, 27.9960 ],
     [ 86.9359, 27.9992 ]
   ];

  map.ground.queryElevation(new Multipoint({ points }), { returnSampleInfo: true })

    // 成功采样所有点
    .then(function(result) {
      // 将每个采样点的结果打印到控制台
      result.geometry.points.forEach(function(point, index) {
        const elevation = Math.round(point[2]);
        const resolution = result.sampleInfo[index].demResolution;

        const coordinateText = "(" + point[0] + ", " + point[1] + ")";
        const resolutionText = Math.round(resolution) + " meter resolution";

        console.log("Sampled " + coordinateText + ": " + elevation + " at " + resolutionText);
      });
    })

    // 采样失败 (e.g. 服务不可访问)
    .catch(function(error) {
      console.error("Failed to query elevation:", error);
    });
});

toJSON(){Object}

将此类的实例转换为其 GeoScene 门户 JSON 表示形式。有关详细信息，请参阅 使用 fromJSON() 指南主题。

返回值:

类型	描述
Object	此类实例的 GeoScene 门户 JSON 表示形式。

when(callback, errback){Promise}

起始版本: GeoScene API for JavaScript 4.22

when() 创建类的实例后，会被执行一次。该方法接受两个参数： callback 函数和 errback 函数。 callback 在类的实例加载时执行。 如果类的实例无法加载，则执行 errback。

参数:

callback Function optional 当 Promise 成功时，该函数将被调用。

errback Function optional 当 Promise 失败时，该函数将被调用。

返回值:

类型	描述
Promise	返回回调结果的新promise，可用于 链接 其他函数。

示例代码:

// 尽管此示例使用 MapView，但任何作为 Promise 的类实例都可以以相同的方式使用 when()
let view = new MapView();
view.when(function(){
  // 当 Promise resolved 时，函数将被执行
}, function(error){
  // 当 Promise 通过 rejected 抛错时，这个函数将被执行
});

类型定义

ElevationQueryResult

queryElevation() promise resolves 时返回的对象:

属性:

geometry Point|Multipoint|Polyline 具有采样 z 值的几何图形。

sampleInfo Object[] optional 包含有关如何对几何图形进行采样的其他信息。此属性的存在取决于用户是否为几何中的每个坐标设置了 options.returnSampleInfo = true。 规范: demResolution Number 对 z 值进行采样的分辨率。如果没有可用于给定坐标采样的数据，则该坐标的 dem 分辨率值将为 -1。 source ElevationLayer 从中对相应坐标的数据进行采样的高程源。

noDataValue Number 没有可用数据时使用的值。