Using the Points Reformatter

9.2 Using the Points Reformatter

To run the Points Reformatter utility, choose Tools>Points Reformatter:

The Reformatter creates a new coordinate file using a format style selected by you. The coordinate values come from the “ProjectName.sbf” binary file created during your last adjustment. You may wish, for example, to create a coordinate file compatible with your COGO program, or your client’s COGO program. Or you may want to rearrange items, such as switch North and East values, or maybe eliminate items, such as outputting a list of point names with elevations and descriptors only.

To run the utility, follow these steps:

1. Select a format from the “Format Style” dropdown selection box. A sample of the output style will appear in the “Example of Formatted Output” box. In the example shown on the previous page, the “Comma Separated” format was selected. Note that

a few format styles are provide with the program, and others may be defined by you as described later in this section.

2. The output file created will be given your project name with a “REF” extension (for example, SouthPark.ref). The name is shown in the “Output to File” field. To use a different name, press the “Change” button and enter a different name.

3. If you need to change any options (as described below), change to the Options tab, make the changes, then return to the Reformat tab.

4. Press the “Reformat” button to perform the actual reformatting.

5. Finally, to review the contents of the output file, go to the “Output File” tab. To change reformatting options, go to the “Options” dialog tab:

In the Options dialog, select whether to export main network stations, sideshot stations, or both. You can also choose to have one or the other, or both sorted by names. If you sort both groups, then you can also choose to have the two coordinate lists merged.

By default, the Points Reformatter utility creates an export file with a “REF” extension (meaning reformatted). However you can change this default extension in the options if you wish. Press the “Change” button and enter a new extension. Note that you are restricted from using certain extensions reserved by the program.

Any options set during a reformatting session are saved and will be used as defaults for the next reformatting run in any project.

Defining Format Styles

A file named “STAR6.FMT” is located in the STAR*NET install directory. It contains several built-in format styles which are used by the Reformatter utility, and also for output formats selected in the Project Options/Other Files dialog. The file can be edited with any text editor, or it can also be edited within the Reformatter utility be pressing the “Edit Format Style File” button. Therefore if you know the basic elements of this definition file, you can then edit it to change any of the current formatting styles, or add new formatting styles of your own.

The “STAR6.FMT” file can have any number of definition lines. Each line has three major parts: the format style title, the 1D/2D/3D indicator, and the formatting definition. Each section is separated from the next by a colon character.

1. The title includes all the text to the left of the first “:” character and is limited to 22 characters. The title for each line is the text that appears in the selection list.

2. A “1D” or “2D” or “3D” code follows the first “:” character. It indicates whether the format will be selectable for a 1D (Lev), 2D or 3D project. If no indicator is entered, the format style can be selected from the dialog dropdown list for any type project.

3. The portion of the line to the right of the second “:” character is the formatting definition. It contains a combination of special characters that tell the Reformatter utility how to format the new coordinate file. Below are a few simple format style lines which illustrate style titles, 1D/2D/3D indicators and format definitions.

Comma Separated :1d :p,z,d Comma Separated :2d :p,n,e,d Comma Separated :3d :p,n,e,z,d

Space Separated :2d :p n e d Space Separated :3d :p n e z d

Name & Descriptor : :p d

There are three named styles defined in the example above. The first style has separate formats for 1D, 2D and 3D projects and the second, for only 2D and 3D projects. The last named style has no 1D/2D/3D indicator entered, and therefore that format will appear and can be selected from the “Format Style” dropdown for all types of projects.

When entering 1D, 2D and 3D formats for a single style, be sure to spell the style names for each format exactly the same or they will be interpreted as separate styles!

Spaces following a style name are ignored as well as any spaces before and after the 1D/2D/3D indicator. This allows you to “line” up the formats to make them more readable in the STAR6.FMT file as illustrated above. Spaces following the second “:” character are not ignored, however. They are considered part of the format definition and will cause spaces to be published in the formatted output.

As discussed above, the portion of each line to the right of the second “:” is the formatting definition and is made up of a combination of special characters that instructs STAR*NET how to format the new points. Only certain characters may be used in this formatting definition. Each character has a special purpose. A list of all formatting characters and the purpose of each is listed in the table below.

This:

Causes this action:

P or R Point Name is written (left or right justified in a field when a field width is entered, i.e. P15 for left justified).

N Northing is written.

E Easting is written.

H When project options coordinate order is set to “NE”, the first occurrence of an “H” writes a Northing, the second writes an Easting. The order is switched when the option is “EN”.

Z Elevation is written.

D Descriptor is written. Comma

A comma is written.

Space

A space is written.

Single Quote

A single quote character (') is written.

Double Quote

A double quote character (") is written.

Brackets [ ] Text between the [ and the ] is written. Slash ( / )

A new line (carriage return) is written.

Reformatting Characters

These formatting characters may be entered as upper or lower case, and of course in any order - the order you wish your data items to appear in the reformatted points file. If any characters other than those in the list above are entered (except for the text entered between the special square bracket characters), an error message “Invalid Definition Style” will be shown when the reformatter routine is used, and you will have to make a correction to the STAR6.FMT file before the routine will work.

Every formatted line written to the output file is automatically ended with a new line (carriage return). However with the special “/” slash character available as shown in the list above, you can cause new lines to be inserted anywhere. Perhaps you would like one or more items on a separate line. Simply use the slash rather than a space or comma separator, and a carriage return will be inserted.

By default, the precisions used (number of places beyond the decimal) for coordinates and elevations are controlled by the “Default Precisions” settings existing in the Project Options/Other Files dialog when the adjustment was last run. However, you can define a different precision if you wish. To specify two places beyond the decimal for a northing definition for example, “N0.2” would be entered rather than just an “N” definition. Or perhaps you want elevations rounded to the nearest foot or meter written to your converted file. Just enter is “Z0.0” rather than the normal “Z” definition. The example illustrates defining coordinates exported to two places and elevations to one place.

p n0.2 e0.2 z0.1

If you want your output items formatted in columns rather than separated by only a space or comma, do this by appending a “field width” to each definition character. For example, if you want your point names, northings, eastings and elevations lined up in column widths of 10, 15, 15 and 9 spaces respectively, and using default precisions, you would enter either of the following format definitions:

p10n15e15z9

(using the actual column width value)

p10 n14 e14 z8

(or a space plus the remaining width)

You can use this field width value with the P (or R), N, E, H and Z definition codes. When you use a field width with the “P” point name code, the name string will be left justified in the field width. When you use a field width with the alternate “R” point name code, the name string will be right justified in the field. Northings, eastings and elevations, when defined with a field width value, are always right justified.

When using field width values for northings, eastings and elevations as shown above, the decimal precision is controlled by the “Default Precisions” settings existing in the Project Options/Other Files dialog when the adjustment was last run. However, as previously described, you can also enter explicit precisions. Simply attach the desired precision to the field width. If we want a 3 place precision for northings and eastings, and 1 place for elevations, the example lines above would look like this:

p10n15.3e15.3z9.1

(using actual column width value)

p10 n14.3 e14.3 z8.1 (or a space plus remaining width value)

It is recommended that you actually use a space separation between defined column widths as shown in the last line above. First, the definition is much easier to read. But more importantly, if for one reason or another a coordinate value is large enough to fill the entire field width, the space in the format definition is guaranteed to create a space in the output rather than allowing the output values to run together.

A few words should be said about the “H” field definition code used to output horizontal coordinate values. Using this code rather than the “N” and “E” codes guarantees that the same output order specified in your Project Options will also be used for exporting coordinates in the Reformatter utility. For example, if the order set in the Project Options was “EN” for the last adjustment run, the following definition would output an Easting for the first “H” and a Northing for the second “H” code.

p10 h14.3 h14.3 z9.1

The double quote character (“) and square brackets characters are particularly useful for converting to certain third-party COGO formats. Many formats require that the descriptor begin (or be surrounded by) the double quote character. Simply include the quote character in your definition exactly where you want it to be in the output. Also some formats require specific text strings to be included in the file to identify the line. Say for example that you wanted each converted output coordinate line to begin with the characters “PNT”, followed by the easting, northing, elevation, point name and the descriptor in that order. Also you would like every item separated from the next by a space, and you need the descriptor surrounded by double quotes. The entire format definition, including the format style title might look like this:

My COGO Format :3D :[PNT] e n z p "d"

A definition, of course, can also be created to export coordinates to a format that can be directly read by STAR*NET as data. Coordinates for STAR*NET always begins with the character “C” and descriptors begin with an single or double quote character.

Therefore the two format definitions below will create coordinate files for 2D and 3D projects that can be read back into STAR*NET as data. In these example definitions the “H” code has been used to output the northings and eastings in the same order used in the last run of the adjustment for a project, listed in columns and with a given precision. The first group defines “free” provisional coordinates, and the second group defines “fixed” coordinates because of the added “! ! !” fixity code text.

STAR*NET Data :2D :[C] p15 h16.5 h16.5 'd STAR*NET Data :3D :[C] p15 h16.5 h16.5 z12.3 'd

STAR*NET Fixed Data :2D :[C] p15 h16.5 h16.5 [! !] 'd STAR*NET Fixed Data :3D :[C] p15 h16.5 h16.5 z12.3 [! ! !] 'd