Teseo2 User Manual
Turn the Eldest Seismograms into the Electronic Original Ones - 2.0.14

Stefano Pintore, Matteo Quintiliani

Istituto Nazionale di Geofisica e Vulcanologia, Roma, Italy

* * *
This documentation needs further updates.
Revision: 1.61 - Date: 2006/08/08 08:19:21
Please, check last revision at http://sismos.ingv.it/teseo/


Contents

1 Introduction

This document is the user manual of Teseo2 software - Copyright © 2005 - Stefano Pintore, Matteo Quintiliani. Revision: 1.61 - Date: 2006/08/08 08:19:21 .

Teseo2 is a software tool for seismogram digitization/vectorization and it is developed in the framework of the Sismos project [Michelini and the Sismos Team, 2005] at Istituto Nazionale di Geofisica e Vulcanologia (Italy). This name was inspired by the myth of Theseus and it is also an acronym for Turn the Eldest Seismograms into the Electronic Original Ones.

Teseo2 is a plug-in for GIMP - GNU Image Manipulation Program - that extends its functionalities for seismological studies. The GIMP is a multiplatform photo manipulation tool freely distributed. It works on many operating systems, in many languages.

Teseo2 allows primarily for:

In order to keep track of the stages and parameters of a seismogram vectorization, Teseo2 is able to write this information into the image saved in xcf format.

Teseo2 is developed following the ''Open-Source'' philosophy and it is freely distributed under GPL license. It is cross-platform and the sources, the binaries for Linux, Windows and Mac OS X, are periodically updated on the Sismos web site.

Official web site: http://sismos.ingv.it/teseo/

Developer e-mail: teseo@ingv.it

User mailing-list: teseo-user@yahoogroups.com

ML archive: http://groups.yahoo.com/group/teseo-user/

2 Installing Teseo

Before installing Teseo2 you need to install GIMP 2.2. Teseo2 has never been tested on GIMP 2.0.

Please refer to the official website at http://www.gimp.org/, user manual [Gimp, 2005] and books [Bunks, 2000], [Kylander and Kylander, 1999], for any information about it.

Teseo2 is developed on Linux but binaries are also available for other platforms such as Windows and Mac OS X. You can be able to compile Teseo2 on every system where GIMP has been successfully installed. Sources and some binary distributions can be downloaded at the official web site, http://sismos.ingv.it/teseo/

In this manual we provide basic information to install Teseo2 plug-in. For specific information, please follow instructions contained in the INSTALL file for your distribution.

2.1 Teseo from Source

Teseo2 is mostly developed in C language, one library is written in Fortran. In order to compile Teseo2 you need gcc, g77 and libg2c.

In general, Teseo2 works with GIMP 2.2, although version 2.2.6 or newer is recommended. We develop Teseo2 using GTK+ and GLib. GTK+ is a library for creating graphical user interfaces. GLib is a general-purpose utility library, which provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on. The versions of GTK+ and GLib are the same used by GIMP.

Moreover, Teseo2 use a GTK+ widget called GtkDataBox which has been designed to display large amounts of numerical data fast and easy. Version greater than 0.4.0 is required. Please, refer to the section 8 for downloading and documentation about GtkDataBox.

Teseo2 sources are subdivided into three separate modules: two libraries (gtk-addons, newuoa) and the GIMP plug-in (teseo-2). Unpack the file teseo-2.x.x.tar.gz and compile the source modules following this order: gtk-addons, newuoa and teseo-2. You can use the stardard command sequence:

./configure
make
make install

For teseo-2, you should launch the configure script with the same prefix of gimp-2.2 and, optionally, set the datadir. For example, if gimp-2.2 is configured with --prefix=/mydir, you have to use:

./configure --prefix=/mydir --datadir=/mydir/share/gimp/2.0

2.2 Teseo for Linux

First of all, install GIMP. Version 2.2.6 or newer is recommended.

Unpack the binary distribution from teseo-2.x.x-bin-linux.tar.gz and run these commands to install Teseo2:

cd teseo-2.x.x-bin-linux
./setup.sh linux

setup.sh needs gimptool-2.0 included in GIMP distributions.

To uninstall run:

cd teseo-2.x.x-bin-linux
./setup.sh linuxuninstall

2.3 Teseo for Windows

2.4 Teseo for Mac OS X

To install Teseo2 on Mac OS X you have 2 possibilities.

  1. Download DMG image that contains Gimp.app with teseo-2 bundled
    (DMG image is about 72 MB)

  2. Download binary distribution pack and use shell script configuration:
    (Distribution is about 1 MB)

    First of all, install GIMP. Version 2.2.6 or newer is recommended.

    Unpack binary distribution teseo-2.x.x-bin-macosx.tar.gz

    cd teseo-2.x.x-bin-macosx
    ./setup.sh macosx /Applications/Gimp.App

    To uninstall run:

    cd teseo-2.x.x-bin-macosx
    ./setup.sh macosxuninstall /Applications/Gimp.App

    If Gimp.app doesn't reside in Applications folder, change it with the correct path.

3 Getting started with Teseo

Teseo2 works only on grayscale images and it could work on any image format manageable by GIMP. We prefer working only on xcf format, the GIMP proprietary format, for several reasons:

To start Teseo2 you have to:

  1. Start GIMP.
  2. Open seismogram image. The image must be converted in grayscale (Image$\rightarrow$ Mode$\rightarrow$ Grayscale in GIMP context) and then saved in xcf format.
  3. Select Teseo-2 from Teseo menu (figure 1). Alternatively, you can use the context menu on the image (right-clicking) or by a customized shortcut.

Figure 1: Teseo menu
Image snapshot1

Warning: When Teseo2 is launched, it is automatically ''linked'' to the image by the GIMP. We suggest to vectorize one image at a time and to respect the following order using Teseo2: open image, open Teseo2, close Teseo2, close image. The name of the image is visible in the main window of Teseo2. If you close the image before Teseo2, then close Teseo2 before reopening the image. Moreover, if you rename the image, Teseo2 work well but the references to the correct session are lost. In this case, we strongly recommend to open Teseo2 only after renaming the image.

Warning: If Teseo2 crashes or GIMP is closed before Teseo2, the session linked to the image remains locked. Next time you open Teseo2 on the same image, a warning message will be shown asking for forcing the session unlock. This mechanism is useful to prevent multiple instances of Teseo2 for the same image: only one instance for each image is allowed for a correct vectorization.

3.1 Session

Teseo2 associates to the image some information related to seismogram paper, seismic event, station data and vectorization parameters. This information is saved in a session and it is referred to a single seismic event.

When you start Teseo2 for the first time on an image, you are required to create a new session. Fill the fields shown in the figures 2, 3, 4, and click OK.

Session properties can be modified at any time selecting File$\rightarrow$ Session$\rightarrow$ Properties (Ctrl+P in Teseo2 context). New sessions related to other events in the same image can be created selecting File$\rightarrow$ Session$\rightarrow$ New (Ctrl+N in Teseo2 context). The user can not change session file name because Teseo2 uses a fixed session naming convention.

Files related to the session are stored in gimp_directory/teseo-2, where gimp_directory is the user-specific GIMP settings directory. Usually, it is the subdirectory .gimp-2.2 in the user home directory.

When Teseo2 is started on an image associated to more sessions, the user can choose the preferred one. All the parameters described below are saved in the session file and, on demand, they can be imported or exported in Teseo2 parasites (section 3.2) and saved in the xcf image.

Figure 2: Session window - Record tab
Image snapshot2

In figure 2 are shown the parameters associated to the seismic record.

Figure 3: Session window - Traces tab
Image snapshot3

In figure 3 are shown the parameters associated to the traces.

Figure 4: Session window - Path tab
Image snapshot4

In figure 4 are shown the parameters associated to the path manipulation.


3.2 Teseo parasites

In order to share and distribute results about the vectorization of a seismogram, Teseo2 includes all information related to the seismogram and his vectorization within a single file. This can be made using GIMP proprietary image format: the xcf format. In fact, xcf format stores paths, layers, channels and ''parasites'', a mechanism provided by GIMP for attaching arbitrary pieces of data to an image.

Teseo2 parasites contain all parameter values for the current session. When you import or export a session as parasites you have to consider the Event number (see figure 2). Remember that Event number is arbitrary and it could be thinked as the ordinal number associated to the sequence of the events occurred in the same Date. You can export only one set of the parameters for each single event.

Parasite operations are:

Warning: When parasites related to an image are modified, remember to save the image before closing it. GIMP won't give you any advice before leaving the image.

4 Vectorization

Teseo2 trace vectorization completely relies on GIMP Path tool, which permits to create piecewise cubic Bézier curves and polygonals. Please, see [Gimp, 2005] for basic usage.

Warning: Teseo2 does not support closed paths.

Warning: Seismogram must be oriented from left to right and top to bottom. If necessary you can use GIMP tools such as Flip or Rotate to modify the image ;-)


4.1 Multiple components in a path

Warning: Unfortunately, GIMP plug-in developers do not have yet available procedures (API) to handle paths with two or more components. User must not create multiple components in a single path.

If you accidentally generate a path containing multiple components you can combine them following these steps:

  1. Export the path in SVG format using the GIMP Path Dialog.
  2. Import the path using the Teseo2 Menu File$\rightarrow$ Path$\rightarrow$ Import$\rightarrow$ SVG Combine. This procedure import the path and link sequentially the components each other.
  3. The previous steps could reverse the points order of the path. In this case use Path$\rightarrow$ Flip in the Teseo2 main window.

4.2 Manual

You can manually vectorize the traces by GIMP Path tool creating several piecewise cubic Bézier curves or polylines.

You should improve your manual dexterity before facing up to a complicated seismogram. Inside the distribution you find a very simple piece of seismogram to test your skill, the file name is example.xcf.gz. Keep in mind that the whole vectorization is based on GIMP Path tool and it is wise to learn as much as possible about it.

example.xcf.gz contains a few paths manually made and others made by the Teseo2 colour weighted mean algorithm, which will be described in the next section 4.3.


4.3 Automatic

Teseo2 is designed to easily add algorithms for automatic seismogram vectorization. An iterative procedure takes place whereby at each step the algorithm is executed providing it with:

in order to find the next point.

Presently, Teseo2 uses an algorithm based on a weighted mean of the trace colour (see subsection 4.3.1)

In future versions of Teseo2 more algorithms should be available (neural network approach too) and will be associated to other buttons beside CWM one.

In figure 5 the main parameters of Teseo2 automatic path vectorization tool are shown:

The arrow buttons on the main window become sensitive when the user chooses an algorithm to execute. To calculate the next point, the algorithm can use the additional information provided by the user who suggests a direction clicking on arrow buttons.


4.3.1 Colour Weighted Mean

For detailed information about this algorithm read [Pintore et al., 2005].

The colour weighted mean algorithm takes a rectangular region of the image having width and height specified in tab shown in figure 6 and centered into the last point of the current path. This algorithm is activated clicking on the colour weighted mean button on the toolbar in figure 5.

The arrow buttons are available to suggest the direction.

Figure 5: Teseo window - General tab
Image snapshot6

Figure 6: Teseo window - Colour weighted mean tab
Image snapshot7

4.4 Path manipulation

Besides GIMP Path manipulation, Teseo2 adds some useful operations in seismogram vectorization. In figure 7 is shown the Teseo2 Path menu. The operations are subdivided in three groups: operations on the current path, operations on all unlocked paths and operations on path that represent Timemark. Some operations rely on GIMP vertical guides tool: you can place a vertical guide clicking on the ruler on the left of the image window and dragging it onto the image at the desired place.

Figure 7: Teseo window - Path menu
Image snapshot8

Warning: Order in operations on multiple paths respects order of the GIMP Path tool, that is from bottom to top. For example, executing a link on paths shown in figure 8 results in a new path concatenating paths a, b and c in this order.

Figure 8: GIMP Path Tool - Path order
Image snapshot9


4.5 Trace import/export

Teseo2 imports and exports several file formats:

Up to now, SVG export is possible only by GIMP Path tool, DXF import is possible only on Teseo2 exported paths, SAC import is not implemented yet.

4.6 Filters

GIMP offers a variety of filters and instruments to manipulate images. We strongly recommend to enhance the ''readability'' of your seismogram before vectorize. For example you could increase the contrast of the image.

Warning: If you want save the history of the changes applied to the image, you may apply the filters on copies of the ''Background Layer''. Remember that all operations usually work on the current layer which could not necessarily be the visible one.

At the moment, Teseo2 provides a graphical filter useful to clean a seismogram. What do we intend to clean a seismogram? Often, before vectorizing, it is advantageous to remove horizontal traces crossing it while mantaining trace continuity. The main idea is to fill unwanted horizontal or vertical segments with the background color of the seismogram.

Warning: Good results are obtained when the noisy lines are perfectly horizontal. You can estimate required rotation using GIMP Measure tool and then using GIMP Rotate trasformation tool to rotate effectively. See GIMP help.

In figure 9 it is possible to see the parameters related to the clean filter.

Figure 9: Teseo Filter Clean
Image snapshot12

If you've never used this filter you should try it on the example image contained in your Teseo2 distribution. Follow these steps:

  1. Open example.xcf.gz
  2. Select the ''Background'' layer inside the GIMP Layer Dialog and apply the filter using the following parameters:

  3. A layer named ''Background copy'' will be created.

  4. Select the ''Background'' layer and apply the filter using the following parameters:

  5. A layer named ''Background copy #1'' will be created.

  6. Select the layer named ''Background copy'' and set the layer parameter Mode to Multiply.

Nice! Isn't it?

An animation of this operation is available on http://sismos.ingv.it/teseo/filters/.

5 Analysis after trace vectorization

The seismogram curve on the image has to be corrected to become a seismic data with right amplitude and time. There are many errors that could be introduced during the digitization procedure that must be taken into account.

Several different corrections have to be applied too in order to eliminate errors due to the recording system of the seismograph.

5.1 Curvature correction

For semplicity we suppose that speed is a constant for the path segment we consider, otherwise we can subdivide path in segments at constant speed, for example from a time marker to the subsequent. Then we can correct the resulting paths one by one.

Figure 10: Mechanical recording schema. Figure provided by A. Schlupp.
Image figure_III.2

The formula for correction of the deformation due to the geometry of the recorder, as well as coordinate conversion (x,y) in time and amplitude, are given by Cadeck:


\begin{displaymath} t(i)= \frac{60}{d} \{ x(i) -r \frac{ arcsin \{ r^2+a^2 -R^2 ... ...}}{ 2 a r } + r \frac{ arcsin ( r^2+a^2 -R^2 +b^2 )}{2 a r} \} \end{displaymath}

where:

R = length of the writing arm, from its rotating axis to the tip of the needle
r = radius of the drive cylinder bearing the smoked paper
a = distance from the rotating arm axis to the driving cylinder axis
b = shift of the arm axis, in millimeters, to the base line on the smoked paper
d = minute length on the original record in millimeters
x(i) = coordinate to transform in seconds for time axis
y(i) = coordinate to transform in millimeters for amplitude axis

This formula applies to intruments modeled as in the schema shown in figure 10. To use this formula, it is necessary to get information about the seismogram. For well known machinery, r, R and a can be retrieved from manufactory papers (figure 10). Otherwise it is possible to adjust these parameters to reasonable values by trial and error. The d value is proportional to speed and resolution.

Figure 11: Mechanical recording schema, details on b. Figure provided by A. Schlupp.
Image figure_III.3

The b value is the most difficult to determine and must be deduced directly from records, see figure 11. A detailed description of the method to evaluate b is available in [Schlupp, 2006].

Figure 12: Curvature Correction window
Image snapshot16

Look at figure 12, showing the Curvature Correction window. You obtain this window clicking on Curvature Correction from Post Analysis.

Figure 13: Plot of the function Error(b)
Image snapshot14

6 Before leaving Teseo

Before closing GIMP is a very good practice to:

  1. Save session (Ctrl+S in Teseo2 context)
  2. Close Teseo2.
  3. Save xcf file, it contains all your paths, layers and Teseo2 parasites. xcf is your friend and gzip or bzip2 too.
  4. Close GIMP.

7 Mailing list and bug report

If you would like to:

at the moment, the best way is subscribing the mailing list devoted to the Teseo2 users: feel free to send an e-mail to teseo-user-subscribe@yahoogroups.com . However, the archive of the messages is open to everybody at http://groups.yahoo.com/group/teseo-user/

7.1 Bug report

Teseo2 is not a bug-free application, so if you find a bug, please report it sending an e-mail to teseo@ingv.it

Please, remember to specify:

We will provide a bug tracking system if necessary.


8 Credits

Teseo2 source distribution contains code developed by other authors and distributed respecting their copyright or license:

Main package dependencies are:

9 Acknowledgements

We would like to thank A. Schlupp for his contribution in the Curvature Correction development. We are also grateful to A. Michelini for his continuous encouragement and to S. Mazza for his useful and constructive suggestions.

10 Warnings

In this section are resumed all warnings contained in the manual.



starttoclow


List of Figures

Bibliography

Autodesk, 1992
Autodesk (1992).
AutoCAD Release 12 DXF Format.
Adobe Systems Incorporated - 1585 Charleston Road - P.O. Box 7900 - Mountain View, CA 94039-7900.
Drawing Interchange and File Formats Release 12.

Bunks, 2000
Bunks, C. (2000).
Grokking the GIMP.
New Riders Publishing, Thousand Oaks, CA.
352pp.

Cadek, 1987
Cadek, O. (1987).
Studying earthquake ground motion in prague from wiechert seismograph records.
Gerl. Beitr. Geoph., 96:438-447.

Gimp, 2005
Gimp (2005).
GNU Image Manipulation Program User Manual.
The GIMP Documentation Team.
URL http://docs.gimp.org/.

Goldstein et al., 2003
Goldstein, P., Dodge, D., and Firpo, M. (2003).
SAC2000: Signal processing and analysis tools for seismologists and engineers.
In Lee, W., Kanamori, H., Jennings, P., and Kisslinger, C., editors, International Handbook of Earthquake & Engineering Seismology, Part B, pages 1613-1614, New York. Academic Press.

Kylander and Kylander, 1999
Kylander, O. and Kylander, K. (1999).
Gimp the Official Handbook with Cdrom.
Coriolis Value.
895pp.

Michelini and the Sismos Team, 2005
Michelini, A. and the Sismos Team (2005).
Collection, digitization and distribution of historical seismological data at ingv.
EOS, 86(28).

Pintore et al., 2005
Pintore, S., Quintiliani, M., and Franceschi, D. (2005).
Teseo: a vectoriser of historical seismograms.
Computers & Geosciences, 31(10):1277-1285.

Schlupp, 2006
Schlupp, A. (2006).
Personal communication.

SVG Working Group, 2003
SVG Working Group (2003).
Scalable Vector Graphics (SVG) 1.1 Specification.
URL http://www.w3.org/TR/2003/REC-SVG11-20030114/.


Index

Buttons
Arm Shift
5.1
Arm shift button
5.1
Axial distance
5.1
Axial distance button
5.1
Correct
5.1 | 5.1
OK
3.1
Slopes
5.1 | 5.1
File formats
ASCII
1 | 4.5
Bézier
4.5
DXF
1 | 3.1 | 4.5 | 4.5
Examples
4.5
SAC
1 | 3.1 | 3.1 | 4.5 | 4.5
SISMA
4.5
SVG
1 | 4.1 | 4.5 | 4.5
Timemark
4.5
Trace
4.5
xcf
1 | 3 | 3 | 3 | 3 | 3 | 3 | 3.1 | 3.2 | 3.2 | 3.2 | 3.2 | 3.2 | 6 | 6
Filters
clean
4.6 | 4.6
GIMP
1 | 2 | 2 | 2 | 2.1 | 2.1 | 2.1 | 2.2 | 2.2 | 2.3 | 2.3 | 2.4 | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 3.1 | 3.2 | 3.2 | 3.2 | 3.2 | 4 | 4 | 4 | 4.1 | 4.1 | 4.1 | 4.2 | 4.2 | 4.4 | 4.4 | 4.4 | 4.4 | 4.4 | 4.4 | 4.4 | 4.4 | 4.5 | 4.5 | 4.6 | 4.6 | 4.6 | 4.6 | 4.6 | 4.6 | 4.6 | 4.6 | 6 | 6 | 7.1 | 7.1
GIMP tools
Flip
4 | 4
Measure
4.6 | 4.6
Path
4 | 4.2 | 4.2 | 4.4 | 4.4 | 4.4 | 4.5
Rotate
4 | 4 | 4.6 | 4.6
GLib
2.1 | 2.1 | 2.1
GTK+
2.1 | 2.1 | 2.1 | 2.1
Keywords
CWM
4.3
parasites
3 | 3.1 | 3.2 | 3.2 | 3.2 | 3.2 | 6
seismic event
3.1
session
3.1 | 3.1 | 3.2 | 3.2
Menu
Curvature Correction
5.1 | 5.1
Post Analysis
5.1
Teseo
3
Teseo-2
3
Parameters
a
5.1 | 5.1 | 5.1 | 5.1
Arm length entry
5.1
Arm shift entry
5.1 | 5.1
Axial distance entry
5.1
Azimuth
3.1
b
5.1 | 5.1 | 5.1 | 5.1 | 5.1 | 5.1 | 5.1 | 5.1 | 5.1
Back
4.3
Base colour
4.6 | 4.6 | 4.6
Choose
5.1
Constant abscissa ascendent
3.1
Cylinder radius entry
5.1
d
5.1 | 5.1
Date
3.1 | 3.2
Elevation
3.1
Event first sample time
3.1
Event number
3.1 | 3.2 | 3.2
Export DXF path relocated in origin
3.1
Fill colour
4.6 | 4.6 | 4.6
Final X
5.1
Final Y
5.1
Forward
4.3
Greater
4.6 | 4.6
Horizontal
4.6 | 4.6
Image file
3.1
Incident angle
3.1
Lateral velocity
5.1
Latitude
3.1
Length
4.6 | 4.6 | 4.6
Less
4.6 | 4.6
Longitude
3.1
Mode
4.6
Name
3.1
New layer
4.6 | 4.6 | 4.6
Paper speed
3.1
Paper velocity velocity
5.1
R
5.1 | 5.1 | 5.1 | 5.1 | 5.1 | 5.1
Resampling step
3.1
Resolution
3.1
Return directly Bézier path
3.1
Rotate
5.1 | 5.1
Scan rotation
5.1
Shift
5.1 | 5.1
Starting X
5.1
Starting Y
5.1
Station data
3.1
Stop to the first guide
4.3
Threshold
4.6 | 4.6 | 4.6
Time mark first sample time
3.1
Time span
5.1
Time span entry
5.1
Trace colour
4.3
Trace thickness
4.3
Transparent
4.6 | 4.6 | 4.6
Use extrema
5.1 | 5.1 | 5.1 | 5.1 | 5.1
Use raster angle
5.1
Use time span
5.1 | 5.1
Vertical
4.6 | 4.6
x(i)
5.1
y(i)
5.1
Software development
g77
2.1
gcc
2.1
GLib
2.1 | 2.1 | 2.1
GTK+
2.1 | 2.1 | 2.1 | 2.1
GtkDataBox
2.1 | 2.1
libg2c
2.1
Teseo modules
gtk-addons
2.1 | 2.1
newuoa
2.1 | 2.1
teseo-2
2.1 | 2.1 | 2.1
Teseo operations
Align unlocked paths
4.4 | 4.4
Link unlocked paths
4.4
Parasite Export
3.2
Parasite Import
3.2
Parasite Remove all
3.2
Path Fit
3.1 | 4.4
Path Flip
4.4 | 4.4
Path Force Polyline
4.4
Path Resample
4.4
Path Snap
4.4
Path Split
4.4
Timemark - Add TMs from guides
4.4
Timemark - Evaluate intermediate TMs
4.4

About this document ...

Teseo2 User Manual
Turn the Eldest Seismograms into the Electronic Original Ones - 2.0.14

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -style teseo2_user_manual_personal.css -image_type png -show_section_numbers -no_navigation -split 0 -address 'Matteo Quintiliani, Stefano Pintore - teseo@ingv.it' teseo2_user_manual

The translation was initiated by mtheo on 2007-01-15

Matteo Quintiliani, Stefano Pintore - teseo@ingv.it