Mesh

网格是一种常规的客户端 3D 几何类型，由具有属性的折点组成。折点包括地理位置、影响照明/阴影的法线以及可用于将图像映射到网格的 uv 坐标。折点被组合成 3D 基元以渲染场景中的网格 (目前仅支持三角形基元)。

网格几何可以具有决定其显示方式的固有材料。与场景图层中的 3D 对象类似，网格几何使用包含 FillSymbol3DLayer 的 MeshSymbol3D 符号进行符号化。

为了支持多种材质 (复杂 3D 模型通常就是这种情况)，网格可以定义为网格中的特定区域定义材质的组件。除了支持多种材质外，组件还可以重用折点，否则这些折点将被复制以形成三角形。

创建简单的网格几何基元

网格几何类具有许多用于创建简单基元形状的便利函数。这些形状可以帮助您开始了解网格几何。

// Create a box mesh geometry
let mesh = Mesh.createBox(location, {
  size: {
    width: 100,
    height: 50,
    depth: 50
  },
  material: {
    color: "red"
  }
});

// Create a graphic and add it to the view
let graphic = new Graphic({
  geometry: mesh,
  symbol: {
    type: "mesh-3d",
    symbolLayers: [ { type: "fill" } ]
  }
});

view.graphics.add(graphic);

手动创建网格几何

可以通过指定 vertexAttributes 和 components 来手动创建网格几何图形，如以下示例所示：

// Create a mesh geometry representing a pyramid
let pyramidMesh = new Mesh({
  vertexAttributes: {
    // vertex positions for the Louvre pyramid, Paris
    position: [
      // vertex 0 - base of the pyramid, south
      2.336006, 48.860818, 0,

      // vertex 1 - base of the pyramid, east
      2.336172, 48.861114, 0,

      // vertex 2 - base of the pyramid, north
      2.335724, 48.861229, 0,

      // vertex 3 - base of the pyramid, west
      2.335563, 48.860922, 0,

      // vertex 4 - top of the pyramid
      2.335896, 48.861024, 21
    ]
  },
  // Add a single component with faces that index the vertices
  // so we only need to define them once
  components: [
    {
      faces: [
        0, 4, 3,
        0, 1, 4,
        1, 2, 4,
        2, 3, 4
      ]
    }
  ],
  // specify a spatial reference if the position of the vertices is not in WGS84
});

// add the mesh geometry to a graphic
let graphic = new Graphic({
  geometry: pyramidMesh,
  symbol: {
    type: "mesh-3d",
    symbolLayers: [ { type: "fill" } ]
  }
});

view.graphics.add(graphic);

注：从版本 4.11 开始，网格几何不再支持自动转换。

另请参阅

构造函数

new Mesh(properties)

参数

properties Object

optional

有关可能传递给构造函数的所有属性的列表，请参见属性。

属性概述

可以设置、检索或侦听任何属性。请参阅使用属性主题。

显示继承属性

隐藏继承属性

类型	描述	类
Object	缓存用于存储从几何中计算的值，这些值需要在发生突变时清除或重新计算。更多详情	Geometry
MeshComponent []	一组网格组件，可用于将材质应用于同一网格的不同区域。更多详情	Mesh
String	类的名称。更多详情	Accessor
Extent	网格几何的 3D 范围。更多详情	Mesh
Boolean	指示几何是否具有 M 值。更多详情	Geometry
Boolean	指示几何是否具有 z 值 (高程)。更多详情	Geometry
SpatialReference	几何的空间参考。更多详情	Geometry
String	表示几何类型的字符串值。更多详情	Mesh
Accessor	此对象可描述网格的每个折点的属性。更多详情	Mesh

属性详细信息

cache Objectreadonly inherited

缓存用于存储从几何中计算的值，这些值需要在发生突变时清除或重新计算。例如，面的范围。

components MeshComponent []autocast

一组网格组件，可用于将材质应用于同一网格的不同区域。组件有三种常见的使用模式。

为整个网格指定材质。在这种情况下，请使用仅具有材质的单个组件 (将面保留为 null)。
重用折点属性。对连续表面进行建模时，只需指定一次折点，然后简单地引用它们，这样会很方便。在这种情况下，请使用设置了面的单个组件来索引形成三角形的折点属性。
为同一网格指定多个材质。在这种情况下，请使用多个组件，其面用于确定组件的材料应用于网格的哪个区域。

declaredClass Stringreadonly inherited

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

extent Extentreadonly

网格几何的 3D 范围。范围是根据存储在 vertexAttributes 中的折点位置计算的。3D 范围是按需计算和缓存的。如果手动修改 vertexAttributes，则必须调用 vertexAttributesChanged() 以确保重新计算范围。

hasM Boolean inherited

指示几何是否具有 M 值。

hasZ Boolean inherited

指示几何是否具有 z 值 (高程)。

在地理或公制坐标系中定义的 Z 值 用米表示。然而，在使用投影坐标系的局部场景中，垂直单位假定为与服务指定的水平单位相同。

spatialReference SpatialReferenceautocast inherited

几何的空间参考。

默认值：WGS84 (wkid: 4326)

type Stringreadonly

表示几何类型的字符串值。

对于 Mesh，类型总是 "mesh"。

vertexAttributes Accessorautocast

此对象可描述网格的每个折点的属性。折点属性是平面数值数组，用于描述每个折点的位置 (强制)、法线 (用于照明计算和着色) 和 uv (用于将材质图像映射到网格表面)。

折点属性可以通过组件 faces 属性中指定的索引进行寻址。如果网格不包含任何组件，或者组件未指定任何面，则折点属性将被解释为每个连续的折点三元组组成一个三角形。

属性

position Float64Array

自动转换自 Number []|Float32Array

折点位置的平面数组。折点位置具有 x、y 和 z 坐标，并且它们应位于几何的空间参考系统中。

uv Float32Array

optional

自动转换自 Number []|Float64Array

折点 uv 坐标的平面数组 (每个折点 2 个元素)。

normal Float32Array

optional

自动转换自 Number []|Float64Array

折点法线的平面数组 (每个折点 3 个元素，范围从 -1 到 1)。

color Uint8Array

optional

自动转换自 Number []|Uint8ClampedArray

起始版本：4.9

折点颜色的平面数组 (每个折点 4 个元素，范围从 0 到 255)。折点颜色乘以组件材料颜色 (如果已定义)。

tangent Float32Array

optional

自动转换自 Number []|Float64Array

起始版本：4.11

折点切线的平面数组 (每个折点 4 个元素，范围从 -1 到 1。第 4 个元素是一个符号值 (-1 或 +1)，表示切线基准的偏手性)折点切线用于法线贴图，请参阅 MeshMaterial.normalTexture。

示例

let mesh = new Mesh({ spatialReference: SpatialReference.WebMercator });

// Specify vertices for two triangles that make up a square
// around a provided point. Uv coordinates are setup to cover the square
// from (0, 0) to (1, 1) from corner to corner.
mesh.vertexAttributes = {
  position: [
    pt.x - 10, pt.y - 10, 100,
    pt.x + 10, pt.y - 10, 100,
    pt.x + 10, pt.y + 10, 100,

    pt.x - 10, pt.y - 10, 100,
    pt.x + 10, pt.y + 10, 100,
    pt.x - 10, pt.y + 10, 100
  ],
  uv: [
    0, 0,
    1, 0,
    1, 1,

    0, 0,
    1, 1,
    0, 1
  ]
};

方法概述

显示继承的方法

隐藏继承的方法

返回值类值	描述	类
	向网格添加一个组件。更多详情	Mesh
	添加一个或多个与对象的生命周期相关联的句柄。更多详情	Accessor
Mesh	将网格居中于指定位置，而不更改其比例。更多详情	Mesh
Mesh	创建 Mesh 对象的深度克隆。更多详情	Mesh
Mesh	创建表示为方格的网格。更多详情	Mesh
Mesh	创建表示圆柱体的网格。更多详情	Mesh
Promise<Mesh>	从 `url` 参数引用的 glTF 模型创建新的网格几何。更多详情	Mesh
Mesh	从面几何创建新的网格几何。更多详情	Mesh
Mesh	创建表示平面的网格。更多详情	Mesh
Mesh	创建表示球体的网格。更多详情	Mesh
*	创建此类的新实例并使用从 GeoScene 产品生成的 JSON 对象值对其进行初始化。更多详情	Geometry
Boolean	如果存在指定的句柄组，则返回 true。更多详情	Accessor
Mesh	将网格几何偏移指定的距离 (以 x、y 和 z 为单位)。更多详情	Mesh
	从网格中移除组件。更多详情	Mesh
	移除对象拥有的句柄组。更多详情	Accessor
Mesh	围绕其 x、y 和 z 轴 (按该顺序) 旋转网格几何。更多详情	Mesh
Mesh	按指定因子缩放网格几何。更多详情	Mesh
Object	将此类的实例转换为 GeoScene Portal JSON 表示。更多详情	Geometry
	通知需要重新计算依赖于折点属性的任何缓存值。更多详情	Mesh

方法详细说明

addComponent(component)

向网格添加一个组件。

参数

component MeshComponent autocast

自动转换自 Object

要添加的组件。

addHandles(handleOrHandles, groupKey)inherited 起始版本：GeoScene Maps SDK for JavaScript 4.25

添加一个或多个与对象的生命周期相关联的句柄。当对象被销毁时，将移除句柄。

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);

参数

handleOrHandles WatchHandle|WatchHandle []

对象销毁后，标记为要移除的句柄。

groupKey *

optional

标识句柄应添加到的组的键。组中的所有句柄稍后都可使用 Accessor.removeHandles() 进行删除。如果未提供键，则句柄将被添加到默认组。

centerAt(location, params){Mesh}

将网格居中于指定位置，而不更改其比例。网格将就地修改。要改为修改网格副本，请在调用 centerAt() 之前使用 clone()。

参数

规范

location Point

网格居中的位置。

params Object

optional

其他参数。

规范

geographic Boolean

optional

是相对于地球还是投影坐标系 (PCS) 进行地理配准。此参数仅与可在局部和全球查看模式 (当前仅限 WebMercator) 中使用的空间参考相关，否则将被忽略。默认值为 true。如果为 true，则应用于网格中心的平移是在笛卡尔坐标系中完成的，其相对于地球上的局部坐标系，并以米为单位指定。

origin Point

optional

要居中的原点。如果未指定，网格将在格网范围中心居中。

类型	描述
Mesh	修改后的网格。

clone(){Mesh}

创建 Mesh 对象的深度克隆。

类型	描述
Mesh	Mesh 对象的新实例，其等于用于调用 `.clone()` 的对象。

createBox(location, params){Mesh}static

创建表示为方格的网格。结果网格的空间参考与其放置位置相同。

方格 UV 坐标空间

方格几何将具有根据以下方案生成的 UV 坐标：

参数

规范

location Point

方格底部中心的位置。

params Object

optional

其他参数。

规范

size Number|Object

optional

统一的大小值或包含单个 ”宽度“、”高度“ 和 ”深度“ 值的对象。大小值的单位派生自所提供位置的空间参考，除非指定了单位。

规范

width Number

optional

创建的网格的宽度。

depth Number

optional

创建的网格的深度。

height Number

optional

创建的网格的高度。

geographic Boolean

optional

是相对于地球还是投影坐标系 (PCS) 进行地理配准。此参数仅与可在局部和全球查看模式 (当前仅限 WebMercator) 中使用的空间参考相关，否则将被忽略。默认值为 true。如果为 true，则在笛卡尔坐标系中创建网格，其相对于地球上的局部坐标系，并以米为单位指定大小。

unit String

optional

大小的单位 (默认为位置空间参考的单位)。

material MeshMaterial autocast

optional

自动转换自 Object

用于网格的材料。

imageFace String

optional

用于生成图像 uv 坐标的面。默认情况下，会为所有面生成一组未解析的 UV 坐标。通过将 imageFace 参数设置为以下值之一：east、west、north、south、up 或 down，指定的面将具有完整大小的 UV 坐标，而其他面将与其常规未解析的 UV 坐标有关。这对于仅将图像应用于框的单个面很有用。提供的 material 参数将应用于指定的 imageFace。生成的格网将有两个组件，第一个包含选定的图像面，第二个包含框的其他面。

类型	描述
Mesh	结果网格。

示例

let mesh = Mesh.createBox(point, {
  size: {
    width: 10,
    height: 100,
    depth: 20
  },
  material: {
    color: "green"
  }
});

let mesh = Mesh.createBox(point, {
  imageFace: "top",
  material: {
    colorTexture: new MeshTexture({ url: "./url-to-image.png" })
  }
});

createCylinder(location, params){Mesh}static

创建表示圆柱体的网格。结果网格的空间参考与其放置位置相同。

圆柱 UV 坐标空间

圆柱体几何将具有根据以下方案生成的 UV 坐标 (以下为 8 个折点圆柱体示例)：

参数

规范

location Point

圆柱体底部中心的位置。

params Object

optional

其他参数。

规范

size Number|Object

optional

统一的大小值或包含单个 ”宽度“、”高度“ 和 ”深度“ 值的对象。大小值的单位派生自所提供位置的空间参考，除非指定了特定单位。

规范

width Number

optional

创建的网格的宽度。

depth Number

optional

创建的网格的深度。

height Number

optional

创建的网格的高度。

geographic Boolean

optional

unit String

optional

大小的单位 (默认为位置空间参考的单位)。

densificationFactor Number

optional

用于生成表示圆柱体网格的其他细分数。densificationFactor 参数为 0 将生成默认的 16 个折点，以近似于圆柱体。densificationFactor 为 1 将生成 32 个折点，依此类推。densificationFactor 越大，网格就越接近完美的圆柱体 (以处理和渲染性能为代价)。

material MeshMaterial autocast

optional

自动转换自 Object

用于网格的材料。

类型	描述
Mesh	结果网格。

createFromGLTF(location, url, params){Promise<Mesh>}static 起始版本：GeoScene Maps SDK for JavaScript 4.11

从 url 参数引用的 glTF 模型创建新的网格几何。结果格网的空间参考与 location 参数相同。有关支持的 glTF 功能的详细信息，可参阅使用 3D 符号可视化点指南主题。目前不支持动画。

参数

规范

location Point

模型原点的位置。如果位置不包含 z 值，则假定 z 为 0。

url String

glTF 模型的 URL。URL 应指向 glTF 文件 (.gltf 或 .glb)，该文件可引用其他二进制文件 (.bin) 和图像文件 (.jpg, .png)。

params Object

optional

其他参数。

规范

geographic Boolean

optional

signal AbortSignal

optional

中止加载过程的 AbortSignal。如果取消，则承诺将被拒绝，并返回一个名为 AbortError 的错误。另请参见 AbortController。

类型	描述
Promise<Mesh>	解析为表示加载的 glTF 模型的格网几何的 promise。

createFromPolygon(polygon, params){Mesh}static

从面几何创建新的网格几何。生成的格网仅包含一个位置折点属性和带有面的单个组件。默认着色将设置为 flat。结果格网的空间参考与输入多边形相同。生成的格网将不包含任何 uv 或法线折点属性。

参数

polygon Polygon

输入面。

params Object

optional

可选参数。

规范

material MeshMaterial autocast

optional

自动转换自 Object

用于网格的材料。

类型	描述
Mesh	表示三角化面的新格网。

createPlane(location, params){Mesh}static

创建表示平面的网格。结果网格的空间参考与其放置位置相同。平面由两个三角形组成，在创建时可以方便地定向。

平面 UV 坐标空间

平面几何将具有根据以下方案生成的 UV 坐标：

参数

规范

location Point

平面底部中心的位置。

params Object

optional

其他参数。

规范

size Number|Object

optional

统一的大小值或包含单个宽度和高度值的对象。大小值的单位派生自所提供位置的空间参考，除非指定了单位。

规范

width Number

optional

创建的网格的宽度。

height Number

optional

创建的网格的高度。

facing String

optional

默认值："up"

平面朝向的方向。

geographic Boolean

optional

unit String

optional

大小的单位 (默认为位置空间参考的单位)。

material MeshMaterial autocast

optional

自动转换自 Object

用于网格的材料。

类型	描述
Mesh	结果网格。

createSphere(location, params){Mesh}static

创建表示球体的网格。结果网格的空间参考与其放置位置相同。

球体 UV 坐标空间

球体几何将具有根据以下方案生成的 UV 坐标（以下为 8x8 个折点球体示例）：

参数

规范

location Point

球体底部中心的位置。

params Object

optional

其他参数。

规范

size Number|Object

optional

统一的大小值或包含单个 ”宽度“、”高度“ 和 ”深度“ 值的对象。大小值的单位派生自所提供位置的空间参考，除非指定了单位。

规范

width Number

optional

创建的网格的宽度。

depth Number

optional

创建的网格的深度。

height Number

optional

创建的网格的高度。

geographic Boolean

optional

unit String

optional

大小的单位 (默认为位置空间参考的单位)。

densificationFactor Number

optional

用于生成表示球体网格的其他细分数。densificationFactor 参数为 0 将生成默认的 16*16 个折点，以近似于球体。densificationFactor 为 1 将生成 32*32 个折点，依此类推。densificationFactor 越大，网格就越接近完美的球体 (以处理和渲染性能为代价)。

material MeshMaterial autocast

optional

自动转换自 Object

用于网格的材料。

类型	描述
Mesh	结果网格。

fromJSON(json){*}static

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

参数

json Object

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

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

hasHandles(groupKey){Boolean}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.25

如果存在指定的句柄组，则返回 true。

参数

groupKey *

optional

组键。

类型	描述
Boolean	如果存在指定的句柄组，则返回 `true`。

示例

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

offset(dx, dy, dz, params){Mesh}

将网格几何偏移指定的距离 (以 x、y 和 z 为单位)。x、y 和 z 的单位是空间参考的单位。当在地理上应用偏移时 (默认为 GCS 或 WebMercator)，则偏移量以米为单位进行解释。网格将就地修改。要修改格网副本，请在调用 offset() 之前使用 clone()。

参数

规范

dx Number

在 x 方向上偏移几何的量。

dy Number

在 y 方向上偏移几何的量。

dz Number

在 z 方向上偏移几何的量。

params Object

optional

其他参数。

规范

geographic Boolean

optional

是相对于地球还是投影坐标系 (PCS) 进行地理配准。此参数仅与可在局部和全球查看模式 (当前仅限 WebMercator) 中使用的空间参考相关，否则将被忽略。默认值为 true。如果为 true，则在笛卡尔坐标系中应用偏移，其相对于地球上的局部坐标系，并以米为单位指定。

origin Point

optional

要应用偏移的原点如果未指定，则网格将从格网范围中心进行偏移。

类型	描述
Mesh	修改后的格网 (此实例)。

removeComponent(component)

从网格中移除组件。

参数

component MeshComponent

要移除的组件。

removeHandles(groupKey)inherited 起始版本：GeoScene Maps SDK for JavaScript 4.25

移除对象拥有的句柄组。

参数

groupKey *

optional

要移除的组键或组键的数组或集合。

示例

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

rotate(angleX, angleY, angleZ, params){Mesh}

围绕其 x、y 和 z 轴 (按该顺序) 旋转网格几何。对于每个旋转角度，当从相应轴的方向看时，旋转方向为顺时针方向。网格将就地修改。要修改格网副本，请在调用 rotate() 之前使用 clone()。

参数

规范

angleX Number

绕 x 轴旋转的角度（以度为单位）。

angleY Number

绕 y 轴旋转的角度（以度为单位）。

angleZ Number

绕 z 轴旋转的角度（以度为单位）。

params Object

optional

其他参数。

规范

geographic Boolean

optional

是相对于地球还是投影坐标系 (PCS) 进行地理配准。此参数仅与可在局部和全球查看模式 (当前仅限 WebMercator) 中使用的空间参考相关，否则将被忽略。默认值为 true。如果为 true，则在笛卡尔坐标系中应用旋转，其相对于地球上的局部坐标系，并以米为单位指定。

origin Point

optional

要围绕其旋转的原点。如果未指定，则格网将围绕格网范围中心进行旋转。

类型	描述
Mesh	修改后的格网 (此实例)。

示例

// rotate the mesh in the horizontal plane (around the z axis) by 90 degrees and tilt it in the lateral
// vertical plane (around the y axis) by 20 degrees.
mesh.rotate(0, 20, 90);

scale(factor, params){Mesh}

按指定因子缩放网格几何。网格将就地修改。要修改格网副本，请在调用 scale() 之前使用 clone()。

参数

规范

factor Number

缩放几何的量。

params Object

optional

其他参数。

规范

geographic Boolean

optional

是相对于地球还是投影坐标系 (PCS) 进行地理配准。此参数仅与可在局部和全球查看模式 (当前仅限 WebMercator) 中使用的空间参考相关，否则将被忽略。默认值为 true。如果为 true，则在笛卡尔坐标系中应用缩放，其相对于地球上的局部坐标系。

origin Point

optional

缩放的原点。如果未指定，则将围绕格网范围中心缩放格网。

类型	描述
Mesh	修改后的格网 (此实例)。

toJSON(){Object}inherited

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

类型	描述
Object	此类实例的 GeoScene Portal JSON 表示。

vertexAttributesChanged()

通知需要重新计算依赖于折点属性的任何缓存值。适当修改折点属性后使用此方法，以便相应地重新计算依赖于这些折点属性的值 (例如，范围的计算)。

GeoScene Maps SDK for JavaScript参考手册

创建简单的网格几何基元

手动创建网格几何

构造函数

属性概述

属性详细信息

方法概述

方法详细说明

方格 UV 坐标空间

圆柱 UV 坐标空间

平面 UV 坐标空间

球体 UV 坐标空间