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

dojo.require("esri.geometry.Circle");

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 esri.geometry.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 esri.geometry.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 esri.geometry.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
    var circleGeometry  = new esri.geometry.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
    var point = new Point([-117.15,32.71]);
    var circleGeometry = new esri.geometry.Circle(point,{radius:2000});
    

new esri.geometry.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
    var circleGeometry  = new esri.geometry.Circle({center:[-117.15, 32.71],
       radius: 100, 
       radiusUnit:units.MILES
       });
    
  • 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
    var point = new Point([-117.15,32.71]);
    var circleGeometry = new esri.geometry.Circle({center:point,
       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

<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:
var polygon = new esri.geometry.Polygon(new esri.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:
var clockwise = esri.geometry.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:
var isIntersecting = new esri.geometry.polygonSelfIntersecting(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
Show Modal