User:Jcreer/Clean Options

The Clean Options dialog

The Clean Options dialog can be accessed by clicking the Clean macro or the Feature Objects | Clean... menu command.

The dialog has several options for cleaning feature objects on a map coverage.

• Features – Determines which features will have clean operations applied to them.
  • All – Every feature in the coverage will be considered by the cleaner, regardless of whether the feature is selected or not.
  • Selected – Only features that are currently selected will be considered. Any unselected features will be ignored by the cleaner, as if they don't exist.
• Snap distance – Indicates how close two features must be in order to snap them together. Features which are within Snap distance of each other can snap together, while those further than this distance cannot. Features are moved one at a time, so it is possible that snapping one feature will make another opportunity available, or make an existing opportunity no longer available. This is also a per-move limit. The current implementation of the cleaner allows features to move up to 5 times each, so a feature's total movement may be as far as 5 snapping distances.
• Full clean – Enables or disables all of its sub-options at once. This is the typical way of cleaning a coverage, but the sub-options can be controlled individually if desired.
  • Snap points, nodes, and vertices together – Controls whether points, nodes and vertices will snap to each other.
  • Snap points, nodes, and vertices to arc segments – Controls whether points, nodes and vertices will snap to arc segments.
  • Intersect arc segments – Controls whether nodes will be inserted where arcs intersect.
• Remove arcs less than ___ in length – Sets a length value which the clean tool will use to remove dangling arcs that are less than the set value. Dangling arcs are arcs where exactly one

node is attached to another arc, or the arc forms a loop.

• Snap selected points, nodes, and vertices – If this option is chosen, SMS will wait for the user to choose a snap target by clicking on any point, node, or vertex, or cancel the operation by clicking away from any valid target. Once a target is chosen, all currently selected points, nodes and vertices will be snapped to it. This is equivalent to clicking and dragging each of the selected points onto the snap target, which is a more typical workflow in SMS.

The Cleaning Algorithm

The cleaning algorithm applies several clean operations to the coverage in sequence. If snapping to segments is enabled, it is possible that cleaning the coverage once will create new cleaning opportunities, so the cleaner will apply multiple iterations and check for convergence.

The cleaning process involves maintaining "sorted" lists of locations (points, nodes and vertices) and arc segments.

1. Sorting

Locations are sorted from left-to-right by their X-coordinates, with ties broken by sorting from bottom-to-top by their Y-coordinates (example 1).

Segments are sorted by comparing their endpoints using the same comparison as for locations. Then the "first" locations on each segment are compared, and the segment containing the earlier location is chosen first. In the event of a tie, the "second" location is used to break the tie (example 2).

1. Steps

Note that when a location is moved, it is locked in place for the remainder of the iteration.

Vertex removal

This step is controlled by the *Snap points, nodes, and vertices together* checkbox. It always runs with the *Snap to points and nodes* and *Snap to vertices* steps. The process is to examine each segment on an arc looking for any segment that is shorter than the snap distance. If one is found, the vertex at the center of the sharpest bend is kept, and the other is removed. The first and last segments are considered last (example 3).

Snap to points and nodes

This step is controlled by the *Snap points, nodes, and vertices together* checkbox. It always runs with the *Vertex removal* and *Snap to vertices* steps. The process is to select the first point or node, then snap all other locations within distance to it before proceeding to the next location. This can remove some opportunities for snapping to locations by snapping a location away from where it otherwise might have gone (example 4). It can also create or remove opportunities for snapping to segments by moving segments toward or away from locations (example 5).

The locations of points and nodes are generally more significant than those of vertices. By only considering points and nodes as snap targets, this step ensures that the location of a vertex is never favored over that of a point or node (example 6).

Snap to vertices

This step is controlled by the *Snap points, nodes and vertices together* checkbox. It always runs with the *Vertex removal* and *Snap to points and nodes* steps. It is identical to the Snap to points and nodes step, except that vertices are now considered as snap targets (example 6).

Since the *Snap to points and nodes* step already snapped everything near points and nodes together, this step can only move vertices around.

Snap to segments

This step is controlled by the *Snap points, nodes, and vertices to arc segments* checkbox. The process is to select the first segment, then examine all other locations, in order, to find one that is within snapping distance. Once found, the nearby location will be snapped to the nearest location on the segment. The segment will also be split in two by inserting a node at the snapping point, and the two new segments will be added to the list of segments to consider (example 7).

Note that this step only snaps to interior locations on a segment. If it finds that the closest location on the segment is actually an endpoint, then the location being considered will be skipped, even though it is within snapping distance of the segment (example 8). Snapping to endpoints is only done by the *Snap to locations* step.

Arc intersection

This step is controlled by the *Intersect arc segments* checkbox. This step inserts nodes wherever two arc segments intersect (example 9). Intersection is done in an order similar to arc snapping, but since no movement happens, order is typically unimportant.

Intersection only considers locations where two arcs cross. An arc segment may also have an endpoint on another arc segment (example 10). Since the two segments do not actually cross, intersection will not do anything with them. To clean this case, segment snapping must be enabled.

Deduplication

This step is always performed when any cleaning option is enabled. It removes any arcs that are duplicates of each other. When removing a duplicate arc, it preferentially removes arcs which are not part of a polygon.

Vertex restoration

This step is always performed when any cleaning option is enabled. It looks for cases where a vertex became a node, and attempts to convert the node back to a vertex again. See example 11.

Remove dangling arcs

This step is performed after all other steps are finished. Unlike the other steps, it only runs once, at the very end. It scans the coverage for any arc that is shorter than the specified length, and deletes it. If the arc was the only one attached to a node, then the node will also be removed along with it (example 12).

Examples

Note: The example images have grid lines displayed every 0.5 units. Unless otherwise noted, all examples use Mode=All, Features=All, and Distance=1. Any unspecified clean options are off.

Example 1: Point sorting

In figure 1, Location 1 sorts before 2 because its Y-coordinate is lower, and it sorts before 3 and 4 because its X-coordinate is lower. Location 2 sorts before 3 and 4 because its X-coordinate is lower. Then 3 sorts before 4 because its Y-coordinate is lower. Location 4 is last because it has the highest X and Y coordinates.

Figure 1, point sorting

Example 2: Segment sorting

In figure 2, location 1 is the first location on segment 1, and location 3 is the first on segment 2. The X-coordinate of location 1 is less than that of location 3, so segment 1 sorts before segment 2.

Similarly, location 5 and 7 are the first locations on segments 3 and 4, respectively. Their X-coordinates are the same, but 5 has a lower Y-coordinate, so segment 3 sorts before segment 4.

Segments 5 and 6 have the same first location, 9. The tie is broken by comparing locations 10 and 11. Location 10 has a lower X-coordinate, so it sorts before location 11, and its segment, 5, sorts before segment 6.

Segments 7 and 8 are similar to 5 and 6, except that locations 13 and 14 have the same X-coordinate, so the Y-coordinate is used. This favors location 13, so segment 7 is chosen first.

Figure 2, segment sorting

Example 3: Vertex removal

This example uses the Snap points, nodes and vertices together option.

In figure 3a, several segments are within the snap distance of 1. The arc starts from node 1 and goes to node 2, so the cleaner starts considering segments from node 1. The second segment from node 1 is too short, so it will be removed. The bend at the first vertex is 45*, while the one at the second vertex is 90*, so the first vertex is removed, giving figure 3b. The new second segment is too short. The bend at the first vertex is about 55*, while the one at the second is 45*, so the first vertex is removed and the second kept, giving figure 3c. Again, the new segment is too short. The bend at the first segment is about 68*, while the one at the second vertex is 90*, so this time the first vertex is kept and the second is removed, giving figure 3d. The middle segment is now long enough to keep. Once interior segments are removed, the first and last ones are considered. The first segment is long enough to keep, but the last is too short. Since this segment includes a node, the vertex is removed, giving figure 3e.

Figure 3a start

Figure 3b

Figure 3c

Figure 3d

Figure 3e end

Example 4: Snapping locations away from locations

This example uses *Snap points, nodes and vertices together*. See figure 4a. Since there are no vertices, only the *Snap to node* step is meaningful in this example. Each node is considered as a snap target, in the order shown in example 1.

• Node 1: Node 3 is nearby, so it snaps to node 1.
• Node 2: There are no locations nearby, so nothing happens.
• Node 3: Node 5 is near where node 3 started, and could have snapped in the beginning. Since node 3 already snapped to node 1, it is now too far away from node 5, so nothing snaps to it.
• Node 4: There are no locations nearby, so nothing happens.
• Node 5: Node 7 is nearby, so it snaps to node 5.
• Node 6: There are no locations nearby, so nothing happens.
• Node 7: Like nodes 3 and 5, node 9 could have snapped to node 7, but node 7 was already snapped to node 5, so the opportunity is lost.
• Node 8: There are no locations nearby, so nothing happens.
• Node 9: There are no locations nearby, so nothing happens.
• Node 10: There are no locations nearby, so nothing happens.

The result is figure 4b.

Figure 4b start

Figure 4b cleaned

Example 5: Snapping segments toward and away from locations

This example uses Full clean. See figure 5a.

The Snap to points and nodes step runs first. The only opportunity for location snapping is to snap node 5 to node 2, yielding figure 5b. The Snap to segments step runs next. Originally, node 7 was close enough to snap to arc 3, but snapping node 5 to node 2 moved arc 3 away from node 7, and now it is no longer in snapping range. On the other hand, node 4 was originally too far to snap to arc 3, but arc 3 moved close enough to snap after all. The result is figure 5c.

Figure 5a start

Figure 5b

Figure 5c end

Example 6: Points and nodes are favored over vertices

This example uses Snap points, nodes, and vertices together. See figure 6a.

Since the vertex on arc 1 is left of node 3, it sorts before the node. However, location snapping considers points and nodes as snap targets first, so node 3 is the first snap target with nearby locations. The vertex and node 5 both snap to it, yielding figure 6b. With all the nodes snapped to, vertices are considered as snap targets next. The vertex on arc 4 sorts before the one on arc 5, and arc 5's vertex is within snapping range, so the vertex on arc 5 snaps to the one on arc 4, yielding figure 6c.

Figure 6a start

Figure 6b

Figure 6c end

Example 7: Snapping nodes to arc segments

This example uses Full clean. See figure 7a.

Node 4 is snapped down to arc 1, splitting it in two and creating a new arc (figure 7b). Then node 6 is snapped down to arc 4, splitting it again and creating a new arc (figure 7c).

Figure 7a start	Figure 7b
Figure 7c end

Example 8: Segment snapping ignores endpoints

This example uses Snap points, nodes, and vertices to arc segments. See figure 8.

"When considering arc 1, node 3 is nearby. But the closest location to it on arc 1 is node 2, so this possibility is skipped. Similarly, when considering arc 2, node 2 is nearby. But it is closest to node 3, so this possibility is also skipped. Since the only available clean possibilities are location snaps, and location snapping is disabled, the cleaner does nothing in this case.

Figure 8

Example 9: Intersecting arcs

This example uses Intersect arc segments. See figure 9a.

The two arcs cross near the middle. The segment intersector inserts a node at the point of intersection, splitting each arc in two and yielding figure 9b.

Figure 9a start

Figure 9b end

Example 10: Intersection ignores points on segments

This example uses Intersect arc segments. See figure 10.

Node 4 is exactly on arc 1, but the segment intersector ignores this case, so no change happens.

Figure 10

Example 11: Vertex restoration

This example uses Snap points, nodes, and vertices together. See figure 11a.

First, the Snap to points and nodes step snaps node 3 down to node 1 (figure 11b). Next, the Snap to vertices step snaps the two vertices on arc 2 down to the matching ones on arc 1 (figure 11c). Finally, the Vertex restoration' step attempts to restore nodes 6 and 8 to vertices. Node 6 can be restored, but node 8 is attached to 3 arcs, so it does not restore. The result is figure 11d.

Figure 11a start	Figure 11b
Figure 11c	Figure 11d end

Example 12: Removing dangling arcs

This example uses Remove dangling arcs with a distance of "1". See figure 12a.

Arc 2 has length 1, so it is removed. Since its nodes had no other arcs attached, its nodes are also removed. Arc 3 also has length 1, it is removed as well. Since node 5 had no other arcs attached, it is also removed. Node 4 is still attached to arc 1, however, so it is retained. The result is figure 12b.

Figure 12a start

Figure 12b end

Example 13: Snap to self

This example uses Snap points, nodes, and vertices together. See figure 13a.

The rightmost vertex on the narrow part of the hourglass snaps to the leftmost one, yielding figure 13b. This illustrates that an arc can potentially snap to itself.

Figure 13a start

Figure 13b end

Example 14: Self-intersection

This example uses Intersect arc segments. See figure 14a.

The arc intersector inserts a node where the arc intersects itself, splitting it into three arcs and yielding figure 14b. This illustrates that an arc can potentially intersect itself.

Figure 14a start

Figure 14b end

Example 15: Multiple iterations

This example uses Full clean. See figure 15a.

The location snapper snaps node 5 to node 1, then node 6 to node 7, yielding figure 15b. The snapped nodes 6,7 are close enough to snap to arc 2, but snapping them locked them in place, so they remain where they are for this iteration. Node 8 is close enough to snap to arc 2, and does, yielding figure 15c. Since changes were made, another iteration begins. Now that node 8 snapped to the arc, it is close enough to be snapped to node 6, yielding figure 15d. After this iteration, cleaning converges and no more changes are made.

Figure 15a start	Figure 15b
Figure 15c	Figure 15d end

Example 16: Selections

This example uses Features = Selected and Full clean. See figure 16a. Arcs 1, 2, and 3 are selected. Nodes 4 and 7 are selected.

No locations can snap initially, so location snapping does nothing. For segment snapping, node 3 is not selected, so it does not snap to arc 1. Node 7 snaps down to arc 2, splitting it into arcs 2 and 7. Arc 6 is not selected, so node 4 does not snap to it. The result is figure 16b. During intersection, arcs 2 and 3 are selected, so an intersection is inserted there. The intersection between arcs 2 and 5 is ignored since arc 5 is not selected. The result is figure 16c. During the second iteration, the location snapping steps are able to snap node 7 to node 14, with the final result being figure 16d.

Figure 16a start	Figure 16b
Figure 16c	Figure 16d end

The Clean Options dialog

The Clean Options dialog can be accessed by clicking the Clean macro or the Feature Objects | Clean... menu command.

The dialog has several options for cleaning feature objects on a map coverage.

• Clean coverage – When turn on, this option enables cleaning of the coverage. Cleaning applies operations such as snapping locations to nearby locations and arcs, and inserting nodes where arcs intersect. The algorithm used is described in more detail below. This option has the following sub-options:
  • Mode dropdown
    • "Locations (nodes, vertices)" – Will only snap locations to nearby locations. Locations will not be snapped to nearby arcs, and no intersection nodes will be inserted.
    • "All (arcs, nodes, vertices)" – A superset of the "Locations" operation. In addition to snapping to locations, it will also snap to arcs and insert intersections.
  • All – Clean all features in the coverage.
  • Selected – Only clean selected ones. Selected features will not snap to nearby unselected features.
  • Distance – The maximum distance a location is allowed to move to snap to another feature. Note that features are snapped one at a time, which means it is possible for one step to move a feature to within snapping distance for another step, or to move it too far away.
• Remove short (dangling) arcs – Removes arcs that are below a provided length.
  • Up to length – Enter the length value for removing dangling arcs.
• Snap selected nodes – Snaps all currently selected nodes to the next node clicked after exiting the dialog. This option is unavailable if no nodes are selected, or if features other than nodes are selected (e.g. vertices, arcs, or disjoint points). This option can only be used by itself, since it is an interactive operation while the others are automated.

The Cleaning Algorithm

The cleaning algorithm performs several operations, in order. This process involves maintaining "sorted" lists of locations (nodes and vertices) and arc segments. Disjoint points that are not part of an arc are not considered when cleaning.

Locations are sorted from left-to-right by their X-coordinates, with ties broken by sorting from bottom-to-top by their Y-coordinates. Segments are sorted by first sorting the locations of the segment, then sorting the segments by their "first" points, then finally breaking ties by their "last" points.

When cleaning selected features, only the ones that are selected are considered. Unselected features will not snap to anything, and nothing will snap to them. From the cleaner's perspective, it is as if they do not exist.

The cleaner distinguishes between "snapping", which moves features around and creates duplicate locations, and "merging", which combines duplicate locations into a single node. Merging happens at the end, after everything is finished moving.

• Location snapping :

This is always done when cleaning is enabled. The process is to select the first location, then snap all other locations within distance to it before proceeding to the next location.

• Arc snapping :

This is only done if the cleaning mode is set to "All". The process is to select the first segment, then examine all other locations, in order, to find one that is within snapping distance. Once found, the nearby location will be snapped to the nearest location on the segment. The segment will also be split in two by inserting a vertex at the snapping point, and the two new segments will be added to the list of segments to consider. The node and vertex will be merged in a later step.

Note that this step only snaps to interior locations on a segment. If it finds that the closest location on the segment is actually an endpoint, then the location being considered will be skipped, even though it is within snapping distance of the segment.

• Arc intersection :

This is only done if the cleaning mode is set to "All". This step inserts nodes wherever two arc segments intersect. Intersection is done in an order similar to arc snapping, but since no movement happens, order is typically unimportant.

Intersection only considers locations where two arcs cross. An arc segment may also have an endpoint on another arc segment. Since the two segments do not actually cross, intersection will not do anything with them.

• Merging :

This step finds all nodes and vertices which share a location and merges them into a single node. If the resulting node was originally a vertex, and can still be a vertex, the cleaner will convert it back afterward.

• Deduplication :

This step is always performed when cleaning is enabled. It removes any arcs that are duplicates of each other. When removing a duplicate arc, it preferentially removes arcs which are not part of a polygon.

• Remove dangling arcs :

This step is performed after all other steps are finished.

Examples

Note: The example images have grid lines displayed every 0.5 units. Unless otherwise noted, all examples use Mode=All, Features=All, and Distance=1.

Example 1

Node 5 snaps to node 1, and node 6 snaps to arc 2.

Example 1 start

Example 1 cleaned

Example 2

This example uses Mode=Locations. Node 5 snaps to node 1, but node 6 does not snap to arc 2 because Mode=Locations does not snap locations to arcs.

Example 2 start

Example 2 cleaned

Example 3

Node 5 snaps to node 1, then node 6 snaps to node 7. Next, node 6 snaps again to arc 2. Nodes 7 and 8 are within range of arc 2, but their snap target is an endpoint of a segment now, so the segment snapper skips them. Arc 4 has no intersection inserted because it does not intersect anything. The end of arc 3 happens to be on arc 4, as well as a vertex on arc 2, but the intersector only considers segments that actually cross.

Example 3 start

Example 3 cleaned

Example 4

This example uses Mode=Locations. Node 3 snaps to node 1, which makes it too far away to snap to node 5. Node 7 then snaps to node 5, making it too far away to snap to node 9. Nothing else snaps.

Example 4 start

Example 4 cleaned

Example 5

Note how, initially, node 4 is too far from arc 3 to snap to it. The cleaner first snaps node 5 to node 2, which reduces the distance between node 4 and arc 3, allowing node 4 to snap to arc 3 in the end.

Example 5 start

Example 5 cleaned

Example 6

This example has a single arc with several vertices. The cleaner snaps the vertices near the center of the hourglass together, producing two different arcs.

Example 6 start

Example 6 cleaned

Example 7

The nodes on arc 2 snap to the vertices on arc 1. This turns the vertices into nodes, and results in a duplicate arc. The cleaner discards the duplicate arc, then observes the nodes can be turned back into vertices, and does so.

Example 7 start

Example 7 cleaned

Example 8

This example uses Features=Selected. Arcs 1, 2, and 6 are selected. Nodes 12 and 9 are selected.

Node 12 snaps to arc 1, inserting a vertex in the process. Next it snaps to arc 2, where it remains. Arc 1 is never intersected with arc 10, because by this point there is no longer an intersection.

Node 8 does not snap to arc 6 because the node is not selected. Similarly, node 9 does not snap to arc 4 because the arc is not selected.

Example 8 start

Example 8 cleaned

Example 9

Previous examples mainly used nodes, but this one shows that vertices also snap. The vertex on arc 2 is snapped to the right vertical segment on arc 1. Additionally, arc 1 is self-intersecting, so the cleaner inserts a node where it intersects itself.

Example 9 start

Example 9 cleaned