# Traverses

A traverse is a way of defining lines and area boundaries as they are described in surveying in the United States.  Although traverses are best known for use in surveying in the US, they can be very useful worldwide in any situation where a line, a boundary, or a record of a path or course can be most easily recorded by noting a series of directions and distances instead of a list of latitude,  longitude coordinates.

Manifold's ability to edit traverses on the fly also is especially useful in general-purpose GIS for drawing lines and areas parametrically, by specifying the direction and distance of a line.  See the example of using traverses for general purpose editing near the end of the Info Pane: Coordinates topic.

Traverses are also known as metes and bounds descriptions or, in Esri jargon, COGO (computational geometry) descriptions.  Manifold uses Esri-style descriptions for traverse commands, using Esri traverse format in the Info pane's coordinates list when we choose Show Traverse.

The primary interface for managing traverses and the coordinates that define them is the Coordinates tab in the Info pane.   The Info Pane: Coordinates topic provides a reference to working with traverses in the Info pane.   This topic provides a more tutorial discussion of traverses.

See the First Look - Edit Traverses video for interactive editing of traverses.

## X,Y Coordinates Compared to Traverse Commands

GIS packages define a line (either a line or a border line for an area) by listing the X,Y (and sometimes Z) coordinates that compose the line.  Traverses define a line using traverse commands that specify the starting point for the line and then describe how to walk that line, in terms of directions and distances to go.  To see the difference, we begin by considering a line drawn in the form of a square, as in the illustration below.

The standard way of defining such a line in GIS is to give a list of the X,Y coordinates in order.   Beginning at 15, 80 the line continues to 20, 80, then to 20, 75, then to 15, 75 and finally back to 15, 80.

Traverses describe how to walk the line instead of listing the coordinates.   The starting point and then each segment of the line are specified by traverse commands, one for each segment.

A simple traverse command is to state the direction to walk and how far to go.  A traverse like that shown above might say, "Start at the beginning point and walk in the 90 degree direction for five meters.  Next, walk in the 180 degree direction for five meters.  Next, walk in the 270 degree direction for five meters.  Finally, walk in the 0 degree direction for five meters."

If a traverse accurately describes the directions and the distances to walk for a closed line, if we follow the instructions we will end up exactly where we started, walking the area boundary of a closed square.   This style of writing traverse commands is called direction and distance, abbreviated DD or Direction + Distance.

An alternate way to write traverse commands that use directions and distances is to use relative directions, that give the angle relative to the preceding segment's bearing as the direction for the next segment.   The traverse above illustrates that approach, and might be written as, "Start at the beginning point and walk in the 90 degree direction for five meters.   Next, turn 90 degrees to your right and walk for five more meters.   Next, again turn 90 degrees to your right and walk five more meters.  Finally, turn 90 degrees to your right and walk five meters."  That sequence of commands uses direction and distance for the first segment, and then relative angles for the next three segments.  Using relative angles in traverse commands is called angle and distance form, abbreviated AD for Angle + Distance.

When using angle and distance commands, the direction for each segment is given by a relative angle to change from the preceding direction.  That means we cannot use an angle and distance command for the very first segment, since there is no preceding direction from which to start.  The first segment therefore is always a DD, that is, a direction and distance segment, after which we can give relative angles AD style.

The above introduction to traverses discusses only straight line segments.   Traverses can also include circular arcs, which involve unintuitive, but geometrically accurate descriptions.

## The Info Pane and Traverses

The Info pane's Coordinates tab is the primary interface for viewing, editing, loading, and saving traverses.

The coordinate list format picker button allows us to choose between showing the coordinates that define a line or an area in either XY/XYZ format or in traverse command format.   Traverses are a way of defining lines or areas, but not points, so there is no traverse format command for a point except for the starting point.  Illustrations below show coordinates for an area with many coordinates.

At any time, including when creating new objects or editing existing objects, we can switch between showing XY/XYZ coordinates or traverse format.

Press the coordinate list format picker button to switch:

XY/XYZ format simply lists the X,Y or X,Y,Z (in the case of lines or areas with a Z value) numbers for each vertex or control point of a curved segment.   Traverse format describes lines or areas by giving the angle or direction, and distance to each next vertex.  Esri traverse format is used in the coordinates list when we choose Show Traverse, using tokens such as SP, DD, AD, TC, and NC.

The Coordinates tab remembers the last used coordinates list format setting for each window.   For example, if we are working with two different map windows and in one we have used the coordinate list format picker button to show XYZ coordinates and in the other we have used it to show traverse commands, as we switch back and forth between the two different map windows the Coordinates tab format will automatically switch back and forth between showing XYZ coordinates and traverse commands.

## Switching between AD and DD Format

Esri traverse format provides options for how straight line segments and circular arc segments are described.   For example, we cans switch from default Direction + Distance style using DD tokens to Angle + Distance style using AD tokens (when allowed).

We can switch just a single row between DD and AD format, or we can switch all rows at once.

For example, if we want to switch the third row from using DD to AD format, we right-click the third row.

In the context menu, we choose Angle + Distance.   The row will immediately switch to using AD format, with Manifold automatically recomputing the angle from an absolute directions to a relative angle.   Instead of an absolute direction of 72.8 degrees, it will use a relative angle of 9.2 degrees to specify the bearing of that line segment.

To switch all rows at once, with the focus on the Info pane we press Ctrl-A to select all rows.   If we want to switch only some of the rows, we can select only the rows we want, using the usual selection moves that work with rows in tables and dialogs.

We then right-click any of the selected DD rows and choose Angle + Distance.   That will switch all selected rows (except the first one) to using Angle + Distance notation, with Manifold automatically recomputing the angles from directions to relative angles.    We can then deselect all rows using a Shift-Ctrl-A.

Note that DD format must be used for the first segment of a line, since there is no prior segment from which a relative angle can be specified.  AD format can be used only for the second and subsequent segments of a line.

## DD and AD Format Example

We can see how the Coordinates tab reports coordinates or traverses for the examples with which we started this topic, using a line that forms a closed square.  To launch the Info pane we would pick the line by Alt-clicking it, and then choosing the Coordinates tab.  Illustrations below do not show the alt-clicked line, but do show what the Coordinates tab would report:

The default display is X,Y coordinates, in the usual GIS way.

Using the coordinate list format picker button we can switch to Show Traverse.  The default traverse format is DD, Direction + Distance format.  The SP token at the beginning gives the coordinates of the Starting Point.

Selecting all rows, right-clicking onto a DD row and choosing Angle + Distance switches the display to using AD, Angle + Distance format for all rows where AD format can be used.

## Traverse Parameters

There are many different notation options for specifying traverses, for example, whether the direction uses North Azimuth, and whether degrees or some other angular units are used, and if degrees are uses whether they are decimal degrees or use degrees - minutes - seconds format.   The Traverse Parameters dialog allows us to choose desired options.

The Traverse Parameters choice in the coordinate list format button menu launches the Traverse Parameters dialog,

The Traverse Parameters dialog specifies the format used to show traverse numbers, allowing us to choose from various Esri formats for direction type and direction units.

 Direction type Standard Esri options as described on the Esri Direction Formats page.  Described in terms of clock positions:   North azimuth - Default.  Angles increase clockwise from the 12:00 position. Polar - Angles increase counter-clockwise from the 3:00 position. Quadrant bearing - N or S followed by an angle, followed by E or W direction. South azimuth - Angles increase clockwise from the 6:00 position. Direction units Standard Esri options for angular units of measure:   Degrees - Default. Decimal degrees. Degrees-minutes-seconds - Degrees, with fractions of a degree as minutes and seconds. Gradians (gons) - 400 gradians in a circle.  Gon is a synonym for Gradian that is used in some European languages. Radians - Approximately 6.28318 radians in a circle.

We can switch traverse parameters at any time, to display the coordinate list numbers as we like.

For example, if we switch from the default North azimuth and Degrees settings to Quadrant bearing and Degrees-minutes-seconds, the Coordinates list in traverse format will instantly switch to displaying numbers using the new formats.

The illustrations above show the before (left) and after (right) coordinate lists.   In the above lists, a DD value like 63.5836... in North Azimuth and Degrees format would become DD N63-35-0.99...E  in Quadrant bearing and Degrees-minutes-seconds format.

## Example: Create Lines or Areas by Entering Traverse Commands

At any time when editing lines or areas we can click into the Coordinates tab of the Info pane, choose Show Traverse in the coordinate mode button, and then double-click into a traverse command to edit the values there.  We can do that even in the middle of an editing session.    The following example shows how to create the figure shown above with a combination of clicks in the map window and interactive editing in the Info pane.

In the cursor mode button on the main toolbar we pick the Create Line tool and then we click approximately where we would like our line to begin.

In the Info pane we choose the Coordinates tab and then we choose Show Traverse in the coordinate mode button.

The only location clicked so far is the starting point.  The traverse command for the starting point starts with SP, short for Starting Point, followed by the X and Y coordinates for the starting point.  We double-click into that traverse command to edit it.

We edit the X, Y numbers (longitude and latitude if we are using degree coordinates) for the starting point to the numbers we want and then we press Enter to accept the edit.

In this case, we have entered 15 80 as the coordinates of the starting point.  As soon as we press Enter the starting point moves to the specified location.   We are still in create line mode, so wherever in the map we move the mouse cursor the segment line rubber bands to the cursor position.   We click at any location near where we would like that first segment to end.

An edit handle appears in the map where we clicked, and a new row appears in the Coordinates tab list for the traverse command implied by that click.   The new row by default uses a Direction + Distance format traverse command, abbreviated DD, followed by the direction in degrees and the distance (length) of the segment in whatever units of measure are used by the drawing.

We double-click that row to edit the traverse command.

We enter the desired direction, in this case 90, and the desired distance, in this case 5.   Press Enter to accept the edit.

The coordinate at the end of the segment defined by the traverse command immediately moves to a position 5 units to the East (90 degrees) of the starting point.

To enter the next traverse command, we click in approximately the location for the next segment.   It doesn't matter where we click, since we will edit the provisional traverse command use the exact traverse command we want.

An edit handle appears where we clicked and a new traverse command row appears in the Coordinates tab list.   We double-click that traverse command row to edit it.

We are drawing a square figure, so for the next segment we want to enter a command that takes the traverse directly South for five units.  There are two ways to do that.   We can use a DD command with a direction of 180 and a distance of 5, or we can use an AD command, for Angle + Distance, giving a relative angle from the prior direction and a distance.    All corners in a square are 90 degree changes of direction, so for an AD command we use an angle of 90 and the distance, as before, is 5 units.

Press Enter to accept the edit.

The coordinate at the end of the segment defined by the traverse command immediately moves to a position 5 units in a direction that is 90 degrees from the direction of the previous segment.

To enter the next traverse command, we click in approximately the location for the next segment.    An edit handle appears at the coordinate location we clicked.

We could edit that new traverse command right away as we did for the previous two segments, but we do not have to do that.   We can click again to mark another location.   We then can edit both of the new traverse command rows that appear in the Coordinates tab list.

We double-click the first of the two new traverse command rows to edit it.  Note that by default new traverse commands are shown using DD format.

We enter AD 90 5, meaning, to add a new segment in the direction that is 90 degrees from the proceeding segment's direction, and at a distance of 5 units.  Press Enter to accept the edit and the end coordinate for that segment immediately moves to a location 5 units in distance and in a direction 90 degrees from the preceding segment's direction.

We double-click on the second of the two new traverse command rows added.

We then enter AD 90 5 for that command row as well, and press Enter to accept the edit.

The final coordinate for the last segments moves into position, closing the figure.    We have drawn a square that starts at a given starting point.   The first segment must use DD format since there is no preceding line from which a relative angle can be specified.   That first segment says to continue the figure due East (90 degrees) for 5 units.  The traverse command for the next segment says to make a 90 degree turn and to proceed for 5 units.  The traverse command for the third segment says to make a 90 degree turn and to proceed for 5 units.   The traverse command for the fourth segment says to make a 90 degree turn and to proceed for 5 units, closing the figure.

Note how we can mix DD (Direction + Distance) and AD (Angle + Distance) commands however we like, provided the first segment is always a DD command.

To create the line object, we press Add Record in the Info pane, or we can right-click in the map window and choose Save Changes, or, with the focus in the map window we can press Ctrl-Enter, a keyboard shortcut to save changes.

The new line object appears exactly as we specified.  We have previously used the Style pane to style lines using a dot as a beginning symbol and a red arrow head as an end symbol, to make it clear in which direction the line object runs.

## Example:  Editing an Existing Traverse

We can edit existing objects by editing the traverse commands that define them.   The following example shows how to edit traverse commands, and also illustrates that editing a traverse command will affect the position of segments drawn by all following traverse commands.

To pick an object for editing, we Alt-click the object.   That picks the object for editing in the map window (redrawing it in blue provisional color with editing handles), and opens the object in the Info pane.

We click on the Coordinates tab to see the coordinates list for the object.  Choosing the Coordinates tab shows a larger edit handle square for the current vertex or segment.

We choose Show Traverse in the coordinate mode button if the Coordinates tab is not already showing traverse commands (it remembers the last used list style, either XYZ coordinates or traverses).

Double-click onto the second row in the list to open that traverse command for editing.   That command draws the first segment of the square line by specifying a direction of 90 degrees and a distance of 5 units.

As soon as we click or double-click on a traverse command row, the segment for that command will be indicated by the large square editing handle at the end of the segment.   That large square editing handle shows the position that is reached by that traverse command.

When we open a traverse command by double-clicking it, we open the cell for editing just like editing any text in any text cell.   We can change the 5 in the command to a 4, meaning to go only four units in the 90 degree direction.

Press Enter to apply the edit to that row.

The proposed change is shown in blue provisional color in the map.   Shortening the first segment in the traverse will reposition all subsequent segments.

To apply the edit to the traverse, press Update Record.

If we would like the traverse to close, that is, to finish where it began, we will have to shorten the third segment in the square.   To do that, we double-click into the traverse command row for the third segment, and we change the 5 distance in that command to 4.   As soon as we click or double-click into the traverse command for the third segment, the big editing handle will jump to the end of that segment, to show which segment we are editing.

When we press Enter to alter the traverse command, the provisional display in the map will update to show how the traverse will look with that change.  The third segment will become shorter, which will alter the position of the fourth and final segment.   It will not change the positions of the first or second segments.

Press Update Record to apply the change to the traverse.

If we alt-click outside the object or otherwise edit picked mode, we see how the traverse has been altered.   The first and third segments have been shortened, from a distance of 5 units to a distance of 4 units.  That converts the square shape drawn by the line into a vertical rectangle shape.

When we edit traverses, we can switch between any of the coordinate and command display modes.   For example, we can switch to showing XYZ coordinates in the list and edit those, we can switch back to showing traverses and edit those, we can switch between using DD or AD style traverse commands, and so on.

## Example: Editing a Line Compared to Editing an Area

Editing lines using traverse commands has one key difference compared to editing areas using traverse commands:  areas are always closed objects, in that the final vertex of an area boundary always falls exactly on the first vertex of the boundary.    If we edit any of the line segments that make up an area boundary, the final segment of the boundary will automatically adjust the bearing and length of that segment to close the boundary.

In contrast, when editing any of the line segments that make up a line, the final segment will remain unchanged.   We can see how that works by first considering an example using a line, and then taking a look at an example that makes the same edit on a similar area.

Consider the line shown above.  The last segment of the line ends exactly on the beginning of the first line segment.   We Alt-click the line to pick it.

When we pick the line with an Alt-click it shows the vertices and line segments that make up the line, and the Info pane automatically launches and comes to the foreground if it is not already open and in the foreground.

In the Coordinates tab we use the coordinates list format picker button to switch to showing traverse commands, and then we double-click the second row to edit that traverse command.  That traverse command says to draw a line segment in the 90 degree direction for a distance of 5 units.

We will change the distance to 6 units.

The change makes the entire table appear in provisional blue color, since the change has not yet been committed.

In the drawing we can see the proposed change.   We press Update Record in the Info pane to commit the change.

Extending the first segment by an additional unit changes the length of that segment, but the traverse commands for all the other segments are unchanged, so they all end up simply shifting one unit as well.

We will now take a look at how the same edit works with an area object.

We start with an area object that has been drawn by using snap to click exactly on the vertices of the line object that we used in the prior example.

We Alt-click the area to pick it.

When we pick the area with an Alt-click it shows the vertices and line segments that make up the area.

In the Coordinates tab we use the coordinates list format picker button to switch to showing traverse commands, and then we double-click the second row to edit that traverse command.  That traverse command says to draw a line segment in the 90 degree direction for a distance of 5 units.   We will change the distance to 6 units.

Note that all of the traverse commands are exactly the same as with the line, since the area boundary was created by clicking exactly on the same vertices of the line used in the prior example, so the segments of the area boundary are exactly the same as the segments of the line.

The change makes the entire table appear in provisional blue color, since the change has not yet been committed.

In the drawing we can see the proposed change.   Note that the second and third segments which make up the area boundary have been shifted, but that the final segment that makes up the area boundary has automatically changed to close the area.

We press Update Record in the Info pane to commit the change.

The result is a closed area, where the final segment has automatically adjusted to close the area boundary.

## Close Gap

When loading traverses from files or entering a series of traverse commands from a surveying description we may discover that the end of a traverse line does not coincide exactly with the starting point.   If the traverse line is supposed to be the boundary of a parcel, that obviously indicates some error in the compilation of traverse commands, since the boundary of a parcel must end precisely where it started.

For example, consider the traverse created in the Example: Create Parcels from Traverse Files topic:

Zooming in to the starting point at the Northwest corner, we see that the final segment does not end precisely on the starting point:

The traverse commands, therefore, are in error, since the traverse is supposed to represent the closed boundary of a parcel, with no undershoots, overshoots, or gaps between the final segment and the initial segment.    The key question in such cases is what error or errors have caused the problem.   Is the problem caused by errors of direction and/or distance in the traverse command for final segment only, with all other segments having exactly correct traverse commands?   Is the problem caused by errors in traverse commands for other segments?

A simple way to close the traverse is to pick the line for editing, and then, with snap turned on, to move the final coordinate for the final segment directly onto the coordinate for the starting point.   That will adjust the traverse command for the final segment only, basically acting on a belief that the commands for all other segments are precisely accurate.

The reality in real life surveying, however, is that when traverses do not close the error usually is not just in the final segment, but is either in some other segment or, more frequently, the result of slight inaccuracies measuring angles and distances for all the segments, and thus more or less evenly distributed throughout all the traverse commands for all segments.    A useful approach used in practical surveying is to adjust all segments slightly in an evenly distributed way, so the result of all the slight adjustments is to close the traverse, with the end of the final segment coinciding precisely with the starting point.

There are many possible algorithms that can be (and have been) used to "evenly" distribute changes between all segments of a traverse to close the traverse.   One of the most popular and widely used algorithms is called the compass rule, and is also known as the Bowditch rule.  See the discussion on this web page.  The compass rule is implemented automatically in Manifold's End Current Branch + Close Gap editing command, which is available when editing an object in insert mode.

For example, suppose we would like to close the traverse shown in the Example: Create Parcels from Traverse Files topic.

We alt-click the line and put it into editing mode to extend the last branch, which is insert coordinates mode.   With the mouse cursor anywhere in the map, we right-click to call up the editing context menu.

Choose End Current Branch + Close Gap in the menu.

Instantly, the segments in the traverse are moved so the end coordinate of the final segment precisely coincides with the starting point of the first segment.     The slight green stub in the illustration above shows how the end segment before adjustment overshot the starting point.

Zooming out, we can see how the new line is visibly slightly different from the original traverse in various segments, but using the same starting point as the original starting point.   If we zoomed in, we would see the adjustments are evenly distributed through all of the segments.

For a detailed, step by step example using the End Current Branch + Close Gap command, see the Example: Create Parcels from Traverse Files topic.

## Saving and Reading Coordinate Lists to and from Files

We can create lines or areas using traverse format either by clicking interactively in a map window and editing traverse commands interactively, or by reading saved geometry from a file.

The Info pane can read from a file or save to a file a coordinates list in either Manifold Coordinates format or Esri Traverse format.  Whichever format is displayed when we press the Save button will be the format used for the text file that is created.   Manifold Coordinates format saves coordinates as X Y numbers, adding a third Z number if the object has a Z value.   Esri Traverse format saves coordinate geometry in standard Esri traverse file format.

• When reading coordinate lists from text files, case is not important and additional whitespace, apart from line ends, is not important. Line ends can be CRLF, LF, or CR.  The system validates all data after loading a coordinate list from a file and removes invalid curves or branches.  Text encoding is detected automatically.   Supported encodings are ANSI, UTF8, UTF16 BE, and UTF16 LE.  The file can contain empty lines, which will be ignored. The file can contain comment lines with comments starting with #.  Comment lines are also ignored.
• When saving coordinates lists to a text file, Manifold keeps things simple, using single spaces, uppercase letters and no comments.

## Manifold Coordinates Format

Manifold coordinates format closely matches what is displayed in the list and preserves all data.

The first line contains a single character specifying the type of object: P for point, L for line, or A for area.  Lines following the first line contain coordinates, with each line beginning with a C, CC, CE, CS, or E code indicating the nature of the coordinate:

 The first line:  a single character specifying the type of object: P for point, L for line, or A for area. C [] A coordinate. CC [] A circle arc coordinate. CE [] An ellipse arc coordinate. CS [] A spline coordinate. E [] A coordinate that ends a branch.

Coordinate values are separated by one or more whitespace characters.

Example: A text file saving coordinates for an area with four vertices might contain:

A

C 826590.1661996043 5425098.995517982

C 826608.2333529602 5425149.516990494

C 826635.595683797 5425139.733152165

C 826630.820077642 5425126.359355299

C 826617.5285304413 5425089.211733231

E 826590.1661996043 5425098.995517982

The area above has no Z value, so just X Y coordinates are listed.

## Esri Traverse Format

Esri traverse format preserves X Y values, but not Z,  and preserves circle arcs, but not ellipse arcs or spline arcs.  For details, see the Esri Traverse file format page.

The first two line specifies the format for direction type, which can be QB for Quadrant Bearing, NA for North Azimuth, SA for South Azimuth, or P for Polar.   Useful Esri illustrations of direction type are at the Esri Direction Formats page for ArcGIS Pro.  The second line specifies direction units, which can be decimal degrees, degrees-minutes-seconds, radians, or gradians.  Lines following the first two lines contain coordinates, with each line beginning with an S, EP, DD, AD, TC, or NC code indicating the nature of the coordinate:

 SP Starting coordinate.  Abbreviation for Starting Point. EP Ending coordinate.  Abbreviation for End Point. DD Coordinate in the specified direction and distance. Abbreviation for Direction + Distance. AD Coordinate in the specified direction relative to the direction of the immediately preceding straight line segment.  Abbreviation for Angle + Distance. TC Circle arc tangent to the current direction. The arc parameters are any pair of:  central angle, arc length, chord length, or radius, plus whether the arc turns left or right.  Abbreviation for Tangent Circle. NC Circle arc not necessarily tangent to the current direction. The arc parameters are those for a tangent arc plus one extra direction that can be: tangent, radial, or chord.  Abbreviation for Non-tangent Circle.

Example: A text file saving a traverse for an area with four vertices might contain:

DT NA

DU DD

SP 826590.1661996043 5425098.995517982

EP 826590.1661996043 5425098.995517982

DD 19.67772861193131 53.654834033368054

DD 109.67532131261366 29.058916725681254

DD 199.65097484711967 14.200875211356259

DD 199.687384449253 39.453910481159284

DD 289.67522183971334 29.05889868676386

Circle arc parameters come in two forms: tangent circle arcs, TC, and non-tangent circle arcs, NC.

Tangent Circle Arcs (TC) - A tangent circle arc specification begins with TC and then includes two token specifications that define the circle arc, where each token specification is a D, A, C, or R followed by a value.  A tangent circle arc specification ends with an L or an R, to indicate a left-turning or right-turning arc.  See the illustrated guide to tangent and non-tangent circle arcs, along with the summary below:

D <angle> - Angle subtended by the arc.

A <distance> - Length of the arc.

C <distance> - Length of the chord across the arc.

R <distance> - The radius of the circle from which the arc is taken.

Example:

TC D 47.117 R 167.288 L

Defines a tangent circle arc where the angle subtended by the arc is 47.117 degrees and the radius of the circle is 167.288 units.  The arc is a left-turning arc.

Non-tangent Circle Arcs (NC) - A non-tangent circle arc specification begins with NC and then includes two token specifications that define the circle arc, where each token specification is a D, A, C, or R followed by a value.

D <angle> - Angle subtended by the arc.

A <distance> - Length of the arc.

C <distance> - Length of the chord across the arc.

R <distance> - The radius of the circle from which the arc is taken.

The first two values are followed by a single token specification that specifies the orientation, using a single token that is C, R, or T followed by a value.

C <direction> - Chord direction.

R <direction> - Radial direction, to the center of the circle.

T <direction> - Tangent direction, bearing of a line tangent to the start of the arc.

A non-tangent circle arc specification ends with an L or an R, to indicate a left-turning or right-turning arc.

Example:

NC D 154.366 R 57.431 T 180.683 L

Defines a non-tangent circle arc where the angle subtended by the arc is 154.366 degrees and the radius of the circle is 57.431 units.  The arc is oriented by a tangent line with a directional bearing of 180.683.  The arc is a left-turning arc.

After loading a coordinate list from an Esri traverse format file, the system remembers the format used for direction type and direction units as well as the format used for each coordinate, and retains those settings during editing.   Future builds may provide user interfaces to allow changing the format for direction type and direction units, and may also provide a command for closing a branch by distributing any closing error between branch coordinates.

See an example of loading an Esri traverse file in the Example: Create Parcels from Traverse Files topic.

## Esri Format Display Options

Manifold can show segment/coordinates positions using standard Esri variations in Esri display formats.   Esri traverse segments, also called courses, can be straight line segments, or they can be circle arc segments.

## Straight Line Segments

Esri traverse segments can be straight line segments, using DD (direction distance) or AD (angle distance) parameters, as allowed by Esri Traverse file format standard.  We can set the display option for a straight line segment in a particular row in the Coordinates list to use a desired Esri parameter style.  That can make it much easier to compare values in the display list with those in a traverse file that use a particular Esri parameter style.   To change the parameter style for a given row, right-click the row and choose the desired display parameter style.     If a row is selected, changing the display parameter style for that row will also change it to the same style for all selected rows.

Right-clicking on the third row and choosing Angle + Distance will switch the display of that row from DD (Direction + Distance) to AD (Angle + Distance) style.

The third row in the Coordinates list gives the position of the third coordinate of the object, using traverse format.  The first row gives the location of the first coordinate, called the starting point, SP, in Esri nomenclature.  The second row gives the location of the second coordinate of the object, which is the end of the first line segment.  In Esri traverse format, the location of the second coordinate is given using a direction and distance from the first coordinate, that is, the angular direction of the line segment and the length of that line segment.   We can read from the Coordinates table that the angular direction is (rounding) 53.3 degrees, with a distance of 24.6 units.   We will ignore the distance since the distance parameter is the same in both DD and AD format - only the way the angular direction is specified is different.

The third coordinate is the end of the second line segment.  In DD format, the location of the third coordinate is at direction of 54.8 degrees and a distance of 25.9 units.   When we switch to AD, Angle + Distance, style, the angle is reported in the Coordinates list as 1.5 degrees.  That is an angular direction relative to the prior segment.  That makes sense, because travelling in the 54.8 degree direction is continuing in the same direction as the prior segment, 53.3 degrees,  plus 1.5 degrees, that is, a slight nudge in the clockwise direction.

In the example above, we changed a single row from DD to AD format.  If we select all rows, we can change all rows for segments other than the first from DD to AD format.

When we right-click a selected row to change format, the change applies to all selected records.   In the illustrations above, we have pressed Ctrl-A to select all rows, and then we right-clicked on the fifth row to choose Angle + Distance.   All selected rows that use Direction + Distance  (DD) style are immediately changed to AD style.

The first row is a starting point, the coordinate of which is designed in absolute coordinate numbers, and cannot be changed.  The second row cannot be changed from DD mode, since AD mode specifies direction based on the prior segment, but the very first segment has no prior segment based on which a relative change in direction can be specified.   AD mode can only be used with the third or later row.

Note that the Manifold list uses only positive numbers for a relative direction change: instead of quoting a negative number, -2.8, for the directional change from the third row to the fourth row, the Coordinates list uses the equivalent positive number, a relative directional change of 357.2.    That works because 360 - 2.8 = 357.2.   Manifold uses positive numbers only to avoid confusing formatting when direction types like degrees-minutes-seconds are used.  Esri traverse files allow use of positive or negative numbers: if desired, future builds may introduce an option to use negative numbers in AD displays in the Coordinates list as well should the community prefer those.

## Circle Arc Segments

Esri traverse segments can be circle arc segments, also called courses, using TC (tangent circle arc) or NC (possibly non-tangent circle arc) parameters, as allowed by Esri Traverse file format standard.   As with straight line segments, we can set the display option for a circle segment in a particular row in the Coordinates list to use a desired Esri parameter style.  That can make it much easier to compare values in the display list with those in a traverse file that use a particular Esri parameter style.   To change the parameter style for a given row, right-click the row and choose the desired display parameter style.     If a row is selected, changing the display parameter style for that row will also change it to the same style for all selected rows.

Esri allows various different ways of specifying circular arc segments in a traverse.  Esri's allowed methods can seem complex, since they define a circular arc by giving distances, angles or bearings that mathematically imply what the arc must be.   Esri takes two approaches: in the case of circular arcs which can be said to continue from the bearing of a previous straight line segment, those are called tangent circle arcs, and the definition is slightly simpler since the bearing of the previous segment provides an important hint to what the arc must be.  In cases of circle arc segments which do not start by continuing the same bearing as the prior straight line segment, the circle arc is said to be non-tangent and the definition requires an extra step of defining a starting direction, which can be specified in any of three different ways, to provide the extra hint that tangent circle arcs can get automatically from the prior segment.

If this sounds complex and non-intuitive, we are well on the way to grasping the process, because it is indeed complex and non-intuitive.  That is not Esri's fault, as there are historical reasons why circle arcs have been defined in such ways in metes and bounds / COGO surveying definitions.

Consider a portion of a traverse, as seen below in a map.  The traverse comes into view at left with a straight line segment, which is followed by a circle arc segment, which is followed by a straight line segment that continues out of view at the bottom of the window.   The traverse has been alt-clicked to pick it, and then the coordinate at the end of the circular segment has been clicked to launch the traverse into Move Coordinates editing mode, which also opens the Coordinates tab of the Info pane, loaded with the coordinates of the traverse.

We have clicked the coordinate list format picker button, choosing Show traverse,  to display the geometric definition of the traverse in Esri format.   The coordinates list cursor (dotted outline box) is on the row for the coordinate at the end of the circle arc, the coordinate that we clicked.  We can see the circular arc is defined as a non-tangent circular arc using an NC code.

The full entry for that circular arc is:

NC D 154.36583333394242 R 57.43099347890822 T 180.68291666680415 L

Rounding a bit, we can decode the above to understand the above defines a non-tangent circle arc where the angle subtended by the arc is 154.366 degrees and the radius of the circle is 57.431 units.  The arc is oriented by a tangent line with a directional bearing of 180.683, meaning the arc starts off heading almost due South.   The arc is a left-turning arc, that is, left-turning relative to the starting direction.  If we stand at the beginning of the arc, looking South, we see the arc turns to the left.   See notes above, the illustrated guide to tangent and non-tangent circle arcs, and the  Esri Traverse file format page for the parameters used.

We can right-click that row for a context menu of different choices of display parameter styles allowed by Esri for non-tangent circle arcs.  We can choose one of the options above the dividing line and a second option below the dividing line.   The two correspond to the two different classes of choices for specifying non-tangent circle arcs in Esri traverses.    To understand the different choices, we should consider how tangent and non-tangent circle arcs may be defined.

## Automatic Replacement of Ellipse and Spline Arcs

Traverses use Esri traverse commands in the Coordinates tab, which means that new objects created with traverse commands can only consist of circle arcs in addition to straight line segments, since there are no Esri traverse commands to create ellipse arc or spline arc segments.   A similar restriction applies when we edit existing objects using traverse commands.

In addition to circle arcs and straight line segments, line and area objects in Manifold can also contain ellipse arcs and spline arcs.  If we make any changes to an existing object using Show Traverse mode in the Coordinates tab, ellipse arc and spline arc segments will be replaced by a straight line segment from the starting vertex to the end vertex of the arc segment, while straight line segments and circle arc segments will be retained.  That ensures that the resulting set of traverse commands conforms to the requirements of Esri traverse format.

## An Illustrated Guide to Tangent and Non-tangent Circle Arcs

We will illustrate how tangent and non-tangent circle arcs work with two examples, first looking at a traverse that ends in a tangent circle arc, and then looking at a traverse that ends in a non-tangent circle arc.    The actual circle arcs at the end of both traverses are the same:  what makes one tangent and the other non-tangent is the straight line segment that comes immediately before the circle arc segment.

Consider a line that shows a path we have walked in the Tuileries Garden in Paris, between the Place de la Concorde and the Louvre.

The path starts at the upper left, at one side of a large, circular pond with a fountain in the center.   We walk on four straight line segments and then we walk on a circular arc segment to the end, on the other side of the pond.    The illustration above adds blue square icons at the locations of coordinates between segments.  We use a Google satellite layer as a background.

For more legible display, we set the Google layer to 30% opacity in the Layers pane, so it is less visually intrusive.   In the illustration we have colored the circular arc segment blue.

Zooming into the region of the circular arc segment, we can see four parameters that can be used to define the circular arc segment: the length of the chord, the length of the radius, the length of the arc, and the angle between the radius line and the perpendicular to the end of circular arc.   Specifying any two of these parameters, plus saying whether the arc bends to the right or to the left, is enough to exactly and unambiguously define the circular arc.

D <angle> - Angle subtended by the arc.

A <distance> - Length of the arc.

C <distance> - Length of the chord across the arc.

R <distance> - The radius of the circle from which the arc is taken.

Comparing the different parameters, any two of which are required, to the choices in the dropdown menu, and to the token codes in the list above, we can see that the choices in the upper part of the menu provide a choice of the different combinations allowed by Esri token codes (choices in the lower part of the menu are used for non-tangent circle arcs).

For example, we can choose a specification that gives the length of the Chord and the length of the Radius, or we can choose a specification that gives the Angle and the length of the Chord.   Manifold automatically recomputes the values to display in the Coordinates list for whatever style we want to use.

The illustration above shows why the circular arc segment in this case is called a tangent circular arc segment: the beginning of the circular arc is a smooth continuation from the bearing of the preceding straight line segment.  If the preceding line segment was extended (shown in green with no dashes) through the Radius line, and if the circular arc was extended (shown in blue with no dashes) to form a complete circle, the circle and line would be tangent to each other.

The tangency of the circle and preceding line segment is lost if the left arc is used in the construction.  However, using the left arc shows why the Radius length is called that, since it is the length of the radius of the circle from which the circular arc is taken.  Likewise, the illustration above shows why given the Angle and any one of the three lengths (Arc, Chord, or Radius) defines the circular arc.

We can take any two of the parameters (Arc Length, Chord Length, Radius Length, Angle) and specify using the Left-turning arc and the circular arc is unambiguously, exactly, defined.  Any combination of two parameters can be used either in the traverse file, or used by Manifold in the Coordinates list to display the parameters which define the tangent circular arc.

Non-tangent circle arcs initially do not proceed in the same direction as the preceding segment.  A non-tangent circle arc is shown in the illustration below.

Non-tangent circle arcs do not have the benefit of starting with an initial hint, the tangent direction, to provide needed orientation.  Non-tangent arcs therefore require one extra parameter, the specification of orientation, that tangent circle arcs do not require.

To better show the circle arc, we have colored it in blue and black color above, with straight line segments styled in green and blue.  We have made the background layer partially transparent, so more of the white background shows through, to reduce the visual effect of the background.

Specifying a non-tangent circle arc begins the same way as specifying a tangent circle arc, by specifying any two of four parameters:  the length of the chord, the length of the radius, the length of the arc, and the angle between the radius line and the perpendicular to the end of circular arc.   Specifying any two of these parameters, plus specifying one of the three possible orientation parameters, plus saying whether the arc bends to the right or to the left, is enough to exactly and unambiguously define the circular arc.

D <angle> - Angle subtended by the arc.

A <distance> - Length of the arc.

C <distance> - Length of the chord across the arc.

R <distance> - The radius of the circle from which the arc is taken.

As with a tangent circle arc, we can see that the choices in the upper part of the menu provide a choice of the different combinations allowed by Esri token codes.   For example, we can choose a specification that gives the length of the Chord and the length of the Radius, or we can choose a specification that gives the Angle and the length of the Chord.

The illustration above shows why the circular arc segment in this case is called a non-tangent circular arc segment: the beginning of the circular arc is not  a smooth continuation from the bearing of the preceding straight line segment.  If the preceding line segment was extended (shown in green with no dashes), and if the circular arc was extended (shown in blue with no dashes) to form a complete circle, the circle and line would not be tangent to each other.

Because the system cannot use the tangent direction of the previous segment as the implied orientation, we must add an orientation token, one of C, R, or T followed by a direction value, that gives the orientation.

Choices in the lower part of the context menu correspond to the three orientation options allowed by Esri token codes:

C <direction> - Chord direction.

R <direction> - Radial direction, to the center of the circle.

T <direction> - Tangent direction, bearing of a line tangent to the start of the arc.

Note from the illustrations above and below that because the circle arc is not tangent to the last line segment, the tangent direction for the circle arc is not the same direction as a continuation of the last straight line segment of the traverse.   We have to specify it manually, or we can specify one of the other two directions, chord direction or radial direction, to specify the orientation of the non-tangent circle arc.

The final step in specifying a non-tangent circle arc is to specify whether the arc is left-turning or right-turning:

In this case, we specify a Left-turning circle arc.

## Notes

AD tokens cannot come first - When defining straight line segments in a traverse, an AD (angle + distance) token specification cannot be used for the first segment, and it cannot come immediately a circle arc definition.   An AD token specifies a straight line segment in a direction relative to the direction of the immediately preceding straight line segment.  If there is no immediately preceding straight line segment, there is no basis for knowing the relative direction given in an AD token.  A DD (direction + distance) token, in contrast, uses an absolute direction that does not depend on the direction of a preceding straight line segment.  DD tokens can therefore be the first line segment token in a traverse and can also be the first line segment token following a circular arc segment.

Tangent circle arcs cannot come first - A tangent circle arc using a TC code can be used as a definition only if it is preceded by a straight line segment.   It cannot be the first segment in a traverse and it cannot come immediately after another circle arc segment.  If a straight line segment does not immediately precede the circle arc segment, there is no direction that can be taken from a preceding straight line segment to provide a tangent direction.  We can always use the equivalent NC definition, adding a tangent direction parameter, to define a circle arc segment which is not preceded by a straight line segment.

Why do the context menus always have two parts?  Why do non-tangent circle specification options always appear in the context menu, even if the circle arc is a tangent circle arc?   The choices appear because we can define a tangent circle arc using non-tangent definition if we want.

A tangent circle arc can take the tangent direction from the previous segment.   If we use that same direction for the Tangent Direction (the last choice in the context menu) in an NC (non-tangent circle arc) definition, we get an equivalent definition to the TC (tangent circle arc) definition where that tangent direction is implied.

If we right-click a TC (tangent) row in the Coordinates list and choose Chord Direction or Radial Direction from the context menu, the row automatically will be converted to an NC (non-tangent) token.  Conversely, if we right-click an NC (non-tangent) row in the Coordinates list and choose Tangent Direction from the context menu, the row automatically will be converted to a TC (tangent) token if there is a preceding straight line segment and the difference between the tangent of that preceding segment and the starting tangent of the arc is sufficiently small.

Why are traverses used?  GIS users outside of the US are often puzzled by what seems to be an inefficient way of describing geometry that is used in traverses in the US.    Given that very slight errors in angles and distances over a complicated sequence of segments described in a traverse can cause the traverse not to close, that is, the line does not end up where it started and thus the line does not describe an accurate area boundary, it seems like asking for trouble to use traverses to define real estate parcels, their primary use in the US.

As with many legacy formats, there are good, sensible, historical reasons why traverses are used to define parcels in the US.   The primary reason is that while it was not so easy in historical times for a surveyor in a field to measure the exact latitude and longitude location of each vertex that defines a parcel (let alone to decompose a curved portion of a parcel into many such vertices), it has been relatively straightforward for hundreds of years to measure simple angles and distances.   Starting with a marker at a known, recorded position, a surveyor with good accuracy could jot down the bearing direction of a boundary line, and measure with good accuracy how far that boundary line ran to the next turn.  What seems to be a non-intuitive way of describing a circular arc segment, in terms of chord lengths, angles, and so on, in the field can be measured accurately and reliably using simple instruments.

In modern times it may be impractical to record a path walked or a linear feature by noting the latitude and longitude of each coordinate that marks the path, but it may be possible to record the compass direction and distance travelled.   Entering such notes into a traverse file using whichever Esri notation is most convenient makes it possible to import such linear features into Manifold as a line.

A new use for traverses is as a convenient editing mode for drawing vector shapes.  It's often easier to specify the direction and distance of a line than it is to click on a grid or to draw an object freehand.

## Videos

First Look - Edit Traverses  - Manifold has the rare ability to edit traverses on the fly, either when interactively creating a new traverse, or to edit existing traverses imported from parcel or other traverse descriptions. The video shows how easy it is to edit traverses in Release 9, including how with one click you can automatically adjust a traverse so it closes precisely, using the mathematically sophisticated "compass rule" to automatically adjust angles and distances throughout the traverse.