You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by sh...@apache.org on 2022/01/19 04:52:10 UTC
[echarts-doc] branch dev updated: add geo projection apache/echarts#16364
This is an automated email from the ASF dual-hosted git repository.
shenyi pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
The following commit(s) were added to refs/heads/dev by this push:
new 5cf8e4d add geo projection apache/echarts#16364
5cf8e4d is described below
commit 5cf8e4d59e3c16ba7d9d227597acf27ba467c696
Author: pissang <bm...@gmail.com>
AuthorDate: Wed Jan 19 12:43:13 2022 +0800
add geo projection apache/echarts#16364
---
en/option/component/geo-common.md | 83 ++++++++++++++++++++++++++++++++++++-
zh/option/component/geo-common.md | 86 +++++++++++++++++++++++++++++++++++++--
2 files changed, 163 insertions(+), 6 deletions(-)
diff --git a/en/option/component/geo-common.md b/en/option/component/geo-common.md
index 18f31c1..d78aa93 100644
--- a/en/option/component/geo-common.md
+++ b/en/option/component/geo-common.md
@@ -79,18 +79,97 @@ The demo above shows that SVG format can be used in ECharts. See more info in [S
{{ use: partial-roam() }}
+#${prefix} projection(Object)
+
+For custom map projection, at least two methods `project`, `unproject` should be provided to calculate the coordinates after projection and before projection respectively.
+
+For example, for the Mercator projection.
+
+```ts
+series: {
+ type: 'map',
+ projection: {
+ project: (point) => [point[0] / 180 * Math.PI, -Math.log(Math.tan((Math.PI / 2 + point[1] / 180 * Math.PI) / 2))],
+ unproject: (point) => [point[0] * 180 / Math.PI, 2 * 180 / Math.PI * Math.atan(Math.exp(point[1])) - 90]
+ }
+}
+```
+
+In addition to our own implementation of the projection formula, we can also use exists projection implementations provided by third-party libraries such as [d3-geo](https://github.com/d3/d3-geo).
+
+```ts
+const projection = d3.geoConicEqualArea();
+// ...
+series: {
+ type: 'map',
+ projection: {
+ project: (point) => projection(point),
+ unproject: (point) => projection.invert(point)
+ }
+}
+
+```
+
+Note: Custom projections are only useful when using `GeoJSON` as a data source.
+
+##${prefix} project(Function)
+
+```ts
+(coord: [number, number]) => [number, number]
+```
+
+Projection of latitude and longitude coordinates to other coordinates.
+
+##${prefix} unproject(Function)
+
+```ts
+(point: [number, number]) => [number, number]
+```
+
+Calculate the raw latitude and longitude coordinates from the projected coordinates
+
+##${prefix} stream(Function)
+
+This property is mainly used to adapt the [stream](https://github.com/d3/d3-geo#streams) interface used in [d3-geo](https://github.com/d3/d3-geo). After introducing stream, you can introduce both the [Antimeridian Clipping](https://bl.ocks.org/mbostock/3788999) and [Adaptive Sampling](https://bl.ocks.org/mbostock/3795544) algorithms implemented in [d3-geo](https://bl.ocks.org/mbostock/3795544).
+
+```ts
+const projection = d3.geoProjection((x, y) => ([x, y / 0.75]))
+ .rotate([-115, 0]);
+// ...
+series: {
+ type: 'map',
+ projection: {
+ // We still need project and unproject when stream is provided.
+ project: (point) => projection(point),
+ unproject: (point) => projection.invert(point),
+ // We can directly use the stream method in d3 projection.
+ stream: projection.stream
+ }
+}
+```
+
+Note: `stream` is not required in the `projection`.
+
#${prefix} center(Array)
-Center of current view-port, in longitude and latitude.
+Center of current view-port, in longitude and latitude by default. Use the projected coordinates if `projection` is set.
Example:
+
```ts
center: [115.97, 29.71]
```
+```ts
+projection: {
+ projection: (pt) => project(pt)
+},
+center: project([115.97, 29.71])
+```
+
#${prefix} aspectScale(number) = 0.75
-Used to scale aspect of geo.
+Used to scale aspect of geo. Will be ignored if `projection` is set.
The final aspect is calculated by: `geoBoundingRect.width / geoBoundingRect.height * aspectScale`.
diff --git a/zh/option/component/geo-common.md b/zh/option/component/geo-common.md
index 91bbc24..7ae8d2b 100644
--- a/zh/option/component/geo-common.md
+++ b/zh/option/component/geo-common.md
@@ -79,20 +79,98 @@ $.get('map/topographic_map.svg', function (svg) {
{{ use: partial-roam() }}
+#${prefix} projection(Object)
+
+自定义地图投影，至少需要提供`project`, `unproject`两个方法分别用来计算投影后的坐标以及计算投影前的坐标。
+
+比如墨卡托投影：
+
+```ts
+series: {
+ type: 'map',
+ projection: {
+ project: (point) => [point[0] / 180 * Math.PI, -Math.log(Math.tan((Math.PI / 2 + point[1] / 180 * Math.PI) / 2))],
+ unproject: (point) => [point[0] * 180 / Math.PI, 2 * 180 / Math.PI * Math.atan(Math.exp(point[1])) - 90]
+ }
+}
+```
+
+除了我们自己实现投影公式，我们也可以使用 [d3-geo](https://github.com/d3/d3-geo) 等第三方库提供的现成的投影实现：
+
+```ts
+const projection = d3.geoConicEqualArea();
+// ...
+series: {
+ type: 'map',
+ projection: {
+ project: (point) => projection(point),
+ unproject: (point) => projection.invert(point)
+ }
+}
+
+```
+
+注：自定义投影只有在使用`GeoJSON`作为数据源的时候有用。
+
+##${prefix} project(Function)
+
+```ts
+(coord: [number, number]) => [number, number]
+```
+
+将经纬度坐标投影为其它坐标。
+
+##${prefix} unproject(Function)
+
+```ts
+(point: [number, number]) => [number, number]
+```
+
+根据投影后坐标计算投影前的经纬度坐标
+
+##${prefix} stream(Function)
+
+该属性主要用于适配 [d3-geo](https://github.com/d3/d3-geo) 中使用的 [stream](https://github.com/d3/d3-geo#streams) 接口。在引入 stream 后可以同时引入[d3-geo](https://github.com/d3/d3-geo) 中实现的[Antimeridian Clipping](https://bl.ocks.org/mbostock/3788999)以及[Adaptive Sampling](https://bl.ocks.org/mbostock/3795544)算法。
+
+```ts
+const projection = d3.geoProjection((x, y) => ([x, y / 0.75]))
+ .rotate([-115, 0]);
+// ...
+series: {
+ type: 'map',
+ projection: {
+ // project 和 unproject 依旧需要配置。
+ project: (point) => projection(point),
+ unproject: (point) => projection.invert(point),
+ // 可以直接使用 d3-geo 提供的 stream 方法。
+ stream: projection.stream
+ }
+}
+```
+
+该配置并非是必要的。
+
#${prefix} center(Array)
-当前视角的中心点，用经纬度表示
+当前视角的中心点，默认使用原始坐标（经纬度）。如果设置了`projection`则用投影后的坐标表示。
-例如：
+示例：
```ts
center: [115.97, 29.71]
```
+```ts
+projection: {
+ projection: (pt) => project(pt)
+},
+center: project([115.97, 29.71])
+```
+
#${prefix} aspectScale(number) = 0.75
-这个参数用于 scale 地图的长宽比。
+这个参数用于 scale 地图的长宽比，如果设置了`projection`则无效。
-最终的 `aspect` 的计算方式是：`geoBoundingRect.width / geoBoundingRect.height * aspectScale`
+最终的 `aspect` 的计算方式是：`geoBoundingRect.width / geoBoundingRect.height * aspectScale`。
#${prefix} boundingCoords(Array) = null
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org