10.2.5: AGSGeometryEngine Class Reference
10.2.5
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Pages
AGSGeometryEngine Class Reference

Description

Instances of this class represents engines that can perform geometric operations locally on the device. AGSGeometryEngine is functionally similar to AGSGeometryServiceTask except that it does not rely on a remote ArcGIS Geometry Service. You can use the engine even when the device does not have any network connectivity.

See also
Conceptual Doc: Peforming geometric operations
Sample: Geometry sample
Since
1.8
Inheritance diagram for AGSGeometryEngine:

Instance Methods

(double) - areaOfGeometry:
 
(AGSMutablePolygon *) - bufferGeometries:byDistance:
 
(AGSMutablePolygon *) - bufferGeometry:byDistance:
 
(AGSGeometry *) - clipGeometry:withEnvelope:
 
(AGSGeometry *) - convexHullForGeometry:
 
(NSArray *) - cutGeometry:withCutter:
 
(AGSGeometry *) - densifyGeometry:withMaxSegmentLength:
 
(AGSGeometry *) - differenceOfGeometry:andGeometry:
 
(double) - distanceFromGeometry:toGeometry:
 
(AGSGeometry *) - generalizeGeometry:withMaxDeviation:removeDegenerateParts:
 
(double) - geodesicAreaOfGeometry:inUnit:
 
(AGSGeometry *) - geodesicDensifyGeometry:withMaxSegmentLength:inUnit:
 
(AGSGeodesicDistanceResult *) - geodesicDistanceBetweenPoint1:point2:inUnit:
 
(AGSGeometry *) - geodesicEllipseWithParameters:
 
(double) - geodesicLengthOfGeometry:inUnit:
 
(NSArray *) - geodesicMovePoints:byDistance:inUnit:azimuth:
 
(AGSGeometry *) - geodesicSectorWithParameters:
 
(BOOL) - geometry:containsGeometry:
 
(BOOL) - geometry:crossesGeometry:
 
(BOOL) - geometry:disjointToGeometry:
 
(BOOL) - geometry:intersectsGeometry:
 
(BOOL) - geometry:overlapsGeometry:
 
(BOOL) - geometry:relatesToGeometry:byRelation:
 
(BOOL) - geometry:touchesGeometry:
 
(BOOL) - geometry:withinGeometry:
 
(AGSGeometry *) - intersectionOfGeometry:andGeometry:
 
(AGSMutablePoint *) - labelPointForPolygon:
 
(double) - lengthOfGeometry:
 
(NSString *) - mgrsFromPoint:numDigits:rounding:addSpaces:
 
(AGSProximityResult *) - nearestCoordinateInGeometry:toPoint:
 
(AGSProximityResult *) - nearestVertexInGeometry:toPoint:
 
(AGSGeometry *) - normalizeCentralMeridianOfGeometry:
 
(AGSGeometry *) - offsetGeometry:byDistance:withJointType:bevelRatio:flattenError:
 
(AGSPoint *) - pointFromMGRS:
 
(AGSGeometry *) - projectGeometry:toSpatialReference:
 
(double) - shapePreservingAreaOfGeometry:inUnit:
 
(double) - shapePreservingLengthOfGeometry:inUnit:
 
(AGSGeometry *) - simplifyGeometry:
 
(AGSGeometry *) - symmetricDifferenceOfGeometry:andGeometry:
 
(AGSGeometry *) - unionGeometries:
 

Class Methods

(AGSGeometryEngine *) + defaultGeometryEngine
 

Method Documentation

- (double) areaOfGeometry: (AGSGeometry *)  geometry

Gets the simple area for the AGSGeometry passed in. This is a planar measurement using 2D Cartesian mathematics to compute the area.

The geometry must be topologically correct to get its accurate legth. Geometries returned by ArcGIS Server services are always correct. If you construct geometries programmatically or using the sketch layer, or if you modify geometries returned by ArcGIS Server, you should simplify them using simplifyGeometry:

Parameters
geometryThe geometry to calculate the area for.
Returns
The computed area in the same units as the geometry's spatial reference unit.
Since
1.8
See also
- shapePreservingAreaOfGeometry:inUnit:
- (AGSMutablePolygon*) bufferGeometries: (NSArray *)  geometries
byDistance: (double)  distance 

Creates buffers at the specified distance around the given geometries. Will union the results of all buffers.

Parameters
geometriesSpecifies the input geometries.
distanceThe distance in the unit of the geometry's spatial reference for which to buffer the geometries.
Returns
The polygon that represents the buffered area.
Since
1.8
See also
- convertValue:fromUnit: (AGSSpatialReference) and - convertValue:toUnit: (AGSSpatialReference) to convert values between different units
- (AGSMutablePolygon*) bufferGeometry: (AGSGeometry *)  geometry
byDistance: (double)  distance 

Creates a buffer polygon at the specified distance around the given geometry.

Parameters
geometrySpecifies the input geometry.
distanceThe distance in the unit of the geometry's spatial reference for which to buffer the geometry.
Returns
The polygon that represents the buffered area.
Since
1.8
See also
- convertValue:fromUnit: (AGSSpatialReference) and - convertValue:toUnit: (AGSSpatialReference) to convert values between different units
- (AGSGeometry*) clipGeometry: (AGSGeometry *)  geometry
withEnvelope: (AGSEnvelope *)  envelope 

Constructs the polygon created by clipping geometry by envelope.

Parameters
geometryThe geometry to be clipped by the given envelope.
envelopeThe envelope in which to use in order to clip geometry.
Returns
A geometry that represents the area clipped by envelope.
Since
2.2
- (AGSGeometry*) convexHullForGeometry: (AGSGeometry *)  geometry

Returns the minimum bounding geometry that completely encloses the given geometry.

Parameters
geometryfor which convex hull needs to be calculated. Typically either an AGSMultipoint, AGSPolygon, or AGSPolyline.
Returns
minimum bounding geometry
Since
10.2
- (NSArray*) cutGeometry: (AGSGeometry *)  geometry
withCutter: (AGSPolyline *)  cutter 

Splits the input polyline or polygon where it crosses a cutting polyline.

Parameters
geometryThe geometry to be cut.
cutterThe polyline that will be used to divide the target into pieces where it crosses the target.
Returns
Array of cut results.
Since
1.8
+ (AGSGeometryEngine*) defaultGeometryEngine

A singleton geometry engine that can be used. Since an instance of a geometry engine caches state, like the last projection transformation used, it may be beneficial to create one for each spatial reference that you are dealing with, instead of using this.

Returns
A new, autoreleased geometry engine.
Since
1.8
- (AGSGeometry*) densifyGeometry: (AGSGeometry *)  geometry
withMaxSegmentLength: (double)  maxSegmentLength 

Densifies the input geometry by plotting points between existing vertices.

Parameters
geometryThe input geometry
maxSegmentLengthThe maximum distance between points after densification. This distance should be in the same unit as the geometry's spatial reference.
Returns
The densified geometry.
Since
1.8
- (AGSGeometry*) differenceOfGeometry: (AGSGeometry *)  geometry1
andGeometry: (AGSGeometry *)  geometry2 

Constructs the set-theoretic difference between two geometries.

Parameters
geometry1The first geometry.
geometry2The second geometry of dimension equal to or greater than the elements of the first geometry.
Returns
A geometry that represents the difference of the two input geometries.
Since
1.8
- (double) distanceFromGeometry: (AGSGeometry *)  geometry1
toGeometry: (AGSGeometry *)  geometry2 

Measures the simple planar distance between two geometries.

Parameters
geometry1The first geometry.
geometry2The second geometry.
Returns
The distance between the two input geometries in the same unit as the spatial reference of the input geometries.
Since
1.8
- (AGSGeometry*) generalizeGeometry: (AGSGeometry *)  geometry
withMaxDeviation: (double)  maxDeviation
removeDegenerateParts: (BOOL)  removeDegenerateParts 

Generalizes the input geometry by removing vertices based on the Douglas-Poiker algorithm.

Parameters
geometryThe input geometry
maxDeviationthe maximum distance that the generalized geometry can deviate from the original one, specified in the units of the input geometry's spatial reference
removeDegeneratePartsIf YES, degenerate parts of the generalized geometry that are undesired for drawing will be removed.
Since
10.2.3
- (double) geodesicAreaOfGeometry: (AGSGeometry *)  geometry
inUnit: (AGSAreaUnits areaUnit 

Gets the geodesic area for the AGSGeometry passed in. Will return NAN if the calculation results in a linear to angular conversion (for instance, Decimal Degrees to Meters)

Parameters
geometryThe geometry to calculate the area for.
areaUnitThe unit at which the area is calculated.
Returns
The calculated geodesic area in the specified unit.
Since
10.2
- (AGSGeometry*) geodesicDensifyGeometry: (AGSGeometry *)  geometry
withMaxSegmentLength: (double)  maxSegmentLength
inUnit: (AGSSRUnit lengthUnit 

Densifies the input geometry by plotting points between existing vertices.

Parameters
geometryThe input geometry
maxSegmentLengthThe maximum distance between points after densification.
lengthUnitThe unit that the max segment length parameter is in.
Returns
The geodesically densified geometry.
Since
1.8
- (AGSGeodesicDistanceResult*) geodesicDistanceBetweenPoint1: (AGSPoint *)  point1
point2: (AGSPoint *)  point2
inUnit: (AGSSRUnit unit 

Returns the geodesic distance between 2 given points and calculates the azimuth at both points for the geodesic curves that connects the points.

Parameters
point1The first point
point2The second point
unitThe linear units of the distance returned in the AGSGeodesicDistanceResult object
Returns
The AGSGeodesicDistanceResult object containing the shortest distance between the 2 points along the geodesic curve, and the azimuth at both those points.
Since
10.2
- (AGSGeometry*) geodesicEllipseWithParameters: (AGSGeodesicEllipseParameters *)  params

Constructs a geodesic ellipse that is centered on a specified point and defined by it's 2 axes and the direction of it's longest axis. The ellipse is provided as a AGSPolygon, AGSPolyline or AGSMultipoint geometry.

Parameters
paramsSpecifies the parameters for constructing the ellipse.
Returns
The ellipse is returned in the format specified by the geometryType parameter. The ellipse is generalized according to the vertexCount.
Since
10.2
- (double) geodesicLengthOfGeometry: (AGSGeometry *)  geometry
inUnit: (AGSSRUnit lengthUnit 

Gets the geodesic length for the AGSGeometry passed in. Geodesic length is calculated using only the vertices of the polygon and define the lines between the points as geodesic segments independent of the actual shape of the polygon. A geodesic segment is the shortest path between two points on an ellipsoid. Thus, if you have a line that spans the width of the world, with only two vertices, each on the edges of the map, the geodesic lenght would be zero (shortest distance between the two vertices).

Will return NAN if the calculation results in a linear to angular conversion (for instance, Decimal Degrees to Meters)

Parameters
geometryThe geometry to calculate the geodesic length for.
lengthUnitThe unit at which the area is calculated.
Returns
The calculated geodesic length in the specified unit.
Since
1.8
See also
- shapePreservingLengthOfGeometry:inUnit:
- (NSArray*) geodesicMovePoints: (NSArray *)  points
byDistance: (double)  distance
inUnit: (AGSSRUnit unit
azimuth: (double)  degrees 

Gets an array of AGSPoint objects that have been moved by geodetic calculation. Each point in the array is moved by the given distance and azimuth.

Parameters
pointsAn array of points to be moved.
degreesThe angle for the points to be moved along (in degrees).
distanceThe distance by which the points are moved.
unitThe linear units of the distance. The default is AGSSRUnitMeter.
Returns
An array of points moved along a geodesic curve by distance and azimuth.
Since
10.2
- (AGSGeometry*) geodesicSectorWithParameters: (AGSGeodesicSectorParameters *)  params

Constructs a geodesic sector defined by a geodesic arc and 2 radii. The arc is a portion of an ellipse that is centered on a specified point and is defined by it's 2 axes and the length of it's longest axis. The first radius angle is defined by the startDirection angle and the second radius angle is the sum of the startDirection and the sectorAngle. The sector is constructed as a AGSPolygon, AGSPolyline or AGSMultipoint geometry.

Parameters
paramsSpecifies the parameters for constructing the sector.
Returns
The sector is returned in the format specified by the geometryType and is generalized according to the arcVertexCount and the radiusVertexCount parameters.
Since
10.2
- (BOOL) geometry: (AGSGeometry *)  geometry1
containsGeometry: (AGSGeometry *)  geometry2 

Returns YES if geometry1 contains geometry2.

Since
1.8
- (BOOL) geometry: (AGSGeometry *)  geometry1
crossesGeometry: (AGSGeometry *)  geometry2 

Returns YES if geometry1 crosses geometry2.

Since
1.8
- (BOOL) geometry: (AGSGeometry *)  geometry1
disjointToGeometry: (AGSGeometry *)  geometry2 

Returns YES if geometry1 is disjoint to geometry2.

Since
1.8
- (BOOL) geometry: (AGSGeometry *)  geometry1
intersectsGeometry: (AGSGeometry *)  geometry2 

Returns YES if geometry1 intersects geometry2.

Since
1.8
- (BOOL) geometry: (AGSGeometry *)  geometry1
overlapsGeometry: (AGSGeometry *)  geometry2 

Performs relational operation Overlaps. It compares two geometries of the same dimension and returns TRUE if their intersection results in a geometry different from both but of the same dimension.

Since
2.2
- (BOOL) geometry: (AGSGeometry *)  geometry1
relatesToGeometry: (AGSGeometry *)  geometry2
byRelation: (NSString *)  relation 

Determines if geometry1 is related to geometry2 by the relation specified. Example: To test if a polygon 'P' contains a point 'pt' you would pass the following: -[AGSGeometryEngine geometry:P relatesToGeometry:pt byRelation:"T*****FF*"]. This checks:

  1. The interiors of both geometries intersect.
  2. The exterior of P does not intersect the interior of pt
  3. The exterior of P does not intersect the boundary of pt.
Parameters
geometry1The input geometry to be compared.
geometry2The input geometry in which we are comparing geometry1 against.
relationThe DE-9IM string to be evaluated. Strings such as "T*****FF*" are accepted.
Returns
A boolean indicating if the relation is True or False.
Since
10.2
- (BOOL) geometry: (AGSGeometry *)  geometry1
touchesGeometry: (AGSGeometry *)  geometry2 

Returns YES if geometry1 touches geometry2.

Since
1.8
- (BOOL) geometry: (AGSGeometry *)  geometry1
withinGeometry: (AGSGeometry *)  geometry2 

Returns YES if geometry1 is within geometry2.

Since
1.8
- (AGSGeometry*) intersectionOfGeometry: (AGSGeometry *)  geometry1
andGeometry: (AGSGeometry *)  geometry2 

Constructs the set-theoretic intersection between two geometries.

Parameters
geometry1The first geometry.
geometry2The second geometry of dimension equal to or greater than the elements of the first geometry.
Returns
A geometry that represents the intersection of the two input geometries.
Since
1.8
- (AGSMutablePoint*) labelPointForPolygon: (AGSPolygon *)  polygon

Calculates an interior point for a specified polygon. This interior point can be used by clients to place a label for the polygon.

Parameters
polygonThe polygon to get label points for.
Returns
The label point.
Since
1.8
- (double) lengthOfGeometry: (AGSGeometry *)  geometry

Gets the length for a specified AGSGeometry. This is a planar measurement using 2D Cartesian mathematics to compute the length.

The geometry must be topologically correct to get its accurate legth. Geometries returned by ArcGIS Server services are always correct. If you construct geometries programmatically or using the sketch layer, or if you modify geometries returned by ArcGIS Server, you should simplify them using simplifyGeometry:

Parameters
geometryThe geometry to calculate the length for.
Returns
The calculated length in the same units as the geometry's spatial reference unit.
Since
1.8
See also
- shapePreservingLengthOfGeometry:inUnit:
- (NSString*) mgrsFromPoint: (AGSPoint *)  pt
numDigits: (NSInteger)  numDigits
rounding: (BOOL)  rounding
addSpaces: (BOOL)  addSpaces 

Returns a Military Grid Reference System (MGRS) coordinate for the given point. For example : 4Q 612341 2356781

Parameters
ptThe point for which MGRS coordinate is needed
numDigitsThe number of digits to be included in the MGRS coordinate
roundingWhether the numeric value should be rounded
addSpacesWhether the MGRS coordinate string should include spaces
Returns
The MGRS coordinate string
Since
2.2
Deprecated:
Deprecated at 10.2. Use MGRSStringWithNumDigits:rounding:addSpaces: (AGSPoint(CoordinateConversion)) instead.
- (AGSProximityResult*) nearestCoordinateInGeometry: (AGSGeometry *)  geometry
toPoint: (AGSPoint *)  point 

Finds the nearest coordinate in a specified geometry to a specified point.

Parameters
geometryThe geometry in which the nearest coordinate to a specified point is to be found.
pointThe point which to find the nearest coordinate to.
Returns
The proximity result.
Since
1.8
- (AGSProximityResult*) nearestVertexInGeometry: (AGSGeometry *)  geometry
toPoint: (AGSPoint *)  point 

Finds the nearest vertex in a specified geometry to a specified point.

Parameters
geometryThe geometry in which the nearest vertex to a specified point is to be found.
pointThe point which to find the nearest vertex to.
Returns
The proximity result.
Since
1.8
- (AGSGeometry*) normalizeCentralMeridianOfGeometry: (AGSGeometry *)  geometry

Folds the geometry into a range of 360 degrees. This may be necessary when wrap around is enabled on the map.

Parameters
geometryThe geometry that you want folded.
Returns
The folded geometry
Since
1.8
- (AGSGeometry*) offsetGeometry: (AGSGeometry *)  geometry
byDistance: (double)  distance
withJointType: (AGSGeometryOffsetType joinType
bevelRatio: (double)  bevelRatio
flattenError: (double)  flattenError 

Creates offset version of the input geometries.

The offset operation creates a geometry that is a constant distance from an input polyline or polygon. It is similar to buffering, but produces a one sided result. If offsetDistance > 0, then the offset geometry is constructed to the right of the oriented input geometry, otherwise it is constructed to the left. For a simple polygon, the orientation of outer rings is clockwise and for inner rings it is counter clockwise. So the “right side” of a simple polygon is always its inside. The bevelRatio is multiplied by the offset distance and the result determines how far a mitered offset intersection can be from the input curve before it is beveled.

Parameters
geometryThe geometry to calculate offset for. Point and MultiPoint are not supported.
distanceThe offset distance for the Geometries.
joinTypeThe join type of the offset geometry.
bevelRatioThe ratio used to produce a bevel join instead of a miter join (used only when joins is Miter)
flattenErrorThe maximum distance of the resulting segments compared to the true circular arc (used only when joins is Round). If flattenError is 0, tolerance value is used. Also, the algorithm never produces more than around 180 vetices for each round join.
Returns
Returns the result of the offset operation.
Since
1.8
- (AGSPoint*) pointFromMGRS: (NSString *)  mgrs

Returns a point for a given MGRS coordinate string

Parameters
mgrsThe MGRS coordinate string. Can contain spaces.
Returns
A point from the MGRS coordinate. The point will be output in EPSG:4326.
Since
2.2
Deprecated:
Deprecated at 10.2. Use pointFromMGRSString:withSpatialReference: (AGSPoint(CoordinateConversion)) instead.
- (AGSGeometry*) projectGeometry: (AGSGeometry *)  geometry
toSpatialReference: (AGSSpatialReference *)  spatialReference 

Projects the given geometry into a new spatial reference.

Parameters
geometryThe geometry to be projected.
spatialReferenceThe spatial reference to which geometry need to be projected.
Returns
The projected geometry
Since
1.8
- (double) shapePreservingAreaOfGeometry: (AGSGeometry *)  geometry
inUnit: (AGSAreaUnits areaUnit 

Calculates the area of the geometry on the surface of the Earth ellipsoid. This method preserves the shape of the geometry in its coordinate system. This means the true area will be calculated for the geometry you see in the map.

Parameters
geometrywhose area needs to be computed
areaUnitThe unit in which area needs to be computed
Returns
The area of the geometry
Since
2.2
- (double) shapePreservingLengthOfGeometry: (AGSGeometry *)  geometry
inUnit: (AGSSRUnit lengthUnit 

Calculates the length of the geometry on the surface of the Earth ellipsoid. This method preserves the shape of the geometry in its coordinate system. This means the true length will be calculated for the geometry you see in the map. Thus, if you have a line that spans the width of the world, with only two vertices, each on edges of the map, the length returned would be comparable to the distance on earth.

Parameters
geometrywhose length needs to be computed
lengthUnitThe unit in which length needs to be computed
Returns
The length of the geometry
Since
2.2
- (AGSGeometry*) simplifyGeometry: (AGSGeometry *)  geometry

Simplifies the given geometry to make it topologically consistent according to their geometry type. For instance, it rectifies polygons that may be self-intersecting, or contain incorrect ring orientations.

Parameters
geometryThe geometry to be simplified.
Returns
The simplified geometry.
Since
1.8
- (AGSGeometry*) symmetricDifferenceOfGeometry: (AGSGeometry *)  geometry1
andGeometry: (AGSGeometry *)  geometry2 
Since
2.2
- (AGSGeometry*) unionGeometries: (NSArray *)  geometries

The union operation constructs the set-theoretic union of the geometries in the input array.

Parameters
geometriesThe array of geometries to be unioned.
Returns
The union of all the input geometries.
Since
1.8