ArcGIS Runtime SDK for iOS



The AGSGeometry class provides functionality common to all types of geometry. AGSPoint, AGSMultipoint, AGSPolyline, AGSPolygon, and AGSEnvelope all inherit from AGSGeometry, and represent different types of shapes.

The following are common geometry characteristics:


Geometries are immutable


While immutable geometries appear to present problems for editing existing geometries, those problems are solved by using geometry builders. Geometry builders are designed to represent the state of a geometry under construction while allowing modifications, thus enabling editing workflows. Apple's Foundation framework follows a similar pattern of having separate mutable and immutable versions. Examples of these include NSDictionary, NSArray, NSData, and so on.



New instances of AGSEnvelope are defined by specifying a minimum and maximum x-coordinate and minimum and maximum y-coordinate, and a AGSSpatialReference. Optionally, a minimum and maximum z-value can be specified to define the depth of the envelope.

// Create an Envelope using the minimum and maximum x,y coordinates and a Spatial Reference
AGSEnvelope *envelope = [[AGSEnvelope alloc]initWithXMin:-123.0 yMin:33.5 xMax:-101.0 yMax:48 spatialReference:[AGSSpatialReference WGS84]];


AGSPoint *point1 = [[AGSPoint alloc]initWithX:-123 y:33.5 spatialReference:[AGSSpatialReference WGS84]];
AGSPoint *point2 = [[AGSPoint alloc]initWithX:-124 y:34.5 spatialReference:[AGSSpatialReference WGS84]];

// Create an Envelope by passing in two points  
AGSEnvelope *envelope = [[AGSEnvelope alloc]initWithMin:point1 max:point2];



Points store a single set of x,y coordinates that represent the coordinates of a location (longitude and latitude for example), and a AGSSpatialReference. Optionally, a z-value (representing things such as elevation for example) can also be included. Instances of AGSPoint can be created using constructors, which define the full geometry in a single call.

// Create a Point with the x,y coordinates and a Spatial Reference
// Create a Point with the x,y,z coordinates and a Spatial Reference
AGSPoint *point2 = [[AGSPoint alloc]initWithX:-123 y:33.5 z:414 spatialReference:[AGSSpatialReference WGS84]];


You can use AGSCoordinateFormatter to convert a latitude, longitude formatted string directly to a AGSPoint, and also return a latitude, longitude formatted string from an existing AGSPoint. Other coordinate notations, such as Military Grid Reference System (MGRS) and United States National Grid (USNG) are also supported.



Multipoints are composed of a single read-only collection of AGSPoints. To build a AGSMultipoint, create an AGSMultipointBuilder, add points, and the geometry will return an AGSMultipoint.

// Create a MultipointBuilder and add Points
AGSMultipointBuilder *multiPointBuilder = [[AGSMultipointBuilder alloc]initWithSpatialReference:[AGSSpatialReference WGS84]];
[multiPointBuilder.points addPointWithX:121 y:46];
[multiPointBuilder.points addPointWithX:122 y:47];
[multiPointBuilder.points addPointWithX:123 y:48];
[multiPointBuilder.points addPointWithX:119 y:39];
// Pass the Geometry from the MultipointBuilder to the MultiPoint
AGSMultipoint *multiPoint = [multiPointBuilder toGeometry];

To access each AGSPoint in an existing AGSMultipoint, iterate over the read only AGSPointCollection returned from points property.

AGSPointCollection *points = multiPoint.points;
for (AGSPoint *point in points) {
 NSLog(@"Point x = %f, y= %f", point.x, point.y);

Use the AGSMultipointBuilder to modify an existing multipoint.




Create a AGSPolyline using an AGSPolylineBuilder. Add points, and this will create a series of straight AGSLineSegments connecting the points you specified.

AGSPolylineBuilder *polylineBuilder = [[AGSPolylineBuilder alloc]initWithSpatialReference:[AGSSpatialReference WGS84]];
[polylineBuilder addPointWithX:-121 y:38];
[polylineBuilder addPointWithX:-122 y:47];
[polylineBuilder addPointWithX:-123 y:44];
[polylineBuilder addPointWithX:-124 y:46];
[polylineBuilder addPointWithX:-125 y:33];
AGSPolyline *polyline = [polylineBuilder toGeometry];

Polylines can have multiple parts. Each part is a series of connected segments, but the parts can be disjoint from each other, for example, in a polyline representing a discontinuous highway that has an unfinished section. Parts can also intersect at one or more vertices, for example, in a polyline representing a river and its tributaries. The AGSPolyline class inherits from AGSMultipart, which provides members for iterating through the segments and points of each part in a AGSPolyline.

To modify an existing polyline, use AGSPolylineBuilder.




To build an AGSPolygon, create an AGSPolygonBuilder and add points in the correct order around the polygon's perimeter. Next, use the toGeometry method to provide the AGSPolygon.

AGSPolygonBuilder *polygonBuilder = [[AGSPolygonBuilder alloc]initWithSpatialReference:[AGSSpatialReference WGS84]];
[polygonBuilder addPointWithX:-121 y:38];
[polygonBuilder addPointWithX:-122 y:47];
[polygonBuilder addPointWithX:-123 y:44];
[polygonBuilder addPointWithX:-124 y:46];
[polygonBuilder addPointWithX:-125 y:33];
AGSPolygon *polygon = [polygonBuilder toGeometry];



To modify an existing polygon, use a AGSPolygonBuilder.


Multipart (Polygon and Polyline)

AGSPolygon and AGSPolyline inherit from AGSMultipart, which in turn inherits from AGSGeometry. Multipart provides access to the geometry's AGSPartCollection. Each AGSPart in the collection is a collection of AGSSegment objects. You can iterate through the segments or points in each part.

AGSPolyline *polyline = [polylineBuilder toGeometry];
AGSPartCollection *parts =;
// iterate each Part of a Polyline
for (AGSPart *part in parts) {
 AGSEnumerator *enumSegments = part.segmentEnumerator;
 for (AGSSegment *segment in enumSegments) {
  NSLog(@"%f", segment.startPoint.x);
  NSLog(@"%f", segment.endPoint.x);

You can iterate through the points that represent the vertices in all the parts.

AGSPartCollection *parts =;
// iterate each Part of a Polyline
for (AGSPart *part in parts) {
 AGSPointCollection *points = part.points;
 // iterate each Point in the Part
 for (AGSPoint *point in points) {

  NSLog(@"Point x= %f y= %f", point.x, point.y);            


In the same way as AGSPolygons and AGSPolylines are immutable, the collections returned from AGSMultipart are also immutable—AGSPartCollection, AGSPart, and AGSPointCollection. However, when creating polygons and polylines, you use the mutable equivalents—AGSMutablePartCollection, AGSMutablePart, and AGSMutablePointCollection. Point-based helper methods are available on both the mutable and immutable classes.


A segment describes a continuous line between a start location and an end location. Every part in a multipart geometry is a collection of AGSSegments where the end of one segment is at exactly the same location as the start of the following segment. The ArcGIS system supports both straight and curved segments, but at the current release, only straight AGSLineSegments are supported in ArcGIS Runtime SDK. Multipart geometries can be composed from and decomposed into segments if required; until true curves are supported fully, using point-based methods offers equal functionality.

Because a single location is shared by adjacent segments, a single AGSPoint object is used to represent the shared location when you iterate through the points in a part. As a result, when iterating through the points in a part of a polyline, there will be one more AGSPoint than the number of AGSSegments in that same part.

AGSPartCollection *parts =;
// iterate each Part of a Polyline
for (AGSPart *part in parts) {
 NSLog(@"%ld", (long)part.pointCount);
 NSLog(@"%ld", (long)part.segmentCount);

Similar to the geometries they comprise, AGSSegments are immutable.

Other aspects of geometries

Spatial references



Learn more about spatial references

Projection, topological, and other operations



Use the AGSGeometryEngine class to project geometries to a different spatial reference.

AGSPoint *oldPoint = AGSPointMake(-124, 34.5, [AGSSpatialReference WGS84]);
AGSPoint *newPoint = (AGSPoint*)[AGSGeometryEngine projectGeometry:oldPoint toSpatialReference:[AGSSpatialReference webMercator]];

Converting to and from JSON


// convert a Polygon to a JSON representation   
NSString *polygonJSON = [polygon toJSON];
// create a new Polygon from JSON
AGSPolygon *polygon2 = (AGSPolygon*)[AGSPolygon fromJSON:polygonJSON];


Z-values and 3D

Geometries can have z-values, indicating values along the z-axis, which is orthogonal to both the x-axis and y-axis. Z-values can indicate height above or depth below a surface, or an absolute elevation. For example, z-values are used to draw the locations of geometries in SceneViews. Note that geometries are not considered true 3D shapes and are draped onto surfaces in the view, or in some cases, drawn in a single plane by using z-values. Z-values are stored on AGSPoints and AGSEnvelopes. Therefore, because AGSMultipoints, AGSPolylines, and AGSPolygons are created from AGSPoints, all types of geometry can have z-values.




