The surface command of the data file is used to position the cave map on a topographic map [thbook 26]. This command takes as argument the filename of an image (in a format supported by therion, such as PNG), or a grid of 3D data.

In the first case the syntax is

    surface 
      bitmap filename calibration
    endsurface

Here "filename" is the name of the file with the ground map, and "calibration" is a set of eight values that define the correspondence between two points in the image (pixel units) and the two corresponding points in the map (geographics coordinates, units are meters by default). You need two points to position the cartographic image with respect to the cave map. Infact the image is rotated, scaled and translated (no shear). For example

   surface 
     bitmap grigna.png [0 1176 1529079.8 5089914.6 854 186 1529802.9 5089076.7]
   endsurface

In this example the image has size 1900x1176, the coordinate of the entrance on the image are (854,990) [pixels]: X is horizontal, from left to right, Y is vertical downward. In the calibration the Y-axis is considerd upward, therefore instead of 990 there is 186=1176-990. Similarly the upper-left vertex of the image is (0,1176). The size of the pixel is 0.847 in both directions, therefore this vertex has metric coordinates 1529802.9 - 854*0.847 = 1528949.7 and 5089076.7 + 990*.847 = 5089914.6.

In the second case the syntax is

     surface
       grid-units units
       grid x y dx dy nx ny
       grid-flip flip
       data
     endsurface

Here "units" are the units of the grid data. By default it is meters. The grid origin is placed at the map point (x,y). The grid has step (dx,dy) and it has nx nodes horizontally, and ny vertically. The grid data follow: this is the sequence of the altitudes (above see level) at the nodes, starting at the origin and sweeping the grid row-wise from west to east, and from south to north. The grid-flip command is optional: it is used when the grid data are given in another order. It can take values "none", "vertical" or "horizontal".

It is possible to specify both the image and the altitude grid (S. Mudrak 2005-11-30),

  # surface command for entering surface
  surface
    # grid to specify position of surface
    # grid X-start Y-start X-step Y-step C-columns R-rows
    grid 400080 5419750 10 10 190 68
    # calibrated surface texture - not yet supported in 3D viewer
    bitmap <filename> [calibration-parameters]
    # followed by the cols X rows  altitudes matrix
    1520 1530 ...
    ...
    1680 1690 ...
  endsurface

As an example load the surface map file "sovra.png" in the plan map of the example "gm-therion". Add the following command to the data file

    surface
       bitmap sovra.png [114 107 0 0 88 56 -33 -64]
       grid 0 0 25 25 9 7
         670 660 640 660 670 685 705 719 731
         677 664 650 660 674 689 710 726 740
         682 672 659 660 676 691 712 730 743
         691 680 670 664 678 691 710 728 740
         700 693 681 675 678 689 702 720 731
         707 703 698 693 689 687 697 709 720
         720 716 710 705 701 694 708 719 721
    endsurface

The values of the calibration have been found from the position of the cave entrance on the groundmap image, and from the scale and scan resolution of the groundmap image.

In the configuration file you need to add to the layout options to include the surface,

     -layout-transparency on \
     -layout-surface bottom \
     -layout-surface-opacity 80

The first one activates the transparency of the cave map (the default "opacity" value is 70). The second option places the surface on the lowest level, the "bottom" one.

The result is shown in the figure below: the example cave is rather small, and it disappears somewhat in the topographic map.