You edit geometries when you want to change existing geometries or create new ones. However, AGSGeometry objects are immutable. To edit geometries, use geometry builders.
Geometry builders (or builders for short) create or change geometry. A geometry builder contains the same things a geometry contains—vertices, segments, and parts—allowing its state to be changed as needed. You can create new geometries at any point from the builder’s current state. A builder is available for each type of geometry. Each builder exposes the appropriate methods for modifying a specific type of geometry. In the case of AGSPolylineBuilder and AGSPolygonBuilder that share many members, both inherit from AGSMultipartBuilder, which in turn inherits from AGSGeometryBuilder. Other builders inherit directly from AGSGeometryBuilder.
Create the appropriate type of builder and initialize its state by passing in the geometry to be edited to the constructor. For example, modify a polyline by creating an AGSPolylineBuilder and pass in the existing polyline to the builder.
The following code demonstrates an AGSPolylineBuilder held as a member variable in a custom geometry editor class. The addPointToEnd method adds another vertex to the end of the polyline and can be called when a user taps at the required location. Each time an update is made, the drawLatestGeometry method can be used to update an AGSGraphicsOverlay with the new state of the geometry created so far.
A AGSPoint or AGSSegment returned from a geometry’s member will have the same spatial reference as the geometry it came from.
When creating a new AGSPolygon using the constructor, the API first sets the spatial reference parameter for the new AGSPolygon, then the points are added. If there is a mismatch between the spatial reference of the new AGSPolygon and the points being added, this is an error and the constructor will throw an exception.
If required for your workflow, use the projectProject method on AGSGeometryEngine to project points to a different spatial reference.
Use AGSMultipointBuilder to modify an existing AGSMultipoint. Get and modify the mutable point collection from the builder's points method, working directly with this collection to add, remove, or insert points. Call toGeometry to instantiate a new immutable instance of AGSMultipoint from the current state of the builder.
Polygons and polylines can have multiple parts. You can use a multipart polygon to define a group of islands, or a multipart polyline to represent a non-continuous linear feature. Due to the geometric complexity of polygons and polylines, AGSPolylineBuilder and AGSPolygonBuilder are used more frequently than other builders such as AGSPointBuilder. Using the methods on these collections, you can build polygons and polylines by adding points. As with multipoint geometries, use the AGSPointCollection to modify multipart geometries. Or, you can edit the segments in multipart geometries.
Use the AGSMutablePartCollection methods to add, remove, or insert AGSMutableParts to a AGSMultipartBuilder.
The AGSPart is a collection of segments. Working with the point-based method results in defining an ordered series of vertices and, as a consequence, creating straight AGSLineSegments within the builder between those vertices.
Use insertPoint(AGSPoint, int) to insert a vertex at a specific index into a part. This will increase the number of segments in the part by one. Connections between segments are preserved—adjacent segments touch at their starting and ending vertices.
Use removePointAtIndex(int) to remove the vertex at a specific index from a part. The number of segments decreases by one, and connections between segments are preserved.
Use setPoint(AGSPoint, int) to replace a vertex in the collection. The total number of vertices or segments in the collection remains unchanged.
You can add a new vertex to the end of a AGSMultipartBuilder using the addPoint method. This adds a vertex to the end of the last part in the builder. If there are no parts in the builder, this method will create a new part first, then add the new vertex.
When working with point-based methods that take an index parameter, keep in mind that this is the index of the specific vertex, which is a different index than that used when working with segments. This is because where a segment’s ending vertex is at the same location as the starting vertex of the next segment, it is represented by a single AGSPoint in point-based methods.
Use insertSegment(segment, int) to insert a segment into a part at a specific index. This increases the number of segments in the part by one. Be careful: this will result in a gap at either end of the new segment if the start and end vertices do not share a location with the preceding and following adjacent segments, respectively.
Use removeSegmentAtIndex to remove a segment from a part. If you remove anything other than the first or last segment in the part, this will result in a gap between the remaining segments. The number of segments decreases by one, and connections between segments are preserved.
Because segments are immutable, existing segments in a part cannot be changed. However, you can replace the existing segment at a specified index with a new segment by calling setSegment(AGSLineSegment, int).
When working with segment-based methods that take an index parameter, keep in mind that this is the index of the segment within the part and is a different index than that used when working with point-based helper methods. If a segment's ending vertex is at the same location as the starting vertex of the next segment, this location is represented by a single AGSPoint in point-based methods. However, if there is a gap, separate AGSPoints are returned for the two locations that define the gap.
To be saved as a feature in a geodatabase, a geometry must be simplified—that is, be topologically consistent. The rules vary for different types of geometry but include requirements such as polygons not having overlapping parts. Pass a geometry to the AGSGeometryEngine object's simplify method to return a simplified copy that can be saved in a geodatabase.
Geometries can also have m-values, used in linear referencing workflows. Using m-values is generally less common than using z-values. Therefore, instead of using constructors, the AGSPoint and AGSEnvelope classes present static factory methods that allow the creation of geometries with m-values.