Merge pull request #4326 from VisActor/doc/map-rewind-in-guide

docs: add map rewind guide

Author: xuefei1313

docs/assets/guide/en/tutorial_docs/Chart_Types/Map.md

@@ -131,11 +131,36 @@ const vchart = new VChart(spec, { dom: CONTAINER_ID, animation: false });
 vchart.renderSync();
 ```
 
+### rewind
+
+In Geographic Information System (GIS) and map visualization development, **Rewind** is a key operation used to **correct the vertex order (Winding Order) of polygons**.
+
+In simple terms, its function is to ensure that the "outer rings" and "inner rings (holes)" of polygons are arranged in the standard specified direction (clockwise or counterclockwise), preventing serious visual errors from occurring in the rendering engine during drawing.
+
+Generally speaking, if there are no errors in the incoming map data and the mapping configuration is correct, but the drawing effect does not meet expectations, it may be that the vertex order (Winding Order) of the map data does not conform to expectations, causing the rendering engine to draw incorrectly.
+
+In this case, it is necessary to perform a Rewind operation on the map data to ensure that the "outer rings" and "inner rings (holes)" of polygons are arranged in the standard specified direction (clockwise or counterclockwise). VChart provides a `rewind` option in the parameter values for registering maps, which defaults to false.
+
+```
+// Enable rewind option for topojson data
+VChart.registerMap('south-america', topojson, {
+  type: 'topojson',
+  object: 'south-america',
+  rewind: true
+});
+
+// Enable rewind option for geojson data
+VChart.registerMap('world', world_geojson, {
+  type: 'geojson',
+  rewind: true
+});
+```
+
 2.  Meta map data
 
-- one`地理维度`Field specifying the Region to be colored on the base map
-- one`数值`Field used to map the specified visual channel such as shading depth
-  Note: If the Region name in the incoming Geographic Dimension field does not correspond to the base map data, you need to pass`mapChart.nameMap`Specify.
+- One **geographic dimension** field specifying the region to be colored on the base map
+- One **numeric** field used to map the specified visual channel such as shading depth
+  Note: If the region name in the incoming geographic dimension field does not correspond to the base map data, you need to use `mapChart.nameMap` to specify the mapping.
 
 ### Specify nameMap
 
@@ -339,6 +364,8 @@ vchart.renderSync();
 
 # Get Map Data
 
+Note: Please ensure that the map data complies with the standard `right-hand rule`, otherwise it may cause rendering issues. If the data does not comply with the standard, you need to use the **rewind** option to process it.
+
 ## China Map Data
 
 You can get China map data from these websites:

docs/assets/guide/zh/tutorial_docs/Chart_Types/Map.md

@@ -131,6 +131,31 @@ const vchart = new VChart(spec, { dom: CONTAINER_ID, animation: false });
 vchart.renderSync();
 ```
 
+### rewind
+
+在地理信息系统（GIS）和地图可视化开发中，**Rewind**（重绕/回绕）是一个用于**修正多边形（Polygon）顶点顺序（Winding Order）**的关键操作。
+
+简单来说，它的作用是确保多边形的“外环”和“内环（洞）”按照标准规定的方向（顺时针或逆时针）排列，以防止渲染引擎在绘图时出现严重的视觉错误。
+
+一般来说，如果传入地图数据没有报错，映射也配置正确，但是绘图效果不符合预期时，那就有可能是地图数据的顶点顺序（Winding Order）不符合预期，导致渲染引擎绘制错误。
+
+在这种情况下，就需要对地图数据进行 Rewind 操作，确保多边形的“外环”和“内环（洞）”按照标准规定的方向（顺时针或逆时针）排列。vchart 在注册地图的参数值中有提供 rewin 选项，默认为 false。
+
+```
+// topojson 数据开启 rewind 选项
+VChart.registerMap('south-america', topojson, {
+  type: 'topojson',
+  object: 'south-america',
+  rewind: true
+});
+
+// geojson 数据开启 rewind 选项
+VChart.registerMap('world', world_geojson, {
+  type: 'geojson',
+  rewind: true
+});
+```
+
 2. 图元映射数据
 
 - 一个`地理维度`字段，用于指定需要在底图上着色的区域
@@ -339,6 +364,8 @@ vchart.renderSync();
 
 # 免费获取地图数据
 
+注意：请确定地图数据是否符合标准的`右手规则`，否则可能会导致渲染不符合预期。如果不符合标准，需要使用上面提到的 **rewind** 选项来处理。
+
 ## 中国地图数据
 
 可以从这些网站获取中国地图数据：