.

User's Manual

.

.

# Content

The program SurGe is intended for the approximation (interpolation) of points  XYZ  into nodes of a square grid. It contains a method named ABOS (Approximation Based On Smoothing). ABOS is a method for approximating (interpolating) z-coordinates of irregularly spaced points (usually measured in the terrain) by using a continuous function with two independent variables.

Description of the ABOS method

Definition of the interpolation function and notations

The interpolation function is defined by a matrix of real numbers P, which represents the surface at nodes of a square grid. The domain of the interpolation function is defined by the outer lines of the grid:

The value of the surface at any point (x0,y0) within the grid can be evaluated from the equation of the bilinear polynomial
f(x,y) = axy + bx + cy + d,
which is defined by corner points of the grid square containing the point (x0,y0).

The following notation is used in the next text:
 XYZ sequence of irregularly spaced points {Xi,Yi,Zi} i=1,...,n x1,x2 minimum and maximum of  x-coordinates of points  XYZ y1,y2 minimum and maximum of  y-coordinates of points  XYZ Zmin minimum of  z-coordinates of points  XYZ Zmax maximum of  z-coordinates of points  XYZ i1,j1 size of the grid - number of columns and rows of the matrix  P Pi,j elements of the matrix  P, i=1,...,i1 j=1,...,j1 DP auxiliary matrix with the same size as the matrix  P Z vector of z-coordinates of points  XYZ DZ auxiliary vector with the same size as the vector  Z K matrix of parameters for tensioning. It has the same size as the matrix  P Kmax maximal element of the matrix  K NB matrix of integer numbers, which has the same size as the matrix  P  and determines, for any node in the grid, the index of the nearest point  XYZ  (so called matrix of the nearest points)

The algorithm of the ABOS method can be described by the following scheme:

1. Determination of grid size, computation of the matrix NB,  Z -> DZ
2. Per partes constant interpolation of  DZ  values into the matrix  P
3. Tensioning and smoothing of the matrix  P
4. Determination of differences  Z - P -> DZ
5. If the maximal difference (maximal value of elements from the vector  DZ) does not exceed defined precision, algorithm is finished
6. P -> DP,  per partes constant interpolation of  DZ  values into the matrix  P
7. Tensioning and smoothing of the matrix  P
8. P + DP -> P
9. Continue from step 4 again (= start the next iteration step)

Particular steps of the algorithm are explained in more detail:

Step 1. As soon as the input data are read (using menu item  File / Basic file), it is possible to perform the interpolation / approximation using menu item  Interpolation / Calculate grid. The interpolation (approximation) is performed using the stand alone FORTRAN program SURGEF.EXE, which firstly suggests the size of the square grid - a value of  i1  (grid size in x-direction) and a value of  j1  (grid size in y-direction). These values can be changed by the user. However, it is recommended not to change the value of  j1. Despite the fact that the grid is referenced as a "square", in general it is not really possible to set a square grid - the grid is generally formed by rectangles. The program SURGEF.EXE calculates (according to the value of  i1) the value of  j1  so that the difference between sizes of rectangle sides is as small as possible. In the whole SurGe documentation the grid size means max{i1,j1}.
In this step, the matrix  NB  is calculated and values of the vector  Z  are copied into the vector  DZ.

Step 2. Interpolation of  DZ  values into the matrix  P  is performed such that the value  Pi,j  for every node of grid is equal to the value  DZ  of the nearest point  XYZ. Such interpolation (per partes constant, see pic. 2) is very fast.

Pic.2: Per partes constant interpolation

Step 3. Repeated tensioning (see pic.3), linear tensioning (see pic.4) and smoothing (see pic.5) of the matrix  P  improves the shape of the resulting surface, but smoothing decreases the accuracy - surface does not pass through the points  XYZ  exactly.

Pic.3: Tensioning of the matrix P

Pic.4: Linear tensioning of the matrix P

Pic.5: Smoothing of the matrix P

Tensioning  modifies the matrix  P  according to the formula:

Pi,j = (Pi+k,j + Pi,j+k + Pi-k,j + Pi,j-k)/4, k = Ki,j

only if  k > 0. Values of the matrix  k = Ki,j  are determined for each node of the grid during computation of the matrix  NB. The following scheme shows the nodes (marked by gray circles) corresponding to the elements of the matrix P, which are involved in the tensioning.

Tensioning is repeatedly performed in the loop with this pattern:
DO N = MAX(4,Kmax/2+2),1,-1

···
ENDDO

If  k  is greater than decreasing loop variable N, then k = N.

Linear tensioning  modifies the matrix  P  according to the formula:

Pi,j = (Q(Pi+u,j+v + Pi-u,j-v)+ Pi-v,j+u+ Pi+v,j-u)/(2Q+2), where

(u,v)  is the vector from the node  i,j  to the nearest grid node of point  NBi,j  and  Q = L·(Kmax-Ki,j)2. The constant L = 1/((0.107·Kmax-0.714)·Kmax) is an empirical constant suppressing the influence of Kmax . This formula is valid for default degree of linear tensioning 1. Generalized formula for other degrees is in section Degrees of linear tensioning.
The following scheme shows the nodes (marked by gray circles) corresponding to the elements of the matrix P, which are involved in the linear tensioning.

Linear tensioning is repeatedly performed in the loop with this pattern:
DO N = MAX(4,Kmax/2+2),1,-1

···
ENDDO

If the length |(u,v)| of the vector (u,v) is greater than decreasing loop variable N, then the vector (u,v) is multiplied by constant  c  so that  c ·|(u,v)| = N.

Smoothing  replaces elements of the matrix  P  by value of weighted average:

Pi,j = (å Pk,l + Pi,j(q ti,j-1))/(8 + q ti,j),
k=i-1,..,i+1, l=j-1,..,j+1,

where  q  is the user-defined parameter controlling smoothness of the interpolation (its default value is 0.5)  and  ti,j  are weights, which are zero before the first smoothing and afterwards they are computed according to the formula

ti,j = (å(Pi,j-Pk,l))2,

k=i-2...i+2, l=j-2...j+2,

and re-calculated into interval [0,100]. In brief it can be said, the values of  ti,j  are higher at nodes, where the surface has a local extreme and lower at nodes, where the surface is decreasing / increasing. The following scheme shows the nodes (marked by gray circles) corresponding to the elements of the matrix P, which are involved in the smoothing.

Smoothing is repeatedly performed in the loop with this pattern:
DO N = MAX(4,Kmax*Kmax/16)1,-1

···
ENDDO

The process of the interpolation (approximation) is affected by user specified parameters in the dialog "Interpolation / Interpolation parameters". The first one is Filter within the interval  <3,9999>  with the following meaning:
If the horizontal distance between two points [Xi,Yi,Zi] and [Xj,Yj,Zj] is greater than max{(x2-x1),(y2-y1)}/Filter, then these two points are replaced by one point [Xk,Yk,Zk] with average coordinates  Xk=(Xi+Xj)/2,  Yk=(Yi+Yj)/2  and  Zk=(Zi+Zj)/2.  If it occurs, the resulting surface will be generally approximative. Default value of filter is 500. Special value 0 means that only the points having the same x and y coordinates will be filtered. The filter pre-processes the resolution of resulting map, which is similar to the resolution of a digital picture - if the distance of two points with different colors is smaller than the pixel size of the digital picture, you can see only one point with "average" color.

Parameter Smoothness is the constant  q  mentioned in the formula for smoothing. The default value is 0.5.

The last parameter Accuracy determines maximal allowable inaccuracy (percentage value from the difference z2-z1) of the resulting surface. The default value is 1 [%].

There is a possibility to achieve a more linear interpolation between close points using linear tensioning. If such a feature is desired, select suitable value of Linear tensioning:
0 ... no linear tensioning
1 ... medium linear tensioning
2 ... strong linear tensioning
3 ... full linear tensioning

In fact, the parameter Enlargement is not a parameter affecting interpolation / approximation method. The value specifies number of grid rows and columns, which has to overlap interpolation area. By this way, the shape of  the surface near to the grid boundary is improved. The value of parameter Enlargement should be approximately set to (i1+j1)/10 (where i1 and j1 are grid sizes). If it is greater than 98, the program SURGEF estimates it internally.

Step 4. The tensioned and smoothed surface does not pass through the Z-coordinates of points  XYZ  exactly, so the differences  DZi = Zi-f(Xi,Yi), i=1...n  are calculated. The Z-value of the surface is computed at any point (x0,y0) from the bilinear polynomial equation:

f(x,y) = axy + bx + cy + d,

where  a, b, c  and  d  are defined by corner points of the grid square containing the point (x0,y0).
At the beginning of this step, the algorithm offers option (see check box "Faster convergence") to modify elements of the matrix  P  by the transformation

Pi,j = A ·Pi,j + B,

where constants  A  and  B  minimize the term

å(A ·f(Xi,Yi) + B - DZi)2.

By this way, the number of iteration steps can be reduced by 20-50%.

Step 5. If the maximal difference (maximal value of elements of the vector DZ) is less than the specified accuracy of the interpolation / approximation, the algorithm of the ABOS method is finished. In the opposite case the algorithm continues from the step 6.
The accuracy is specified as a percentage value from the difference  Zmax - Zmin.

Step 6. The matrix  P  is copied into the matrix  DP  (element by element) and the vector of differences  DZ  is interpolated into the matrix  P,  likewise as in step 2.

Step 7. The surface of differences represented by the matrix  P  is tensioned and smoothed, likewise as in step 3.

Step 8. The matrices  P  and  DP  are added element by element (sum of two smooth surfaces is a smooth surface) and the result is stored into the matrix  P. The algorithm continues from step 4.

Example of whole interpolating process can be viewed here as an animated GIF - to start the animation click on the next picture or refresh your browser (shortcut key F5 in Microsoft Internet Explorer).

.

The matrices  NB  and  K  are computed using the algorithm based on the "circulation" around the points  XYZ  as the following picture indicates:
Pic. 6: Computation of the matrices  NB  and  K

All elements of the matrices  NB  and  K  are initially set to zero and the process of circulation continues as long as there are zero values in the matrix  NB. The Euclidean distance is compared only if the element  Ki,j  corresponding to the evaluated node is not zero and  IC/SQRT(2)<= Ki,j, where  IC  is the number of the current circulation. By this way, the number of distance computations is significantly reduced.

The computation of matrix  NB  defines the natural division of the domain of the interpolation function into polygons (so called Voronoi or Thiessen polygons, see pic.7), inside which interpolation with constant values is performed.

Pic.7: Division of the domain of the interpolation function

There are four degrees of linear tensioning (0-3) implemented in the ABOS method. The formula for linear tensioning can be expressed in this generalized form:

Pi,j = (Q(Pi+u,j+v + Pi-u,j-v)+ R(Pi-v,j+u+ Pi+v,j-u))/(2Q+2R)
for all  i=1,..,i1, j=1,..,j1; Ki,j>0

where the weights Q and R, depending on the degree of linear tensioning, are calculated as follows:
 Degree Q R L 0 L(Kmax-Ki,j)2 1 0.7/((0.107Kmax-0.714)Kmax) 1 L(Kmax-Ki,j)2 1 1.0/((0.107Kmax-0.714)Kmax) 2 L(Kmax-Ki,j) 1 1.0/(0.0360625Kmax+0.192)) 3 1 0 -

Formulas for the computation of the constant L are empirical and their role is to suppress the influence of Kmax .The next figure contains a cross-section plot demonstrating the typical influence of the linear tensioning degree.

Processing speed can be increased and computer memory can be saved by transforming the interval (Zmin,Zmax) into the subinterval of INTEGER numbers (-24000,24000) (see pic. 8), which are stored in two bytes of RAM.

Pic 8: Transformation of z-coordinates into subinterval (-24000,24000)

The elements of the matrix  P  can also be of type INTEGER. Contour maps prove that the resolution of the subinterval (-24000,24000) of  INTEGER numbers is sufficient for qualitative contours.

Input files containing map objects

Coordinates and labels of points  XYZ  are assumed to be stored in the file  NAME.DTs  (s is a one-character suffix, which enables to distinguish between multiple surfaces - see below). NAME  is the basic name of the surface and must be specified along with the suffix in the initial dialog box as input information. NAME and the suffix s can be specified as arguments in the command line, for example:

`D:\>SURGE D27 A`

If there is a file  NAME.DBs  (containing additional points  XYZ) in the working directory,  points from this file will be added to the points from file  NAME.DTs. Their usage for interpolation can be switched on/off - using the dialog box  Interpolation / Objects for interpolation. File  NAME.DBs  has the same format as the file  NAME.DTs, but labels of points must begin with characters ##.

The shape of the surface can be defined not only by points XYZ, but also by spatial polylines. They can be defined in the file  NAME.LNs. Usage of the spatial polylines for interpolation can be switched on/off by the dialog box  Interpolation / Objects for interpolation.

The process of interpolation can be affected by so called faults. A fault is a sequence of line segments where a discontinuity is to be generated in the resulting surface. If there is a file  NAME.ZL  in the working directory, faults are assumed to be used during interpolation. Usage of faults for interpolation can be switched on/off by the dialog box  Interpolation / Objects for interpolation.

There is also the possibility to specify if a boundary is to be used. The boundary is assumed to be stored in the file  NAME.HR. If such file exists in the working directory, it is automatically read. If usage of the boundary is switched on (by the dialog box  Interpolation / Objects for interpolation), values of x1, x2, y1 and y2 are determined from the boundary points instead of points XYZ.

The interpolation (approximation) can be performed by the menu item  Interpolation / Calculate grid. The selection of this item causes the execution of the stand-alone program SURGEF.EXE. This program firstly estimates the minimal grid size, which can be changed by the user. The user can also change the number of smoothing iterations, which is estimated according to grid size and spatial configuration of points  XYZ. The interpolation (approximation) process is described in the Tutorial.

There is the possibility to double the grid (using the menu item  Interpolation / Double grid). Z-values of newly created grid nodes are computed by means of spline interpolation. The doubled grid provides better isolines and can be used for the creation of an extra smooth surface.

The function  Calculate isolines  in the menu  Interpolation  enables to calculate isolines and save them to the file  NAME.VRs. In the presented dialog box there is the possibility to change the first level of isolines, the last level and isolines level interval.

The function  Blank grid outside boundary  is intended for canceling values of the grid points located outside the boundary. The boundary is defined by the contents of the file  NAME.HR. To obtain isolines only inside the boundary, the function  Calculate isolines must be then performed.

The function  Substitute below  enables to substitute values of the grid nodes with a specified constant. For example, negative values of the grid nodes can be substituted with zero. A similar function has the menu item Substitute above.

Math calculation with grids enables to perform some calculations with all nodes of grids. It is assumed that the first operand is the actual surface and the second one is the previously created surface defined by the suffix. If the second operand is not defined (the suffix is empty), the second operand is assumed to be a constant (specified in the following dialog box). The result of the operation is indicated by one character with the following meaning:
 operand result ~ negation + addition - subtraction * multiplication : division m minimum M maximum a average \$ the first operand; if the second is greater than the first, then average % the second operand; if the second is greater than the first, then average w weighted average (the weights are specified in the following dialog box) d derivative computed as the size of gradient vector

The resulting surface is specified by a new suffix entered in the dialog box. After calculating the grid, new z-coordinates of  XYZ  points and polylines are computed. They can be saved using the menu item  Digitization / Save.

Data analysis runs only the first part of SURGEF.EXE to get essential information about filtering, grid sizes and expected maximal gradient. Then it displays the following dialog box:

The first and second items inform about the number of points before and after the filtration process.
If the grid size is smaller than the Minimal grid size set by filter, there is a high probability that the iteration process will not converge.
The Suggested grid size is a grid size suggested by SURGEF.EXE.
The Comment contains a verbal description of data analysis results and some suggestions.
Edit box Filter enables to change the actual setting of filter (and, for example, to run Data analysis again to observe its influence).
The Target grid size has two purposes:
1. If the Interpolation with trend surface is performed, this grid size will be used without respect to the state of Use check box.
2. If the check box Use is switched on, this grid size will be used for the interpolation / approximation and for the next Data analysis.
The items Normal, Linear, Convex and Auto in the Trend surface group box are intended only for the Interpolation with trend surface (see the next section).

Interpolation with trend surface runs SURGEF.EXE two or three times.
The first run creates the trend surface with a small grid having the following properties:

• the grid size of the small grid is between 80 and 160 or between 40 and 80 or between 20 and 40 (it depends on selection of Preservation of extrapolation trend parameter 1, 2 or 3)
• the Target grid size (see the previous section) is the 2n multiple of the small grid size.

The second (third) run reads the created grid of trend surface, doubles it n-times and then performs steps 4. - 9. of  the interpolating algorithm.
Using this procedure the trend surface is involved into the interpolation, meaning that the resulting surface keeps a proper trend in areas without points.
It is recommended to perform Data analysis before the Interpolation with trend surface and to set desired Target grid size.

In the basic display there are points XYZ (blue dots). If a boundary and/or faults and/or polylines exist, they are displayed too. The boundary is displayed as thick red lines, faults as green thin lines and polylines as thin orange dotted lines. In the move/zoom mode, the display can be moved using cursor keys and zoomed by keys PgUp or PgDn. If you only want to move/zoom basic objects, use Ctrl with these keys. Step of moving and zoom can be changed with shortcut keys "1", "2", "3", "4" or "5". Additional displays can be performed using the items in the Display menu.

The isolines can be displayed (assuming that they were calculated) using the item  Display / Isolines  or by the shortcut key I. The surface can be also represented as a color raster map using  Display / Color Map  (shortcut key C). Labels and z-coordinates of  XYZ  points can be displayed using the menu item  Display / Labels  (shortcut key N) and  Display / Z-coordinates  (shortcut key K), respectively. The menu item  Display / Color scale (Alt+S)  is intended for the color scale used in the color maps and isolines. Display / Mesh scale (Ctrl+S) enables to display a square mesh showing distances (if the mesh has to be labeled, use Ctrl+E). The designed size of the mesh can be altered by the user. The color of the base objects (points XYZ, labels, z-coordinates, boundary, faults and polylines) can be switched using  Display / Change color  (Ctrl+A) in order to achieve better visibility of these objects on the color map. Display / Refresh  (shortcut key R) is intended for restoring of the basic display. Objects of the background can be displayed using  Display / Background  (shortcut key O) menu item. Background color can be changed using  Display / B/W background  color (shortcut key Ctrl+R). If there are cross-sections saved in the file  NAME.RZY, they can be displayed using  Display / Saved cross-sections  (shortcut key Ctrl+C).

There are three items related to the gradient display. The first one,  Display / Gradient in nodes, shows gradient as short oriented line segments starting at the nodes of the grid. The second one,  Display / Gradient in isolines, shows similar line segments starting along the isolines - only if isolines have been calculated. In both cases the user can change (in the provided dialog box) the multiplier constant (default 100) specifying the length of the line segments and the frequency (default 2). For example, frequency=2 means, the gradient line segments will start in every second node. When function  Display / Gradient lines is selected, the program enters digitization mode. In this mode the cursor has the shape of a little cross and the cursor keys move the cursor (and not the map). The gradient lines (starting from the cursor position) can be displayed using the shortcut key Alt+G.

3D display

The menu item  Display / 3D view  is intended for displaying the created surface in 3D from different angles of view and different elevations. In this case the surface is firstly stored to the file  NAMEF.GRs and then is read again. Before surface reading there is a possibility of changing the step of reading node values. The default step value is 1 which means that all grid nodes will be displayed. Higher values enable to display a more sparse grid.
Cursor keys can be used for moving the 3D view around the screen, shortcut keys PgDn and PgUp are intended for zooming.
In the 3D view mode there is a special menu. The surface can be displayed without colors (3DVIEW / Display wiry surface, key S) or with colors (3DVIEW / Display color surface, key C). The horizontal angle of the view is changed by  3DVIEW / Rotate counterclockwise  (key A)  or  3DVIEW / Rotate clockwise (key Shift+A). The vertical angle can be changed by  3DVIEW / Rotate up  (key B)  or  3DVIEW / Rotate down  (key Shift+B). The items  3DVIEW / Increase z-scale (key Z) and  3DVIEW / Decrease z-scale  (key Shift+Z) are intended for increasing and decreasing the superelevation, respectively. The item  3DVIEW / Display / hide labels  (key K) switches on/off the display of point labels.
Step of angles, moving and zoom can be changed with shortcut keys "1", "2" and "3".
The horizontal and vertical angles of view can be also changed by mouse, if the left button is pressed.

Transformation of map objects

The coordinates x and y of the basic map objects (points, boundary, faults and polylines) can be transformed. Transformation functions are contained under the menu  Transformation. The first one (Move to beginning of coordinate system, key Alt+0 (zero)) moves coordinates of the basic map objects into the beginning of the coordinate system - this means that the minimal x-coordinate and the minimal y-coordinate are zeroes. The next two,  Transformation x[i]=MaxX-x[i]  (key Alt+Z) and  Transformation y[i]=MaxY-y[i]  (key Alt+Y), mirrors map objects according to the x axis or the y axis. Coordinates x and y can be interchanged using the item  Interchange x and y coordinates  (key Alt+Z). All objects can be rotated - counterclockwise using the menu item  Rotation counterclockwise  (key Alt+U) or clockwise using the menu item  Rotation clockwise  (key Ctrl+U).

Display of alternative coordinates

There is a possibility to display alternative x and y coordinates using so called georeferencing technique. If there is a file NAME.ARs (s is a suffix) or NAME.AR containing three or six pairs of corresponding points in original cartesian coordinates and in alternative coordinates (for example WGS84), the alternative coordinates of cursor are displayed in square brackets in the program bar. There is also a possibility to save basic data with the alternative coordinates in the file NAME.ACs using the menu item Output / Alternative coordinates. The following list contains an example of georeferencing file - the first two columns are x and y coordinates of points in Gauss-Kruger coordinate system, the second two columns are corresponding coordinates of WGS84 coordinate system.

3511078.77 5560593.11 15.153347261 50.176152875
3590986.91 5555350.91 16.270562075 50.122175817
3519454.31 5515257.34 15.268321319 49.768353636
3579975.16 5515141.73 16.108291028 49.762326103
3529027.56 5476784.13 15.398379111 49.422064694
3598566.69 5478933.50 16.357198764 49.434113817

If there is a linear transformation between the two coordinate systems, only three points are sufficient for precise transformation of coordinates.
For common geodetic coordinate systems, six points ensure reasonable precision of transformation in the range up to 100 kilometres.

Digitization

Digitization is intended for manipulating basic map objects. After selecting any item in the menu  Digitization, the program enters digitization mode with a special menu. In this mode the cursor has the shape of a little cross and cursor keys change the position of the cursor (and not the position of the map). The step of the cursor movement can be changed with shortcut keys "1", "2", "3", "4" or "5". Of course, the location of the cursor can be changed using the mouse too. While the cursor is being moved, the main window bar shows the coordinates of the cursor. Additional information about digitization can be found in the SurGe Tutorial.

The menu  Points  enables to add or delete points XYZ or change their z-coordinate. A new point is specified by the cross cursor position when key B is pressed (or left mouse button). The point next to the cursor position is deleted using key Ctrl+B (or right mouse button). Key Shift+B is intended for setting a new z-coordinate of the point, which is next to the cursor position.

The menu item  Boundaries  is intended for creating and correcting the boundary. The boundary is handled as a horizontal polyline. Key Ctrl+H (or right mouse button) ends the definition of one boundary and starts a new one. A new point of the boundary polyline (including the first one) is defined by the position of the cursor when shortcut key H (or left mouse button) is pressed. The last defined point can be deleted by shortcut key D. Shortcut key U is intended for closing the boundary (for creating a boundary as a closed curve). Any point of the boundary can be marked using shortcut key Shift+H and then moved to a new position by shortcut key M. The last item under menu Boundaries creates a boundary as a convex envelope (convex hull) of points XYZ. The number entered in the following dialog box enables to scale the convex envelope. Using this feature you can change size of interpolation area and to remove grid values outside of the convex envelope - see the section How to modify the size and the shape of the grid area in the SurGe Tutorial.

Spatial polylines can be digitized using the menu  Polylines. Shortcut key Ctrl+L (or right mouse button) ends the creation of one polyline and starts another. A new point is defined by shortcut key L (or left mouse button), the last point can be deleted using shortcut key D. As in the case of the boundary, the polyline can be closed by shortcut key U. When defining a new point, the corresponding z-coordinate must be specified in the provided dialog box. If the z-coordinates of the polyline are to be the same, there is the possibility to predefine a constant z-coordinate by shortcut key F. This function can be canceled by shortcut key Ctrl+F. Any point of the boundary can be marked using shortcut key Shift+L and then moved to a new position by shortcut key M.
If a polyline is created, it is necessary to set its number of internal points. In fact, SURGEF does not work with polylines directly - it works only with the points, which are evenly distributed along the polyline. To specify the number of these points, move the cross cursor near the polyline and press shortcut key P. Then in the provided dialog box enter the number of internal points (typical values are 50 - 200).

The menu item  Faults  enables to edit sequences of line segments (in horizontal plain), at which the resulting surface has to be discontinuous. Each fault is defined by a pair of points. A new point of the fault is specified by the cursor position when shortcut key Z is pressed (or left mouse button). The fault can be deleted using shortcut key D (or right mouse button) - the one whose center is closest to the cursor position. The position of the fault end point can be changed by shortcut key Shift+Z.

In the digitization mode there is also the possibility to modify isolines. The first function,  Mark isoline  (shortcut key X), serves for selecting an isoline. After selection, the isoline is represented by a sequence of white points. If the display is (due to operations) damaged, it can be restored using the menu item  Redraw modified isoline  (shortcut key A). The selected isoline can be smoothed (Smooth isoline, shortcut key S) as a whole, or partially (Smooth between points, shortcut key V) between the points selected using the menu items  Mark first point  (shortcut key Alt+1)  and  Mark second point  (shortcut key Alt+2). There is also the possibility to mark a single isoline point  (Mark point, shortcut key Shift+I) and move it (Move point, shortcut key M). A certain number (the number can be changed using Change number n, shortcut key Ctrl+Q) of isoline points can be moved by  Move n points  (shortcut key Q). The modified isoline can be saved to the file  NAME.VRz using the menu item  Save modified isoline  (shortcut key Ctrl+I).  Write marked isoline  (shortcut key W) enables to store the selected isoline as the ASCII file IZ.\$\$\$.

The menu  Cross-section  enables to specify a polyline in the plane (x,y), which defines the cross-section through the created surface. The first or next point of the cross-section can be specified using the menu item shortcut key G (or left mouse button). Points are displayed in red. A polyline connecting the red points is displayed using the menu item  Display cross-section line  (shortcut key E). All specified cross-section points can be deleted by  Delete specified cross-section  (shortcut key Ctrl+G) and then a new cross-section can be defined. In the cross-section mode (see below), there is a possibility to save the position of the cross-section and name it with a single letter. The function  Select saved cross-section  (shortcut key Shift+G) enables to select one or more saved cross-sections. When the cross-section is defined, the key  Enter or right mouse button is used for creating the cross-section through the surface(s) and entering cross-section mode.

Cross-sections

Cross-section mode is invoked by the menu item  Cross-section / Display cross-section  (shortcut key Enter) in the digitization mode. The following dialog box appears:

The suffix convention enables to create a cross-section through several surfaces (layers). In the presented dialogue box, the suffix of the surface and a short description can be specified. The cross-section is constructed through all specified surfaces and displayed in a 2D plot. There is a special menu in the cross-section mode. The title of the plot and description of axes can be modified using menu items  Graph title  (shortcut key N),  Description of x axis  (shortcut key X) and  Description of y axis  (shortcut key Y). The range of the y axis can be changed by  Change range of y axis  (shortcut key Ctrl+Y). The last menu item,  Save cross-section  (shortcut key U) enables to save the position of the cross-section polyline to the file  NAME.RZY  for later use in digitization mode (see above).  The name of the cross-section must be specified as a single character A-I.

Background

In some cases it is useful to display texts and some characteristic terrain lines and / or objects to improve orientation in the map. For this purpose, there is a special digitization level named  Background  under the menu  Digitization. Objects of background are handled as polylines and here are the following functions for creating, changing or deleting objects from background:
 Start new object   (Ctrl+B) ends construction of the current object and starts construction of a new one New point of object  (B) a new point of object polyline is specified at cursor position Delete last point  (D) the last specified point is deleted Close polygon  (U) the next point will be at the same position as the first point of the polyline Mark point  (Shift+B) mark the nearest point of the polyline by white color Move point  (M) move marked point to a new position New text (T) specify text string, font size, font thickness, font color and text orientation Change text (Shift T) change text string, font size, font thickness, font color and text orientation

Three functions are intended for manipulation with whole objects:
 Select object/text (S) select / unselect the object next to the cursor. Selected object is displayed by violet color Move selected object/text  (Ctrl+M) move whole object; moving vector is given by marked point and the cursor position Delete selected object/text  (Ctrl+D) delete selected object

All background objects can be saved to file  NAME.BG  by the last menu item  Save background  (shortcut key W).

Detail of map

The shortcut key Ctrl D pressed in the move / zoom mode enables to enter a special digitization mode, where using the mouse left button a rectangular region can be selected to determine a detail of map. As soon as the detail is selected, new instance of SurGe containing only the points from the specified region is run (selected points are first saved in the file MAPDET#.DTs, which can be renamed appropriately and then used as a new data file). This function is helpful (especially when used with the shortcut key Alt S) in cases when there are clusters containing a great number of points in the map and the user wants to see the points distribution only in a certain small region.

Model grid

The function  Model grid  in the menu  Digitization  enables to create or to modify an irregular rectangular grid for a mathematical finite difference model, for example MODFLOW. The program switches into a special mode with its own menu. In the menu there are shortcut keys which can be used for creating the irregular rectangular grid. The model grid is stored in the ASCII file  NAME.XY.

Output

Under Output menu, the following items can be selected:

Grid as ASCII file
z
-values of the surface are stored in ASCII format in the file  NAME.GRs. This format is compatible with the grid file format of the program Surfer (Golden Software) - see the next section.

Grid as GRASS file
z
-values of the surface are stored in ASCII format in the file  NAMEs.TXT. This file, compatible with GRASS GIS system, can be imported as a raster file into LandSerf, a free application for the visualization and analysis of surfaces.

Grid as ArcGIS file
z
-values of the surface are stored in ASCII format in the file  NAMEs.GRD. This file, compatible with ArcGIS system, can be imported as a raster file into LandSerf, a free application for the visualization and analysis of surfaces.

Z-values at points
This function reads X and Y coordinates from the specified input ASCII file, computes corresponding Z value at surface and writes the result (X, Y and Z values) into specified output file. The input file must contain X and Y coordinates in the first two items of each row. The rest of row is copied into output file.
The format of the input file rows must be:
X  Y  [any-text]
The format of the output file rows is:
X  Y  Z  [any-text]
Such a type of output provides very important universal tool for transferring of surface z-values into any set of points located in the interpolation / approximation function domain. For example, if the x and y coordinates in the input file are triangle vertexes of an unstructured grid (for example the grid of finite element model), then this tool provides conversion between structured and unstructured grids.

Grid as DAT file
The grid values are stored in the format of the basic data file (see the next section)  NAME.GDs. The file containing grid values in this format is also referred as a generic ASCII grid file and it is used in many GIS systems such as Global Mapper.

Isolines as ASCII file
The isolines are stored in the ASCII format file  NAMEa.VRs.

NPR file
Surface values are interpolated into block centers of the model grid and stored in the ASCII file  NAME.NPs. The model grid  NAME.XY  (see above) must exist.

Remark:
A grid compatible with Surfer (stored in ASCII format) can be read using the menu item File / Read grid from ASCII file.

Format of input / output files

The name of input / output files is referred to as the name of project or basic name (in this documentation denoted as NAME). The first and second characters of the file name extension indicate the type of data and the third character (if any) has an arbitrary suffix, denoted in this documentation as s. The suffix enables to distinguish between several surfaces with the same boundary and / or with the same faults. It can be any character allowed in the extension of a file name. Recommended are letters A-Z or digits 0-9.

The basic input file is an ordinary ASCII file which has a name in the form  NAME.DTs, where  NAME  is the name of the project, DT  is the extension indicating the type of data (points  XYZ) and  s  is the suffix. Each row of the file has this format:

X  Y  Z  L

where  X,  Y  and  Z  are x, y and z coordinates of the points  XYZ  and  L  is the label of the point (min. 1, max. 23 characters). Items in a row must be separated by at least one space. The number of  XYZ points (non-comment rows in the file) is limited only by available computer memory. The basic input file is the only file, which can have comment rows starting with the character # in the first column. An example of an input file can be found in the SurGe Tutorial.

Other input / output files can be:

• NAME.DBs - input file in ASCII format containing additional points XYZ; the file has the same format as the file NAME.DTs. If this file exists in the working directory, it is automatically read after the file NAME.DTs.

• NAME.LNs - input / output file in ASCII format containing coordinates of spatial polylines. The file has this format:
N1  M1
X Y Z
X Y Z
.
.
N2  M2
X Y Z
X Y Z
.
.
Np  Mp
X Y Z
X Y Z
.
.

In  the first row of each sequence of spatial polyline points there must be the number of points in the sequence  (N1, N2, ... , Np). The second and the next rows (X Y Z) contain x, y and z coordinates of polyline segments separated by at least one space. The overall number of points (N1+N2+...+Np) cannot exceed 10000. The number of spatial polylines (p) is limited to 300.
M1
, M2, ... , Mp  are the numbers of internal points. In fact, SURGEF does not work with polylines directly - it works only with the internal points, which are evenly distributed along the polyline. The typical values are 50 - 200.

• NAME.HR - input / output file in ASCII format containing coordinates of points which creates the boundary. The file has this format:
N1
X Y
X Y
.
.
N2
X Y
X Y
.
.
Nb
X Y
X Y
.
.

In  the first row of each sequence of the boundary points there must be the number of points in the sequence (N1, N2, ... , Nb). The second and the next rows (X Y) contains x and y coordinates of the boundary points separated by at least one space. Overall number of the boundary points (N1+N2+...+Nb) cannot exceed 10000. The number of boundaries (b) is limited to 100.

• NAME.ZL - input / output file in ASCII format containing coordinates of initial and end points of the line segments, at which the created surface has to be discontinuous. The file has this format:
X1 Y1 X2 Y2
X1 Y1 X2 Y2
.
.

The coordinates must be separated by at least one space. The number of the lines in the file cannot exceed 1000. The line segments can be connected and so they can form a polyline. They are often referred as faults.

• NAMEf.GRs - binary input / output file containing the matrix  i1j1 of z-coordinates in the nodes of the grid.

• NAME.VRs - binary input / output file containing x and y coordinates of isolines.

• NAME.GRs - input / output file in ASCII format containing the matrix  i1j1 of z-coordinates in the nodes of the grid. The format of the file is compatible with SURFER (Golden Software) grid file format:
DSAA
i1 j1
x1 x2
y1 y2
z1 z2
P1,1   P1,2
P1,3  .... P1,i1
P2,1   P2,2
P2,3  .... P2,i1
.       .                    .
.       .                    .
Pj1,1
Pj1,2    Pj1,3  .... Pj1,i1

• NAME.CLs - input ASCII file containing z-levels for a raster color map. If this file does not exist, default levels and colors are used. The file has the following format:
Z1  [C1] [C0]
Z2  [C2]
Z3  [C3]
.
.
Zn  [Cn]
where Z1,...,Zn (0<n<27) are z-levels specified by the user and C0,C1,...,Cn (0<=Ci<61) are optional color numbers (color Ci will be used between levels Zi and Zi+1). If the color number C0 (the default value is 1 - dark blue) is specified in the first row, it will be used below the level Z1. If there is a row without color specification, the default colors will be selected. The following scale shows colors and their numbers used in SurGe.

• NAME.CL - input ASCII file with the same format and the same meaning as the file NAME.CLs. If this file exists in the working directory, it is used for all maps with the name NAME. But if there is also the file NAME.CLs in the working directory, it has precedence before the file NAME.CL for the map with the suffix s.
• NAME.LVs - input ASCII file containing user-defined z-levels for isolines. The format of this file is:
Z1
Z2
Z3
.
.
Zn
where Z1,...,Zn (1<=n<=700) are z-levels specified by the user. If the file exists, the levels in the file are used for the computation of isolines and the dialog for the specification of isoline levels is not displayed.
• NAME.LV - input ASCII file with the same format and the same meaning as the file NAME.LVs. If this file exists in the working directory, it is used for all maps with the name NAME. But if there is also the file NAME.LVs in the working directory, it has precedence before the file NAME.LV for the map with the suffix s.
• NAME.XY - input / output file in ASCII format containing specification of the irregular rectangular grid constructed for mathematical models based on the finite difference method.
• NAME.NPs - output file in ASCII format containing values of the surface in the block centers of the irregular rectangular grid. The blocks are specified in the file NAME.XY.

The program SURGEF, which implements the interpolation / approximation method ABOS, can be used as an external console program called from user application, for example:

• using system command in C language
• using Shell function in Microsoft Visual Basic
• using WinExec function, which is available in standard Windows library KERNEL32.DLL.

If you want to use SURGEF by this way, your application must provide:

1. Input file(s) for SURGEF (at least the basic input file must exist in the working directory - see the previous section).

2. The application must create an ASCII file PAR.3D (parametric file for SURGEF):
 Row Value Example Meaning 1. string ex1 Name of basic input file 2. character a One-character suffix 3. Y / N / C [,scale] C,1.2 Boundary  has / has not  to be used. If C is used, the boundary will be created as a convex envelope of input points. The following optional number than can be used as a scale of boundary (default value is 1.1). 4. Y / N N Faults  has / has not  to be used 5. Y / N N Additional points  has / has not  to be used 6. Y / N N Polylines  has / has not  to be used 7. Y / N Y Basic points  has / has not  to be used 8. 0-9999 500 Value of filter 9. 5-99 [, 0 / 5-5555, 0 / 5-5555] 99, 300, 200 Grid enlargement, gird dimension(s) 10. 0-4, 0 / 1 1, 1 Degree of linear tensioning, fast convergence off / on 11. 0-99, 0-999.99 [,0-9999] 1, 0.5, 50 Precision, smoothing, number of smoothing cycles 12. Y / N N Blank / do not blank  grid outside the boundary 13. Y / N N Create / do not create  NP file 14. Y / N Y Create / do not create  ASCII grid file [15.] [file-name-xy] points.xy Input file containing x and y coordinates of points as first two items [16.] [file-name-xyz] points.xyz Output file containing records from file-name-xy + surface values

• Values in brackets are optional. If a numeric parameter is missing, it will be estimated by SURGEF internally.
• If there are two or more items in the row, they can be separated by comma and spaces or only by spaces.
• If both grid dimensions are zero, they will be estimated by SURGEF internally. If the first (dimension in x-direction) is greater than zero and the second (dimension in y-dimension) is zero or is missing, the second dimension will be estimated by SURGEF internally according to the first dimension.
• If you use the C option in the third row, the newly created boundary will replace the old one, if it exists. Practical usage of convex envelope is described in the section How to modify the size and the shape of the grid area in the SurGe Tutorial.
• If a boundary is used, the domain rectangle of interpolation function is set according to boundary points and not according to points XYZ.
• At row 15 there may be a name of input ASCII file containing at first two positions x and y coordinates of points which should fall into domain of interpolated function. Then output file named at row 16 will contain records from input file plus surface value at specified points.

3. Now the SURGEF can be called from the application - for example by the following command in C language (do not forget N parameter, which means "normal" interpolation; for other interpolation modes you can use L (linear) or C (convex) - see How to use different modes of interpolation in the Surge Tutorial):

system("C:\SurGe\SURGEF.EXE N");

or

system("C:\SurGe\SURGEF.EXE N A");

The second command line parameter means, that SURGEF will run automatically without waiting for answers to prompts and the following letters can be used:
A ... external grid will not be read - see How to utilize an existing grid in the SurGe Tutorial.
Y ... external grid will be read - see How to utilize an existing grid in the SurGe Tutorial. In this case the external grid must exist.
Q ... preview mode, very fast interpolation without smoothing - see How to use different modes of interpolation in the SurGe Tutorial.

There are no differences between registered and unregistered version of SURGEF. Of course, SURGEF can be also run "manually" as a console application, for example using the command:

E:\SurGeData>c:\SurGe\surgef.exe N Y

The menu item Miscellaneous / Grid info displays the information about grid size and coordinate ranges; the menu item Miscellaneous / Objects info displays information about the number of the objects.

The following tables contain commonly used shortcut keys.

Display
 N labels of points K z-coordinates of points C raster color map I isolines Alt+Q shadowed relief Alt+S color scale Ctrl+S mesh scale Ctrl+E mesh labels R refresh display Ctrl+R change background color O background Ctrl+C saved cross-section(s) Alt+W highlight specified label of point

Move/zoom
 Ctrl+arrow keys move map objects Ctrl+PgUp zoom in map objects Ctrl+PgDn zoom out map objects

The shortcut key Ctrl+L pressed in the basic display enables to edit colors used in the raster map and 3D display:

There are three color areas - the two on the left side display a color cube and the one on the right side contains color strips of palette.

The color cube is a method how to generate all colors defined by three components of the so called RGB (red, green and blue) color model. The intensity of the red component can be selected in the x-direction of the square, the intensity of the green component can be selected in the y-direction. The intensity of the blue component (z-direction) can be selected in the narrow rectangle next to the square.

Colors in all directions can be changed by selecting a color in the z-direction - try shortcut keys R,G and B.

The actual color (marked by a small white rectangle) can be selected in the strips on the right side - using left mouse button or using shortcut keys Shift+arrow up or Shift+arrow down. There is also the possibility to interpolate between two colors marked as 1 and 2. The color 1 can be marked by Ctrl+1 and color 2 by Ctrl+2. The interpolation can be performed using Ctrl+I. Using the interpolation, gradual color shades can be obtained between color 1 and 2 - see the above example, where color 1 is blue and color 2 is white.

The modified color palette can be saved into a file with extension .pal using the shortcut key Ctrl+S and loaded using Ctrl+L.

In addition to the default color palette (file 256.pal) there are four other predefined color palettes: Globe.pal, Polar.pal, Steel.pal and Topo.pal.

Explanations of errors

If faults are used in the created map, SURGEF.EXE may end with the following message:

Error in faults definition.
Return to SurGe and press key U to see undefined nodes of grid.

The next picture illustrates such situation:

In this configuration of points and faults there is an area, from which no point can be "seen over" faults. This area is marked by white points in the next picture:

The white points are displayed by shortcut key U in move/zoom mode. It means, there are grid nodes, which have undefined values. In this case, the interpolation / approximation cannot be performed. The only solution of this situation is to add a point - for example like this: