Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Polygon

require(["esri/geometry/Polygon"], function(Polygon) { /* code goes here */ });

Description

(Added at v1.0)
An array of rings where each ring is an array of points. The first and last points of a ring must be the same.

Samples

Search for samples that use this class.

Class hierarchy

esri/geometry/Geometry
|_esri/geometry/Polygon

Subclasses

Constructors

NameSummary
new Polygon(spatialReference)Creates a new Polygon object.
new Polygon(json)Creates a new Polygon object using a JSON object.
new Polygon(coordinates)Create a new polygon by providing an array of geographic coordinate pairs.

Properties

NameTypeSummary
cacheObjectThe cache is used to store values computed from geometries that need to cleared or recomputed upon mutation.
ringsNumber[][][]An array of rings.
spatialReferenceSpatialReferenceThe spatial reference of the geometry.
typeStringThe type of geometry.

Methods

NameReturn typeSummary
addRing(ring)PolygonAdds a ring to the Polygon.
clearCache()NoneSets the cache property to undefined.
contains(point)BooleanChecks on the client if the specified point is inside the polygon.
fromExtent(extent)PolygonReturns a new Polygon with one ring containing points equivalent to the coordinates of the extent.

Note: This is a static method.

getCacheValue(name)ObjectReturns the value for a named property stored in the cache.
getCentroid()PointReturns the centroid of the polygon as defined here.
getExtent()ExtentReturns the extent of the polygon.
getPoint(ringIndex, pointIndex)PointReturns a point specified by a ring and point in the path.
insertPoint(ringIndex, pointIndex, point)PolygonInserts a new point into a polygon.
isClockwise(ring)BooleanChecks if a Polygon ring is clockwise.
isSelfIntersecting(polygon)BooleanWhen true, the polygon is self-intersecting which means that the ring of the polygon crosses itself.
removePoint(ringIndex, pointIndex)PointRemove a point from the polygon at the given pointIndex within the ring identified by ringIndex.
removeRing(ringIndex)Point[]Removes a ring from the Polygon.
setCacheValue(name, value)NoneSets the value for a named property stored in the cache.
setPoint(ringIndex, pointIndex, point)PolygonUpdates a point in a polygon.
setSpatialReference(sr)GeometrySets the spatial reference.
toJson()ObjectConverts object to its ArcGIS Server JSON representation.
Constructor Details

new Polygon(spatialReference)

Creates a new Polygon object.
Parameters:
<SpatialReference> spatialReference Required Spatial reference of the geometry.
Sample:
require([
  "esri/geometry/Polygon", "esri/SpatialReference", ... 
], function(Polygon, SpatialReference, ... ) {
  var poly = new Polygon(new SpatialReference({wkid:4326}));
  ...
});

new Polygon(json)

Creates a new Polygon object using a JSON object.
Parameters:
<Object> json Required JSON object representing the geometry.
Sample:
require([
  "esri/geometry/Polygon", ... 
], function(Polygon, ... ) {
  var polygonJson  = {"rings":[[[-122.63,45.52],[-122.57,45.53],[-122.52,45.50],[-122.49,45.48],
    [-122.64,45.49],[-122.63,45.52],[-122.63,45.52]]],"spatialReference":{"wkid":4326 }};
  var polygon = new Polygon(polygonJson);
  ...
});

new Polygon(coordinates)

Create a new polygon by providing an array of geographic coordinate pairs. For a single ring polygon specify an array of coordinate pairs. For a multi-ring polygon specify an array of array coordinate pairs. (Added at v3.6)
Parameters:
<Number[][] | Number[][][]> coordinates Required An array of geographic coordinates that define the polygon.
Sample:
var singleRingPolygon = new Polygon([[50, 0], [150, 20], [150, -20], [50,0]]);
Property Details

<Object> cache

The cache is used to store values computed from geometries that need to cleared or recomputed upon mutation. An example is the extent of a polygon. The default value is undefined. (Added at v3.13)
Default value: undefined
Sample:
var map;

require([
  "esri/InfoTemplate",
  "esri/layers/FeatureLayer",
  "esri/map",
  "esri/tasks/query", "dojo/domReady!"
], function (InfoTemplate, FeatureLayer, Map, Query){

  map = new Map("map", {
    basemap: "topo",
    center: [-122.45, 37.75], // longitude, latitude
    zoom: 10
  });

  var infoTemplate = new InfoTemplate("Attributes", "${*}");

  var countiesFeatureLayer = new FeatureLayer("http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/3",
    {
      mode: FeatureLayer.MODE_ONDEMAND,
      infoTemplate: infoTemplate,
      outFields: ['*']
    });
  var highwaysFeatureLayer = new FeatureLayer("http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/1",
    {
      mode: FeatureLayer.MODE_ONDEMAND,
      infoTemplate: infoTemplate,
      outFields: ['*']
    });

  map.on("load", function (){
    map.addLayer(countiesFeatureLayer);
    map.addLayer(highwaysFeatureLayer);

    var query = new Query();
    query.geometry = map.extent;
    query.spatialRelationship = Query.SPATIAL_REL_ENVELOPEINTERSECTS;
    query.returnGeometry = true;
    query.outFields = ["*"];

    countiesFeatureLayer.queryFeatures(query, function (featureSet){
      var polygon = featureSet.features[0].geometry;
      // populate the Geometry cache by calling getExtent()
      var polygonExtent = polygon.getExtent();
      console.log("polygonExtent", polygonExtent);
      console.log("polygon.cache._extent", polygon.cache._extent);

      for (var i = 0; i < featureSet.features.length; i  ) {
        var feature = featureSet.features[i];
        console.log("Polygon geometry cache, %o", feature.geometry.cache);
        feature.geometry.clearCache();
        console.log("Polygon geometry clear cache, %o", feature.geometry.cache);
        // Break out of the loop after the first result
        break;
      }
    });

    highwaysFeatureLayer.queryFeatures(query, function (featureSet){
      var line = featureSet.features[0].geometry;
      // populate the Geometry cache by calling getExtent()
      var lineExtent = line.getExtent();
      console.log("lineExtent", lineExtent);
      console.log("line.cache._extent", line.cache._extent);

      for (var i = 0; i < featureSet.features.length; i  ) {
        var feature = featureSet.features[i];
        console.log("Line geometry cache, %o", feature.geometry.cache);
        feature.geometry.clearCache();
        console.log("Line geometry clear cache, %o", feature.geometry.cache);
        // Break out of the loop after the first result
        break;
      }
    });

  });
});

<Number[][][]> rings

An array of rings. Each ring is made up of three or more points.
See also: addRing()

<SpatialReference> spatialReference

The spatial reference of the geometry. See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references.

<String> type

The type of geometry.
Known values: point | multipoint | polyline | polygon | extent
Method Details

addRing(ring)

Adds a ring to the Polygon. The ring can be one of the following: an array of numbers or an array of points. When added the index of the ring is incremented by one.
Return type: Polygon
Parameters:
<Point[] | Number[][]> ring Required A polygon ring.
Sample:
require([
  "esri/geometry/Polygon", "esri/SpatialReference", ... 
], function(Polygon, SpatialReference, ... ) {
  var polygon = new Polygon(new SpatialReference({wkid:4326}));
  polygon.addRing([[-180,-90],[-180,90],[180,90],[180,-90],[-180,-90]]);
add points counter-clockwise to create a hole
  polygon.addRing([[-83,35],[-74,35],[-74,41],[-83,41],[-83,35]]);
  ...
});
See also: rings

clearCache()

Sets the cache property to undefined. (Added at v3.13)

contains(point)

Checks on the client if the specified point is inside the polygon. A point on the polygon line is considered in.
Return type: Boolean
Parameters:
<Point> point Required The location defined by an X- and Y- coordinate in map units.

fromExtent(extent)

Returns a new Polygon with one ring containing points equivalent to the coordinates of the extent.

Note: This is a static method.

(Added at v3.11)
Return type: Polygon
Parameters:
<Extent> extent Required The Extent geometry to convert to a Polygon.
Sample:
  var selectionPolygon = Polygon.fromExtent(selectionExtent);

getCacheValue(name)

Returns the value for a named property stored in the cache. (Added at v3.13)
Return type: Object
Parameters:
<String> name Required The property name of the value to retrieve from the cache.

getCentroid()

Returns the centroid of the polygon as defined here. For a polygon with multiple rings, returns the centroid of the largest ring. Note: Polygon with holes supported as of version 3.8. (Added at v3.7)
Return type: Point

getExtent()

Returns the extent of the polygon.
Return type: Extent
Sample:

var taxLotExtent = selectedTaxLot.geometry.getExtent();

getPoint(ringIndex, pointIndex)

Returns a point specified by a ring and point in the path.
Return type: Point
Parameters:
<Number> ringIndex Required The index of a ring.
<Number> pointIndex Required The index of a point in a ring.

insertPoint(ringIndex, pointIndex, point)

Inserts a new point into a polygon. (Added at v1.4)
Return type: Polygon
Parameters:
<Number> ringIndex Required Ring index to insert point.
<Number> pointIndex Required The index of the inserted point in the ring.
<Point> point Required Point to insert into the ring.

isClockwise(ring)

Checks if a Polygon ring is clockwise. Returns true for clockwise and false for counterclockwise.
Return type: Boolean
Parameters:
<Point[] | Number[][]> ring Required A polygon ring.
Sample:
require([
  "esri/geometry/Polygon", ... 
], function(Polygon, ... ) {
  var polygon = new Polygon( ... );
  var clockwise = polygon.isClockwise(polygon.rings[0]);
  ...
});

isSelfIntersecting(polygon)

When true, the polygon is self-intersecting which means that the ring of the polygon crosses itself. Also checks to see if polygon rings cross each other. (Added at v2.2)
Return type: Boolean
Parameters:
<Polygon> polygon Required The polygon to test for self-intersection.
Sample:
require([
  "esri/geometry/Polygon", ... 
], function(Polygon, ... ) {
  var polygon = new Polygon( ... );
  var isIntersecting = polygon.isSelfIntersecting(polygon);
  ...
});

removePoint(ringIndex, pointIndex)

Remove a point from the polygon at the given pointIndex within the ring identified by ringIndex. (Added at v2.0)
Return type: Point
Parameters:
<Number> ringIndex Required The index of the ring containing the point.
<Number> pointIndex Required The index of the point within the ring.

removeRing(ringIndex)

Removes a ring from the Polygon. The index specifies which ring to remove.
Return type: Point[]
Parameters:
<Number> ringIndex Required The index of the ring to remove.

setCacheValue(name, value)

Sets the value for a named property stored in the cache. (Added at v3.13)
Parameters:
<String> name Required The property name for the value Object to store in the cache.
<Object> value Required The value Object for a named property to store in the cache.

setPoint(ringIndex, pointIndex, point)

Updates a point in a polygon. (Added at v1.4)
Return type: Polygon
Parameters:
<Number> ringIndex Required Ring index for updated point.
<Number> pointIndex Required The index of the updated point in the ring.
<Point> point Required Point to update in the ring.

setSpatialReference(sr)

Sets the spatial reference.
Return type: Geometry
Parameters:
<SpatialReference> sr Required Spatial reference of the geometry.

toJson()

Converts object to its ArcGIS Server JSON representation.
Return type: Object