简体中文

地图查看器

Viewer 类

Viewer 是 3D 地图查看器的核心类，提供了地图显示、相机控制、图层管理、场景渲染等功能。

构造函数

constructor(containerId: string, options?: ViewerOptions)

参数：

containerId (string): 容器 DOM 元素的 ID
options (ViewerOptions, 可选): 初始化配置选项

示例：

const viewer = new Viewer('map-container', {
  proj4: '+proj=utm +zone=50 +datum=WGS84 +units=m +no_defs',
  sunLight: true,
  baseMapUrls: 'https://your-domain.com/tiles/{z}/{x}/{y}.png',
  terrainUrl: 'https://your-domain.com/terrain'
});

属性

运行时属性

属性名	类型	描述
`app`	`ViewerApp`	ViewerApp 实例
`container`	`HTMLDivElement`	场景容器 DOM 元素
`renderer`	`object`	渲染器对象，包含 `domElement` (HTMLCanvasElement)

视图相关

属性名	类型	描述
`viewMode`	`"2D" \| "3D"`	视图模式
`viewInfo`	`object`	当前视图信息（heading, pitch, position）
`projectedViewRange`	`object`	投影视图范围，包含坐标数组
`fov`	`number`	视野角度（Field of View）
`proj4`	`string`	Proj4 投影字符串
`userDefinedProj4`	`string?`	用户自定义的 Proj4 字符串

相机属性

属性名	类型	描述
`camera`	`object`	相机对象，包含 position、rotation、fov、aspect、type
`controlMode`	`number`	控制模式
`viewCollision`	`boolean`	滚轮缩放防撞

场景渲染

属性名	类型	描述
`sunLight`	`boolean`	是否启用太阳光
`isSunShadow`	`boolean?`	是否启用太阳阴影
`sunFlare`	`boolean`	太阳耀光效果
`sunIntensity`	`number`	太阳光强度
`envLightIntensity`	`number`	环境光强度
`useAdditionalEnvLight`	`boolean`	是否使用额外的环境光
`sceneDate`	`Date`	场景日期时间
`useSceneDate`	`boolean`	是否使用场景日期

后处理效果

属性名	类型	描述
`postProcessingManager`	`object`	后处理管理器，详见下方
`lut`	`string?`	已废弃，被 postProcessingManager 取代

postProcessingManager 对象：

属性名	类型	描述
`lut`	`string?`	LUT 色彩查找表
`lutIntensity`	`number`	LUT 强度
`brightness`	`number`	亮度
`contrast`	`number`	对比度
`saturation`	`number`	饱和度
`hue`	`number`	色调
`ACESFilmicToneMapping`	`boolean`	ACES 色调映射
`blooming`	`boolean`	泛光效果
`bloomingStrength`	`number`	泛光强度
`bloomingThreshold`	`number`	泛光阈值
`colorTemperature`	`number`	色温调节
`ao`	`boolean`	环境光遮蔽（Ambient Occlusion）
`on`	`function`	事件监听，如 `on('LUTLoad', callback)`

地形相关

属性名	类型	描述
`terrainTransparency`	`number`	地形透明度 (0-1)

等高线设置

属性名	类型	描述
`contourSetting`	`object`	等高线配置对象
`contourSetting.enabled`	`boolean`	是否启用等高线
`contourSetting.color`	`number`	等高线颜色
`contourSetting.lineWidth`	`number`	线宽
`contourSetting.contourInterval`	`number`	等高线间隔
`contourSetting.minHeight`	`number`	最小高度
`contourSetting.maxHeight`	`number`	最大高度

交互相关

属性名	类型	描述
`identifyDrawing`	`boolean`	是否识别绘制对象
`identifyFeature`	`boolean`	是否识别要素
`rotationBoxControl`	`boolean`	是否显示旋转控制盒
`rotationBoxLocale`	`LocaleName`	旋转控制盒语言

地图显示区域

属性名	类型	描述
`enableMapDisplayArea`	`boolean`	是否启用地图显示区域限制
`mapDisplayArea`	`object`	地图显示区域配置
`mapDisplayArea.coords`	`[number, number]`	左上和右下坐标
`mapDisplayArea.fromEPSG`	`number \| string`	坐标系 EPSG 代码

云和天空

属性名	类型	描述
`cloudBox`	`CloudBoxSetting?`	云盒设置（getter/setter）
`cloud`	`SceneCloudSetting?`	场景云设置（getter/setter）
`volumetricLighting`	`VolumetricLightingSetting?`	体积光设置（getter/setter）

底图和地形

属性名	类型	描述
`baseMapUrls`	`BaseMapUrl \| BaseMapUrl[]`	底图 URL 配置（setter）
`baseMapUrls`	`Array<{uuid, wrapper}>`	底图列表（getter）
`terrainUrl`	`string \| string[]?`	地形 URL（setter）
`terrainUrl`	`string?`	地形 URL（getter）
`basemapScreenSpaceError`	`number`	底图屏幕空间误差（LOD 控制）

其他

属性名	类型	描述
`animations`	`Record<string, any>`	动画集合
`locale`	`LocaleName`	语言设置

方法

相机控制

`zoomTo(options: CameraPose): void`

快速跳转到指定相机位置（无动画）。

参数：

options (CameraPose): 相机姿态配置

viewer.zoomTo({
  x: 500000,
  y: 3000000,
  z: 1000,
  heading: 0,
  pitch: -45
});

`flyTo(options: CameraPose): void`

飞行到指定相机位置（带动画）。

参数：

options (CameraPose): 相机姿态配置

`flyToLookAt(options): void`

飞行并查看指定位置。

参数：

{
  x: number,
  y: number,
  z: number,
  distance?: number  // 相机距离目标点的距离
}

点云图层

`addPointcloudLayer(options: PointCloudLayerOptions): Promise<{id, layer}>`

添加点云图层。

返回： Promise，包含图层 ID 和图层对象

`flyToPointcloudById(id: number | string): void`

飞行到指定点云图层。

`setPointcloudOpacityById(id: number | string, opacity: number): void`

设置点云不透明度。

参数：

opacity: 0-1 之间的小数

`setPointcloudPointSizeById(id: number | string, size: number): void`

设置点云点大小。

`setPointCloudColorScheme(id: number | string, scheme: PointCloudColorScheme): void`

设置点云颜色方案。

`setPointCloudHeightRange(id: number | string, minHeight: number, maxHeight: number): void`

设置点云高度范围过滤。

`setPointCloudIntensityRange(id: number | string, minIntensity: number, maxIntensity: number): void`

设置点云强度范围过滤。

3D Tiles 图层

`add3DTilesLayer(options: Tiles3DLayerOptions): Promise<{id, layer}>`

添加 3D Tiles 图层。

返回： Promise，包含图层 ID 和图层对象

`flyTo3DTilesById(id: number | string, options?): void`

飞行到指定 3D Tiles 图层。

参数：

options?: {
  heading?: number,
  pitch?: number
}

`set3DTilesOpacityById(id: number | string, opacity: number): void`

设置 3D Tiles 不透明度（0-1）。

`set3DTilesVisibleById(id: number | string, visible: boolean): void`

设置 3D Tiles 可见性。

`set3DTilesFeatureVisibleById(layerId: number | string, features: number[]): void`

设置 3D Tiles 指定要素的可见性。

`set3DTilesNoFlattening(layerIds: (number | string)[], isNoFlatten: boolean): void`

设置 3D Tiles 是否不进行扁平化处理。

`getIs3DTilesNoFlatteningById(layerId: number | string): boolean`

获取指定图层是否启用了不扁平化。

`getNoFlatteningList(): (number | string)[]`

获取所有不扁平化的图层 ID 列表。

`get3DTilesFeatureTree(layerId: number | string): any`

获取 3D Tiles 要素树结构。

`setIs3DTilesRawFeatureTypesVisible(layerId, featureKeys, boolean): void`

设置 3D Tiles 原始要素类型的可见性。

`flyTo3DTilesBBox(layerId: number | string, bbox: any): void`

飞行到 3D Tiles 的边界框。

`clear3DTilesFeatureColorById(layerId: number): void`

清除 3D Tiles 要素颜色。

`set3DTilesDefaultColorById(layerId: number, color: number, alpha: number): void`

设置 3D Tiles 默认颜色。

`set3DTilesFeatureColorById(layerId: number, featureIds: number[], color: number, alpha: number): void`

设置 3D Tiles 指定要素的颜色。

`getIs3DTilesWireframeById(layerId: number | string): boolean`

获取是否启用线框模式。

`setIs3DTilesWireframeById(layerId: number | string, isWireframe: boolean): void`

设置 3D Tiles 线框模式。

`setIs3DTilesUseEnvMap(layerId: number | string, isUseEnvMap: boolean): void`

设置 3D Tiles 是否使用环境贴图。

`set3DTilesLoadStartEvent(layerId: number | string, callback: () => void): void`

设置 3D Tiles 加载开始事件回调。

`set3DTilesLoadEvent(layerId: number | string, callback: () => void): void`

设置 3D Tiles 加载完成事件回调。

`set3DTilesErrorTarget(layerId: number | string, val: number): void`

设置 3D Tiles 错误目标值（LOD 控制）。

底图管理

`addBaseMapLayer(value: BaseMapUrl, index: number): void`

在指定索引位置添加底图图层。

`removeBaseMapLayer(index: number): void`

移除指定索引的底图图层。

`moveUp(index: number): void`

提升瓦片地图的顺序（向上移动）。

`moveDown(index: number): void`

降低瓦片地图的顺序（向下移动）。

`getTileMap(): object | undefined`

获取瓦片地图对象。

返回：

{
  buffGeometryLayers: {
    highlightById: (options: { idArray: number[] }) => void
  },
  updateStyleByIndex: (index: number, baseMap: BaseMapUrl) => void
} | undefined

`updateTile(id, originalGeoJSON, modifiedGeoJSON, originalProj4, currentProj4): void`

更新瓦片数据。

截图和录制

`getScreenCaptureRaw(): Promise<Blob>`

获取屏幕截图的原始数据。

返回： Promise

`getScreenCapture(pictureName: string): void`

保存屏幕截图到文件。

`startVideoRecord(): void`

开始视频录制。

`stopVideoRecord(videoName: string): void`

停止视频录制并保存。

动画

`playOrbitAnimation(config?: Partial<OrbitAnimationConfig>): void`

播放环绕动画。

参数：

{
  duration?: number,           // 总时长
  lookAt?: Position3D,        // 观察点
  isCounterClockwise?: boolean, // 是否逆时针
  heading?: number,           // 航向角
  pitch?: number,             // 俯仰角
  distance?: number,          // 距离
  circleDuration?: number     // 单圈时长
}

`stopOrbitAnimation(): void`

停止环绕动画。

高斯泼溅（Splatting）

`setSplatting(path, positionInfo, cb?): void`

设置高斯泼溅模型。

参数：

path: string,
positionInfo: {
  position: Position3D,
  heading: number,
  pitch: number,
  roll: number,
  scale: number
},
cb?: () => void

`flyToSplatting(): void`

飞行到高斯泼溅模型。

天气和场景

`setWeather(weather: Weather): void`

设置天气效果。

参数：

weather: "SUNNY" | "RAINY" | "FOGGY" | "SNOWY"

位置信息

`getScale(): number`

获取当前比例尺。

`getPositionLocal(): {x, y, z}`

获取当前本地坐标位置。

`getCartographic(): [longitude, latitude]`

获取当前经纬度坐标。

旋转控制盒

`setRotationBoxTopRight(config: {top?, right?}): void`

设置旋转控制盒的位置。

事件

使用 on 方法监听事件：

viewer.on(eventName, callback);

事件列表

`identify`

要素识别事件。

回调参数： IdentifyData

viewer.on('identify', (featureInfo) => {
  console.log('识别到要素:', featureInfo);
});

`bimFeatureTypeLoad`

BIM 要素类型加载完成事件。

回调参数：

json: Record<string, number[]> - 要素类型映射
id: number - 图层 ID

`cameramove`

相机移动事件（普通精度）。

回调参数：

{
  x: number,
  y: number,
  z: number,
  heading: number,
  pitch: number
}

`cameramoveprecise`

相机移动事件（高精度）。

回调参数： CameraPose

`click`

鼠标点击事件。

回调参数：

(
  position: { x: number, y: number, z: number },
  obj: any,
  event: MouseEvent
)

`move`

鼠标移动事件。

回调参数：

(
  position: { x: number, y: number, z: number },
  obj: any,
  event: MouseEvent
)

配置选项

ViewerOptions

Viewer 构造函数的配置选项。

参数	类型	必需	默认值	描述
`far`	`number`	否	-	相机远裁剪面距离
`proj4`	`string`	否	-	Proj4 投影字符串
`sunLight`	`boolean`	否	-	是否启用太阳光
`baseMapUrls`	`BaseMapUrl \| BaseMapUrl[]`	否	-	底图配置
`terrainUrl`	`string`	否	-	地形服务 URL
`isWebGL2`	`boolean`	否	-	是否使用 WebGL2
`mapMaximumLevel`	`number`	否	-	地图最大层级
`licensingServiceUrl`	`string`	否	-	许可服务 URL
`basemapScreenSpaceError`	`number`	否	-	底图屏幕空间误差（LOD）
`viewCollision`	`boolean`	否	-	滚轮缩放防撞
`useSceneDate`	`boolean`	否	-	是否使用场景日期

底图配置 BaseMapUrl

底图支持多种服务类型，可以是字符串 URL 或配置对象。

1. 字符串模板 URL

type BaseMapUrl = string;

直接使用瓦片 URL 模板：

viewer.baseMapUrls = 'https://your-domain.com/tiles/{z}/{x}/{y}.png';

2. TEMPLATE 类型

类型： TEMPLATEOptions

字段	类型	必需	描述
`type`	`"TEMPLATE"`	是	服务类型
`url`	`string`	是	瓦片 URL 模板
`opacity`	`number`	否	不透明度 (0-1)

{
  type: "TEMPLATE",
  url: "https://your-domain.com/{z}/{x}/{y}.png",
  opacity: 0.8
}

3. WMS 服务

类型： WMSOptions

WMS (Web Map Service) 标准服务配置。

字段	类型	必需	默认值	描述
`type`	`"WMS"`	是	-	服务类型
`url`	`string`	是	-	WMS 服务基础 URL
`version`	`string`	是	`"1.3.0"`	WMS 版本号
`layers`	`string`	是	`"0"`	图层名称（逗号分隔）
`format`	`string`	是	`"image/png"`	图像格式
`styles`	`string`	是	`""`	图层样式
`key`	`string`	是	`""`	API 密钥/令牌
`opacity`	`number`	否	-	不透明度 (0-1)

示例：

{
  type: "WMS",
  url: "https://your-domain.com/wms",
  version: "1.3.0",
  layers: "layer1,layer2",
  format: "image/png",
  styles: "",
  key: "your-api-key"
}

4. ArcGIS MapServer

类型： ArcGisMapServerOptions

ArcGIS 地图服务配置。

字段	类型	必需	描述
`type`	`"ArcGIS_MapService"`	是	服务类型
`url`	`string`	是	ArcGIS MapServer URL
`format`	`string`	是	图像格式（默认 "png8"）
`epsg`	`string`	是	坐标系 EPSG 代码
`key`	`string`	是	API 密钥

示例：

{
  type: "ArcGIS_MapService",
  url: "https://services.arcgis.com/xxx/arcgis/rest/services/xxx/MapServer",
  format: "png8",
  epsg: "EPSG:4326",
  key: "your-api-key"
}

5. ArcGIS FeatureServer

类型： ArcGisFeatureServerOptions

ArcGIS 要素服务配置（支持矢量渲染）。

继承自： TileMapStyle

字段	类型	必需	描述
`type`	`"ArcGIS_FeatureService"`	是	服务类型
`url`	`string`	是	ArcGIS FeatureServer URL
`epsg`	`string`	否	坐标系 EPSG 代码
`pointColor`	`string`	否	点颜色
`pointSize`	`number`	否	点大小（像素）
`lineColor`	`string`	否	线颜色
`lineWidth`	`number`	否	线宽（像素）
`fillColor`	`string`	否	填充颜色

示例：

{
  type: "ArcGIS_FeatureService",
  url: "https://services.arcgis.com/xxx/arcgis/rest/services/xxx/FeatureServer/0",
  epsg: "EPSG:4326",
  pointColor: "#FF0000",
  pointSize: 5,
  lineColor: "#0000FF",
  lineWidth: 2,
  fillColor: "#00FF0080"
}

6. WFS 服务

类型： WFSOptions

WFS (Web Feature Service) 标准服务配置。

继承自： TileMapStyle

字段	类型	必需	默认值	描述
`type`	`"WFS"`	是	-	服务类型
`uuid`	`string`	否	-	唯一标识符
`url`	`string`	是	-	WFS 服务 URL
`version`	`string`	是	-	WFS 版本号
`typeName`	`string`	是	-	图层类型名称
`outputFormat`	`string`	是	`"GeoJSON"`	输出格式
`key`	`string`	否	-	API 密钥
`rule`	`any`	否	-	样式规则
`SLD`	`SldObj`	否	-	SLD 样式对象
`fields`	`string[]`	否	-	字段列表
`text`	`object`	否	-	文本样式配置
`opacity`	`number`	否	-	不透明度 (0-1)

文本样式：

text?: {
  color?: string,              // 文本颜色
  fontSize?: number,           // 字体大小
  property?: string,           // 属性字段名
  scaleDenominator?: {         // 比例尺范围
    min: number | null,
    max: number | null
  }
}

示例：

{
  type: "WFS",
  url: "https://your-domain.com/geoserver/wfs",
  version: "2.0.0",
  typeName: "workspace:layer",
  outputFormat: "application/json",
  pointColor: "#FF0000",
  lineColor: "#0000FF",
  lineWidth: 2
}

7. GeoTwin FeatureTileService（可编辑图层）

类型： GeoTwinFeatureTileServiceOptions

GeoTwin 专用的矢量瓦片服务，支持高性能渲染和复杂样式。

字段	类型	必需	默认值	描述
`type`	`"GeoTwin_FeatureTileService"`	是	-	服务类型
`uuid`	`string`	否	-	唯一标识符
`url`	`string`	是	-	服务 URL（不含 `/{z}/{x}/{y}`）
`token`	`string`	否	-	访问令牌
`format`	`string \| boolean`	否	`true`	响应格式（true=二进制，推荐）
`count`	`number`	否	-	每个请求最大要素数
`fields`	`string[]`	是	-	字段列表（建议明确指定）
`rule`	`GtFeatureTileStyleRule`	否	-	样式规则（将迁移到 SLD）
`SLD`	`SldObj`	否	-	SLD 样式对象
`params`	`Record<string, string\|boolean>`	否	-	自定义请求参数
`TEXTLAYER_OPTIONS`	`object`	否	-	文本标注配置
`clampToModel`	`boolean`	否	-	是否贴合模型
`highlight`	`Highlight`	否	-	高亮配置
`opacity`	`number`	否	-	不透明度 (0-1)

TEXTLAYER_OPTIONS：

{
  clustering: boolean  // 是否启用文本聚合
}

高亮配置：

highlight?: {
  idArray: number[],
  style: {
    lineColor?: string,
    lineWidth?: number,
    fillColor?: string
  }
}

示例：

{
  type: "GeoTwin_FeatureTileService",
  url: "https://api.your-domain.com/tiles/layer1",
  token: "your-token",
  fields: ["ogc_fid", "name", "type"],
  rule: {
    type: "classification",
    property: "type",
    styles: [
      {
        value: "residential",
        fillColor: "#FFD700",
        lineColor: "#FF4500",
        lineWidth: 2
      }
    ]
  }
}

TileMapStyle（瓦片地图样式）

用于矢量图层的基础样式配置。

字段	类型	描述
`pointColor`	`string`	点颜色（6 位十六进制或 rgba 字符串）
`pointSize`	`number`	点大小（像素）
`lineColor`	`string`	线条颜色
`lineWidth`	`number`	线宽（像素）
`fillColor`	`string`	填充颜色
`graphicFill`	`any`	图形填充
`dashArray`	`number[]`	虚线样式

GtFeatureTileStyleRule（样式规则）

用于 GeoTwin FeatureTileService 的高级样式规则。

规则类型

type GtFeatureTileStyleRuleType = "classification" | "range" | "gradient" | "histogram3D";

classification: 分类规则，根据字段的不同值设置样式
range: 范围规则，根据字段值的范围设置样式
gradient: 渐变规则，根据字段值设置渐变颜色
histogram3D: 三维柱状图

规则配置

字段	类型	描述
`type`	`GtFeatureTileStyleRuleType`	规则类型
`property`	`string`	属性字段名
`material`	`string`	材质
`baseHeight`	`string \| number`	基础高度
`topHeight`	`string \| number`	顶部高度
`styles`	`GtFeatureTileStyleRuleStyle[]`	样式数组
`sideTexture`	`SideTexture`	侧面纹理
`style`	`object`	样式配置（用于渐变等）

样式配置（GtFeatureTileStyleRuleStyle）

支持非常丰富的样式选项，包括：

点样式：

pointColor: 点颜色
pointRadius: 点半径
text: 文本样式
IconMarker: 图标标记
TextMarker: 文本标记
GLTFModelJson: 3D 模型
SectorScanJson: 扇形扫描效果

线样式：

lineColor: 线条颜色
lineWidth: 线宽
lineJoin: 连接样式（"round" | "bevel" | "miter"）
lineCap: 端点样式（"round" | "butt" | "square"）
dashArray: 虚线数组
GlowLineJson: 发光线条
TraceLineJson: 轨迹线条
HorizontalDynamicFenceJson: 水平动态围栏

面样式：

fillColor: 填充颜色
graphicFill: 图形填充（支持线条填充等）
GenericDrawPolygon: 通用面绘制

示例：分类样式

{
  type: "classification",
  property: "building_type",
  styles: [
    {
      value: "residential",
      fillColor: "#FFD700",
      lineColor: "#FF4500",
      lineWidth: 2,
      text: {
        color: "#000000",
        fontSize: 14,
        property: "name"
      }
    },
    {
      value: "commercial",
      fillColor: "#87CEEB",
      lineColor: "#4169E1",
      lineWidth: 2
    }
  ]
}

示例：渐变样式

{
  type: "gradient",
  property: "population",
  style: {
    from: 0,
    to: 100000,
    styles: [
      { value: 0, fillColor: "#FFFFE0" },
      { value: 50000, fillColor: "#FFA500" },
      { value: 100000, fillColor: "#FF0000" }
    ]
  }
}

示例：3D 柱状图

{
  type: "histogram3D",
  property: "value",
  baseHeight: 0,
  topHeight: "value", // 使用字段值作为高度
  material: "basic",
  styles: [
    {
      fillColor: "#4169E1",
      lineColor: "#000000",
      lineWidth: 1
    }
  ]
}

示例：图标标记

{
  IconMarker: {
    icon: "/assets/marker.png",
    offset: 0,
    size: { x: 32, y: 32 },
    center: { x: 0.5, y: 1 }
  }
}

示例：3D 模型标记

{
  GLTFModelJson: {
    path: "/models/tree.glb",
    coordinateSystem: "EPSG:4326",
    pitch: 0,
    heading: 0,
    roll: 0,
    scaleX: 1,
    scaleY: 1,
    scaleZ: 1
  }
}

示例：发光线条

{
  GlowLineJson: {
    color: "#00FFFF",
    lineWidth: 3,
    glowWidth: 10,
    brightness: 2,
    renderOnTop: true
  }
}

类型定义

CameraPose（相机姿态）

interface CameraPose extends Position3D, Rotation {
  epsg?: string;
  roll?: number;
}

包含：

x, y, z: 位置坐标
heading: 航向角（度）
pitch: 俯仰角（度）
roll: 滚转角（度，可选）
epsg: 坐标系（可选）

Position3D / Position2D

interface Position3D {
  x: number;
  y: number;
  z: number;
}

interface Position2D {
  x: number;
  y: number;
}

Rotation

interface Rotation {
  heading: number;  // 航向角（度）
  pitch: number;    // 俯仰角（度）
}

Weather（天气类型）

type Weather = "SUNNY" | "RAINY" | "FOGGY" | "SNOWY";

CloudBoxSetting（云盒设置）

interface CloudBoxSetting {
  visible: boolean;      // 是否可见
  coverage: number;      // 覆盖度
  shadow: number;        // 阴影
  thickness: number;     // 厚度
  steps: number;         // 步数
  noise: number;         // 噪声
  windSpeed: number;     // 风速
}

SceneCloudSetting（场景云设置）

interface SceneCloudSetting {
  visible: boolean;      // 是否可见
  topLevel: number;      // 顶层高度
  baseLevel: number;     // 底层高度
  range: number;         // 范围
  flowSpeed: number;     // 流动速度
  steps: number;         // 步数
  coverage: number;      // 覆盖度
  cloudType: number;     // 云类型
}

VolumetricLightingSetting（体积光设置）

interface VolumetricLightingSetting {
  filterLen: number;     // 滤镜长度
  intensity: number;     // 强度
}

IdentifyData（识别数据）

识别事件返回的数据类型，可以是以下几种之一：

IdentifyBimData（BIM 数据识别）

interface IdentifyBimData {
  layerId: number | string;
  featureId: number | undefined;
  attributes: AnyOptions | undefined;
  position: { x: number; y: number; z: number };
}

IdentifyPointCloudData（点云数据识别）

interface IdentifyPointCloudData {
  layerId: number | string;
  featureId: null;
  pointAttributes: {
    position: { x: number; y: number; z: number };
    color: [r: number, g: number, b: number, a: number];
    intensity: number;
    classification: number;
  };
}

IdentifyMapData（地图数据识别）

type IdentifyMapData = IdentifyMapSuccessData | IdentifyMapFailureData;

interface IdentifyMapSuccessData {
  layerId: string;
  position: Position2D;
  type: "GeoTwin_FeatureTileService" | "WFS";
  attributes: Record<string, string | number | boolean | null>;
  geometry?: Geometry;  // GeoJSON Geometry
}

interface IdentifyMapFailureData {
  error: string;
  layerId: undefined;
  position: Position2D;
  type: string;
}

使用示例

基础初始化

import { Viewer } from './Viewer3D';

const viewer = new Viewer('map-container', {
  proj4: '+proj=utm +zone=50 +datum=WGS84 +units=m +no_defs',
  sunLight: true,
  baseMapUrls: [
    'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}',
    {
      type: "GeoTwin_FeatureTileService",
      url: "https://api.your-domain.com/tiles/roads",
      token: "your-token",
      fields: ["ogc_fid", "name", "road_type"],
      rule: {
        type: "classification",
        property: "road_type",
        styles: [
          {
            value: "highway",
            lineColor: "#FF0000",
            lineWidth: 4
          },
          {
            value: "local",
            lineColor: "#FFFFFF",
            lineWidth: 2
          }
        ]
      }
    }
  ],
  terrainUrl: 'https://your-domain.com/terrain'
});

监听事件

// 相机移动事件
viewer.on('cameramove', (pos) => {
  console.log('相机位置:', pos);
});

// 要素识别事件
viewer.on('identify', (data) => {
  if ('layerId' in data && 'attributes' in data) {
    console.log('识别到要素:', data.attributes);
  }
});

// 点击事件
viewer.on('click', (position, obj, event) => {
  console.log('点击位置:', position);
});

相机控制

// 飞行到指定位置
viewer.flyTo({
  x: 500000,
  y: 3000000,
  z: 1000,
  heading: 0,
  pitch: -45
});

// 环绕动画
viewer.playOrbitAnimation({
  lookAt: { x: 500000, y: 3000000, z: 0 },
  distance: 2000,
  circleDuration: 30000,
  pitch: -30
});

添加图层

// 添加 3D Tiles
const { id, layer } = await viewer.add3DTilesLayer({
  url: 'https://your-domain.com/tileset.json',
  name: 'Building Model'
});

// 添加点云
await viewer.addPointcloudLayer({
  url: 'https://your-domain.com/pointcloud/metadata.json',
  name: 'Point Cloud Data'
});

后处理效果

// 启用泛光效果
viewer.postProcessingManager.blooming = true;
viewer.postProcessingManager.bloomingStrength = 1.5;
viewer.postProcessingManager.bloomingThreshold = 0.8;

// 色彩调整
viewer.postProcessingManager.brightness = 0.1;
viewer.postProcessingManager.contrast = 1.2;
viewer.postProcessingManager.saturation = 1.1;

// 加载 LUT
viewer.postProcessingManager.lut = '/assets/luts/cinematic.cube';
viewer.postProcessingManager.lutIntensity = 0.8;

天气效果

// 设置天气
viewer.setWeather('RAINY');

// 云盒配置
viewer.cloudBox = {
  visible: true,
  coverage: 0.6,
  shadow: 0.5,
  thickness: 50,
  steps: 100,
  noise: 0.3,
  windSpeed: 10
};

注意事项

底图顺序：baseMapUrls 数组中，越靠前的底图层级越低（在下层）
LUT 已废弃：直接使用 viewer.lut 已废弃，请使用 viewer.postProcessingManager.lut
坐标系统：确保所有图层和相机位置使用一致的坐标系统（通过 proj4 配置）
性能优化：使用 basemapScreenSpaceError 和 set3DTilesErrorTarget 控制 LOD，平衡性能和质量
GeoTwin FeatureTileService：
- 推荐使用二进制格式（format: true）以获得最佳性能
- 明确指定 fields 列表，避免遗漏或加载不必要的数据
- 样式规则 rule 将逐步迁移到 SLD 对象
事件监听：使用 TypeScript 时，事件回调会自动推断正确的类型

ON THIS PAGE

地图查看器#

目录#

Viewer 类#

构造函数#

属性#

运行时属性#

视图相关#

相机属性#

场景渲染#

后处理效果#

地形相关#

等高线设置#

交互相关#

地图显示区域#

云和天空#

底图和地形#

其他#

方法#

相机控制#

zoomTo(options: CameraPose): void#

flyTo(options: CameraPose): void#

flyToLookAt(options): void#

点云图层#

addPointcloudLayer(options: PointCloudLayerOptions): Promise<{id, layer}>#

flyToPointcloudById(id: number | string): void#

setPointcloudOpacityById(id: number | string, opacity: number): void#

setPointcloudPointSizeById(id: number | string, size: number): void#

setPointCloudColorScheme(id: number | string, scheme: PointCloudColorScheme): void#

setPointCloudHeightRange(id: number | string, minHeight: number, maxHeight: number): void#

setPointCloudIntensityRange(id: number | string, minIntensity: number, maxIntensity: number): void#

3D Tiles 图层#

add3DTilesLayer(options: Tiles3DLayerOptions): Promise<{id, layer}>#

flyTo3DTilesById(id: number | string, options?): void#

set3DTilesOpacityById(id: number | string, opacity: number): void#

set3DTilesVisibleById(id: number | string, visible: boolean): void#

set3DTilesFeatureVisibleById(layerId: number | string, features: number[]): void#

set3DTilesNoFlattening(layerIds: (number | string)[], isNoFlatten: boolean): void#

getIs3DTilesNoFlatteningById(layerId: number | string): boolean#

getNoFlatteningList(): (number | string)[]#

get3DTilesFeatureTree(layerId: number | string): any#

setIs3DTilesRawFeatureTypesVisible(layerId, featureKeys, boolean): void#

flyTo3DTilesBBox(layerId: number | string, bbox: any): void#

clear3DTilesFeatureColorById(layerId: number): void#

set3DTilesDefaultColorById(layerId: number, color: number, alpha: number): void#

set3DTilesFeatureColorById(layerId: number, featureIds: number[], color: number, alpha: number): void#

getIs3DTilesWireframeById(layerId: number | string): boolean#

setIs3DTilesWireframeById(layerId: number | string, isWireframe: boolean): void#

setIs3DTilesUseEnvMap(layerId: number | string, isUseEnvMap: boolean): void#

set3DTilesLoadStartEvent(layerId: number | string, callback: () => void): void#

set3DTilesLoadEvent(layerId: number | string, callback: () => void): void#

set3DTilesErrorTarget(layerId: number | string, val: number): void#

底图管理#

addBaseMapLayer(value: BaseMapUrl, index: number): void#

removeBaseMapLayer(index: number): void#

moveUp(index: number): void#

moveDown(index: number): void#

getTileMap(): object | undefined#

updateTile(id, originalGeoJSON, modifiedGeoJSON, originalProj4, currentProj4): void#

截图和录制#

getScreenCaptureRaw(): Promise<Blob>#

getScreenCapture(pictureName: string): void#

startVideoRecord(): void#

stopVideoRecord(videoName: string): void#

动画#

playOrbitAnimation(config?: Partial<OrbitAnimationConfig>): void#

stopOrbitAnimation(): void#

高斯泼溅（Splatting）#

setSplatting(path, positionInfo, cb?): void#

flyToSplatting(): void#

天气和场景#

setWeather(weather: Weather): void#

位置信息#

getScale(): number#

getPositionLocal(): {x, y, z}#

getCartographic(): [longitude, latitude]#

旋转控制盒#

setRotationBoxTopRight(config: {top?, right?}): void#

事件#

事件列表#

identify#

地图查看器

目录

Viewer 类

构造函数

属性

运行时属性

视图相关

相机属性

场景渲染

后处理效果

地形相关

等高线设置

交互相关

地图显示区域

云和天空

底图和地形

其他

方法

相机控制

`zoomTo(options: CameraPose): void`

`flyTo(options: CameraPose): void`

`flyToLookAt(options): void`

点云图层

`addPointcloudLayer(options: PointCloudLayerOptions): Promise<{id, layer}>`

`flyToPointcloudById(id: number | string): void`

`setPointcloudOpacityById(id: number | string, opacity: number): void`

`setPointcloudPointSizeById(id: number | string, size: number): void`

`setPointCloudColorScheme(id: number | string, scheme: PointCloudColorScheme): void`

`setPointCloudHeightRange(id: number | string, minHeight: number, maxHeight: number): void`

`setPointCloudIntensityRange(id: number | string, minIntensity: number, maxIntensity: number): void`

3D Tiles 图层

`add3DTilesLayer(options: Tiles3DLayerOptions): Promise<{id, layer}>`

`flyTo3DTilesById(id: number | string, options?): void`

`set3DTilesOpacityById(id: number | string, opacity: number): void`

`set3DTilesVisibleById(id: number | string, visible: boolean): void`

`set3DTilesFeatureVisibleById(layerId: number | string, features: number[]): void`

`set3DTilesNoFlattening(layerIds: (number | string)[], isNoFlatten: boolean): void`

`getIs3DTilesNoFlatteningById(layerId: number | string): boolean`

`getNoFlatteningList(): (number | string)[]`

`get3DTilesFeatureTree(layerId: number | string): any`

`setIs3DTilesRawFeatureTypesVisible(layerId, featureKeys, boolean): void`

`flyTo3DTilesBBox(layerId: number | string, bbox: any): void`

`clear3DTilesFeatureColorById(layerId: number): void`

`set3DTilesDefaultColorById(layerId: number, color: number, alpha: number): void`

`set3DTilesFeatureColorById(layerId: number, featureIds: number[], color: number, alpha: number): void`

`getIs3DTilesWireframeById(layerId: number | string): boolean`

`setIs3DTilesWireframeById(layerId: number | string, isWireframe: boolean): void`

`setIs3DTilesUseEnvMap(layerId: number | string, isUseEnvMap: boolean): void`

`set3DTilesLoadStartEvent(layerId: number | string, callback: () => void): void`

`set3DTilesLoadEvent(layerId: number | string, callback: () => void): void`

`set3DTilesErrorTarget(layerId: number | string, val: number): void`

底图管理

`addBaseMapLayer(value: BaseMapUrl, index: number): void`

`removeBaseMapLayer(index: number): void`

`moveUp(index: number): void`

`moveDown(index: number): void`

`getTileMap(): object | undefined`

`updateTile(id, originalGeoJSON, modifiedGeoJSON, originalProj4, currentProj4): void`

截图和录制

`getScreenCaptureRaw(): Promise<Blob>`

`getScreenCapture(pictureName: string): void`

`startVideoRecord(): void`

`stopVideoRecord(videoName: string): void`

动画

`playOrbitAnimation(config?: Partial<OrbitAnimationConfig>): void`

`stopOrbitAnimation(): void`

高斯泼溅（Splatting）

`setSplatting(path, positionInfo, cb?): void`

`flyToSplatting(): void`

天气和场景

`setWeather(weather: Weather): void`

位置信息

`getScale(): number`

`getPositionLocal(): {x, y, z}`

`getCartographic(): [longitude, latitude]`

旋转控制盒

`setRotationBoxTopRight(config: {top?, right?}): void`

事件

事件列表

`identify`