In the map editor mode xtherion can write, edit, and save files with drawing data, called map files. The syntax of these files is not complex at all. It is however better to use the map editor than to write the commands with a text editor because of the numerical values of the command arguments. You should remember that xtherion is not WYSIWYG (what you see is what you get) and it displays points and lines where in the final drawing there will be symbols, labels, and so on. The map editor deals with only a part of the graphical commands of therion. However the map files can be edited with the text editor of xtherion, or any other text editor. Furthermore xtherion does not do any syntax check. The only way to find errors is to run therion. Another limitation of xtherion is that it has no syntax highlights, which would be very useful to detect errors while writing.

To switch to the map editor mode choose the menu "Window | Map editor". The window of xtherion shows a drawing canvas and a control panel (on the side). The latter contains the following controls:

• "Objects": list of the items of the map file
• "Search and select": to search graphical items in the map file
• "Command preview": command text as it appears in the map file
• "Points": point items in the map
• "Lines": line items in the map
• "Line points": points of a line
• "Areas": area items in the map
• "Scraps": scrap items in the map
• "Text editor": text editor to insert text verbatim in the map file
• "Drawing area": control of the drwaing canvas
• "Background images": control for the background images (these images are not included in the output).

The map editor has two operational modes: insert and select. You switch from the "insert" to "select" pressing the escape ("Esc") key. You switch from "select" to "insert" when you select one of the menus "Edit | Insert" (or with an equivalent command, or shortcut). Depending on the menu you insert points, lines, or areas. Inserting a scrap or a text leaves the map editor in "select" mode.

By selecting the menu "File | New" the drawing canvas becomes yellow and is ready to draw. First save the file assigning it a name: menu "File | Save as".

To open an existing th2 file, use the menu "File | Open", or "File | Open (no pics)" if you want to open it without loading the background images (which is faster).

The menu "Edit" has submenus specific to the map editor,

• "Insert", with a choice among "point", "line", "area" "text" and "scrap"
• "Insert image" to load a background image.

You can move the drawing with a click-and-drag of the right mouse button. You can change the zoom, by selecting the new one in the "Drawing area" control, or with the menu "Edit | Zoom ...".

Now open a background image (menu "Edit | Insert image"). xtherion can read images in GIF, PNM, PPM, and XVI format (xvi is the vector format of xtherion). If you have the tkImg extension of Tcl/Tk installed, xtherion can load also PNG and JPEG images.

As explained by M. Sluka (see the figure below):

xvi means Xtherion Vector Image. The primary idea was to use the data measured in the cave as background to draw the map directly in the cave. You start by writing a ".th" file with only one shot, and generate the ".xvi" file. Next you use this file as background in the new ".th2" file and draw a piece of the cave wall. Then you switch to the text editor, add a second shot, compile and go back to the map editor: the background has changed according to the new data. It have moved and you might have to reposition it by using the "Move to" button of the "Background images" control. You continue drawing the cave, and so on.

You can load a background image also with the button "Insert" of the "Background images" control. The background images are not part of the drawing but are loaded in xtherion memory and are used to draw the scraps. To remove them use the button "Remove" of the "Background images" control. You can also remove them temporarily from the memory using the "visibility" checkbox, to save system resources, if you need.

You can have more background images at the same time, select one and put it before the others ("Move front") or behind ("Move back"). Using the slider you can display it darker (move the slider to the left) or lighter (to the right). Finally you can move each one in the canvas independently, entering the new position and using the button "Move to", or by click-n-drag with the right mouse button. When there are more than one overlapping background image, you can drag all of them or just one: double click to switch among the different possibilities.

It is not possible to rotate and rescale each image individually. Therefore, it is advisable to prepare the scanned images with the same orientation and the same resolution (pixel per meter, that is same DPI if the images have the same scale) [thbook 29].

The menu "Edit | Auto adjust" (or the analogous button of the "Drawing area" control) computes the size of the drawing area, using the background images, and resize the yellow canvas. [thwiki 2]. After loading a background image select this menu to display it in the middle of the drawing area.

This control is also very useful when you start a scrap, using a background image, and have to insert another image to continue it. You first insert the new image (menu "Edit | Insert image"), next you move it to the correct position (use the "Move to" button of the "Background images" control). Finally by clicking the "Auto adjust" button of the "Drawing area" you adjust the size of the canvas to contain all the images you have inserted.

You can prepare images by printing the centerline on a paper and drawing the cave sketch around it. Or you can directly use the sketches drawn in the cave, however these should be drawn in scale with reduction of length, eg, by using the therion protractor, or using millimetric paper and estimating angles with an accurcy of +/- 5 degrees.

There is no direct way to print a xvi map, but you can generate a pdf map with all the items of the xvi. Use the "export" command with a pdf output and set the foreground color with the "color map-fg" option. If you have some scraps already drawn in your data, you need to define a map (with the top level survey) and "select" it before the "export" command. For example,

  source
    map my_map
      top_level_survey
    endmap
  endsource

  select my_map
  export map.pdf -layout-color map-fg 80

A cave map is composed of scraps, and every element of the map must be contained in a scrap [thbook 17]. A scrap is a piece of the drawing that correspond to a portion of the cave with no overlying passages. To faciltate the connection among the scraps to form the whole map, it is advisable to break the map up into scraps where the cave is "simple" (plain walls with no features to be drawn). The Therion book also suggests to limit the size of each scrap to about 100 m. This comes from the figure limit in MetaPost, which is about 1 m: a 100 m scrap at a scale 1:200 makes a figure of about 0.5 m size.

Now insert a scrap: select the menu "Edit | Insert - scrap", or the button "Insert scrap" of the "Objects" control, or the shortcut Ctrl-R. You may notice that the "Command preview" control has a new line which starts scrap scrap1 .... This control is useful to see the commands that xtherion writes in the map data file, for each drawing element [thwiki 10]. If you check the "Objects" control you see three lines

    scrap
    endscrap
    end of file

All the elements that belong to the scrap will go between the first two lines.

You can put more than one scrap in a map data file. In this case you have more scrap-endscrap sections in the "Objects" control. It is important that when you insert a drawing element one scrap is selected, so that the element will go inside it. When you insert a scrap, this is automayically selected. Therefore if you start inserting drawing elements after having inserted a scrap, these go inside it.

The "Scrap" control lets you change the properties of the scrap. The most important are the projection type and the id (the name of the scrap). Another properties of a scrap is the author. The syntax is "-author date name", for example -author 2007.10.10 "marco corvi" (if the name contains a space it must be enclosed in quotes). The author is displayed in the "Drawn by:" section of the map header. Other options are the title, -title string, and the copyright, -copyright date string.

In the canvas there are two small red squares, in the lower part, connected by a read arrow. They serve as reference for the scrap when there is only one station in the scrap, such as is the case of cross sections. To define the scale of the scrap you must drag the squares at the opposite corners of a (ideal) rectangle that contains the drawing. For example, the left one on the bottom-left and the right one on the top-right. Next you must assign the coordinates to these two points (expressed in meters if you are using the meter as unit): for example (0,0) to the left one and (width, height) to the right one. Alternately, you can leave the arrow horizontal and specify the real size of it, ie, assign the two squares the coordinates (0,0) and (size,0).

The position of the squares is translated in the ".th2" file into the option of the "scrap" command

   -scale [0 0 200 200 0.0 0.0 10 0.0 m]

The first four numbers are the coordinates X1,Y1,X2,Y2 on the drawing. The following four numbers are the map coordinates, followed by the units.

The position of the squares defines also the orientation of the drawing. For example if the squares are placed diagonally in the drawing and we assign them the map coordinates (0,0) amd (10,0), the drawing is rotated by 45 degrees clockwise, as in the figure below.

If the cross section has a different scale than the plan (or the extended section) you must use rescaled coordinates. For example, if the plan is 1:1000 and the cross section is 1:500 you must double the values of the map coordinates.

The scrap reference points