Deck.gl学习笔记（二）：核心类中文文档翻译（持续更新中）

安装

//use npm
npm install deck.gl

//use yarn
yarn add deck.gl

在react中使用

import {Deck} from '@deck.gl/core';
import {ScatterplotLayer, TextLayer} from '@deck.gl/layers';

// a JSON file of flight locations in the shape of [{lon: -122.39, lat: 37.62, alt: 1800, callSign: 'SKW 3342'}, ...]
const flights = '/path/to/data.json';

const layers = [
  new ScatterplotLayer({
    id: 'circles',
    data: flights,
    getPosition: d => [d.lon, d.lat, d.alt],
    getFillColor: [255, 255, 255],
    getRadius: 3,
    radiusUnits: 'pixels'
  }),
  new TextLayer({
    id: 'labels',
    data: flights,
    getText: d => d.callSign,
    getPosition: d => [d.lon, d.lat, d.alt],
    getSize: 12
  })
];

const deckInstance = new Deck({
  initialViewState: {
    longitude: -122.4,
    latitude: 37.8,
    zoom: 8
  },
  controller: true
  layers
});

API详解

Layers

import {ScatterplotLayer} from '@deck.gl/layers';

const layer = new ScatterplotLayer({
  id: 'bart-stations',
  data: [
    {name: 'Colma', passengers: 4214, coordinates: [-122.466233, 37.684638]},
    {name: 'Civic Center', passengers: 24798, coordinates: [-122.413756,37.779528]},
    // ...
  ],
  stroked: false,
  filled: true,
  getPosition: d => d.coordinates,
  getRadius: d => Math.sqrt(d.passengers),
  getFillColor: [255, 200, 0]
});

基本属性

1.Layer ID : id prop是该层在所有层中的唯一标识符，id的默认值是层 “name”。如果一个特定层类型的多个实例同时存在，它们必须拥有deck的不同id字符串。像deck一样，在其自身中构造一个新层实例不会对性能产生任何影响。Gl只在创建层(第一次出现id)或更新层(为相同的id传递不同的props)时进行昂贵的计算。

2.data：data(Iterable | string | Promise | AsyncIterable | object, optional):  期待类型为  map、set、array、url、promise。默认为数组。

● 如果提供字符串，deck.gl将尝试将其作为URL加载，将其解析为JSON，然后使用预期 结果JavaScript数组作为其数据支柱。

● 如果是Promise函数，deck.gl将使用resolve解析值作为其数据支柱。

3.visible(Boolean): 层是否可见。在大多数情况下，建议使用可见道具来控制图层的可见性，不是使用条件渲染。

4. opacity(Number): 图层的不透明度

● 交互属性

1. pickable(Boolean, default: false): 层是否响应鼠标指针选择事件。

2. onHover(Function): 当鼠标进入/离开此deck.gl层的对象时，将调用此回调,具有以下参数:

        ● info: 此时鼠标下的信息

        ● event: 事件对象

1. onClick(Function): 当鼠标点击此deck.gl层的对象时,将调用此回调,具有以下参数: 同onHover

2. onDragStart, onDrag, onDragEnd同Deck回调事件;

3. highlightColor(Array, [0, 0, 128, 128])

● RGBA颜色用于渲染突出显示的对象。当指定3 component (RGB)数组时，alpha使用默认值255。

6. highlightedObjectIndex(Integer, -1)

● 当提供一个有效值时，对应的对象(实例渲染中的一个实例或具有相同拾取颜色的一组原语将使用highlightColor高亮显示。

7. autoHighLight(Boolean, false)

● 当为true时，鼠标指针指向的当前对象(悬停在其上时)用highlightColor高亮显示。要求picable为真。

● 坐标系统的属性 ---- 通常只在应用程序希望使用非Web Mercator投影经纬度的坐标时使用

1. coordinateSystem(Number): 指定如何对层位置和偏移量进行地理解释。

2. coordinateOrigin([Number, Number]): 将coordinateSystem设置为coordinate_system . meter_offset时需要。

3. wrapLongitude(Boolean, false): 自动将纵向缠绕在第180个反物质上，以获得当前视区的 佳可视性。

4. modelMatrix(Number[16]):一个可选的4x4矩阵，它被乘进着色器项目GLSL函数和Viewpor 的项目和非项目JavaScript函数使用的仿射投影矩阵

● 数据属性

1. dataComparator(Function): 这个支持使用自定义比较函数对数据支持进行比较。使用旧数 和新数据对象调用compare函数，如果它们进行相等的比较，则期望返回true。

2. numInstances(Number): deck.gl通过计算数据中对象的数量，自动从数据支柱中获取绘图 例的数量。但是，开发人员可能希望使用此道具手动覆盖它。

3. updateTriggers(Object): 调用getColor和getPosition等访问器来检索第一次添加层时的颜 和位置。从那以后，为了最大化性能，deck。gl不会重新计算颜色或位置，除非通过浅比较更改数据柱。

• Accessors:  访问器是一种将data中的对象映射到其可视配置的道具，例如圆的半径，线的颜色等。所有访问器道具名称都以get开头。如果accessor prop被设置为一个函数，当层第一次要在屏幕上绘制时，层将遍历数据流并调用每个元素的accessor函数。accessor接受两个参数，object、objectInfo                                         object：数据流中的当前元素。如果data是数组或可迭代对象，则使用当前迭代的元素。如果data是不可迭代对象，则此参数始终为空。

• objectInfo：当前元素的上下文信息。包含以下字段:

•  index：当前迭代的索引值

•  data ： 传递的data值

•  target：预分配的数组。accessor函数可以选择性地将数据填充到这个数组中并返回它，而不是为每个对象创建一个新数组。在某些浏览器中，这通过减少垃圾收集显著提高了性能。

• Interactivity：用来控制相机，deck.gl提供了将键盘、鼠标或触摸输入映射到相机状态变化的视口控制器。启用可视化的平移/缩放/旋转最简单的方法是将Deck或<DeckGL>上的controller属性设置为true，并使用initialViewState对象来定义初始相机设置: Interactivity | deck.gl

• Picking：pickable设置为true

    包含：

• onHover

• onClick

• onDragStart

• onDrag

• onDragEnd

     包括两个参数，info包含了交互时的信息、event表示指针事件

     The PickingInfo Object： Interactivity | deck.gl

     

import {Deck} from '@deck.gl/core';

new Deck({
  // ...
  // Callback when the pointer enters or leaves an object in any pickable layer
  onHover: (info, event) => console.log('Hovered:', info, event),
  // Callback when the pointer clicks on an object in any pickable layer
  onClick: (info, event) => console.log('Clicked:', info, event)
})

坐标系

1. World：世界坐标系，这里的数值就是经纬度与海拔，这个坐标系本质上是墨卡托坐标系，所以其内部空间是非线性坐标，一般只用于作输入传入，几何运算与线性变换都不在这个坐标系处理。

2. Common：公用坐标系，这里本质上就是在讲墨卡托坐标进行转换之后的三维坐标系，这个坐标系是线性坐标系，绝大部分几何运算与线性变换都可以在这个坐标系内部完成。

3. Pixel：屏幕空间坐标系，及是相机裁减空间在屏幕上的投影坐标，显然这是二维坐标系，常用于作一些固定像素大小的图形，比如文字图例之类的。

4. Clipspace：裁减空间坐标系，这里本质上是相机裁减空间也就是顶点最终输出的坐标系，这个坐标系也不是线性的，只能作为输出使用一般不进行几何运算。

Deck类

 Deck是一个使用Deck的类。deck.gl层实例和viewport参数，将这些层呈现为透明覆盖，并处事件;

● Deck类的属性:

1. width: 画布的宽(Number)
2. height: 画布的高(Number)
3. layers: 要渲染的层的集合 --- 将要渲染的层放到一个数组里面,进行逐个渲染(Array)

4. layersFilter: 接收一个函数,函数的参数为layer, viewport, isPicking, cullRect, renderPass,用来过滤层,调整视口, 是否发生拾取事件,所有层在渲染之前都会走这个函数,所以层的显隐可以在这里实现。如果层被渲染返回true。

• cullRect (object) - 如果定义，则表示只需要呈现到给定矩形的内容。

• renderPass

• 'screen' - drawing to screen

• 'picking:hover' - drawing to offscreen picking buffer due to pointer move

• 'picking:query' - drawing to offscreen picking buffer due to user-initiated query, e.g. calling deck.pickObject.

• 'shadow' - drawing to shadow map

注意：使用layerFilter如果通过visible: false或pickable: false禁用图层，不会覆盖其可见性。即使使用此方法过滤掉一个图层，也会触发除draw之外的所有生命周期方法

new Deck({
  // ...
  layerFilter: ({layer, viewport}) => {
    if (viewport.id !== 'minimap' && layer.id === 'geofence') {
      // only display geofence in the minimap
      return false;
    }
    return true;
  }
}

5. getCursor: 接收一个函数,来检索游标类型的自定义回调(Function: ({isDragging}) => isDragging ? 'grabbing' : 'grab')

6. views: 单个视图或视图实例的数组(可选与Viewport实例混合，尽管后者是不推荐的)。如没有提供，将创建一个MapView。如果提供了空数组，则不会显示任何视图。(Array)

7. viewState: 地理空间视图状态(Object)

● latitude: 经度(Number)
● longitude: 纬度(Number)

● zoom: 缩放程度(Number)
● bearing: 轴承程度(Number)

● pitch: 倾斜角度(Number: 0 - 90) 可以通过改变viewState的参数值来改变画布实例的角度位置

8. initialViewState: 如果提供了initialViewState, Deck组件将使用内部状态跟踪来自任何附加控制器的视图

 状态更改，initialViewState作为其初始视图状态。如果viewState prop是由应用程序提供的，那么提供的viewState将始终被使用，覆盖Deck组件的内部视图状态。(Object: 属性和viewState一样)

9. controller: 视窗互动选项，例如:平移，旋转和缩放与鼠标，触摸和键盘。如果使用默认视图 即单个MapView)，这是定义与视图道具交互的简写。

其值有以下几种类型:

● null or false: 默认不启动控制器
● true: 默认启动默认控制器
● Controller: 使用默认选项启动所提供的控制器。必须是MapController的子类。 

● 默认为null

1.  effects (Effect[]):要呈现的效果数组。如果提供一个空数组，将添加一个照明效果。参考effect的文档查看详细信息: LightingEffect | deck.gl

2.  _framebuffer :(实验性)渲染到自定义帧缓冲区而不是屏幕。

3.  getTooltip:

接收参数：

• info-描述悬停对象的拾取信息。

返回下列之一：

• null- 工具提示被隐藏，CSSdisplay属性设置为none。

• 字符串 - 该字符串使用下面描述的默认 CSS 样式在工具提示中呈现。

• 具有以下字段的对象：

  • text（字符串，可选） - 指定innerText工具提示的属性。

  • html(string，可选) - 指定innerHTML工具提示的属性。请注意，这将覆盖指定的innerText。

  • className（string，可选）- 附加到工具提示元素的类名。该元素的默认类名为deck-tooltip。

  • style(object，可选) - 应用于工具提示元素的 CSS 样式对象，可以覆盖默认样式。

  ● Deck类的配置属性:

1. id(String): Canvas ID允许在CSS中定制样式;

2. style(Object): deckgl-canvas的Css样式;

3. pickingRadius(Number): 在选择时指针周围要包括的额外像素。当呈现的对象难以定位时 这是很有帮助的，例如不规则形状的图标、小的移动圆圈或触摸交互。默认为0。

4. useDevicePixels(Boolean): 如果为真，设备的全分辨率将用于渲染，这个值可以在每帧中 变，比如在屏幕之间移动窗口或改变浏览器的缩放级别。默认为真,但是一般都将其设置为false,因为 个会非常消耗性能,除非机器的性能足够高.

5. gl(Object): gl的上下文,如果不提供将会自动创建; 

 ● Deck类的回调函数:

1. onWebGLInitialized(Function: (gl) => {....})：一旦webGL上下文被初始化,就会被调用;

2. onViewStateChange(Function: (viewState) -> {....}): 当用户改变画布角度时调用.例如使 鼠标拖曳, 键盘控制等.onViewStateChange({viewState, interactionState, oldViewState}):viewState表示更新后的view state对象，interactionState描述调用视图状态更改的交互动作。oldViewState表示更新前的view state对象。

3. onLayerHover(Function: ): 当指针下的对象发生变化时调用。在鼠标悬浮在物体之上发生 回调;

● 参数: info, pickedInfos, event
● info: 在坐标中最顶层选择的info对象，在没有选择对象时为null;

● pickedInfos: 所有受影响的可选层的信息对象数组。 ● event: 原始MouseEvent对象

4. onLayerClick(Function): 当指针点击时发生的回调.参数同Hover回调
5. onDragStart, onDrag, onDragEnd(Function): 拖曳开始, 拖曳中, 拖曳结束

● 参数: info, event 同Hover事件的参数

6. onLoad(Function): 在创建gl上下文和Deck组件(ViewManager、LayerManager等)之后调一次。可用于触发视口转换;

● Deck类的方法:

1. finalize: 立即释放与此对象关联的资源(而不是等待垃圾收集)。 deck.finalize();

2. setProps: 更新属性. deck.setProps({.....})

3. pickObject: 在给定的屏幕坐标上获取最近的可选可见对象. 

deck.pickObject({x, y, radius, layerIds, unproject3D})
x: x位置(像素)
y: y位置(像素)
radius: 以像素为单位的公差半径
layerIds: 要查询的层id的列表。如果没有指定，则查询所有可选的和可见的层

unproject3D: 如果为true，则info. coordinate 将通过将x, y屏幕坐标投影到所选几何上而成为一个3D点。默认false。

4.getCanvas：获取附加到这个Deck实例的canvas元素

5.pickMultipleObjects:执行深度pick。在给定的屏幕坐标上找到所有接近可选的可见对象，即使这些对象被其他对象遮挡。

deck.pickMultipleObjects({x, y, radius, layerIds, depth, unproject3D})

depth ：指定要返回的对象的最大数量。默认10。

6.pickObjects：获取边界框内所有可选择和可见的对象。

deck.pickObjects({x, y, width, height, layerIds, maxObjects})

metrics：Deck | deck.gl

源码地址

Deck类源码地址：modules/core/src/lib/deck.ts