geom~Polygon(linearRings)

多边形即面状几何对象。即:由线环围成的区域。
当多边形由多个线环构成时，第一个线环默认是外边界，其他线环默认是内边界。
当在第一个线环围成的区域内，包含其他线环时，面状几何对象表现为环状的几何对象，即岛洞。
1.多边形包含一个区域(称为其内部)，该区域总是有一个可测量的面积。
2.构成多边形的线段只在它们的顶点处相交。即:恰好两条边在每个顶点相交。
3.边的数量总是等于顶点的数量。

Extends:

Summary

Methods:
createRegularPolygon

创建规则的多边形。
该方法可以创建出正三角形、正方形、正五边形、正六边形、正N边形；
一般地，当边数达到20以上时，所创建的多边形可以近似地表示一个圆。
fromCircle

从一个圆形几何对象生成一个多边形几何对象对象。
fromExtent

从一个范围对象生成一个多边形。
appendLinearRing

把一个线环追加到面状几何对象的线环数组中。
applyTransform

给定一个函数，用来修改几何对象的坐标值。该方法可能改变原几何对象的坐标值，如果需要保留原几何对象，可以使用clone方法复制为副本。
atApproximatePoint

检测一个坐标是否在几何对象的边界范围以内。本计算基于边界盒与坐标的相交运算，不包含高程方向的运算，一般用于近似相交判断。注意：与边界盒相交的坐标不一定在几何对象内，可能会在几何对象的边缘以外附近。
边界盒：即几何对象的地理范围构成的多边形区域。
clone

复制一个多边形几何对象对象。
destroy

销毁对象。
difference

两个多边形的差集
distanceTo

计算两个地理几何对象之间的距离（X-Y平面内）。
getArea

获取面状几何对象的面积。
getAreaOnMap

获取该多边形覆盖的地图三维场景中三维面积。不考虑多边形顶点中的Z值，每个顶点的Z值以地图实际场景的Z值为准。
getBBox

计算多边形几何对象的三维包围盒。
getBuffer

获取几何对象的缓冲区。缓冲区限于X-Y平面内，非三维空间中的缓冲区。
getCentroid

计算多边形的质心。
getClosestPoint

从构成多边形几何对象的所有点中，获取离传入坐标最近的一个点。
getCoordSeqs

获取多边形的坐标序列数组。从起始索引开始提取，取到结束索引的前一位，即按“前闭后开”的原则进行提取坐标序列。
1.当startIndex小于0时则取0，当endIndex大于坐标序列长度时取坐标序列长度；
2.当endIndex未传入时，返回startIndex以后的CoordSeq；
3.如果startIndex与endIndex参数为空，返回所有CoordSeq。
4.当startIndex大于等于endIndex，返回空数组。
getExtent

计算多边形几何对象的地理范围。该地理范围界定了X-Y平面的边界，不含高程信息。带有“岛洞”的多边形，其地理范围取决于最外面的环
getLinearRing

获取第n个线环。
getLinearRingCount

获取线环数量。
getLinearRings

获取所有线环。
getMaxDistPoint

从构成多边形几何对象的所有点中，获取离传入坐标最远的一个点。
getPerimeter

计算周长。
getType

获取几何对象类型。
intersect

两个多边形的交集
intersectsExtent

检测几何对象与地理范围是否相交。
intersectsGeometry

检测与另一个几何对象是否相交。
isSelfIntersects

自相交判断。
moveByDelta

沿坐标轴正方向，将几何对象的所有坐标按给定的参数偏移。如果参数为负，则向坐标轴负向偏移。该方法可能改变原几何对象的位置，如果需要保留原几何对象，可以使用clone方法复制为副本。
rotate

绕着指定直线（旋转轴）旋转，所指定的直线穿过给定点且平行于坐标轴。旋转后的坐标可能发生变化。绕轴旋转的本质如下： 绕平行于Z轴的直线旋转即是在XY平面内旋转；绕平行于X轴的直线旋转即是在YZ平面内旋转；绕平行于Y轴的直线旋转即是在XZ平面内旋转
scale

按各坐标轴的缩放比例和指定的缩放原点进行缩放几何对象。该方法可能改变原几何对象的坐标值，如果需要保留原几何对象，可以使用clone方法复制为副本。
simplify

简化多边形几何对象。在尽可能不改变原几何对象形状的情况下，减少构成几何对象的坐标数量。采用道格拉斯-普克算法，构成多边形几何对象的每条线环中应至少包含三个点。
transform

将一个多边形几何对象中点所对应的地理坐标从源坐标系转换到目标坐标系。该方法可能改变原几何对象的坐标值，如果需要保留原几何对象，可以使用clone方法复制为副本。
union

多个多边形的并集

Constructor

new Polygon(linearRings)

构造一个面状几何对象。

Parameters:
Name Type Description
linearRings Array.<module:geom~LinearRing>

线环数组。
Example
let coord1 = new hmap.basetype.Coordinate(120,30,0);
let coord2 = new hmap.basetype.Coordinate(121,31,0);
let coord3 = new hmap.basetype.Coordinate(122,32,0);
let coord4 = new hmap.basetype.Coordinate(123,33,0);
let p1 =  new hmap.geom.Point(coord1);
let p2 =  new hmap.geom.Point(coord2);
let p3 =  new hmap.geom.Point(coord3);
let p4 =  new hmap.geom.Point(coord4);
let linearRing = new hmap.geom.LinearRing([p1,p2,p3,p4]);
let polygon = new hmap.geom.Polygon([linearRing]);

Methods

static createRegularPolygon(origin, radius, sides, rotation) → {module:geom~Polygon|null}

创建规则的多边形。
该方法可以创建出正三角形、正方形、正五边形、正六边形、正N边形；
一般地，当边数达到20以上时，所创建的多边形可以近似地表示一个圆。

Parameters:
Name Type Description
origin module:basetype~Coordinate

多边形的中心点的地理坐标
radius Number

半径，地图单位，可以通过地图对象上的getDegreePerMeter和getMeterPerDegree方法，对地图单位进行度和米的转换。点与中心点连线为半径
sides Number

边数。边数可以确定多边形的形态。例如正方形，四条边，六边形。20条边可以近似表示一个圆
rotation Number

多边形的起始顶点与中心点的连线和x轴正方向形成的夹角（origin即为坐标原点），夹角逆时针方向为正
单位是角度。如果是0度，默认是x轴正方向开始创建多边形
Returns:
module:geom~Polygon | null -

一个多边形对象。当边数小于3时返回null

Example
let coord = new hmap.basetype.Coordinate(120,30,0);
let result = hmap.geom.Polygon.createRegularPolygon(coord,30,4,20);

static fromCircle(circle) → {module:geom~Polygon|Null}

从一个圆形几何对象生成一个多边形几何对象对象。

Parameters:
Name Type Description
circle module:geom~Circle

圆几何对象对象
Returns:
module:geom~Polygon | Null -

若生成成功，返回一个多边形对象；若生成失败，则返回null。

Example
let result = hmap.geom.Polygon.fromCircle(circle);

static fromExtent(extent) → {module:geom~Polygon|null}

从一个范围对象生成一个多边形。

Parameters:
Name Type Description
extent module:basetype~Extent

地理范围,类型不是Extent时方法返回null。
Returns:
module:geom~Polygon | null -

多边形对象.

Example
let extent = new hmap.basetype.Extent(120.1,30.07,120.7,30.3);
let result = hmap.geom.Polygon.fromExtent(extent);

appendLinearRing(linearRing) → {Boolean}

把一个线环追加到面状几何对象的线环数组中。

Parameters:
Name Type Description
linearRing module:geom~LinearRing

线环。
Returns:
Boolean -

true表示添加成功，false表示添加失败。

Example
let result = polygon.appendLinearRing(linearRing2);

applyTransform(callback)

给定一个函数，用来修改几何对象的坐标值。该方法可能改变原几何对象的坐标值，如果需要保留原几何对象，可以使用clone方法复制为副本。

Parameters:
Name Type Description
callback function

用于处理坐标值的回调函数，回调函数的参数为坐标对象，该回调函数会作用在几何对象的每个坐标上

atApproximatePoint(coord) → {Boolean}

检测一个坐标是否在几何对象的边界范围以内。本计算基于边界盒与坐标的相交运算，不包含高程方向的运算，一般用于近似相交判断。注意：与边界盒相交的坐标不一定在几何对象内，可能会在几何对象的边缘以外附近。
边界盒：即几何对象的地理范围构成的多边形区域。

Parameters:
Name Type Description
coord module:basetype~Coordinate

地理坐标
Returns:
Boolean -

返回true表示在几何对象的边界盒范围以内；返回false表示不在几何对象的边界盒范围以内

clone() → {module:geom~Polygon}

复制一个多边形几何对象对象。

Returns:
module:geom~Polygon -

返回新的多边形

destroy()

销毁对象。

Example
polygon.destroy();

difference(polygon)

两个多边形的差集

Parameters:
Name Type Description
polygon Polygon

用来计算差集的另一多边形

distanceTo(geometry, options) → {Number|Object}

计算两个地理几何对象之间的距离（X-Y平面内）。

Parameters:
Name Type Description
geometry module:geom~Geometry

地理几何对象，继承module:geom~Geometry的任意几何对象
options Object

距离计算时的可选配置项

Name Type Description
details Boolean

指定返回结果的格式，默认为false
若为true，则返回一个对象:{"distance":xxx,"x0":xxx,"y0":xxx,"x1":xxx,"y1":xxx}。其中 distance 表示几何对象到目标几何对象的距离；x0 和 y0 属性表示当前几何对象上最靠近目标几何对象的坐标；x1 和 y1 表示目标几何上最靠近当前几何对象的坐标。
但当edge为false且两个几何对象相交，则计算距离的详细交点信息的：x0,y0,x1,y1 无参考意义！
若为false，则返回几何对象到目标几何对象的距离值，距离的单位跟当前地图的坐标系使用的长度单位保持一致。
edge Boolean

是否计算一个几何图形到目标几何图形边缘的最近距离，默认为true。 如果为true， 一个几何图形完全包含在目标几何图形中时，计算距离为负数；如果为false，两个几何图形相交情况下 计算距离为0。
Returns:
Number | Object -

两个几何之间的距离。details为true 返回Object 否则返回 Number

getArea() → {Number}

获取面状几何对象的面积。

Returns:
Number -

几何对象的面积，单位是地图单位的平方

Example
let result = polygon.getArea();

getAreaOnMap(line, precision) → {number|null}

获取该多边形覆盖的地图三维场景中三维面积。不考虑多边形顶点中的Z值，每个顶点的Z值以地图实际场景的Z值为准。

Parameters:
Name Type Description
line module:map~Map

待计算三维面积的多边形所在的地图场景。
precision Number

精度，值越大，计算出的三维面积越准确，但是性能消耗也越高，默认值为1。
Returns:
number | null -

多边形在地图场景中的三维面积，单位是地图单位的平方。当该多边形不完全在地图当前显示的范围内时，返回null。

getBBox() → {module:basetype~BBox}

计算多边形几何对象的三维包围盒。

Returns:
module:basetype~BBox -

返回该多边形的三维包围盒

getBuffer(dist, sideType) → {module:geom~Polygon}

获取几何对象的缓冲区。缓冲区限于X-Y平面内，非三维空间中的缓冲区。

Parameters:
Name Type Default Description
dist Number

缓冲距离，一个正数，单位同地图单位，可以通过地图对象上的getDegreePerMeter和getMeterPerDegree方法，对地图单位进行度和米的转换。注意，缓冲半径过大可能出现重叠或岛洞
sideType String FULL

面缓冲类型，"FULL"：包含原几何对象，"OUTSIDE"：不包含原有几何对象
Returns:
module:geom~Polygon -

返回一个面状几何对象

getCentroid() → {module:basetype~Coordinate}

计算多边形的质心。

Returns:
module:basetype~Coordinate -

多边形质心的地理坐标

Example
let result = polygon.getCentroid();

getClosestPoint(coord) → {module:geom~Point}

从构成多边形几何对象的所有点中，获取离传入坐标最近的一个点。

Parameters:
Name Type Description
coord module:basetype~Coordinate

一个地理坐标
Returns:
module:geom~Point -

多边形几何对象上的一个点

getCoordSeqs(startIndex, endIndex) → {Array.<module:basetype~CoordSeq>}

获取多边形的坐标序列数组。从起始索引开始提取，取到结束索引的前一位，即按“前闭后开”的原则进行提取坐标序列。
1.当startIndex小于0时则取0，当endIndex大于坐标序列长度时取坐标序列长度；
2.当endIndex未传入时，返回startIndex以后的CoordSeq；
3.如果startIndex与endIndex参数为空，返回所有CoordSeq。
4.当startIndex大于等于endIndex，返回空数组。

Parameters:
Name Type Default Description
startIndex Number 0

起始索引。如果不传，默认是0
endIndex Number

结束索引。如果不传，默认是坐标序列数组长度
Returns:
Array.<module:basetype~CoordSeq> -

坐标序列数组

Example
let result = polygon.getCoordSeqs();

getExtent() → {module:basetype~Extent}

计算多边形几何对象的地理范围。该地理范围界定了X-Y平面的边界，不含高程信息。带有“岛洞”的多边形，其地理范围取决于最外面的环

Returns:
module:basetype~Extent -

返回多边形几何对象的地理范围

Example
let result = polygon.getExtent();

getLinearRing(n) → {module:geom~LinearRing}

获取第n个线环。

Parameters:
Name Type Default Description
n Number 0

线环的索引,一个整数数值。当索引越界时，返回null
Returns:
module:geom~LinearRing -

获取的线环

Example
linearRing=polygon.getLinearRing(1);//线环为空 linearRing=null;

getLinearRingCount() → {Number}

获取线环数量。

Returns:
Number -

线环数量

getLinearRings() → {Array.<module:geom~LinearRing>}

获取所有线环。

Returns:
Array.<module:geom~LinearRing> -

包含所有线环的数组

Example
let result = polygon.getLinearRings();

getMaxDistPoint(coord) → {module:geom~Point}

从构成多边形几何对象的所有点中，获取离传入坐标最远的一个点。

Parameters:
Name Type Description
coord module:basetype~Coordinate

一个地理坐标
Returns:
module:geom~Point -

多边形几何对象上的一个点

getPerimeter(linearRingIndex, srid) → {Number}

计算周长。

Parameters:
Name Type Default Description
linearRingIndex Number

线环索引。如果linearRingIndex非空，则计算对应线环的长度，否则计算所有线环长度之和。
srid String 4326

空间参考系的ID
Returns:
Number -

周长

getType() → {String}

获取几何对象类型。

Returns:
String -

返回几何对象类型

intersect(polygon)

两个多边形的交集

Parameters:
Name Type Description
polygon Polygon

用来计算交集的另一多边形

intersectsExtent(extent) → {Boolean}

检测几何对象与地理范围是否相交。

Parameters:
Name Type Description
extent module:basetype~Extent

地理范围
Returns:
Boolean -

为true时表示相交，为false时表示不相交

intersectsGeometry(geom) → {Boolean}

检测与另一个几何对象是否相交。

Parameters:
Name Type Description
geom module:geom~Geometry

另一个几何对象
Returns:
Boolean -

返回true表示相交；返回false表示不相交

isSelfIntersects() → {Boolean}

自相交判断。

Returns:
Boolean -

返回true表示相交；返回false表示不相交

moveByDelta(deltaX, deltaY, deltaZ) → {module:geom~Polygon}

沿坐标轴正方向，将几何对象的所有坐标按给定的参数偏移。如果参数为负，则向坐标轴负向偏移。该方法可能改变原几何对象的位置，如果需要保留原几何对象，可以使用clone方法复制为副本。

Parameters:
Name Type Description
deltaX Number

X坐标轴方向的平移量
deltaY Number

Y坐标轴方向的平移量
deltaZ Number

Z坐标轴方向的平移量
Returns:
module:geom~Polygon -

移动后的多边形几何对象

rotate(axis, angle, center) → {module:geom~Polygon}

绕着指定直线（旋转轴）旋转，所指定的直线穿过给定点且平行于坐标轴。旋转后的坐标可能发生变化。绕轴旋转的本质如下： 绕平行于Z轴的直线旋转即是在XY平面内旋转；绕平行于X轴的直线旋转即是在YZ平面内旋转；绕平行于Y轴的直线旋转即是在XZ平面内旋转

Parameters:
Name Type Description
axis String

坐标轴，旋转轴平行于该坐标轴并与坐标轴同向。可选值为"X","Y","Z",默认值为Z
angle Number

旋转的角度，超过360度时，取angle/360的余数。逆时针为正，顺时针为负
center module:basetype~Coordinate

旋转轴所穿过的点，可选项。该参数为空时，绕坐标轴旋转
Returns:
module:geom~Polygon -

返回旋转后的面状几何对象

scale(xFactor, yFactor, zFactor, origin) → {module:geom~Polygon}

按各坐标轴的缩放比例和指定的缩放原点进行缩放几何对象。该方法可能改变原几何对象的坐标值，如果需要保留原几何对象，可以使用clone方法复制为副本。

Parameters:
Name Type Description
xFactor Number

X坐标值缩放比例，必须大于0
yFactor Number

Y坐标值缩放比例，必须大于0
zFactor Number

Z坐标值缩放比例，必须大于0
origin module:basetype~Coordinate

缩放原点，以该点为参考点进行缩放。默认以几何对象地理范围的中心点进行缩放
Throws:
  • RangeError -

    当xFactor, yFactor, zFactor的值不为正时

  • TypeError -

    origin类型错误时

Returns:
module:geom~Polygon -

返回缩放后的几何对象

simplify(tolerance) → {module:geom~Polygon}

简化多边形几何对象。在尽可能不改变原几何对象形状的情况下，减少构成几何对象的坐标数量。采用道格拉斯-普克算法，构成多边形几何对象的每条线环中应至少包含三个点。

Parameters:
Name Type Default Description
tolerance Number 0.00001

道格拉斯算法中简化所用的容差值，大于等于0，单位和地图单位一致，可以通过地图对象上的getDegreePerMeter和getMeterPerDegree方法，对地图单位进行度和米的转换。容差值越大,构成几何对象的坐标数量越少。默认值0.00001。
Returns:
module:geom~Polygon -

返回简化后的几何对象

transform(source, destination) → {module:geom~Polygon}

将一个多边形几何对象中点所对应的地理坐标从源坐标系转换到目标坐标系。该方法可能改变原几何对象的坐标值，如果需要保留原几何对象，可以使用clone方法复制为副本。

Parameters:
Name Type Description
source String

源坐标系，考虑到实际转换时，数据量可能较大，故传入CRS的SRID，而非CRS实例，以减少CRS实例数量，进而降低内存成本
destination String

目标坐标系
Returns:
module:geom~Polygon -

坐标转换后的几何对象。

Example
...
let polygon = new hmap.geom.Polygon(lineRings);
polygon.transform(3857, 4326);

union(polygon)

多个多边形的并集

Parameters:
Name Type Description
polygon Polygon

用来计算并集的另一多边形