# dmap

> 3d map visualization lib

Latest version **0.2.9** (published 2017-09-14) · 0 weekly downloads

## Install

```sh
npm install dmap
pnpm add dmap
yarn add dmap
bun add dmap
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.9 |
| Published | 2017-09-14 |
| First published | 2015-05-19 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.8.0 |
| Dependencies | 16 |
| Known vulnerabilities | 0 (+17 in 5 direct dependencies) |
| Install scripts | no |
| Author | zhouningyi |
| Maintainers | fish, guowei, polokobe, wandergis, zhouningyi |

## Links

- npm: https://www.npmjs.com/package/dmap
- npm.io page: https://npm.io/package/dmap

## Dependencies (16)

- [async](https://npm.io/package/async.md) 2.1.4
- [bcore](https://npm.io/package/bcore.md) 0.0.21
- [three](https://npm.io/package/three.md) 0.86.0
- [jquery](https://npm.io/package/jquery.md) 2.1.4
- [lodash](https://npm.io/package/lodash.md) 4.17.2
- [dat-gui](https://npm.io/package/dat-gui.md) 0.5.0
- [leaflet](https://npm.io/package/leaflet.md) 0.7.7
- [request](https://npm.io/package/request.md) *
- [ngeohash](https://npm.io/package/ngeohash.md) 0.6.0
- [tween.js](https://npm.io/package/tween.js.md) 16.3.5
- [chroma-js](https://npm.io/package/chroma-js.md) 1.3.4
- [node-geocoder](https://npm.io/package/node-geocoder.md) *
- [normalize.css](https://npm.io/package/normalize.css.md) 4.2.0
- [aliyun-map-utils](https://npm.io/package/aliyun-map-utils.md) 0.0.29
- [polyline-normals](https://npm.io/package/polyline-normals.md) ^2.0.2
- [aliyun-common-utils](https://npm.io/package/aliyun-common-utils.md) 0.0.28

## Recent versions

- 0.2.9 (latest) — 2017-09-14
- 0.2.8 — 2017-08-18
- 0.2.7 — 2017-08-18
- 0.2.6 — 2017-08-05
- 0.2.5 — 2017-08-04
- 0.2.4 — 2017-08-04
- 0.2.3 — 2017-08-04
- 0.2.2 — 2017-08-04
- 0.2.1 — 2017-08-04
- 0.1.69 — 2017-08-03
- 0.1.68 — 2017-08-03
- 0.1.67 — 2017-08-03
- 0.1.66 — 2017-08-03
- 0.1.65 — 2017-04-07
- 0.1.64 — 2017-03-13
- … 42 more at https://npm.io/package/dmap/versions

## README

# dmap
高性能、通用的 webgl地图组件库

-------------
## 简介
dmap是一种3d的地理类可视化引擎（一些非地理相关的功能也能实现）

dmap依赖开源、通用的jquery 和 three.js。

dmap基于webgl，性能合表现比svg、canvas等其他dom元素形成的可视化更好。但webgl非所有浏览器支持，如需兼容性更好的2d地图，可以使用[ldmap](git@gitlab.alibaba-inc.com:datav/l-dmap.git) 

### 安装

```
tnpm install @ali/ldmap
```

### 启动
dmap的组件采用require机制，你可以用 [node-cube](https://github.com/node-cube/cube) 启动 

```
sudo npm install node-cube -g
cd your_dir
cube start
```

浏览demo ```http://localhost:9999/demo/``` 

### 绑定
一些地理数据放在内部服务器，需日常环境绑定

```
10.189.224.26 daily.s.aliyun.com# daily
```


## 引入:
可以整体引入

```javascript
var D = require('@ali/dmap');
var map = new D.Map(container, options);
```
也可部分引入

```javascript
var Map = require('@ali/dmap/map/map');
var map = new Map(container, options);
```

为了选择性引入，可以了解dmap的目录组织 ↓↓↓

## 目录:
d-map目录组织如下：

| 名称 | 说明 |
| ----|:-----:|
|map	|map是地图的核心，此目录包括map的构造、投影、交互、渲染等|
|layer  |3d图层，包括地理类图层和可视类图层，详见下文|
|layer_2d|2d的可视化贴图，可以贴图在地球等实体表面|
|render|和绘图相关的，如特殊3d结构、shader等|
|core|公共方法等|
|mapping|贴图|
|demo	|案例|



## 数据:
组件开发主要涉及地理数据和可视化数据。
### 地理类：
地理类数据组要为geojson格式，如地理边界、公路数据等。 [详细](http://www.oschina.net/translate/geojson-spec?cmp)

### 可视类：
在javascript语法层面上，可视类数据一般有2层结构，如:

[[]] 型: 
```
[['上海', 222], ['宁波市':111], ...]
```

[{}] 型: 
```
[{name: '上海', value: 222}, {name: '宁波市', value:111}, ...] 
```

{{}} 与 {[]}型数据同理。

从展现形式区分 分为连接型数据、与点状、面状、轨迹数据。

点状数据（点图、热力图等）:
```
[{name: '上海', value: 222}, {name: '宁波市', value:111}, ...]
```
连接型数据（飞线数据等）:
```
[{name: '上海', value: 222, from: { lat: 30, lng: 120}, to: { lat: 30.5, lng: 120.6}], {name: '上海', value: 222, from: { lat: 30, lng: 120}, to: { lat: 30.9, lng: 120.8}], ...]
```


## map
map是地图的核心，包含:
1、初始化三维环境
2、与输入进行交互
3、定义了地理投影
4、触发各类事件等

当移动或缩放map结束，鼠标离开时，map默认会打印现在的位置信息。

map的交互方式有2种，平移和旋转，敲击键盘自动切换(外部禁了敲击事件除外)。

### map的初始化:

```javascript
var Map = require('@ali/dmap/map/map');
var container = $('#map-container');
var map = new Map(container, {});
```

### map的配置: 

| 名称 | 类型 |说明 |
| ----|:-----:| ----:|
| projection |String| 投影方式， 详见下表 |
| angle | Number|相机视野的角度，50为人眼视野角度 |
| near | Number |相机可视最近距离 |
| far | Number |相机可视最远距离 |
|rotation|Object| 相机旋转角 {x: x, y: y} |
|rotateSpeed|Number| 相机旋转缓动速度 |
|center|Object| 相机视觉的中心坐标 {x: x, y: y， z:z}|
|moveSpeed|Number| 相机中心移动的速度|
|distance|Number| 相机距离中心的距离 |
|moveSpeed|Number| 相机缩放缓动速度 |
|autoRotateSpeed|Number|自动旋转速度|
|clearColor|ColorString|webgl背景色|
|clearAlpha|Number|0-1 webgl背景透明度|
|globalAlpha|Number|0-1 总体透明度|


projection的分类:

| map投影方式 | 说明 |
| ----|:-----:|
| plane / mecator | 墨卡托投影 最通用的平面投影方式|
| sphere | 球面投影|
| origin_2d | 将经纬度直接按照数值映射到平面上|
| normal |  {x:x,y:y,z:z} -> {x:x,y:y,z:z}(非经纬度映射)|

### map的方法:

## layer

layer是3d地图的层，层即具有独立意义的整体。

和数据一样，layer可分为地理展现和可视展现。

地理展现包括贴图地球、太阳、地理边界、建筑层等。

可视展现包括点图、热力图、飞线图、区域热力图等。

但对于组件而言，一个组件也许兼具两种类型,如/layer/area.js 其可以勾勒地理边界，也可以填充颜色形成区域热力图(即所谓Choropleth map)

大部分可视化图层，都能跟随map的投影方式，如平面图和地球。

layer/addons目录存放不常用的，辅助性的图表，如标注、辅助线等。

部分layer会分为2个层次，如 flying_lines 和 flying_line。 flying_lines管理一组飞线，而flying_line管理一根飞线。

### layer分类:
| 名称 | 说明 |
| ----|:-----:|
|globe.js|地球的模型 支持多种贴图|
|sky.js|天空,支持贴图和颜色|
|solar.js|太阳， 可以做光源、支持发光效果|
|areas.js	|通过geojson格式的边界地理数据，绘制矢量层|
|flying_lines.js|飞线图，支持如两地交易、电话通信等关联性数据可视化|
|layer_2d.js|生成2d的可视化贴图|
|heatmap_height.js	|高度热力图|
|scatter.js|3d点图|
|addons/markers|3d标注|

### layer初始化:

```javascript
var Map = require('@ali/dmap/map/map');
var Solar = require('./../layer/solar');
//初始化地图
var container = $('#map-container');
var map = new Map(container, {});
//各种不同的组件 构造的方式都很类似
var scatter = new Scatter();
scatter.addTo(map);
scatter.render([{lat:30, lng: 120}]);
```


### layer的配置:
配置采用多层的配置结构，传入组件后和组件的配置深度合并。

#### 普通通用配置:

| 名称 | 类型 |说明|
| ----|:-----:|-----:|
|ratio| Number|当投影为球面的时候，为了避免多个层重叠，各层在径向上的scale的比例|
|offset| Object|在投影结束后进行的偏移 {x:x,y:y,z:z}|

#### 函数型通用配置:
各组件配置中，有许多函数型配置，如颜色对应函数，经纬度提取函数等，以经纬度提取函数为例:
在我们传入render函数的data，组织结构也许非常多变，如:
```
//案例1
{
  lat: 30,
  lng: 120,
  value:1
}
//案例2
[30, 120, 1]
//案例3
{
  cp:{
  lat: 30,
  lng: 120
  },
  value: 1
}
//案例4
{
  cp:[30,120],
  value: 1
}
```

我们很难枚举这些常用的经纬度组合，为了获得数据中的经纬度，我们通过函数传入:


```
var getLat = function(d){
    var lat = d.lat || d.latitude || d[0];
    if(lat) return lat;
    var center = d.cp || d.center || d.c || d.pos || d.position;
    if(center) return center.lat || center[0] || center.latitude;
  };
//
var options = {
  lat: getLat
};
......
```
这些常用的字段可以为函数，
其中，d为可视数据中的一项，id为其序号或id。v为提取出来的可视化字段，min, max为其中的最值,feature为geojson的单元。

| 名称 | 说明 |常见输入值|
| ----|:-----:|-----:|
|lat|纬度提取函数|d, id|
|id|获取数据的id| d, id|
|geoid|获取地理数据的地理id|feature|
|color|色彩映射函数|v, min, max|
|value|获取需要可视化字段值的方法|d, id|


#### 特殊对象型通用配置:
配置中有一些具有普遍的特殊对象:
gradient对象：

```javascript
{
    'from': '#001f6b',//起始颜色
    'to': '#e4f2f1',//结束颜色
    'easing': 'Quadratic.Out.1.1',//过渡函数
    'space': 'hsl'//色彩空间
  }
```

gradient对象到组件内部，会通过内置的高阶函数构造一个颜色映射函数，当输入0-1的数值，返回相应的颜色。
easing字段用.隔开成3段， 前两段采用 TWEEN.js中描述过渡函数的记号，如线性变换Linear.None:

```javascript
function(k){
  return k;
}
```
后者在这个基础上进行乘方，如 Linear.None.2.2:
```javascript
function(k){
  return Math.pow(k, 2.2);
}
```

sprite对象:
经过内部处理，生成粒子系统、2d点图等的贴图，如:
```javascript
var options = {
  'sprite': {
    'drawN': 1.15,
    'color': {
        'from': 'hsla(20,100%,75%,0.8)',
        'to': 'hsla(120,100%,50%,0.1)',
        'easing': 'Linear.None.1.7',
        'space': 'rgb'
      }
  }
};
```
#### layer的方法:
不同组件有些公共的方法

| 名称 | 说明 |
| ----|:-----:|
|initialize	|初始化|
|init|init型的方法，各种初始化，如initEvents initDom|
|update|update型方法，多针对属性的改变进行更新，如updateColor|
|addTo	|加入地图|
|data|导入数据 有时进行一些处理|
|render| 接受数据并绘制|
|draw|仅仅绘制或图形更新|
|hide|回到初始状态而不销毁 可以用于组件回收|
|destroy|彻底清除|

## layer_2d
layer层基本是通过在3维空间里建立实体实现，另外有一种可视化方案，在贴图中实现可视化，贴入3d的实体表面，甚至与shader进行交互，layer_2d内的组件就是为了实现这种贴图。

| 名称 | 说明 |
| ----|:-----:|
|scatter|点/热力图|

---
_Source: https://npm.io/package/dmap · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._