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

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

Description

(Added at v3.8)
A circle (Polygon) created by a specified center point. This point can be provided as an esri/geometry/Point object or an array of latitude/longitude values.

Samples

Search for samples that use this class.

Class hierarchy

esri/geometry/Geometry
|_esri/geometry/Polygon
  |_esri/geometry/Circle

Constructors

NameSummary
new Circle(center, options?)Create a new Circle by specifying an input center location using either an esri.geometry.Point object or a latitude/longitude array and an object with the following optional properties: radius, radiusUnits, geodesic and numberOfPoints.
new Circle(params)Create a new Circle by specifying an object with a required center location, defined as a longitude/latitude array or an esri.geometry.Point, and the following additional optional parameters: radius, radiusUnits, geodesic, and numberOfPoints.

Properties

NameTypeSummary
cacheObjectThe cache is used to store values computed from geometries that need to cleared or recomputed upon mutation.
centerPoint | Number[]Center point of the circle.
radiusNumberThe radius of the circle based.
radiusUnitStringUnit of the radius.
ringsNumber[][][]Array of coordinate values constituting the circle like [[x1, y1], [x2, y2],...].
spatialReferenceSpatialReferenceThe spatial reference of the circle will be the same as the spatial reference of the center point.
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.
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 Circle(center, options?)

Create a new Circle by specifying an input center location using either an esri.geometry.Point object or a latitude/longitude array and an object with the following optional properties: radius, radiusUnits, geodesic and numberOfPoints. See the options table for additional details.
Parameters:
<Point | Number[]> center Required Center point of the circle. It could be a esri.geometry.Point, or an array with value [longitude, latitude].
<Object> options Optional See options descriptions for further information.
options properties:
<Boolean> geodesic Optional Applicable when the spatial reference of the center point is either set to Web Mercator or geographic/geodesic as true would apply. Other coordinate systems will not create geodesic circles. By default, the value is false.
<Number> numberOfPoints Optional A circle can be thought of similar to a polygon. This value controls how many points along the curve of the circle. If nothing is specified, the default value is 60.
<Number> radius Optional Radius of the circle. If nothing specified, defaults to 1000.
<String> radiusUnit Optional Unit of the radius. For example, a linear unit, such as METERS, MILES and so on, or an angular unit, such as DECIMAL_DEGREES. When the option geodesic is true, it must be a linear unit. The default value is esri.Units.METERS.
Sample:
  • This example shows how to create a Circle
    with an optional radius of 2000 meters with the required center location using lon/lat
    require(["esri/map", "esri/geometry/Circle"], function(Map, Circle){
      var circleGeometry = new Circle([-117.15, 32.71],{
        "radius": 2000
      });
    });
    
  • This example shows how to create a Circle
    with an optional radius of 2000 meters with the required center location using a provided
    esri.geometry.Point
    require(["esri/map", "esri/geometry/Circle", "esri/geometry/Point"], function(Map, Circle, Point){
      var point = new Point([-117.15,32.71]);
      var circleGeometry = new Circle(point,{
        "radius": 2000
      });
    });
    

new Circle(params)

Create a new Circle by specifying an object with a required center location, defined as a longitude/latitude array or an esri.geometry.Point, and the following additional optional parameters: radius, radiusUnits, geodesic, and numberOfPoints. See the options table for additional details on the optional parameters.
Parameters:
<Object> params Required If no center parameter is provided, it must be set within the options. See options descriptions for further information.
params properties:
<Point | Number[]> center Required The center point of the circle. This option must be specified by either passing in an already defined esri.geometry.Point object or an array of longitude/latitude values.
<Boolean> geodesic Optional Applicable when the spatial reference of the center point is either set to Web Mercator or geographic/geodesic as true would apply. Other coordinate systems will not create geodesic circles. By default, the value is false.
<Number> numberOfPoints Optional A circle can be thought of similar to a polygon. This value controls how many points along the curve of the circle. If nothing is specified, the default value is 60.
<Number> radius Optional The radius of the circle. It nothing specified, defaults to 1000.
<String> radiusUnit Optional Unit of the radius. For example, a linear unit, such as METERS, MILES and so on, or an angular unit, such as DECIMAL_DEGREES. When the option geodesic is true, it must be a linear unit. The default value is esri.Units.METERS.
Sample:
  • This example shows how to create a Circle
    by specifying an object with a center location using long/lat and a radius of 100 miles
    require(["esri/map", "esri/geometry/Circle", "esri/units"], function(Map, Circle, Units){
      var circleGeometry = new Circle({
        center: [-117.15,32.71],
        radius: 3000,
        geodesic: true
      });
    });
    
  • This example shows how to create a Circle by specifying an
    object with a center location using an esri.geometry.Point and a radius of 100 miles
    require(["esri/map", "esri/geometry/Circle", "esri/units", "esri/geometry/Point"], function(Map, Circle, Units, Point) {
      var centerPoint = new Point([-117.15,32.71]);
      var circleGeometry = new Circle({
        center: centerPoint,
        radius: 100,
        radiusUnit: Units.MILES
      });
    });
    
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;
      }
    });

  });
});

<Point | Number[]> center

Center point of the circle. This center must be specified either as an esri.geometry.Point object or an array of longitude/latitude.

<Number> radius

The radius of the circle based.
Default value: 1000

<String> radiusUnit

Unit of the radius. For example, a linear unit, such as METERS, MILES and so on, or an angular unit, such as DECIMAL_DEGREES. See Units for a list of valid values. When the option geodesic is true, it must be a linear unit.
Default value: METERS

<Number[][][]> rings

Array of coordinate values constituting the circle like [[x1, y1], [x2, y2],...]. The circle only has one ring, which is the circle curve. Specify the rings coordinate values for the circle's curve.

<SpatialReference> spatialReference

The spatial reference of the circle will be the same as the spatial reference of the center point.

<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]]);
  ...
});

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.

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