Geometry Objects
The ArcGIS API for iOS 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, ArcGIS API for iOS only supports 2 dimensional geometries with X & Y values for vertices. M (Measure) and ID values are also not currently supported by ArcGIS API for iOS.
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).
All geometry objects 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.
See http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//003r00000002000000.htm for more information about Coordinate Systems.
Mutable versus Immutable objects
Objective-C classes representing the basic geometry types in ArcGIS API for iOS 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 by ArcGIS API for iOS. 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 ore 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 it's 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* jsonPoint = @"{ \"x\" : -118.4 , \"y\" : -45.2 , \"spatialReference\" : {\"wkid\" : 4326} }";
SBJsonParser *parser = [[SBJsonParser alloc] init];
NSDictionary *json = [parser objectWithString:jsonPoint];
AGSPoint* point = [[AGSPoint alloc] initWithJSON:json];
// from object to json
NSDictionary *json = [point encodeToJSON];
SBJsonWriter *writer = [[SBJsonWriter alloc] init];
NSString* jsonPoint = [writer stringWithObject:json];
![Note Note](rsrc/note.png)
The above code snippet uses the JSON processing library from http://code.google.com/p/json-framework/. Version 2.3 of the library is already included with ArcGIS API for iOS.