From 620cebbd83b71cf1be57b65f8a727508c220c0d6 Mon Sep 17 00:00:00 2001 From: susiwen8 Date: Thu, 30 Dec 2021 12:01:10 +0800 Subject: [PATCH] Earth doc (#904) * docs: refine `Earth` doc * docs: style lint * docs: description --- docs/api/base.zh.md | 1 - docs/api/earth/earth.zh.md | 118 ++++++++++++++++++------ docs/api/earth/flyline.zh.md | 51 ++++++---- docs/api/earth/point.zh.md | 50 +++++++--- stories/customMap/components/earth2.tsx | 2 +- 5 files changed, 162 insertions(+), 60 deletions(-) diff --git a/docs/api/base.zh.md b/docs/api/base.zh.md index 49414b70c6..57b421ce58 100644 --- a/docs/api/base.zh.md +++ b/docs/api/base.zh.md @@ -264,7 +264,6 @@ layer.color('type*value', (type, value) => { - 也可以直接指定某一个具体的颜色值 color，如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 - 示例 ```javascript diff --git a/docs/api/earth/earth.zh.md b/docs/api/earth/earth.zh.md index 5c42bf9bc8..7078e390a5 100644 --- a/docs/api/earth/earth.zh.md +++ b/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() }); ``` +L7 地球图层 + ### 地球内发光/大气图层 atomLayer -atomLayer 作为地球的效果图层，不需要传入数据，所以可以不调用 source 方法 +`atomLayer` 作为地球的效果图层，不需要传入数据，所以可以不调用 `source` 方法 ```javascript const atomLayer = new EarthLayer() @@ -131,9 +187,11 @@ const atomLayer = new EarthLayer() }); ``` +L7 地球图层大气效果 + ### 地球内外发光/辉光图层 bloomLayer -bloomLayer 作为地球的效果图层，不需要传入数据，所以可以不调用 source 方法 +`bloomLayer` 作为地球的效果图层，不需要传入数据，所以可以不调用 `source` 方法 ```javascript const bloomLayer = new EarthLayer() @@ -143,3 +201,5 @@ const bloomLayer = new EarthLayer() opacity: 0.5, }); ``` + +L7 地球图层辉光效果 diff --git a/docs/api/earth/flyline.zh.md b/docs/api/earth/flyline.zh.md index 463ef749b7..c577bb7c0a 100644 --- a/docs/api/earth/flyline.zh.md +++ b/docs/api/earth/flyline.zh.md @@ -9,10 +9,26 @@ order: 3 用户在地球模式下使用飞线图层无需做额外的操作，L7 会自动识别地球模式并相关的转化 +L7地球飞线图层 + ## 使用 ```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); +}); ``` diff --git a/docs/api/earth/point.zh.md b/docs/api/earth/point.zh.md index 678705e978..81c42734b1 100644 --- a/docs/api/earth/point.zh.md +++ b/docs/api/earth/point.zh.md @@ -9,28 +9,52 @@ order: 3 用户在地球模式下使用点图层无需做额外的操作，L7 会自动识别地球模式并相关的转化 +## 示例图片 + +L7 地球点图层 + ## 使用 ```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); +}); ``` diff --git a/stories/customMap/components/earth2.tsx b/stories/customMap/components/earth2.tsx index ab60d1b937..42cec8d7a5 100644 --- a/stories/customMap/components/earth2.tsx +++ b/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, // 环境光