ArcGIS API for iOS - Geometry Objects

The API includes several lightweight geometry classes. These classes can be used to display a variety of geometric shapes on a map, or they can be sent to an ArcGIS Server to perform additional analysis. Even though ArcGIS Desktop and ArcGIS Server support 3 dimensional geometries, the API only supports 2 dimensional geometries with X & Y values for vertices. Additionally, M (Measure) and ID values are also not currently supported by the API.

There are 5 basic geometry types in the API -

Point
Multipoint
Polyline
Polygon
Envelope

Spatial Reference

All geometry objects essentially define a location or a shape on the earth's surface using one or more pairs of (X,Y) coordinates. These coordinates represent the longitude and latitude values of that location. It is important for all geometry objects to use a common basis of specifying their position so that they can be displayed correctly on a map and relative to each other. Just as the Metric System provides a standard way to describe measurements, Coordinate Systems provide a framework for describing geographic positions. Describe a location using only it's latitude and longitude values without specifying the coordinate system to which those values belong is similar to describing the length of a rope using only a number without specifying the unit of measurement (meters, inches, etc).

Learn more about Coordinate Systems.

All geometry objects in the API have a spatial reference property which defines the coordinate system being used. A coordinate system can be uniquely identified either by a well-known ID (WKID) or a well-known text (WKT). Different regions in the world use different coordinate systems for a variety of historical and scientific reasons.

Refer to this topic for information about supported spatial references.

Mutable versus Immutable objects

Objective-C classes representing the basic geometry types in the API come in 2 flavors - mutable and immutable. Mutable geometry objects can be modified or altered even after they have been created, whereas immutable geometry objects cannot. The following table lists the Objective-C classes for both immutable and mutable versions of the basic geometry types.

Geometry type	Immutable object	Mutable object
Point	AGSPoint	AGSMutablePoint
Multipoint	AGSMultipoint	AGSMutableMultipoint
Polyline	AGSPolyline	AGSMutablePolyline
Polygon	AGSPolygon	AGSMutablePolygon
Envelope	AGSEnvelope	AGSMutableEnvelope

Mutable geometry objects are useful when creating new data or editing existing data. Immutable objects are better suited for all other purposes as they are inherently thread-safe and safeguard against inadvertent modification. Apple's Foundation framework also follows a similar pattern of having separate mutable and immutable versions. Examples of these include NSDictionary, NSArray, NSData, etc.

Most of the geometric data returned by ArcGIS Server web services is exposed as immutable geometry objects in the API. However, you can easily retrieve a mutable version of an immutable geometry by following the Objective-C convention of invoking the mutableCopy method on the object.

AGSPoint* point = ...;
AGSMutablePoint* mutable = [point mutableCopy]; 
[mutable updateWithX:20 y:20];

Point

Point geometries represent a single point, a place, or a location. For example, a house in a neighborhood, or a sewer in a water utility network. Larger geographic entities, such as cities, may also be represented as points on small-scale maps. Point geometries contain only a single vertex defined by a pair of X and Y coordinates that represent the defining longitude and latitude of the location.

AGSPoint* point = [AGSPoint pointWithX:10 y:10 spatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

Multipoint

Multipoint geometries represent an ordered collection of points. Multipoints are more efficient to store and analyze in a geodatabase when the data consists of large number of points. For example, Lidar data may contain observations from billions of points, and storing each as an individual point feature in a geodatabase is not practical. Storing them as a multipoint geometry allows them to be regarded as a single feature and also enables them to share a common set of attributes.

AGSMutableMultipoint multiPoint = [[AGSMutableMultipoint alloc] initWithSpatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];
[multiPoint addPoint: [AGSPoint pointWithX:10 y:10 spatialReference:nil]]; 
[multiPoint addPoint: [AGSPoint pointWithX:20 y:20 spatialReference:nil]]; 
[multiPoint addPoint: [AGSPoint pointWithX:30 y:30 spatialReference:nil]];

Polyline

Polyline geometries represent the shape and location of linear features. For example, a street in a road network, or a pipeline in an oil refinery. Polylines are considered multi-part geometries containing one or more paths. Each path is series of connected points (vertices). Paths in a polyline may be completely disjoint, for example, in a polyline representing a discontinuous highway that has an unfinished section. Paths may also coincide at one or more vertices, for example, in a polyline representing a river and its tributaries.

AGSMutablePolyline* poly = [[AGSMutablePolyline alloc] initWithSpatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

[poly addPathToPolyline];
[poly addPointToPath:[AGSPoint pointWithX:10 y:10 spatialReference:nil]];
[poly addPointToPath:[AGSPoint pointWithX:30 y:10 spatialReference:nil]];
[poly addPointToPath:[AGSPoint pointWithX:30 y:30 spatialReference:nil]];

[poly addPathToPolyline];
[poly addPointToPath:[AGSPoint pointWithX:20 y:10 spatialReference:nil]];
[poly addPointToPath:[AGSPoint pointWithX:20 y:-10 spatialReference:nil]];

Polygon

Polygon geometries represent the shape and location of areas. For example, a country, or a lake. Polygons are considered multi-part geometries containing one or more rings. Each ring is a series of connected points (vertices) that enclose an area. Note that the starting and ending points of a ring must coincide. Rings in a polygon may be completely disjoint, for example, in a polygon representing the state of Hawaii made up of 8 major islands. Or one ring may be completely within another ring thus representing a hole, for example, in a polygon representing the country of South Africa with the enclave of Lesotho. However, it is not permissible for a ring to touch or intersect another ring - in such cases it is more appropriate to have a single, large ring covering the areas of both the rings.

AGSMutablePolygon* poly = [[AGSMutablePolygon alloc] initWithSpatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

[poly addRingToPolygon]; 
[poly addPointToRing:[AGSPoint pointWithX:10 y:10 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:30 y:10 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:30 y:30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:10 y:30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:10 y:10 spatialReference:nil]];

[poly addRingToPolygon]; 
[poly addPointToRing:[AGSPoint pointWithX:-10 y:-10 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:-30 y:-10 spatialReference:nil]];
[poly addPointToRing:[AGSPoint pointWithX:-30 y:-30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:-10 y:-30 spatialReference:nil]]; 
[poly addPointToRing:[AGSPoint pointWithX:-10 y:-10 spatialReference:nil]];

Envelope

Envelope geometries represent the shape and location of perfectly rectangular areas. For example, a soccer field. Most commonly though, envelopes are used to represent the minimum bounding box (extent) for geometries such as polygons or polylines. Thus envelopes are usually used for map navigation, such as zooming in to a particular neighborhood, although they can also be displayed on a map.

AGSEnvelope env = [AGSEnvelope envelopeWithXmin:10 ymin:10 xmax:30 ymax:30 spatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];

JSON representation

The geometry classes provide a way to serialize their values to JSON and also deserialize values from JSON. The JSON representation is as per the ArcGIS Server REST API specification. Developers can use this encoding and decoding mechanism to exchange geometries with custom REST web services or to store them in files on the device.

// from json to object 
NSString* jsonPointAsString = @"{ \"x\" : -118.4 , \"y\" : -45.2 , \"spatialReference\" : {\"wkid\" : 4326} }"; 
NSDictionary *json = [jsonPointAsString AGSJSONValue]; 
AGSPoint* point = [[AGSPoint alloc] initWithJSON:json];

// from object to json 
json = [point encodeToJSON]; 
jsonPointAsString = [json AGSJSONRepresentation];

Note:

The above code snippet uses the JSON processing library from http://code.google.com/p/json-framework/. Version 2.3 of this library is already included in the ArcGIS library. Refer to the Working with JSON topic for more information.

12/7/2011