Virterf Help File (obsolete)

Dr P.Smars, 2002

• Introduction
• Command Reference
• Database Structure
• Installation

Introduction

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:

• %load ve_wdb -- the main library, allowing to open a 3D window to show and edit the database
• ve_link -- a library to create link to external documents, loaded with ve_wdb
• %load ve_text -- an definable output destination for text (standard output or file)
• %load ve_unit_system -- a library allowing to define user unit systems, used in conjunction with ve_text
• %load ve_vtk -- a subset of ve_wdb, limited to vector graphic

Session management

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.

• %window_name reset -- reset the window view as it was when the program started (line of sight in the y-direction, focal point in the centre of the model)
  
• %window_name setviewpoint x y z -- set the viewpoint
  
• %window_name setfocalpoint x y z -- set the focalpoint
  
• %window_name getdistance -- return the distance between the view point and the focal point
  
• %window_name setdistance Value -- set the distance between the camera and the focalpoint
  
• %window_name setlogdistance Value -- set a logarithmic distance (-100:very close, +100: very far)
  
• %window_name getazimuth -- return the azimuth (horizontal angle between the line of sight and the y-axis)
  
• %window_name setazimuth Value -- set the azimuth (rotating the line of sight around the focalpoint)
  
• %window_name setyaw Value -- set the azimuth (rotating the line of sight around the viewpoint)
  
• %window_name getelevation -- return the elevation (angle between the line of sight and the z-axis)
  
• %window_name setelevation Value -- set the elevation (rotating the line of sight around the focalpoint)
  
• %window_name setpitch Value -- set the elevation (rotating the line of sight around the viewpoint)
  
• %window_name getroll -- return the roll (angle between the view-vertical and the z-axis)
  
• %window_name setroll Value -- set the roll (rotate aroung the line of sight)
  
• %window_name perspective Code -- set the projection mode (on: central, off: parallel)
  
• %window_name setcliprange front_value back_value -- set minimum and maximum distances at which the model is visible
  
• %window_name setbrightness Value -- change the brightness of the texture
  
• %window_name setopacity Front_value(0..1) Back_value(0..1) -- change the opacity of the model
  
• %window_name setambient Value(0..1) -- set an ambient light (default: 0.3)
  
• %window_name setforeground Red_value(0..1) Green_value(0..1) Blue_value(0..1) -- change the colour of the foreground
  
• %window_name setbackground Red_value(0..1) Green_value(0..1) Blue_value(0..1) -- change the colour of the model when no texture is applyed
  
• %window_name light code -- fix the light at the current viewpoint (sun) or make the light follow the viewpoint (spot)
  
• %window_name setfocaldepth value -- create the illusion of focal-depth, focus being set on the focalpoint
  
• %window_name cursor Code -- set the cursor mode (on: visible, off: not visible)
  

Interactors

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

The available interactors are:

• standard -- used to navigate around the model
• point -- used to draw points on points picked on the surface of the model
• line -- used to draw lines or polylines between points picked on the surface of the model
• cut -- used to draw section through the model
• dist -- used to get numerical information about a segment
• select -- used to select or de-select triangles
• block -- in development...
  

• Left button -- rotation around the focalpoint
• Shift + Left button -- translation
• Right button -- zoom
• keystroke 'w' -- show the model in wireframe
• keystroke 's' -- show the model as a solid
• keystroke '3' -- show the model as an anaglyph

• standard
  Ctrl + Left button: rotation around the axis of vision
  
• point
  Ctrl + Left button: draw a point on the model.
  Points can also be drawn from a console command.
  
• line
  Polylines are defined by a plane passing by two end points and by the view point
  For the first point:
  Ctrl + Left button: define the the first point & a straight line will be drawn
  Ctrl + Right button: define the the first point & a polyline will be drawn
  For the following points:
  Left button: the second point is defined, the segment (or polyline) is drawn and the second point become the origin of a new segment (or polyline), allowing the process to continue
  Right button: the process is interupted
  Lines can also be drawn from a console command
• cut
  The section plane is defined by 2 or 3 points.
  For the first point:
  Ctrl + Left button: define the first point & a general section line will be drawn (defined by 3 points)
  Ctrl + Right button: define the first point & a vertical section is drawn (defined by 2 points)
  For the next point(s):
  Left button: define a new point
  Right button: abort the process
  Sections can also be drawn from a console command
• dist
  A segment is defined picking its extremities. Their coordinates are returned, the distance (d) is computed as well as the distance along the axes (dx, dy, dz) and the orientation (altitude, azimuth and director cosines (cx, cy, cz)). This tool can be used for very different purposes, like controls of verticality or deformation. User Units can be used.
  For the first point:
  Ctrl + Left button: define the first point
  For the second point:
  Left button: define the second point
  Right button: abort the process
  
• select
  The interactor has got three modes (changed pressing a key):
  
  • selection one by one, by picking (p) default value
  • selection via a polygone, only the triangles inside being selected (i)
    
  • selection via a polygone, all the triangles inside and crossing the border being selected (o)
    
  In the (p) mode:
  Ctrl + Left button: select a triangle
  Ctrl + Right button: de-select a traingle
  In the (i) or (o) mode:
  For the first point:
  Ctrl + Left button: define the first point of a selection loop & start a selection process
  Ctrl + Right button: define the first point of a selection loop & start a de-selection process
  For the next points:
  Left button: define a new point of the loop
  Right button: stop the process & select (de-select) the triangles
  console commands can assist the process
  
• refine
  For the first point:
  Ctrl + Left button: define the first point
  For the second point:
  Left button: define the second point & refine the mesh
  Right button: abort the process
  
• block
  

Texture

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.

• %window_name settexture texture_name -- load and project a texture on the model
  
• %window_name listtextures -- return a list of the available textures
  
• %window_name texture code -- show or hide the texture (code: on, off)
  

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.

• %window_name newtheme a theme_name -- create a new theme and a new 'unknown' layer
  
• %window_name settheme a theme_name -- set the curent attribute theme
  
• %window_name gettheme a -- return the current attribute theme
  
• %window_name listthemes a -- return a list of the existing attribute themes
  
• %window_name erasetheme a theme_name -- erase an attribute theme
  
• %window_name newlayer a layer_name -- create a new layer in the current theme
  
• %window_name setlayer a layer_name -- set the current attribute layer
  
• %window_name eraselayer a layer_name -- erase an attribute layer
  
• %window_name getlayer a -- return the current attribute layer
  
• %window_name listlayers a -- return a list of the existing attribute layers
  
• %window_name applylayer a -- apply the curent attribute layer to the selected triangles
  
• %window_name save -- save the database (used during attribute themes editing)
  
• %window_name area -- return the total area (sum for the selected triangles), the absolute and relative area of the active theme's layers. It can be used for example to compute the surface of brick on a façade or the surface of the damaged tiles on a roof. The database basis unit is the one chosen for the reference's topographic measurements. Additional user units are definable (for distances and surfaces). In some cases, they can bring insight to the compositional process. Numerical results from the model interrogation are given in the basis and possibly in the user unit system.
  
• %window_name select code -- select a set of triangles (used in conjuction with applylayer or erase). The selection can also be done with an interactor.
  
  • %window_name select all -- select all the triangles
    
  • %window_name select none -- un-select all the triangles
    
  • %window_name select layero -- invert the selection set (un-select, selected triangles and select un-selected one)
    
  • %window_name select layera -- add the triangles belonging to the current layer to the selection set
    
  • %window_name select layerr -- select triangles belonging to the current layer from the selection set
    
  • %window_name select layerd -- suppress triangles belonging to the current layer from the selection set
    
• %window_name erase triangles -- erase the selected triangles
  

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.

• %window_name newtheme v theme_name -- create a new theme and a new '0' layer
  
• %window_name settheme v theme_name -- set the curent vector theme
  
• %window_name gettheme v -- return the current vector theme
  
• %window_name listthemes v -- return a list of the existing vector themes
  
• %window_name erasetheme v theme_name -- erase an vector theme
  
• %window_name newlayer v layer_name -- create a new layer in the current theme
  
• %window_name setlayer v layer_name -- set the current vector layer
  
• %window_name eraselayer v layer_name -- erase an vector layer
  
• %window_name getlayer v -- return the current vector layer
  
• %window_name listlayers v -- return a list of the existing vector layers
  
• %window_name point x y z -- draw a point in the active vector layer
  
• %window_name line x1 y1 z1 x2 y2 z2 -- draw a line in the active vector layer
  
• %window_name polyline x1 y1 z1 x2 y2 z2 -- draw a polyline between the projection of the 2 points on the model, in a plane defined by these 2 points and the viewpoint
  
• %window_name vertex x y z -- define a polyline vertex (used in conjunction with endpolyline or closepolyline)
  
• %window_name endpolyline -- link the vertex defined to draw a polyline & reset the vertex count
  
• %window_name closepolyline -- link the vertex defined to draw a polyline, close the polyline linking the last vertex with the first one & reset the vertex count
  
• %window_name cut x1 y1 z1 x2 y2 z2 x3 y3 z3 -- cut the model with a plane defined by 3 points
  
• %window_name layer layer_name code -- show (on) or hide (off) a vector layer
  
• %window_name setthickness value(1,2,3) -- set the pixel-thickness of the points and lines in the current vector layer
  
• %window_name setcolor Red_value(0..1) Green_value(0..1) Blue_value(0..1) -- set the colour of the points and lines in the current vector layer
  
• %window_name erase point -- erase points one by one, starting with the last drawn
  
• %window_name erase line -- erase lines one by one, starting with the last drawn
  
• %window_name erase polyline -- erase polylines one by one, starting with the last drawn
  

Links

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.

• %window_name addlink -- add a link to an external document
  
• %window_name links code -- show (on) or hide (off) the links relevant with the attribute theme
  
• %window_name listlinks -- return a list of the links
  

Links are created with ve_link

• %ve_link link_handle -- create a link and place it in the centre of the 3D window (defined using one of the interactors)
  
• %link_handle setname link_name -- give a name to the link
  
• %link_handle getname -- return the name of the link
  
• %link_handle setfile link_file -- set the name of the file refered by the link
  
• %link_handle getfile -- set the name of the file refered by the link
  
• %link_handle run -- open the file with the application set in the link.ext file
  

Import/Export

• %window_name import code file_name -- import some data
  
  • %window_name import dxf file_name -- import a dxf file (lines and points organised in layers), place the points and lines in the current vector theme and create layers if necessary
    
  • %window_name import lnk file_name -- import links coming from a file
    
  • %window_name import tri file_name -- import a triangle file
  • %window_name import vec file_name -- import vector data (lines and points organised in themes and layers) coming from a file and create themes and layers if necessary
    
• %window_name export -- export some data
  
  • %window_name export dxf_a file_name -- export a dxf file with the selected triangles, create layers corresponding with the attribute layers
    
  • %window_name export dxf_v file_name -- export a dxf file with the points, lines and polylines in the current vector theme
    
  • %window_name export jpg file_name -- export a jpg file of the current view
    
  • %window_name export tif file_name -- export a tif file of the current view
    
  • %window_name export vrml file_name -- export a vrml file of the current scene (the angle should be changed...)
    
  • %window_name export vtk file_name -- export a vtk file of the current scene in the Visualisation Toolkit format
    
  • %window_name export xml file_name -- export a xml file of the current scene (under development)
    
  • %window_name export lnk file_name -- export a file with all the links
    
  • %window_name export vec file_name -- export a file with all the vector data
    
  • %window_name export rib file_name -- export a rib file to use for rendering with bluemoon
    

ve_text

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

• %load ve_text -- load the library in the tcl interpreter
• %ve_text text_name -- create a ve_text object.
• %test_name output code -- print results to the output (code: on=default, off). can be used to switch off the results output.
• %test_name unit code -- print results using the user unit system (code: on, off=default). can be used to switch off the user unit system when printing numbers who don't have to be formatted.
• %test_name put text -- print text
• %test_name putd value -- print number
• %test_name setfile file_name -- set the output channel. if file_name=standard, the output will be the standard output, otherwise it will be a text file named accordingly.
• %test_name setunit ve_unit_system-object -- set the user unit system which is going to be used to print numericals results
• %test_name getunit -- get a handle to the user unit system
• %test_name setdimension value -- set the dimension of the next output numbers (value: 1,2)

ve_unit_system

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

• %load ve_unit_system -- load the library in the tcl interpreter
• %ve_unit_system unit_name -- create a ve_unit_system object
• %unit_name open file_name -- load a file (*.uni), defining the unit system
• %unit_name dim1 number -- print a 1-dimensional number
• %unit_name dim2 number -- print a 2-dimensional number
• %unit_name getname -- return the name of the unit system