Merge branch 'master' of https://github.com/antvis/L7

docs/api/earth/earth.zh.md

@@ -7,34 +7,39 @@ order: 1
 
 ## 简介
 
-L7Earth 相较于高德地图、mapbox 地图，是完全不同的一种表现形式，提供了全球视角下的可视化展示能力，为用户提供了更多的地理信息可视化表现形式。
+l7-maps 提供 `Earth` 地图，相较于高德地图、mapbox 地图，是完全不同的一种表现形式，提供了全球视角下的可视化展示能力，为用户提供了更多的地理信息可视化表现形式。
 
-✨ 为了区别普通的地图，L7Earth 提供了全新的 Earth 地图类型以及对应的 EarthLayer 图层
+✨ 为了区别普通的地图，l7-maps 提供了全新的 `Earth` 地图类型， L7 提供对应的 `EarthLayer` 图层
+
+```js
+import { EarthLayer } from '@antv/l7';
+import { Earth } from '@antv/l7-maps';
+```
 
 ## 目前在地球模式下支持的图层类型
 
 ### 点图层
 
-- 平面点
-- 圆柱点
+- 平面点: `shape: 'circle'`
+- 圆柱点: `shape: 'cylinder'`
 
 ### 线图层
 
-- 3D 弧线
+- 3D 弧线: `shape: 'arc3d'`
 
 ## 使用
 
 ```javascript
 // 1、引入对应模块
-import { Earth } from '@antv/l7-maps';
+import { Scene, Earth } from '@antv/l7-maps';
 import { EarthLayer } from '@antv/l7-layers';
-...
+
 // 2、构建 Earth Map
 const scene = new Scene({
-      id: 'map',
-      map: new Earth({}),
-    });
-...
+  id: 'map',
+  map: new Earth({}),
+});
+
 // 3、构建地球图层，当前的 shape 为 base，表示基础球体
 const earthlayer = new EarthLayer()
   .source(
@@ -61,41 +66,90 @@ const earthlayer = new EarthLayer()
   })
   .animate(true);
 
-// 4、添加基础地球球体
-scene.addLayer(earthlayer);
-
+scene.on('loaded', () => {
+  // 4、添加基础地球球体
+  scene.addLayer(earthlayer);
+});
 // 经过上述的步骤，我们就可以在场景中添加一个基础的地球了
 ```
 
 ## 独立的地图类型 Earth
 
-### 构造函数 Earth(args)
+### 构造函数 Earth
 
-作为 L7Earth 的基础地图类型，Earth 提供了地球系统的相机系统，目前只需要传入一个空对象。
+作为 l7-maps 的基础地图类型，`Earth` 提供了地球系统的相机系统，目前只需要传入一个空对象。
 
 - args: {}
 
-### rotateY(option: { force: boolean; regScale: number})
+```js
+import { Scene, Earth } from '@antv/l7-maps';
 
-提供了简单的方法控制地球系统的旋转（实际上控制的是相机的旋转）
+const scene = new Scene({
+  id: 'map',
+  map: new Earth({}),
+});
+```
 
-- force: false 判断是否强制生效，默认该方法的优先级比用户鼠标操作要低，当用户操作相机的时候，该方法会失效
-- regScale: 0.01 旋转的角度（视觉上地球的旋转角度）， regScale 表示的并不是实际的旋转角度，而是单位旋转角度的比例  
+### rotateY
+
+提供了简单的方法控制地球系统的旋转（实际上控制的是相机的旋转，需要传入一个对象
+
+- force: `false` 判断是否强制生效，默认该方法的优先级比用户鼠标操作要低，当用户操作相机的时候，该方法会失效
+- regScale: `0.01` 旋转的角度（视觉上地球的旋转角度）， `regScale` 表示的并不是实际的旋转角度，而是单位旋转角度的比例  
   🌟 单位旋转角度 = Math.min(this.earthCameraZoom \* this.earthCameraZoom, 1)
 
+```js
+import { Scene, Earth } from '@antv/l7-maps';
+
+const scene = new Scene({
+  id: 'map',
+  map: new Earth({}),
+});
+
+const mapService = scene.getMapService();
+
+function step() {
+  mapService.rotateY({
+    option: {
+      force: true,
+      regScale: 350,
+    },
+  });
+  requestAnimationFrame(step);
+}
+
+scene.on('loaded', () => {
+  scene.addLayer(earthlayer);
+  requestAnimationFrame(step);
+});
+```
+
 ## 地图图层 EarthLayer
 
 地球图层区别于普通高德地图和 Mapbox 地图的图层，只在地球模式下可以被使用，用于表示地球的球体、大气层、辉光等效果。  
-🌟 使用不同的 shape 参数表示区别不同的地球图层
+🌟 使用不同的 `shape` 参数表示区别不同的地球图层。
 
 ### 地球球体图层 baseLayer
 
-- source(map, parser)
-  map: 地球表面纹理贴图的地址
-  parser: 解析器，目前只需要写固定的对象值即可 { parser: { type: "image" } }
-- shape: 'base'  
-  🌟 目前支持的 shape 类型有 base、atomSphere、bloomSphere，当用户的 shape 参数不被识别时，自动降级为 base 类型
-- globelOtions: style 方法中的参数 ambientRatio: 环境光、diffuseRatio: 漫反射、specularRatio: 高光反射
+- source: 数据
+
+  - map: 地球表面纹理贴图的地址
+  - parser: 解析器，目前只需要写固定的对象值即可: `{ parser: { type: "image" } }`
+
+- shape: 图层类型
+
+  默认值是 `base`, 目前支持的 `shape` 类型有:
+
+  - base: 球体
+  - atomSphere: 大气层
+  - bloomSphere: 辉光
+
+  当用户的 `shape` 参数不被识别时，自动降级为 `base` 类型
+
+- globelOtions: 图层样式
+  - ambientRatio: 环境光
+  - diffuseRatio: 漫反射
+  - specularRatio: 高光反射
 
 ```javascript
 const earthlayer = new EarthLayer()
@@ -117,9 +171,11 @@ const earthlayer = new EarthLayer()
   });
 ```
 
+<img src="https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*i_TBRZRLSuYAAAAAAAAAAAAAARQnAQ" alt="L7 地球图层" width="300" height="300">
+
 ### 地球内发光/大气图层 atomLayer
 
-atomLayer 作为地球的效果图层，不需要传入数据，所以可以不调用 source 方法
+`atomLayer` 作为地球的效果图层，不需要传入数据，所以可以不调用 `source` 方法
 
 ```javascript
 const atomLayer = new EarthLayer()
@@ -131,9 +187,11 @@ const atomLayer = new EarthLayer()
   });
 ```
 
+<img src="https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*1MU_RZQyFTkAAAAAAAAAAAAAARQnAQ" alt="L7 地球图层大气效果" width="300" height="300" >
+
 ### 地球内外发光/辉光图层 bloomLayer
 
-bloomLayer 作为地球的效果图层，不需要传入数据，所以可以不调用 source 方法
+`bloomLayer` 作为地球的效果图层，不需要传入数据，所以可以不调用 `source` 方法
 
 ```javascript
 const bloomLayer = new EarthLayer()
@@ -143,3 +201,5 @@ const bloomLayer = new EarthLayer()
     opacity: 0.5,
   });
 ```
+
+<img src="https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*FTniTZOZkNUAAAAAAAAAAAAAARQnAQ" alt="L7 地球图层辉光效果" width="300" height="300" >

docs/api/earth/flyline.zh.md

@@ -9,10 +9,26 @@ order: 3
 
 用户在地球模式下使用飞线图层无需做额外的操作，L7 会自动识别地球模式并相关的转化
 
+<img src="https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*4ZCnQaH_nLIAAAAAAAAAAAAAARQnAQ" alt="L7地球飞线图层" width="300" height="300">
+
 ## 使用
 
 ```javascript
-// 1、引入对应模块
+import { Scene, EarthLayer, LineLayer } from '@antv/l7';
+import { Earth } from '@antv/l7-maps';
+const scene = new Scene({
+  id: 'map',
+  map: new Earth({}),
+});
+
+const flydata = [
+  {
+    coord: [
+      [104.195397, 35.86166],
+      [100.992541, 15.870032],
+    ],
+  },
+];
 const flyLine = new LineLayer({ blend: 'normal' })
   .source(flydata, {
     parser: {
@@ -22,20 +38,23 @@ const flyLine = new LineLayer({ blend: 'normal' })
   })
   .color('#b97feb')
   .shape('arc3d')
-  .size(0.5)
-  .active(true)
-  .animate({
-    interval: 2,
-    trailLength: 2,
-    duration: 1,
-  })
-  .style({
-    opacity: 1,
-    segmentNumber: 60,
-    globalArcHeight: 20,
-  });
-...
-// 2、注册服务
-scene.addLayer(flyLine);
+  .size(0.5);
 
+const earthlayer = new EarthLayer()
+  .source(
+    'https://gw.alipayobjects.com/mdn/rms_23a451/afts/img/A*3-3NSpqRqUoAAAAAAAAAAAAAARQnAQ',
+    {
+      parser: {
+        type: 'image',
+      },
+    },
+  )
+  .color('#2E8AE6')
+  .shape('base');
+
+scene.on('loaded', () => {
+  scene.addLayer(earthlayer);
+  scene.addLayer(flyLine);
+  earthlayer.setEarthTime(4.0);
+});
 ```

docs/api/earth/point.zh.md

@@ -9,28 +9,52 @@ order: 3
 
 用户在地球模式下使用点图层无需做额外的操作，L7 会自动识别地球模式并相关的转化
 
+## 示例图片
+
+<img src="https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*ck1XSZ4Vw0QAAAAAAAAAAAAAARQnAQ" alt="L7 地球点图层" width="300" height="300" >
+
 ## 使用
 
 ```javascript
-// 1、构建 pointlayer
+import { Scene, PointLayer, EarthLayer } from '@antv/l7';
+import { Earth } from '@antv/l7-maps';
+const scene = new Scene({
+  id: 'map',
+  map: new Earth({}),
+});
+
+const d = [{ lng: 121.61865234375, lat: 25.29437116258816 }];
+
 const pointlayer = new PointLayer()
+  .source(d, {
+    parser: {
+      type: 'json',
+      x: 'lng',
+      y: 'lat',
+    },
+  })
+  .shape('circle')
+  .color('#f00')
+  .size(10)
+  .active(true);
+
+const earthlayer = new EarthLayer()
   .source(
-    data,
+    'https://gw.alipayobjects.com/mdn/rms_23a451/afts/img/A*3-3NSpqRqUoAAAAAAAAAAAAAARQnAQ',
     {
       parser: {
-        type: 'json',
-        x: 'lng',
-        y: 'lat',
+        type: 'image',
       },
     },
   )
-  // .shape('circle') // cylinder
-  .color('#f00')
-  .size(20) // .size('', () => [1, 1, 10])
-
-...
-
-// 2、添加 pointlayer 图层对象
-scene.addLayer(pointlayer);
+  .style({
+    globelOtions: {
+      ambientRatio: 1, // 环境光
+    },
+  });
 
+scene.on('loaded', () => {
+  scene.addLayer(earthlayer);
+  scene.addLayer(pointlayer);
+});
 ```

stories/customMap/components/earth2.tsx

@@ -69,7 +69,7 @@ export default class ScaleComponent extends React.Component {
           },
         },
       )
-      .shape('fill')
+      .shape('base')
       .style({
         globelOtions: {
           ambientRatio: 0.6, // 环境光