Skip To Content

Sketch layer

In this topic

The sketch layer makes it easy to create and modify geometries interactively. Users can annotate maps with sketches and contribute geographic content by drawing shapes such as areas, lines, and points. You don't have to write code to implement the sketching behavior; wire up the sketch layer so that it can track and respond to user interaction.

A sketch layer complements a feature layer. Geometries drawn by a sketch layer can be used to create new features or modify existing features in a feature layer. These features can then be persisted in a geodatabase using an ArcGIS Server Feature service.

Sketch workflow

This section describes the user interaction required to create or modify a sketch.

  • When the sketch layer is active, tap the map to add a vertex to the sketch. If you are sketching a polygon, polyline, or multipoint, tap repeatedly to add more vertices to the sketch. If you are sketching a point, tapping the map again moves the existing vertex to the new location.
  • To add a vertex after a specific vertex, select the vertex by tapping it, then tap the map where you want to add the new vertex.
  • To insert a vertex between two vertices, select the mid-point between the two vertices by tapping it. Move the midpoint by tapping the map where you want to insert the new vertex. This inserts a new vertex at the tapped location.
  • To move a vertex, select the vertex by tapping it. Tap and hold the vertex for a few seconds. If you have enabled the showMagnifierOnTapAndHold property on the map view, a magnifier appears. Drag your finger to the location where you want to move the vertex to. When you release your finger, the vertex is moved to that location.

Sketch symbology

A sketch consists of many different visual elements. Each element is symbolized independently. For example:

  • Vertex
  • Midpoint between vertices
  • Selected vertex
  • Area enclosed by the vertices
  • Line joining the vertices
Sketch symbology
Default sketch symbology

You can change the symbology of each of these elements by modifying some properties on the AGSSketchGraphicsLayer class. The mainSymbol property allows you to modify the line and fill symbols for the sketch. The vertexSymbol, selectedVertexSymbol, and midVertexSymbol properties allow you modify the symbol for vertices, selected vertex, and the midpoint between vertices respectively.

Use a sketch layer

To use the sketch layer, instantiate an object of the AGSSketchGraphicsLayer class, then add it to the map. If you know the type of geometry the user needs to sketch, pass in a geometry while instantiating the layer. Alternatively, you can instantiate the layer without a geometry as shown below, then assign the geometry later.

let sketchLyr = AGSSketchGraphicsLayer()
self.mapView.addMapLayer(sketchLyr, withName: "Sketch Layer")

The type of geometry you assign to the layer dictates the type of shape a user is allowed to sketch. The geometry can be one of the following types :

  • AGSMutablePoint
  • AGSMutableMultipoint
  • AGSMutablePolyline
  • AGSMutablePolygon

A mutable geometry needs to be assigned to the layer because it will be updated by the layer as the user sketches.

If the geometry assigned to the layer is empty, the initial sketch is blank and the user can create a new sketch from scratch. However, if the geometry is not empty, the initial sketch represents the existing geometry and the user can modify it.

//empty geometry for new sketch
let sketchPolygon = AGSMutablePolygon(spatialReference: self.mapView.spatialReference)
sketchLyr.geometry = sketchPolygon
        
//or, existing geometry for modifying sketch
let sketchPolygon = polygon.mutableCopy() as AGSMutablePolygon
sketchLyr.geometry = sketchPolygon

Adding the sketch layer to a map and assigning it a geometry is not enough to begin the sketch operation; set it as the map's touch delegate so that it can track and respond to user interaction.

self.mapView.touchDelegate = sketchLyr

Note:

Only one object can serve as the map's touch delegate at a time. Setting the sketch layer as the delegate replaces any previous object serving as the delegate. Delay making the sketch layer a touch delegate until when you want the user to start sketching.

At this point, the user can start sketching on the map and the geometry is modified as the user sketches. You can access the sketch geometry anytime as follows :

let sketch = sketchLyr.geometry

To start another sketch, you do not need to create a new layer; assign the existing layer a new geometry.

Once the sketch workflow is over, choose the sketch layer's geometry, clear the layer, and unset the layer as the map's touch delegate to prevent any further sketches. Restore the original touch delegate to enable other parts of the application that depend on tracking map touch events.

Note:

After the user finishes the sketch, simplify the sketch geometry using the simplifyGeometry: method on AGSGeometryEngine. This makes the necessary corrections if the geometry intersects itself, or if a polygon geometry has rings in reverse orientation. If wrap around is enabled on the map, normalize the geometry using the normalizeCentralMeridianOfGeometry: method on AGSGeometryEngine.

Undo and redo changes

The sketch layer provides the ability to undo and redo changes made to the sketch. The layer uses Apple's NSUndoManager class under the hood to maintain a history of sketch changes. When a sketch is modified, by invoking methods on the sketch layer or by interacting with the map, the layer tracks the change. You can undo and redo these sequence of changes by invoking corresponding methods on NSUndoManager as follows :

let mgr = sketchLyr.undoManager
//Undo a change
if mgr.canUndo {
	mgr.undo()
}
        
//Or, redo a change
if mgr.canRedo {
	mgr.redo()
}

For more information about undo and redo, refer to Apple's Undo Architecture guide.

Note:

Sketch changes are specific to a geometry. The history of sketch changes automatically clears when the sketch layer's geometry is replaced.

Modify a sketch programmatically

A sketch can be modified programmatically in addition to being modified interactively as described above. This may be useful if you want to simplify the sketching process for the user or implement some advanced behavior.

You can modify the sketch geometry programmatically through methods on the AGSSketchGraphicsLayer class such as insertVertex:inPart:atIndex:, moveVertexInPart:atIndex:toPoint:, removeVertexInPart:atIndex:, and so on. These methods allow you to make incremental changes to the geometry. You can also use applyGeometry: to completely reshape the existing sketch geometry. You can use this approach when you want to make bulk changes to the geometry, or if you want to use complex criteria for constructing geometries. For example, creating geodetically correct geometries.

The sketch layer tracks changes using these methods so that you can undo or redo them using NSUndoManager..

Note:

Avoid directly modifying the geometry object used by the sketch layer. This may cause the sketch display to get out of sync with the geometry. Furthermore, changes made to the geometry in this manner are not tracked by the undo manager.

Notifications

The sketch layer posts a AGSSketchGraphicsLayerGeometryDidChangeNotification message when its geometry changes. You can subscribe to this notification message as follows if you want to monitor changes to the geometry:

//register self for receiving notifications
NSNotificationCenter.defaultCenter().addObserver(self, selector: "respondToGeomChanged:", name: AGSSketchGraphicsLayerGeometryDidChangeNotification, object: nil)
        
//method to be called when notification is posted
func respondToGeomChanged(notification:NSNotification) {
	//do something 
}