Virterf Help File (obsolete)

Dr P.Smars, 2002


Virterf is a software combining recent developments in computer vision and reverse engineering targeted for professionals working in the field of architectural conservation. This help file is concerned with the second module of the software, offering tools to qualify and query the 3D model of a building. Information can be added, organised in themes or linked to the model. The resulting database with the software's visualisation capacities facilitates comparison, synthesis and decision.

The module is built in four levels:

The first level uses existing C++ library. For the visualisationm, we use VTK (Visualization Toolkit), an "open source, freely available software system for 3D computer graphics, image processing, and visualization". It provides basic methods to define, show and transform 3D data. For the database management, we use MySQL and its C++ interface.

The second level implements the general structure of the module in a set of new C++ classes. An efficient low-level language allows computation intensive functions to perform fast.

The third level implements a set of commands giving access to the C++ classes of the second level. They are extensions of the Tcl scripting language (Tool Command Language). Scripting languages gives more flexibility to the user who can customize the code (not compiled). New Tcl commands can be written in C++. They are compiled in a library (DLL) that can be loaded in a Tcl interpreter, extending the functionalities. The code can be written manually but we used a freely available software tool, SWIG to automate the process. SWIG connects programs written in a variety of low-level programming language (such as C++) with a variety of high-level languages (such as Tcl/Tk). It automatically creates interface code using the original C++ classes' headers and files specifying the interface.

The fourth level uses the original Tcl commands; the one developed in the third level and Tk commands to build a user interface. Tk (toolkit) comes with Tcl (usually referred as Tcl/Tk), it allows to quickly create graphical applications.

The user can interact with the model at the third level (with commands typed in a console window) or at the fourth (with the graphical user interfaces). All the actions are recorded in a log file. This allows the user to reconstruct a previous stage of the model (not yet automatically). Log files are also a record of how something was done and by whom and open the possibility to judge about the quality of every piece of information of the model. The ability to store set of commands in small files, Tcl scripts, allows storing the key used to produce a result instead of the results itself. This can save memory and remain valid if the model is changed.

Command reference

This help file describes the commands of the third level.
Commands are executed from a tcl command prompt:

Libraries extend the vocabulary of Tcl. They are loaded in the shell using the command:
%load library_name

Session management

The model is saved as a MySQL database located on a server. It can be displayed, queryed or edited using a ve_wdb window from a client. A window is opened using the command:
%ve_wdb window_name server_name user_name password database_name
ex: %ve_wdb w abpc-ps2 absps lemaire wells
%window_name getname -- return the name of the database
%rename window_name "" -- close the ve_wdb window
%window_name setoutputfile ve_text -- set the destination of text results (an object of type ve_text)
%window_name getoutputfile -- get a handle to the outputfile
%window_name setlogfile ve_text -- set the destination of log of all commands (an object of type ve_text)
%window_name getlogfile -- get a handle to the log

Viewing options

Interaction with the user is made through 3D viewing windows, visualising selected information from the database: the geometry (possibly textured), possibly an attribute theme and possibly a vector theme.
The controls are done via interactors (the standard interactor in particular) or via commands to achieve a precise control.


Interactors are devised to assist the user in viewing, querying or editing the model, giving him a mouse driven interface.

The available interactors are:

%window_name interact interactor_name -- load the interactor
The following functionalities are common to all interactors: The following functionalities are specific:


Images can be projected on the model. The best image can be chosen to study or help editing a particular part of the model. Old photographs can be used to track changes, deformations and disappeared features. Special photograph technique (low-angled light, photo-interpreted images, IR, UV) may also put new features in evidence.

Attribute Themes

Attribute themes may group information on materials, pathology or construction phases. Themes are further divided in layers related to the attributes types (stone and wood in a material theme for instance). The structure is created by the users, according to their needs. The texture colour is changed to reflect the layer of each triangle. When a new theme is created, a layer 'unknown' is automatically assigned to all the triangles. The user must then create specific layers and qualify the geometry relating triangles to layers. This is a three times process: making a selection, choosing an attribute and apply it to the selection. The colours of the deselected elements become darker to give a feedback to the user.

Different options are available to define a set of geometrical data. Triangles can be selected (or de-selected) with the mouse. A selection set can be redefined by intersection, union or difference with the triangles belonging to a given layer. It can also be inverted, made empty or include all the triangles. With this system it is for instance possible to select elements inside a given area, built in stone and prior to a given construction stage. As the model's construction progresses, adding new attributes becomes therefore easier. Small Tcl scripts can be written with all the commands necessary to easily reuse selection sets.

When a selection is made, an attribute can be assigned from the list of existing attributes (layers) from the active theme. The selection set remains active until the complete set is reselected. So more attributes can be applied to the same set. One element complicates the process: feature edges may not correspond to triangles edges. The transition line between brick and stone may for instance fall inside a triangle. If the triangles were very small (their dimension being of the order of magnitude of the details), it would not be so important, but it is unlikely to be so. A tool was therefore devised to refine the mesh. It uses a cutting segment defined on the model with the mouse. The triangles created receive by default the attributes and texture from the original triangle.

Vector Themes

Sometimes it may be interesting to extract 1D information from the 2D model: sections, architectural features (edges, masonry joints), pathology features (cracks). It may also be interesting to import graphical data produced externally (results from deformation monitoring, modelling). This is done in vector themes. Like attribute data, vector data is organised in themes and layers.

Points and segments can be drawn. They are placed in the active layer of the active theme. They are drawn via picking or via coordinate introduction. Display points defined by the mouse (2D) are projected on the model (3D). It is possible to draw a segment connecting the two 3D points so defined or a polyline intersecting the model.


Not all the information related to an object is geometrical. Specialists produce reports. They also may want to annotate some parts of the model to clarify the meaning of layers or characterise special elements. Information is not necessarily textual. It can consist of images, figures, databases or html documents. These have normally relations with elements of the model (geometric or thematic). The possibility to define links was included to express them. Links are materialised by small spheres coloured according to the type of file linked. With the mouse, the user can query their name and a description or visualise their content via an external application. They are only visible in the themes relevant to them. It is probably not interesting to have direct access to an archaeologist report from a theme created by an engineer but one observation of the former may be of importance for the stability. If a specialist thinks that the attribute layers paradigm does not suit his needs (because precise borders are impossible to define for instance), he can create themes only to set links to relevant documents.

Links can be placed on the model or just hang in space. They can be saved in files. The possibility to link to html documents allows the user to incorporate the virterf model in a more general scheme.

Links are created with ve_link



A definable output destination for text. See lower an example of application


A library allowing to define user unit systems, used in conjunction with ve_text

The unit files (*.uni) are so structured:

long_name_level1 short_name_level1 ratio_user_unit/basic_unit
long_name_level2 short_name_level2 number_of_level2_units_in_1_level1_unit
long_name_level3 short_name_level3 number_of_level3_units_in_1_level2_unit
long_name_level1 short_name_level1 ratio_user_unit/basic_unit
long_name_level2 short_name_level2 number_of_level2_units_in_1_level1_unit
long_name_level3 short_name_level3 number_of_level3_units_in_1_level2_unit

Opening a new ve_wdb window, the program first search a default file model.uni in the current directory and if it doesn't find any, it search in the directory where the binary files are stored (known through the environment variable ve_lib) Example:

feet ft 3.50262697023
inches in 12
digits d 12
sq_feet ft2 12.2683956926
sq_inches in2 144

A typical starting session could be:

%load ve_wdb
%ve_wdb w server_name user_name password database_name
%load ve_unit_system
%set unit [ve_unit_system]
%$unit open unit_file_name
%load ve_text
%set text [ve_text]
%$text setunit $unit
%$text unit on
%w setoutputfile $text

Database Structure


This file indicates which programs are used to open the files pointed to by ve_link's objects. link.ext is so structured:

extension program R_value G_value B_value

The RGB values define the colour used for the symbols (small balls) indicating the link in a ve_wdb window. The program first search the file in the current directory and if it doesn't find any, it search in the directory where the binary files are stored (known through the environment variable ve_lib)

jpg c:\progra~1\window~1\access~1\imagevue\kodakimg.exe 1 1 0
tif c:\progra~1\window~1\access~1\imagevue\kodakimg.exe 1 1 0
gif c:\progra~1\window~1\access~1\imagevue\kodakimg.exe 1 1 0
bmp c:\progra~1\window~1\access~1\imagevue\kodakimg.exe 1 1 0
lsp notepad.exe 0 1 1
txt notepad.exe 0 1 1
log notepad.exe 0 1 1
doc c:\progra~1\micros~2\office\winword.exe 0 1 1
xls c:\progra~1\micros~2\office\excel.exe 0 1 0
htm c:\progra~1\intern~1\iexplore 0 0 1
html c:\progra~1\intern~1\iexplore 0 0 1


The settings can be done (by an administrator for Windows NT or 2000) in the control pannel (control pannel/system/advanced/environment variables) or can be stored in a batch file. To make the process easier, this batch file can then be called from a shortcut.

set ve_lib=c:\progra~1\virterf\bin
path %path%;%ve_lib%;%ve_lib%\tcl\bin
set PATHEXT=%PATHEXT%;.tcl;.dll
set tcl_library=%ve_lib%\tcl\tcl8.3
cd d:\

Back to home page