安装
//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): 图层的不透明度
● 交互属性
-
pickable(Boolean, default: false): 层是否响应鼠标指针选择事件。
-
onHover(Function): 当鼠标进入/离开此deck.gl层的对象时,将调用此回调,具有以下参数:
● info: 此时鼠标下的信息
● event: 事件对象
-
onClick(Function): 当鼠标点击此deck.gl层的对象时,将调用此回调,具有以下参数: 同onHover
-
onDragStart, onDrag, onDragEnd同Deck回调事件;
-
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)
})
坐标系
-
World:世界坐标系,这里的数值就是经纬度与海拔,这个坐标系本质上是墨卡托坐标系,所以其内部空间是非线性坐标,一般只用于作输入传入,几何运算与线性变换都不在这个坐标系处理。
-
Common:公用坐标系,这里本质上就是在讲墨卡托坐标进行转换之后的三维坐标系,这个坐标系是线性坐标系,绝大部分几何运算与线性变换都可以在这个坐标系内部完成。
-
Pixel:屏幕空间坐标系,及是相机裁减空间在屏幕上的投影坐标,显然这是二维坐标系,常用于作一些固定像素大小的图形,比如文字图例之类的。
-
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. callingdeck.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
-
effects (Effect[]):要呈现的效果数组。如果提供一个空数组,将添加一个照明效果。参考effect的文档查看详细信息: LightingEffect | deck.gl
-
_framebuffer :(实验性)渲染到自定义帧缓冲区而不是屏幕。
-
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