add geo projection apache/echarts#16364

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`.
 

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