Getting started

Content

Starting surfit

To start surfit you could run programm called surfit (surfit.exe under Windows). This program is extended Tcl shell application which automatically loads all surfit libraries. If surfit was installed correctly, you should see the following:

loading surfit v3.0
surfit version 3.0, Copyright (c) 2002-20013 Dmitrievskiy & Kutrunov
surfit comes with ABSOLUTELY NO WARRANTY; for details type `show_w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show_c' for details.
loading module surfit_io v3.0
loading module globe v3.0
loading module freeflow v3.0

A common error received by first-time users is:

couldn't load file "libsurfit.so": libsurfit.so: cannot open shared object file:
No such file or directory

under Unix/Linux, or

couldn't load library "libsurfit.dll": this library or a dependent 
library could not be found in library path

under Windows. Here is solution for this problem:

Unix environment

This error is generated because the dynamic linker can't locate the libsurfit.so library. When shared libraries are loaded, the system normally only checks a few standard locations such as /usr/lib and /usr/local/lib. To fix this problem, there are several things you can do. First, you can set the LD_LIBRARY_PATH environment variable to include the directory with libsurfit library. If setting LD_LIBRARY_PATH, be aware that setting this variable can introduce a noticeable performance impact on all other applications that you run. To set it only for surfit, you might want to do this instead:

$ env LD_LIBRARY_PATH=/home/beazley/projects/lib surfit

Finally, you can use a command such as ldconfig to add additional search paths to the default system configuration (this requires root access and you will need to read the man pages).

Windows environment

This error is generated because system can't locate the libsurfit.dll library. To fix this probelm you must set the PATH environment variable to the directory with libsurfit.dll:

(Windows 95/98/Me): The search path in Windows is normally specified in the autoexec.bat file, which is typically located in the root directory (c:). To add the surfit installation directory to your search path do the following from an MS-DOS Prompt Window:

(Windows NT/Windows 2000):

How to get results quickly

This way is useful for most common task: interpolation of scattered data points or for contours approximation.

You will need only 3 commands: file_load, surfit and file_save. Also you may want to use surf_plot command to get results in PostScript file.

$ file_load my_data.txt 
$ surfit
$ file_save my_results.dat
$ surf_plot my_result.ps

First commands loads your data from my_data.txt file. It recognizes most of file format and data types supported by surfit. Second command runs surfit gridding algorithm. Also it automatically creates so called "gridding rules" for loaded data and creates grid for that data. Third commad saves all data in memory with the surface obtained after gridding into "my_results.dat" file. Last commands plots resulting surface into PostScript file.

Loading data to surfit

To examine data, already loaded use mem_info command.

Automatic file loading

There is file_load command that tries to recognize file format and load it into surfit memory.

loading points

The pnts_read command reads formatted text files containing scattered data points coordinates. Text file should be organized as a rectangular table of numbers, separated by blanks, with one row per line, and an equal number of elements in each row. For example, outside of surfit, create a text file containing these four lines:

    16.0     3.0     2.0    13.0
     5.0    10.0    11.0     8.0
     9.0     6.0     7.0    12.0
     4.0    15.0    14.0     1.0

Store the file under the name points.txt Then the command

$ pnts_read points.txt my_points 4 1 2 3
13/01/05 15:02:52 : reading points "my_points" from file points.txt

reads the file and creates the points dataset. This dataset contains 4 points with X,Y and Z coordinates placed in first, second and third columns. If points.txt consists of only 3 columns:

    16.0     3.0     2.0
     5.0    10.0    11.0
     9.0     6.0     7.0
     4.0    15.0    14.0

then the command arguments can be truncated:

$ pnts_read points.txt my_points
13/01/05 15:02:52 : reading points "my_points" from file points.txt

You can get some info about points datasets with following commands:

# Get number of points dataset:
$ pnts_size
1
# If there is no points datasets in memory, surfit returns 0.
#
# Print points name 
$ pnts_getName
my_points
#
# Get number of points in points dataset
$ pnts_getCount my_points
4
$ Minimum and maximum values:
$ pnts_minx my_points
4.0
$ pnts_maxx my_points
16.0
$ pnts_miny my_points
3.0
$ pnts_maxy my_points
15.0
$ pnts_minz my_points
2.0
$ pnts_maxz my_points
14.0

Here you can browse all commands for points.

loading curves

surfit supports several types of curves:

curve 2D piecewise linear curve
area polygonal region
contour 3D piecewise linear curve

The curves reading commands read formatted text files containing coordinates of curve nodes. The text file should organized as a rectangular table of numbers, separated by blanks, with one row per line, and an equal number of elements in each row. For example, outside of surfit, create a text file curve.txt containing these lines:

57099.085411    60514.295924
57065.433147    60505.330833
57003.367936    60511.976722
56999.6438      60513.47112
56948.876992    60541.501355
56917.649718    60581.114875
56914.83462     60637.571493
56919.935389    60652.716872
56959.468869    60684.079163
56995.964528    60685.666331
57018.666043    60682.271289
57060.443913    60665.765085
57102.780849    60632.737514
57119.301496    60610.562283
57133.154687    60592.618067
57138.674487    60577.882496
57131.297193    60533.391477
57116.652575    60516.980407
57099.085411    60514.295924

To read curve from file curve.txt use command: 

$ curv_read curve.txt my_curve
14/01/05 11:00:12 : reading curve "my_curve" from file curve.txt
1

loading surfaces

surfaces can be loaded from Surfer GRD-ASCII and surfit datafile format. To load surface from Surfer GRD-ASCII file use the command:

$ surf_load_grd surface.grd my_surface
14/01/05 16:32:50 : loading surface from Surfer GRD-ASCII format file surface.grd
1

To load surface from surfit datafile use the command:

$ surf_load surface.dat my_surface
14/01/05 16:33:20 : loading surf "my_surface" from file surface.dat
1

Here you can browse all commands for surfaces.

Creating grid

surfit uses equdistant grid for gridding procedures. This grid can be described with only 6 parameters:

You can create grid object with grid_get command. For example, command

$ grid_get 0 100 10 0 200 20 my_grid
15/01/05 22:38:32 : grid: (0.00 <-> 100.00) / 10.00; (0.00 <-> 200.00) / 20.00.

In most cases you can use grid command with only 2 parameters to specify cell sizes:

$ grid 10 20

surfit automatically produces grid with cells of specified size. This grid will cover all data objects, loaded into memory.

Gridding

Gridding methods produce a regularly spaced, rectangular array of Z values from regularly and irregularly spaced XYZ data. The term "irregularly spaced" means that the points follow no particular pattern over the extent of the map, so there are many "holes" where data are missing. Gridding fills in these holes by extrapolating or interpolating Z values at those locations where no data exists.

For each data, loaded into surfit memory you can specify gridding rule, which describes how to use your data in surfit gridding algorithm.

Gridding procedure consists of 4 steps:

Here is some examples: 

    <UL>
    <LI>
    <a href="points__exact_8tcl-example.html">Interpolation of scattered data points</a>
    <LI>
    <a href="trend_8tcl-example.html">Interpolation of scattered data points with trend and fault</a>
    <LI>
    <a href="points__approx_8tcl-example.html">Approximation of scattered data points</a>
    <LI>
    <a href="curve_8tcl-example.html">Interpolation/approximation of curves with constant values</a>
    <LI>
    <a href="contour_8tcl-example.html">Interpolation/approximation of contours</a>
    <LI>
    <a href="area_8tcl-example.html">Interpolation/approximation of areas</a>
    <LI>
    <a href="surface_8tcl-example.html">Interpolation of surface</a>
    <LI>
    <a href="surface__add_8tcl-example.html">Approximation of surface</a>
    </LI>
    </UL>

Saving results

After gridding procedure result saves as new surface named with map_name variable value. You can export it to Surfer GRD-ASCII format with command surf_save_grd or to surfit datafile with command surf_save. Also you can save your results into surfit datafile with all other data in memory with command file_save.

Visualising results

The simplest way to visualise your results is to use funner program. This program can be founded here: www.gridding.info. funner accepts both Surfer GRD-ASCII and surfit datafiles.

funner window

Funner window screenshot

Also you can select file from command line:

> funner my_map.dat


surfit: gridding and contouring software.