Chart3D is added to absorb all commonalities in 3D charts (pyecharts#550

)

* 🔨 code refactoring and 🔥 remove duplicated code, collapse chart inheritance structure

* 📚 update documentation

* 🔨 code refactor geolines

* 📰 add missing test fixture

* Update: 图形类部分细节修改

* Fixed: make flake5 happy

* Update: micro docs update

docs/class-relationship-diagram.uml

@@ -4,7 +4,6 @@ Base <|-- Timeline
 Base <|-- Grid
 Base <|-- Overlap
 Chart <|-- Bar
-Chart <|-- Bar3D
 Chart <|-- Boxplot
 Chart <|-- EffectScatter
 Chart <|-- Funnel
@@ -13,7 +12,6 @@ Chart <|-- Graph
 Chart <|-- HeapMap
 Chart <|-- KLine
 Chart <|-- Line
-Chart <|-- Line3D
 Chart <|-- Liquid
 Chart <|-- Map
 Chart <|-- Parallel
@@ -22,8 +20,15 @@ Chart <|-- Polar
 Chart <|-- Radar
 Chart <|-- Sankey
 Chart <|-- Scatter
-Chart <|-- Scatter3D
 Chart <|-- ThemeRiver
 Chart <|-- TreeMap
 Chart <|-- WorldCould
+Chart <|-- Chart3D
+
+Chart3D <|-- Bar3D
+Chart3D <|-- Line3D
+Chart3D <|-- Scatter3D
+
+Geo <|-- GeoLines
+
 @enduml

docs/zh-cn/charts.md

@@ -2,7 +2,7 @@
 
 * 图形初始化
 * 通用配置项
-    * xyAxis：直角坐标系中的 x、y 轴(Line、Bar、Scatter、EffectScatter、Kline)
+    * xyAxis：平面直角坐标系中的 x、y 轴。(Line、Bar、Scatter、EffectScatter、Kline)
     * dataZoom：dataZoom 组件 用于区域缩放，从而能自由关注细节的数据信息，或者概览数据整体，或者去除离群点的影响。(Line、Bar、Scatter、EffectScatter、Kline、Boxplot)
     * legend：图例组件。图例组件展现了不同系列的标记(symbol)，颜色和名字。可以通过点击图例控制哪些系列不显示。
     * label：图形上的文本标签，可用于说明图形的一些数据信息，比如值，名称等。
@@ -37,15 +37,14 @@
     * Scatter（散点图）
     * Scatter3D（3D 散点图）
     * ThemeRiver（主题河流图）
-    * TreeMap（树图）
+    * TreeMap（矩形树图）
     * WordCloud（词云图）
 * 用户自定义
     * Grid 类：并行显示多张图
     * Overlap 类：结合不同类型图表叠加画在同张图上
     * Page 类：同一网页按顺序展示多图
     * Timeline 类：提供时间线轮播多张图
 * 统一风格
-* 关于项目
 
 
 # 图形初始化
@@ -75,14 +74,14 @@
     画布背景颜色，默认为 '#fff'
 * page_title -> str  
     指定生成的 html 文件中 `<title>` 标签的值。默认为'Echarts'
-* renderer -> str
+* renderer -> str  
     指定使用渲染方式，有 'svg' 和 'canvas' 可选，默认为 'canvas'。3D 图仅能使用 'canvas'。
 
 
 # 通用配置项
 **通用配置项均在 ```add()``` 中设置**
 
-**xyAxis：直角坐标系中的 x、y 轴(Line、Bar、Scatter、EffectScatter、Kline)**
+**xyAxis：平面直角坐标系中的 x、y 轴。(Line、Bar、Scatter、EffectScatter、Kline)**
 
 * is_convert -> bool  
     是否交换 x 轴与 y 轴
@@ -210,6 +209,7 @@
         // 数据图形的颜色
         color: string,
     }
+    ```
 * yaxis_name -> str  
     y 轴名称
 * yaxis_name_size -> int  
@@ -2715,8 +2715,8 @@ tr.render()
 **Note：** 可以看到，每个数据项中的第三个数值就是该项的种类，而种类可以在 `add()` 第一个参数指定。
 
 
-## TreeMap（树图）
-> 树图是一种常见的表达『层级数据』『树状数据』的可视化形式。它主要用面积的方式，便于突出展现出『树』的各层级中重要的节点。
+## TreeMap（矩形树图）
+> 矩形树图是一种常见的表达『层级数据』『树状数据』的可视化形式。它主要用面积的方式，便于突出展现出『树』的各层级中重要的节点。
 TreeMap.add() 方法签名
 ```python
 add(name, attr, value,
@@ -2728,7 +2728,7 @@ add(name, attr, value,
 * name -> str  
     图例名称
 * data -> list  
-    树图的数据项是 **一棵树**，每个节点包括`value`, `name`（可选）, `children`（也是树，可选）如下所示
+    矩形树图的数据项是 **一棵树**，每个节点包括`value`, `name`（可选）, `children`（也是树，可选）如下所示
     ```
     [
         {
@@ -2801,14 +2801,14 @@ data = [
             }]}
 ]
 
-treemap = TreeMap("树图-默认示例", width=1200, height=600)
+treemap = TreeMap("矩形树图-默认示例", width=1200, height=600)
 treemap.add("演示数据", data, is_label_show=True, label_pos='inside')
 treemap.render()
 ```
 ![treemap-0](https://user-images.githubusercontent.com/19553554/35082247-b6f5ff88-fc53-11e7-84ca-bcb1f621ec68.png)
 
 ```python
-treemap = TreeMap("树图-下钻示例", width=1200, height=600)
+treemap = TreeMap("矩形树图-下钻示例", width=1200, height=600)
 treemap.add("演示数据", data, is_label_show=True, label_pos='inside',
             treemap_left_depth=1)
 treemap.render()
@@ -2818,7 +2818,7 @@ treemap.render()
 ```python
 from pyecharts import TreeMap
 
-treemap = TreeMap("树图示例", width=1200, height=600)
+treemap = TreeMap("矩形树图示例", width=1200, height=600)
 import os
 import json
 with open(os.path.join("..", "json", "treemap.json"), "r", encoding="utf-8") as f:

docs/zh-cn/flask.md

@@ -2,14 +2,16 @@
 
 ## Step 0: 首先新建一个 Flask 项目
 
-* Linux/MacOS 系统  
+#### Linux/MacOS 系统
+
 ```shell
 $ mkdir flask-echarts
 $ cd flask-echarts
 $ mkdir templates
 ```
 
-* Windows 系统
+#### Windows 系统
+
 新建一个 flask-echarts 文件夹，在其下新建 templates 子文件夹。
 
 ## Step 1: 为项目提供自己的模板
@@ -101,15 +103,17 @@ def generate_3d_random_point():
 
 ## Step 3: 运行项目
 
-* Linux/MacOS 系统
+#### Linux/MacOS 系统
+
 ```shell
 $ export FLASK_APP=server.py
 $ flask run
 * Serving Flask app "server"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 ```
 
-* Windows 系统
+#### Windows 系统
+
 ```shell
 $ set FLASK_APP=server.py
 $ flask run

pyecharts/__init__.py

@@ -17,8 +17,6 @@
 
 from pyecharts.charts.kline import Kline
 
-Candlestick = Kline
-
 from pyecharts.charts.line import Line
 from pyecharts.charts.line3D import Line3D
 from pyecharts.charts.liquid import Liquid
@@ -45,3 +43,6 @@
 from pyecharts.conf import configure
 from pyecharts.echarts.style import Style
 from pyecharts.conf import jupyter_image
+
+# alias
+Candlestick = Kline

pyecharts/chart.py

@@ -398,3 +398,82 @@ def _config_components(
 
         if not is_toolbox_show:
             self._option.pop("toolbox", None)
+
+
+class Chart3D(Chart):
+    """
+    `Chart3D`类是所有 3D 类图表的基类，继承自 `Chart` 类
+    """
+
+    def __init__(self, title="", subtitle="", **kwargs):
+        kwargs["renderer"] = constants.CANVAS_RENDERER
+        super(Chart3D, self).__init__(title, subtitle, **kwargs)
+        self._js_dependencies.add("echartsgl")
+        self._3d_chart_type = None  # 3d chart type, don't use it directly
+
+    def add(self, *args, **kwargs):
+        self.__chart3d_add(*args, **kwargs)
+
+    def __chart3d_add(
+        self,
+        name,
+        data,
+        grid3d_opacity=1,
+        grid3d_shading=None,
+        xaxis3d_type="value",
+        yaxis3d_type="value",
+        zaxis3d_type="value",
+        **kwargs
+    ):
+        """
+
+        :param name:
+            系列名称，用于 tooltip 的显示，legend 的图例筛选。
+        :param data:
+            数据项，数据中，每一行是一个『数据项』，每一列属于一个『维度』。
+        :param grid3d_opacity:
+            3D 笛卡尔坐标系组的透明度（线的透明度），默认为 1，完全不透明。
+        :param grid3d_shading:
+            三维柱状图中三维图形的着色效果。
+            color：
+                只显示颜色，不受光照等其它因素的影响。
+            lambert：
+                通过经典的 lambert 着色表现光照带来的明暗。
+            realistic：
+                真实感渲染，配合 light.ambientCubemap 和 postEffect 使用可以让
+                展示的画面效果和质感有质的提升。ECharts GL 中使用了基于物理的渲
+                染（PBR）来表现真实感材质。
+        :param xaxis3d_type:
+            空间直角 3D 图表 x 轴类型
+        :param yaxis3d_type:
+            空间直角 3D 图表 y 轴类型
+        :param zaxis3d_type:
+            空间直角 3D 图表 z 轴类型
+        :param kwargs:
+        """
+        chart = self._get_all_options(
+            xaxis3d_type=xaxis3d_type,
+            yaxis3d_type=yaxis3d_type,
+            zaxis3d_type=zaxis3d_type,
+            **kwargs
+        )
+
+        self._option.get("legend")[0].get("data").append(name)
+        self._option.update(
+            xAxis3D=chart["xaxis3D"],
+            yAxis3D=chart["yaxis3D"],
+            zAxis3D=chart["zaxis3D"],
+            grid3D=chart["grid3D"],
+        )
+
+        self._option.get("series").append(
+            {
+                "type": self._3d_chart_type,
+                "name": name,
+                "data": data,
+                "label": chart["label"],
+                "shading": grid3d_shading,
+                "itemStyle": {"opacity": grid3d_opacity},
+            }
+        )
+        self._config_components(**kwargs)

pyecharts/charts/bar3D.py

@@ -1,18 +1,16 @@
 # coding=utf-8
 
-from pyecharts.chart import Chart
-import pyecharts.constants as constants
+from pyecharts.chart import Chart3D
 
 
-class Bar3D(Chart):
+class Bar3D(Chart3D):
     """
     <<< 3D 柱状图 >>>
     """
 
-    def __init__(self, title="", subtitle="", **kwargs):
-        kwargs["renderer"] = constants.CANVAS_RENDERER
-        super(Bar3D, self).__init__(title, subtitle, **kwargs)
-        self._js_dependencies.add("echartsgl")
+    def __init__(self, *args, **kwargs):
+        super(Bar3D, self).__init__(*args, **kwargs)
+        self._3d_chart_type = "bar3D"
 
     def add(self, *args, **kwargs):
         self.__add(*args, **kwargs)
@@ -51,31 +49,16 @@ def __add(
                 染（PBR）来表现真实感材质。
         :param kwargs:
         """
-        kwargs.update(
+        super(Bar3D, self).add(
+            name,
+            data,
+            grid3d_opacity=grid3d_opacity,
+            grid3d_shading=grid3d_shading,
             xaxis3d_type="category",
             yaxis3d_type="category",
             zaxis3d_type="value",
+            **kwargs
         )
-        chart = self._get_all_options(**kwargs)
 
-        self._option.get("legend")[0].get("data").append(name)
-        self._option.update(
-            xAxis3D=chart["xaxis3D"],
-            yAxis3D=chart["yaxis3D"],
-            zAxis3D=chart["zaxis3D"],
-            grid3D=chart["grid3D"],
-        )
         self._option.get("xAxis3D").update(data=x_axis)
         self._option.get("yAxis3D").update(data=y_axis)
-
-        self._option.get("series").append(
-            {
-                "type": "bar3D",
-                "name": name,
-                "data": data,
-                "label": chart["label"],
-                "shading": grid3d_shading,
-                "itemStyle": {"opacity": grid3d_opacity},
-            }
-        )
-        self._config_components(**kwargs)

pyecharts/charts/funnel.py

@@ -32,8 +32,8 @@ def __add(self, name, attr, value, **kwargs):
         for data in zip(attr, value):
             _name, _value = data
             _data.append({"name": _name, "value": _value})
-        for a in attr:
-            self._option.get("legend")[0].get("data").append(a)
+        for element in attr:
+            self._option.get("legend")[0].get("data").append(element)
         _dset = set(self._option.get("legend")[0].get("data"))
         self._option.get("legend")[0].update(data=list(_dset))
 

pyecharts/charts/geo.py

@@ -18,6 +18,7 @@ def __init__(self, title="", subtitle="", **kwargs):
     def add_coordinate(self, name, longitude, latitude):
         """
         Add a geo coordinate for a position.
+
         :param name: The name of a position
         :param longitude: The longitude of coordinate.
         :param latitude: The latitude of coordinate.
@@ -28,6 +29,7 @@ def add_coordinate(self, name, longitude, latitude):
     def get_coordinate(self, name, raise_exception=False):
         """
         Return coordinate for the city name.
+
         :param name: City name or any custom name string.
         :param raise_exception: Whether to raise exception if not exist.
         :return: A list like [longitude, latitude] or None
@@ -70,14 +72,8 @@ def __add(
         :param type:
             图例类型，有'scatter', 'effectscatter', 'heatmap'可选。
         :param maptype:
-            地图类型。 支持 china、world、安徽、澳门、北京、重庆、福建、福建、甘肃、
-            广东，广西、广州、海南、河北、黑龙江、河南、湖北、湖南、江苏、江西、吉林、
-            辽宁、内蒙古、宁夏、青海、山东、上海、陕西、山西、四川、台湾、天津、香港、
-            新疆、西藏、云南、浙江，以及 [363个二线城市](https://github.com/chfw/
-            echarts-china-cities-js#featuring-citiesor-for-single-download]地图。
-            提醒：
-                在画市级地图的时候，城市名字后面的‘市’要省去了，比如，石家庄市的
-                ‘市’不要提，即‘石家庄’就可以了。
+            地图类型。 从 v0.3.2+ 起，地图已经变为扩展包，支持全国省份，全国城市，全国区县，
+            全球国家等地图，具体请参考 [地图自定义篇](zh-cn/customize_map)
         :param symbol_size:
             标记图形大小。
         :param border_color: