Vector editing

Documentation | Other Specifications | Vector editing

Vector editing features enable a user to create new or modify existing shape geometry using visual tools or coding. Both options are controlled by the TGIS_Editor class , which is responsible for the basic editing functionality. Editing features include:

• selecting vertices,
• moving vertices,
• adding new vertices,
• deleting vertices,
• adding shape parts (line segment, polygon hole, or island),
• snapping to the location of existing geometry,
• redo/undo operations,
• topology control.

The features discussed in this article are found in the TGIS_Editor class and in the desktop TatukGIS Editor application.

Editing is closely coupled with the TGIS_Viewer class, responsible for the visual presentation and controlling the editing interaction. Upon activating edit mode in the viewer and selecting a shape for editing, the renderer draws the selected shape using special styling.

• Editing first part of a polygon.
  
• Editing the polygon’s interior part.
  

During the editing process, the vertices (i.e., points) forming the edited shape are styled using:

• a red dot (i.e., small filled circle) represents the first vertex of the active shape;
• green dots represent the other vertices forming the active shape part;
• blue dots represent vertices forming other parts (if any) of the active shape.

Each vertex composing a shape is assigned a number which can be displayed. The Z coordinate values for vertices forming a 3D shape can also be displayed.

The Editor class has many interesting properties that change the visual presentation and behavior during the editing process:

• ShowTracking
  If True, show vertices to trace from a shape in the snap-to layer.
• ShowPointsNumbers
  If True, show the vertex numbers of the actively edited shape.
• ShowPoints3D
  If True, show the Z coordinates for the vertices of an actively edited 3D shape.
• ShowDraggingTrack
  If True, show dragging track when dragging (moving) a vertex to a new position.

• hide vertex numbers;
  
• hide 3D shape Z coordinates;
  
• show dragging track.
  

The editing mode determines how new vertices are created relative to existing vertices forming the shape part:

• Default
  usually TGIS_EditorMode.NearestPoint, but upon pressing CTRL same as TGIS_EditorMode.AfterActivePoint;
• Reversed
  editing performed opposite to the default mode;
• NearestPoint
  added vertex modifies the nearest line segment or polygon edge;
• AfterActivePoint
  a new vertex is added sequentially (by vertex number) after the last active vertex.

• State before adding a new point.
  
• Added point modifies the nearby line segment.
  
• Point added after the previously active point.
  

The following properties enable changing the predefined editor styling, such as the presentation colours of lines or points:

• EditingLinesStyle
  edits the style of lines'
• EditingPointsStyle
  edits the style of vertices.

For accurate editing vector layer geometries, the snapping feature enables the placement of vertices to the exact locations of already existing vertices, line segments, polygon edges, intersections, or other geometric features, by holding the cursor (or finger or pointer when using a tablet computer) within a distance tolerance to the snap-to feature. The geometry that is snapped to may exist in the layer being edited or in a different layer (or layers), normally positioned below the editing layer. The snap-to layer can contain any geometry (e.g., polygons, lines, points, multi-points), and snapping can simultaneously use multiple snap-to layers. As an example, a user might edit a polygon layer by snapping to polygon features in one snap-to layer and also point or line features in a second snap-to layer.

To use snapping, the user must select one or more snap-to layers, a snap-type mode, and a distance tolerance. The following properties control snapping behavior during the editing process:

• SnapMargin
  the distance tolerance from the snap-to feature for a snap to occur;
• SnapGridSpacing
  the spacing of the grid to which points will be snapped;
• SnapToIntersection
  if True, snap to the point of intersections between shapes;
• SnapLayer
  layer containing geometry to which edited points will be snapped.

When snapping is active, the vertices active for editing, and the snapping points are presented as yellow dots:

The SnapType property additionally tells the editor how to calculate the search for a snap-to point:

• Point
  snap to the position of the nearest vertex from the cursor (within the distance tolerance);
• Line
  snap to the closest position on the nearest line segment or polygon edge;
• Custom
  custom snap to a point defined by the user from an event
• PointOverLine
  prefer point snapping over line snapping:
  1. try to select the closest vertex.
  2. then the closest intersection
  3. then the closest segment/edge.
• EndPoint
  snap to the first or last vertex of the closest line or the polygon shape;
• Midpoint
  snap to a line or polygon edge at the midpoint position between any the nearest two sequential vertices forming a line or polygon edge;
• Perpendicular
  snap to the point on the closest line segment or polygon edge that results in a perpendicular (90 deg) line drawn from the previously drawn point.
• GridPoint
  snap to grid points defined by grid spacing.

The following images illustrate different snapping types:

• Snap to the nearest vertex (Point).
  
• Snap to the nearest point on edge (Line).
  
• Snap the midpoint of an edge (Midpoint).
  
• Snap to a polygon endpoint (EndPoint).
  
• Snap to position on edge, creating a 90-degree angle (Perpendicular).
  
• Snap to shape intersection (+SnapToIntersection).
  
• Snap to grid 0.05 (GridPoint).
  

The snap-to layers are managed the following Editor functionality:

• SnapLayer
• AddSnapLayer
• ClearSnapLayers
• RemoveSnapLayer
• FindSnapLayer

The ShowTracking property presents the tracking path when using the mouse cursor to drag an active point to a new position. A small red rectangle highlights each eligible snap-to location. Depending on the SnapType property, snap-to positions can be vertices, line segment or polygon edge midpoints, shape intersections, etc.

When tracking is enabled, the user can customize the rendering of eligible snap-to locations by:

• using FindSnapPoint function inside the viewer MouseMove event to find the best snap-to candidate
• calling the TGIS_ViewerWnd.InvalidateTopmost method on the viewer
• drawing a tracking location inside the viewer TGIS_ViewerWnd.PaintExtraEvent event using the available renderer

• Tracking as implemented in TatukGIS Editor showing candidate location.
  

The Editor class also exposes events for notifying and custom controlling the editing operation before the result is committed to memory, such as:

• PointChangeEvent
  notifies of a point change;
• PointEditingEvent
  notifies of editing a point;
• SnapPointEvent
  calls a custom snap routine.

Shape editing can also be performed using code. The CreateShape method is called to create a new shape. The EditShape method is called to modify an existing shape. After the shape is loaded into the editor, operations can be executed by adding a new vertex, adding a part, or modifying existing vertices. When done with editing a shape, the EndEdit method must be called to finalize the process by committing the editing changes to memory.

The SimpleEdit sample offers additional guidance on using the Editor API.