Seismon Documentation Project

Stefan Mertl


Table of Contents

Seismon User Guide
1. Seismon installation
2. Running Seismon
3. Seismon basics
4. Using Seismon
Tutorials
1. Seismon Basics
Seismon Developer's Guide
1. Introduction
2. Tracedisplay Tools

Seismon User Guide

Stefan Mertl



List of Figures

2.1. The Seismon GUI
2.2. Select the menu create new user
2.3. create new database user dialog box
3.1. select the menu new project
3.2. create new project dialog
3.3. create new project dialog with an example user input
3.4. database login dialog
3.5. The Seismon GUI after a new project has been created.
3.6. select the load project menu item
3.7. select the project file to load
3.8. select the user
3.9. login to the database
3.10. Select the collection→new menu.
3.11. Enter the desired name in the popup dialog.
3.12. The new collection name on top of the collection listbox.
3.13. Select the category to which the module is assigned to.
3.14. Add the selected module by selecting the add menu of the context menu.
3.15. The added module will appear in the collection listbox.
3.16. Select the Autodrm import bulletin module in the collection listbox.
3.17. Select the edit menu
3.18. Add files using the context menu (right mouse click in the listbox).
3.19. The selected files are shown in the listbox.
3.20. Select the collections→load in the collection listbox context menu.
3.21. Select the collection to load in the collection selection dialog.
3.22. The loaded collection with the name "another collection" contains two modules.
3.23. Example collection holding 4 modules.
4.1. Classical geometry setup with each station holding a unit with 3 sensors.
4.2. A geometry layout example showing 6 stations and one unit having 6 sensors (e.g. 6 vertical component geophones). Each sensor is assigned to an individual station. This layout might represent a small seismic profile layout.
4.3. Add the edit units database module to the collection.
4.4. Execute the edit units database module.
4.5. Select the file ↦ import ASCII menu.
4.6. The imported units will appear in the dialog window.
4.7. Add the module edit stations database to your collection.
4.8. Execute the moduel.
4.9. Open the file selection dialog.
4.10. The imported stations will appear in the window.
4.11. Add or remove units using the context menu.
4.12. Add or remove sensors of a unit.
4.13. Select the field that you like to edit (e.g. the sensor serial field holding the value 2)
4.14. Click the right mouse button to open the edit dialog.
4.15. Use the context menu of the stations listbox to add or remove a station.
4.16. Select the field that you like to edit (e.g. the name field holding the GB01 value).
4.17. Click the right mouse button to open the edit dialog.
4.18. Edit the sensors assigned to the station using the context menu of the sensors table.

Chapter 1. Seismon installation

Stefan Mertl

2010-04-02

Introduction

SeisMon is a MATLAB program and therefore should run on different operating systems without any problems or limitations. You should ensure, that you are using the newest version of MATLAB and that you have got the required toolboxes and third party software installed. The following section lists the requirements needed to run Seismon on your computer.

Requirements

The following software packages are needed to run Seismon:

How to obtain Seismon

Seismon can be downloaded from my homepage http://www.stefanmertl.com/science/software/seismon/ . Before downloading you have to register to the site. After registering you get access to the download area.

To get the most recent code from an SVN server, you can use a SVN client. On windows I recommend Tortoise SVN and on Linux you should find a SVN client bundled with your distribution.

Installing the Seismon source code

  1. Download the latest Seismon release.

  2. Create a directory of your choice where to install the Seismon code to.

  3. If you have downloaded a Seismon release, extract the downloaded Seismon release (seismon-X.Y.Z.zip) into this directory. A directory named seismon-X.Y.Z (the SEISMON_ROOT directory) will be created.

    If you are using SVN, than you can checkout the code into the directory of your choice.

Database setup

Seismon is based on the open source SQL server MySQL. You can find the documentation of the MySQL products at dev.mysql.com/doc/. The program files can be downloaded at dev.mysql.com/downloads/. The following sections will give you instruction how to install the database tools needed to run Seismon.

Database server installation

Seismon requires the MySQL database server (at least version 5.0.2). If you are using Linux, you might install the MySQL database server from your distribution’s installation medium. Try this possibility first to ensure a server configuratioin adjusted to your system. But make sure to check the MySQL server version. If your distribution doesn’t provide the MySQL server package or if you are using different operating system than Linux, then follow the link dev.mysql.com/downloads/mysql/ to download the current release of the MySQL database server software. Install the MySQL database server following the instructions in the MySQL documentation. No special database setup routines have to be carried out prior to using Seismon. The only requirement is, that you need to know the database root password.

Java database connector (JDBC) setup

To enable Matlab© and Seismon to communicate with the MySQL database server software, the Java Database Connector (JDBC) has to be installed. Download the database connector from the MySQL homepage (dev.mysql.com/downloads/connector/j/) or install it from your Linux distribution’s installation medium. If you download the JDBC from the MySQL homepage, look for a tool called Connector/J in the connectors section of the MySQL download homepage. Now you need to tell Matlab to use the JDBC and where to find it. This involves the following steps:

  1. Find the name of the Java jar file that contains the JDBC drivers. For example, if you are using the MySQL JDBC version 5.1 this file would be named mysql-connector-java-5.1.10-bin.jar. You can find this file in the zipped archive that you have downloaded from the MySQL homepage. The name of this file may differ depending on the version and operating system that you are using, but it should be named similiar to the example given above.

  2. Specify the location of the drivers file (the .jar file mentioned above) in the MAGLAB Java classpath. To do this, add this file’s path to the Matlab® classpath.txt file. You can find this file in the MATLAB_ROOT/toolbox/local/ directory. For example you might have stored your JDBC file in the following location: /usr/share/java/mysql-connector-java-5.1.10-bin.jar. Than you have to add the complete path including the filename of the jar file (/usr/share/java/mysql-connector-java-5.1.10-bin.jar) to the classpath.txt file.

  3. In case that Matlab® is running, restart Matlab® before you access the database.

  4. f the JDBC drivers file is not located where the classpath.txt indicates, Matlab© doesn’t display errors, but it does not establish a database connection. make sure, that you update the classpath.txt file with the correct locatioin and filename of your drivers if the path and/or name of the JDBC .jar file changes.

MySQL GUI tools

Downlaod and install the MySQL GUI tools (MySQL Adminstrator, MySQL Query Browser) from dev.mysql.com/downloads/gui-tools. These tools are not required to run Seismon, but may be a help to maintain your Seismon database.

Test the database connection

To test the database connection, you can run the script testSeismonDatabaseConnection.m located in the SEISMON_ROOT folder. This script tries to connect to the MySQL database using the JDBC. You will be asked for the MySQL Server root password. If the script can't connect to the database, please check that the MySQL server is running and that the path to the JDBC .jar file is set correctly.

Chapter 2. Running Seismon

Starting Seismon

To start Seismon, you first have to start Matlab. Change the Matlab Current Folder to your Seismon root directory (e.g. /opt/local/seismon). Type the command seismon in the Matlab command window and hit enter. After this, Seismon will start showing the Seismon splash screen until the Seismon initialization has been finished and the Seismon GUI appears on the screen.

When running Seismon for the first time, some installation routines will be executed automatically. This installation includes the compilation of some C-coded source files using the Matlab Mex compiler. During this compilation, you might be asked to specify a C-compiler. The programs should compile without an error using the LCC compiler shipped with Matlab. On Linux systems you can use the GCC compiler. If you are using a Windows 64-bit operating system, then the LCC compiler is not available. In this case, you can use the free Microsoft Visual Studio 2008 Express Edition. Please follow the instructions of the Matlab® solution How can I set up Microsoft Visual Studio 2008 Express Edition for use with MATLAB 7.7 (R2008b) on 64-bit Windows XP? to use a C-compiler on a 64-bit windows system. If you have any problems with your C-compiler you can check the Matlab® compatibility here.

The Seismon GUI

After the Seismon initialization has finished, the Seismon GUII appears on screen.

<title>Seismon GUI</title>
The Seismon GUI

Figure 2.1. The Seismon GUI


The Seismon GUI is divided into two main sections: on the left side, you can see the Collection section and on the right there is the Module section. In the Collection section you can find the Collection listbox and the Collection execute button. The Module section is divided into the Module category popup and the Module listbox.

On top there is the Seismon menu bar. After startup only the File, the Database and the Help menus are activated.

The Seismon database user

To work with Seismon, you first have to create a MySQL database user. This database user is used by Seismon to create all the tables needed for a Seismon project One can create multiple projects using the same user.

When running Seismon with the MySQL database server running on the same computer (localhost), then one can use the Seismon GUI to create the Seismon database user. If a remote MySQL database server is used, please follow the instructions given in the section Creating a user using MySQL commands to create the database user. To create the Seismon database user you have to know the MySQL server root password. This is needed, because to create the new database user, a root login to the MySQLdatabase server is needed.

You can create one or more database users, depending on your needs.

When creating a Seismon database user, a MySQL database named seismon_USERNAME is created. All database tables created with the user named USERNAME will be stored inside this database.

Creating a user using the Seismon GUI

Please follow these steps to create a MySQL database user having the MySQL server running on localhost.

  1. Start Seismon

  2. Select the menu Databasecreate new user

    <title></title>
    Select the menu create new user

    Figure 2.2. Select the menu create new user


  3. Enter the root password, the desired username and the password into the dialog box. If no password is needed, leave the password field empty.

    <title></title>
    create new database user dialog box

    Figure 2.3. create new database user dialog box


  4. Hit the ok button to confirm the values.

Creating a user using MySQL commands

Seismon as a multi-user system

Chapter 3. Seismon basics

Seismon project

When using Seismon, you can organize its work in socalled projects. A project holds several information about the used data (e.g. seismic data, station geometry) as well as the user relevent settings. For each project, a set of database tables, a directory structure and a project file is created. The database tables are created inside the user's database (named seismon_USERNAME). Each database table name gets the Seismon project name as a prefix.

Creating a Seismon project

Before creating a Seismon project, please make sure, that you already have created a Seismon database user (see The Seismon database user).

  1. Select the menu Filenew project

    <title></title>
    select the menu new project

    Figure 3.1. select the menu new project


  2. The Create a new project dialog will appear.

    <title></title>
    create new project dialog

    Figure 3.2. create new project dialog


  3. Fill in the project parameters

    • project name

      The name of the project.

    • base directory

      The directory, where to create the project directory structure. Inside the specified base directory, a directory with the project name will be created. This directory holds all the project relevant files and directories. I will refer to this newly created directory as PROJECT_DIR

    • connector

      The database connector used to make Matlab talk to the database server. Currently there's only the JDBC option to select.

    • db server

      The URL or ip address of the database server. If the server runs on the computer as you are working on, then localhost should be entered.

    • username

      The user with which you'd like to create the project. All the database tables linked to the new project will be created inside the user's database (see The Seismon database user).

    <title></title>
    create new project dialog with an example user input

    Figure 3.3. create new project dialog with an example user input


  4. Confirm your choices by clicking the ok button.

  5. The database login dialog will appear.

    The dialog field will already have the correct user and server host filled in.

    If you are using a password for the user, type in the password.

    Click the ok button to confirm the values.

    <title></title>
    database login dialog

    Figure 3.4. database login dialog


After the project has been created successfully, all menu items will be available in the Seismon GUI.

<title></title>
The Seismon GUI after a new project has been created.

Figure 3.5. The Seismon GUI after a new project has been created.


Saving a Seismon project

To save a Seismon project select the menu item Filesave project. This will save all the settings of your project to the project file. The project file is named with the project name. It has the ending .spr and resides inside the PROJECT_DIR directory.

For example, if you have created a project named tutorial01 in the base directory /home/stefan/uni/seismonProjects, than the location of the project file would be /home/stefan/uni/seismonProjects/tutorial01/tutorial01.spr.

Loading a Seismon project

To work with a saved project, you have to load the project file (.spr ending) of the desired project.

  1. Select the menu item Fileload project.

    <title></title>
    select the load project menu item

    Figure 3.6. select the load project menu item


  2. Locate the project file (.spr ending) in the file selection dialog and click open.

    <title></title>
    select the project file to load

    Figure 3.7. select the project file to load


  3. Select the user with which you'd like to open the project.

    <title></title>
    select the user

    Figure 3.8. select the user


  4. Login to the database.

    <title></title>
    login to the database

    Figure 3.9. login to the database


    After the project has been created loaded, all menu items will be available in the Seismon GUI. If there already exist colletions in the project, the last used collection will be displayed.

Seismon projects in a multi-user system

Documentation will follow.

Seismon modules and collections

The functions within Seismon are provided as modules which can be combined in collections. Within a project the user can create several collections depending on the individual needs and add the desired modules to the collection. The collections can be saved for later use. A collection acts as a kind of a container for several modules. For example, one collection might hold all the modules to handle the geometry of the seismic network, another collection holds the modules to import the data in various formats, ....and so on.

What is a Seismon collection?

A Seismon collection is a container to hold a set of Seismon modules. Depending on the modules within the collection, a collection can be executed with a flow-like behaviour having one module passing the output to the next one, or it can simply be a container of standalone modules that are ignored when executing the collection.

What is a Seismon module?

A module is a bit of Matlab® code that provides some functionality to the Seismon user (e.g. import files, display trace data, ...). The available modules are organized in categories. The available module categories are listed in the Module category popup. When selecting one of the categories, all available modules of this category are displayed in the Module listbox.

To use a module, it has to be added to a collection. Depending on the type of the module (editabel, uneditable, standalone) the module provides several methods to acces its functionality. The different types of modules and how to use them is explained in the next section Types of modules.

Types of modules

A Seismon module can be one of three types:

  • editable

  • uneditable (identified by the "°" sign after the module name)

  • standalone (identified by the "*" sign after the module name)

Depending on their type, each module shows a different behaviour within a Seismon collection.

Editable modules

Editable modules provide a list of module parameters which can be set for each module before executing the collection. The module parameters can be set using the edit menu in the collection listbox context menu (see Editing a module in a collection). Using this edit menu, a GUI is shown providing the user an interface to set or change the module's parameters. The appearance of this user interface depends on the module. The module parameters are used as an input when executing the module during the execution of the collection.

Examples of editable modules are the load from database or the trace display modules.

Uneditable modules

Uneditable modules don't have any parameters to be set before executing the collection.

Examples of uneditable modules are the view geometry in google earth or the apply geometry modules.

Standalone modules

Standalone modules are ignored when executing the collection. They provide a user interface that can be accessed by using the execute menu in the Modules listbox context menu.

Examples of standalone modules are the edit station database or the edit units database modules.

Creating a collection

To create a collection you have to select the collection→new menu in the collection listbox context menu. After selecting this menu, a popup dialog appears asking you for the collection name. Enter the desired name and confirm by clicking the ok button. The new collection name will appear on top of the collection listbox.

After the collection has been created, modules can be added to the collection.

  1. Select the collection→new menu in the collection listbox context menu

    <title></title>
    Select the collection→new menu.

    Figure 3.10. Select the collection→new menu.


  2. Enter the desired collection name in the appearing popup dialog.

    <title></title>
    Enter the desired name in the popup dialog.

    Figure 3.11. Enter the desired name in the popup dialog.


  3. The new collection name appears on top of the collection listbox.

    <title></title>
    The new collection name on top of the collection listbox.

    Figure 3.12. The new collection name on top of the collection listbox.


Adding modules to a collection

To work with Seismon modules, you first have to add a module to a collection. To add a module to a collection you have to select the desired module in the modules listbox. Select the menu add or add before in the module listbox context menu to add the module to the currently loaded collection. Selecting the add menu, adds the selected module in the modules listbox after the selected module in the collection listbox. Selecting the add before menu, adds the selected module in the modules listbox before the selected module in the collection listbox.

To find the desired module in the modules listbox you have to select the module's category in the module category popup. All modules assigned to the selected category will appear in the modules listbox.

As an example I will show how to add the MiniSeed import module to a collection. I assume, that a collection has already been created or loaded.

  1. Select the category File Import in the module category popup.

    <title></title>
    Select the category to which the module is assigned to.

    Figure 3.13. Select the category to which the module is assigned to.


  2. Select the MiniSeed import module and click the add menu in the modules listbox context menu.

    <title></title>
    Add the selected module by selecting the add menu of the context menu.

    Figure 3.14. Add the selected module by selecting the add menu of the context menu.


  3. The MiniSeed import will appear in the collection listbox.

    <title></title>
    The added module will appear in the collection listbox.

    Figure 3.15. The added module will appear in the collection listbox.


Editing a module in a collection

Editable modules provide a GUI to set and change parameters used by the module when beeing executed. To access this GUI and to edit the parameters of an editable module you first have to add the module to a collection. Then you have to select the module in the collection listbox and afterwards select the edit menu in the collection listbox context menu. The layout of the module's edit GUI is not restricted to a uniform layout, so the appearance of this GUI varies from very simple layouts (e.g. MiniSeed import) to quite sophisticated ones (e.g. select seismon event).

After you have edited the module parameters you can confirm these settings by hitting the ok button or you can discard them by clicking the cancel button. When confirming the changes using the ok button, the module parameters are saved with the module in the collection and can be accessed and changed at a later time.

To illustrate how to edit a module I will demonstrate the editing of the Autodrm bulletin import module. For this example I assume, that the Autodrm bulletin import module has already been added to a collection.

  1. Select the Autodrm bulletin import module in the collection listbox.

    <title></title>
    Select the Autodrm import bulletin module in the collection listbox.

    Figure 3.16. Select the Autodrm import bulletin module in the collection listbox.


  2. Select the edit menu in the collection listbox context menu to open the Autodrm bulletin import edit window.

    <title></title>
    Select the edit menu

    Figure 3.17. Select the edit menu


  3. Edit the parameters of the module. In this case you can select the bulletin files which you like to import in to the seismon database. You can use the bulletin file 200712_december.txt in the tutorial01 dataset (you can find the file in the autodrmBulletin folder). To open the file selection dialog in the Autodrm bulletin import edit window you can use the add files menu in the context menu of the input files listbox.

    <title></title>
    Add files using the context menu (right mouse click in the listbox).

    Figure 3.18. Add files using the context menu (right mouse click in the listbox).


  4. The selected file(s) will appear in the input files listbox showing the complete filepath. Click the ok button to confirm the edited values.

    <title></title>
    The selected files are shown in the listbox.

    Figure 3.19. The selected files are shown in the listbox.


Loading a collection

As already noted at the beginning of this chapter you can create as many collections as needed for your tasks. Changes to collections are automatically saved. You can access already existing collections by using the collections→load menu of the collection listbox context menu. After selecting this menu, a selection dialog will appear with all available collections listed. Select the collection to load and confirm by clicking the ok button. The loaded collection will appear in the collection listbox.

  1. Select the collections→load menu in the collection listbox. The collection selection dialog will appear.

    <title></title>
    Select the collections→load in the collection listbox context menu.

    Figure 3.20. Select the collections→load in the collection listbox context menu.


  2. Select the collection to load in the listbox and confirm your selection by clicking the ok button.

    <title></title>
    Select the collection to load in the collection selection dialog.

    Figure 3.21. Select the collection to load in the collection selection dialog.


  3. The loaded collection will appear in the collection listbox.

    <title></title>
    The loaded collection with the name "another collection" contains two modules.

    Figure 3.22. The loaded collection with the name "another collection" contains two modules.


Executing a collection

After you have created or loaded a collection, added modules to the collection and edited the parameters of the editable modules in your collection you can execute the collection to actually run the module funtions. When executing a collection, the modules inside the collection are executed from top to bottom. Standalone modules and disabled modules are ignored during this execution. You can disable and enable a selected module in the collection listbox by selecting the disable/enable menu in the collection listbox context menu. Disabled modules are marked with a light gray italic module label.

Some modules are awaiting input parameters coming from the previous module executed in the collection (the modules behave like executing a flow). For these modules you have to make sure, that the modules are listed in the correct order in the collection listbox. To change the order of the modules you can use the move up and move down menus in the collection listbox context menu.

To find out more about the behaviour of specific modules, please see the individual module documentation in the Seismon Module Documentation.

As an example how the execution of different module types behave I will explain what's going on when executing the collection shown in the following figure.

Example collection holding 4 modules.

Figure 3.23. Example collection holding 4 modules.


  1. The first moduel edit stations database is ignored because it is a standalone module. The standalone module is marked by a "*" sign following the module name.

  2. The second module, load from database is executed. This module loads selected waveform data from the database and passes the selected waveform ids to the next module in the collection. So the next module in the collection has to be a module that can handle the output of this collection.

  3. The third module, Apply Geometry, is an uneditable module (marked with the "°" sign). This module is disabled, notice the light gray, italic text. Therefore, this module is ignored when executing the collection. If this module wouldn't be disabled, the execution of the flow would produce an error because the Apply Geometry module can't process the output data of the load from database module.

  4. The fourth module is the trace display module, an uneditable module. This module awaits a list of waveform ids to load and displays these waveform data in a window.

The Seismon database

Chapter 4. Using Seismon

This chapter will describe the basic usage of Seismon. Seismon has been created to quickly access waveform data with the focus on seismic datasets but not limited to it. It should provide an interface for the researcher to play around with the data using Matlab's great possibilities of data processing and visualization. I always see Seismon as a kind of Seismic Prototyping Software which lets you realize your ideas without having to mess around with waveform data management, data organization and waveform visualization. These things should be minor parts in a scientific work and more time should be spent in really working on whats going on in your mind - whatever this will be...

To find out more how to use Seismon to help you with your ideas, you can't avoid knowing about the basics:

  • Setting up a geometry

  • Loading waveform data into Seismon

  • Displaying the waveform data

  • Learn how to use Seismon events

The Seismon geometry

The first thing when working with seismic datasets is setting up the appropriate geometry of the seismic stations. The Seismon geometry includes the locations of seismic stations and the association of digitizers/dataloggers and seismic sensors to these stations.

Stations, units and sensors

Within Seismon, the geometry is built using three elements: a station, a unit and a sensor. A unit basically represents the digitizer/datalogger and it contains one or more sensors. A sensor represents one recording channel of the digitizer (e.g. a 3-comp geophone would be represented as 3 sensors in the Seismon geometry).

To provide a great amount of flexibility in creating the geometry, each single sensor and not only the units can be assigned to one station. This comes in handy, if you are using a multichannel digitizer, let's say a 6-channel Reftek 130 unit and connect 6 vertical geophones to it. These six geophones are deployed forming a seismic line with each geophone representing a seismic station. Using Seismon you can easily set up this geophone layout. Moreover for each sensor, a deployment timespan can be assigned. This deployment timespan defines the period during which the sensor has be placed at a given station. This makes it easy to work with changing sensor placements which might be used in active seismic experiments or in the case of unit and sensor redeployments in case of damage of other unexpected circumstances.

See the following figures for two example geometry setups. The first one, Figure 4.1, shows a classical geometry setup having two stations each holding 3 sensors belonging to one unit. The second example, Figure 4.2, shows a more sophisticated layout with one 6-channel unit with each sensor forming an individual station.

Classical geometry setup with each station holding a unit with 3 sensors.

Figure 4.1. Classical geometry setup with each station holding a unit with 3 sensors.


<title></title>
A geometry layout example showing 6 stations and one unit having 6 sensors (e.g. 6 vertical component geophones). Each sensor is assigned to an individual station. This layout might represent a small seismic profile layout.

Figure 4.2. A geometry layout example showing 6 stations and one unit having 6 sensors (e.g. 6 vertical component geophones). Each sensor is assigned to an individual station. This layout might represent a small seismic profile layout.


The assignment of the sensors to the stations can be constrained in time. So it's possible to move one sensor to another station within the same Seismon project.

The geometry database tables

Building the Seismon geometry

Up to now, you should have gained a basic understanding of how the geometry is handled within Seismon. This section shows you how to actually import your geometry data into the Seismon database tables and how to edit the station, unit or sensor parameters.

To import a geometry layout, the easiest way is to import it from formatted text files. This makes it easy to import a large amount of stations without manually typing each value in the appropriate field of a dialog window. After you have imported the geometry layout from the text files, you can use the Seismon GUI to control and edit these values.

There are two modules that are important when working with the geometry:

  • edit units database

  • edit stations database

You can find these modules in the geometry category.

The units/sensors import file format

To import the units and sensors data into the Seismon database you will need a textfile, I will call it unitsImport.suf, in a special format (the Seismon Unit File format (*.suf)). Lines starting with /* characters are interpreted as comments.

In the Seismon Unit File format, a unit is split into 3 sections:

  • The unit section (keyword: #UNIT)

    Each #UNIT keyword follows one line (the unit line) holding the unit values.

  • The sensor section (keyword: #SENSOR)

    Each #SENSOR keyword follows one line (the sensor line) holding the sensor values.

  • The sensor parameter section (no keyword, all lines following the first line in the sensor section)

    Each sensor line follows one line (the sensor parameter line) holding the sensor paramters. Currently only one set of sensor parameters is allowed, for the future the support for temporal changing sensor parameters is planned.

See the file unitsImport.suf or the listing below for an example. This example contains two units, each one having three sensors.

/* This is a comment. */
#UNIT
9D6C, Reftek 130-01
#SENSOR
101, Z, 1, GS11D
32, 1.5895E-6, 81.9, V/m/s, none,,, 1
#SENSOR
102, N, 1, GS11D
32, 1.5895E-6, 81.9, V/m/s, none,,, 1
#SENSOR
103, E, 1, GS11D
32, 1.5895E-6, 81.9, V/m/s, none,,, 1

/* Unit number 2. */
#UNIT
9898, Reftek 130-01
#SENSOR
101, Z, 2, GS11D
32, 1.5895E-6, 81.9, V/m/s, none,,, 1
#SENSOR
102, N, 2, GS11D
32, 1.5895E-6, 81.9, V/m/s, none,,, 1
#SENSOR
103, E, 2, GS11D
32, 1.5895E-6, 81.9, V/m/s, none,,, 1

The unit line:

recorder serial

The serial number of the recorder/digitizer. (String)

recorder type

The type of recorder/digitizer used. (String)

The sensor line:

channel specifier

The specifier of the channel as it is used in the raw data file. For example, the channels in a Reftek 130 recorder are labeled as 101, 102, 103 representing the first, second and third channel of the first data stream. These labels are written to the raw data files. When applying the geometry to the data files, these labels are used to identify the channel of the data file. You have to assigne a channel name for each channel specifier (see the next field). (String).

channel name

This is the channel label that will be used within Seismon. Following the example above, if you have connected the Z, N and E sensor of your geophone to the 101, 102 and 103 channel of the digitizer respectively, than you have to assign these channel_name labels to the appropriate channel_specifier. (String)

sensor serial

The serial number of the sensor (e.g. the serial number of the used geophone). (String)

sensor type

The type of the used sensor (String).

The sensor parameters line:

gain

The gain value of the digitizer. (float)

bitweight

The bitweight of the digitizer. (float)

sensitivity

The sensitivity of the sensor. (float)

sensitivity units

The units of the sensitivity. Allowed values are V/m, V/m/s, V/m/s^2 representing displacement, velocity and acceleration sensors. (String)

tf type

The type of the transfer function. Allowed values are none, m, m/s and m/s^2. These values currently aren't used within Seismon. (String).

poles

The poles of the transfer function as comma seperated values. These values currently aren't used within Seismon. (String)

zeros

The zeros of the transfer function as comma seperated values. These values currently aren't used within Seismon. (String)

normalization_factor

The normalization factor of the transfer function. (float)

The stations import file format

To import the stations data into the Seismon database you will need a CSV textfile, I will call it stationsImport.ssf, in a special format. See the file stationsImport.ssf or the file listing below for an example. This example contains two stations with each one having 3 sensors assigned to it. The sensors correspond to those listed in the sensors example above. Lines starting with /* characters are interpreted as comments.

/* This is a comment. */
#STATION
GB01, 337402.18, 5206280.96, 1370.45, UTM_33_N
9D6C, 101, 1, 2008-10-08 00:00:00, running
9D6C, 102, 1, 2008-10-08 00:00:00, running
9D6C, 103, 1, 2008-10-08 00:00:00, running

/* Station number 2. */
#STATION
GB02, 336633.6, 5205909.43, 1444.82, UTM_33_N
9898, 101, 2, 2008-10-08 00:00:00, running
9898, 102, 2, 2008-10-08 00:00:00, running
9898, 103, 2, 2008-10-08 00:00:00, running

Each station section is marked using the #STATION keyword. In the line after this keyword the station coordinate line holding the station name and its coordinates follows. After this station coordinate line, the sensors associated with the stations follow. Each sensor line consists of the the unit serial number, the sensor channel specifier, the sensor serial number, the time span start and the time span end. You can add as many sensors to the station as needed. The beginning of the next station is marked by the #STATION keyword.

station coordinate line (station name, x coordinate, y coordinate, height, coordinate system)

station name

The name of the station.

x coordinate / longitude

The x (or longitude) coordinate of the station.

y coordinate / latitude

The y (of latitude) coordinate of the station.

height

The height of the station.

coordinate system

The type of the coordinate system. Possible types are WGS84 and UTM. In case of UTM coordinates you have to additionally specify the UTM zone and the hemisphere seperated by underlines (e.g. UTM_33_N for UTM zone 33 north).

sensor line (unit serial, channel specifier, sensor serial, time span start, time span end)

unit serial

The serial number of the unit. (String)

channel specifier

The channel specifier of the used channel. (String)

sensor serial

The serial number of the sensor. (String)

time span start

The start of the time span during which the sensor has been placed at the station. (YYYY-MM-DD HH:MM:SS)

time span end

The end of the time span during which the sensor has been placed at the station, running if this date is open. (YYYY-MM-DD HH:MM:SS)

Importing the geometry layout

The easiest way to transfer your geometry layout to the Seismon database is the import of formatted textfiles. These textfiles have to be formatted as described in the two sections above. First, you should import all the units (including the sensors) that you are going to use in your project.

  1. Add the edit units database module to your collection.

    <title></title>
    Add the edit units database module to the collection.

    Figure 4.3. Add the edit units database module to the collection.


  2. Execute the standalone module edit units database by clicking the right mousebutton and selecting the execute menu in the context menu.

    <title></title>
    Execute the edit units database module.

    Figure 4.4. Execute the edit units database module.


  3. Select the menu fileimport ASCII.

    <title></title>
    Select the file ↦ import ASCII menu.

    Figure 4.5. Select the file ↦ import ASCII menu.


  4. Select the units import file (formatted in the way described in units/sensor file format.

  5. The units and sensors listed in the units import file will be imported into the Seismon database and they will appear in the edit units database window.

    <title></title>
    The imported units will appear in the dialog window.

    Figure 4.6. The imported units will appear in the dialog window.


The second step will be the import of the stations including the assignment of the sensors to the stations using the stationsImport.csv.

Warning

Please remember that the assignemnt of the sensors to the stations is only possible, if the units and sensors already have been imported into the database!

  1. Add the edit stations database to your collection.

    <title></title>
    Add the module edit stations database to your collection.

    Figure 4.7. Add the module edit stations database to your collection.


  2. Execute the standalone module edit stations database by clicking the right mousebutton and selecting the execute menu in the context menu.

    <title></title>
    Execute the moduel.

    Figure 4.8. Execute the moduel.


  3. Select the menu fileimport csv.

    <title></title>
    Open the file selection dialog.

    Figure 4.9. Open the file selection dialog.


  4. Select the stations import file (formatted in the way described in stations file format.

  5. The stations with the assigned sensors listed in the stations import file will be imported into the Seismon database and they will appear in the edit stations database window.

    <title></title>
    The imported stations will appear in the window.

    Figure 4.10. The imported stations will appear in the window.


    The listbox on the left side holds all stations (GB01, GB02). The uppermost table on the right side displays the paramters of the selected station (in the image above, all parameters of the station GB01 are shown). The table on the bottom right side shows all sensors assigned to the currently selected station.

Editing stations, units and sensors

You can use the modules edit stations database and edit units database to add, edit and remove stations and units.

Editing the units and sensors

The edit units database enables you to add, remove and edit the units and sensors manually.

  • To add or remove a unit, you can use the context menu of the units listbox.

    <title></title>
    Add or remove units using the context menu.

    Figure 4.11. Add or remove units using the context menu.


  • To add or remove a sensor to a unit, you can use the context menu of the sensor listbox.

    <title></title>
    Add or remove sensors of a unit.

    Figure 4.12. Add or remove sensors of a unit.


  • Editing parameters of the unit and the sensors

    The Recorder parameters can be directly edited using the serial and type edit field.

    To edit the sensor parameters in the sensors table (e.g. sensor serial, sensor type, ...) you first have to select the according field that you like to edit (e.g. click inside the sensor serial field holding the value 2) and than you have to click the right mouse button to open a dialog box to edit the sensor parameter. Enter the desired value in the dialog box and click ok to confirm the changes.

    To confirm the changes of the unit and the associated sensors click the apply button. Click the discard button to discard your changes of the unit and the sensors.

    <title></title>
    Select the field that you like to edit (e.g. the sensor serial field holding the value 2)

    Figure 4.13. Select the field that you like to edit (e.g. the sensor serial field holding the value 2)


    <title></title>
    Click the right mouse button to open the edit dialog.

    Figure 4.14. Click the right mouse button to open the edit dialog.


Editing the stations
  • To add or remove stations, you can use the context menu of the stations listbox in the edit stations database.

    <title></title>
    Use the context menu of the stations listbox to add or remove a station.

    Figure 4.15. Use the context menu of the stations listbox to add or remove a station.


  • Editing parameters of a station.

    To edit the station parameters in the station table (e.g. name, x, y, ...; The id value is not editable) you first have to select the according field that you like to edit (e.g. click inside the name field holding the value GB01) and than you have to click the right mouse button to open a dialog box to edit the selected parameter. Enter the desired value in the dialog box and click ok to confirm the changes.

    To confirm the changes of the station parameters click the apply button.

    <title></title>
    Select the field that you like to edit (e.g. the name field holding the GB01 value).

    Figure 4.16. Select the field that you like to edit (e.g. the name field holding the GB01 value).


    <title></title>
    Click the right mouse button to open the edit dialog.

    Figure 4.17. Click the right mouse button to open the edit dialog.


  • Assigning sensors to a station

    As described in the section called “Stations, units and sensors” a sensor can be assigned to a station. The sensor assigned to a station are listed in the senors table. You can use the context menu of the sensors listbox to add and remove sensors to a station. Moreover you can change the deployment timespan of each sensor using the context menu.

    <title></title>
    Edit the sensors assigned to the station using the context menu of the sensors table.

    Figure 4.18. Edit the sensors assigned to the station using the context menu of the sensors table.


  • Applying or discarding the changes

    To permanently save the changes you have made to the station parameters and the sensors you have to click the apply button.

    You can restore the original values by clicking the discard button. All the changes that you have made to the station parameters will be lost.

Visualizing the geometry

Getting waveform data into Seismon

Working on it

Displaying waveform data

Working on it.

Events and how to use them

Working on it.

What else can be done with Seismon?

Working on it.

Tutorials



Table of Contents

1. Seismon Basics

Chapter 1. Seismon Basics

In here you can find a set of tutorials dealing with the basic Seismon functions.

Seismon Developer's Guide

Stefan Mertl



Chapter 1. Introduction

Stefan Mertl

2010-04-02

Table of Contents

Play with your data

Play with your data

As a scientist I'd like to play and experiment with the data that I have collected in the field. In seismology the first thing you usually have to solve before reaching the data playground is to read the data into the software of your choice. Usually, caused by the multitude of different data formats and almost as many data conversion and processing tools (each of them doing one special task), this becomes a time consuming nightmare. I found Matlab™ beeing the most suitable tool for scientific software development and therefore I started to develop the Seismon software package which I like to name a Seismic Prototyping Tool. The emphasis on prototyping instead of the common processing naming is because I don't see Seismon to step in and replace already existing seismological processing tools like Seisan or MatSeis, but to provide a framework to easily develop new processing algorithms and to integrate them easily into the existing Seismon software.

The Developer's Guide provides a starting point for you to begin with Seismon software development and to add algorithms fitting your needs building on the powerful framework of the Seismon software. As you will see in the following chapters just with a few lines of code following some coding guidelines you can build on the Seismon visualization module and access waveform data without having to mess around with loading, visualizing and preprocessing your data. Seismon takes care of all the annoying and time consuming data management things. Just grab the junk of data that you want to process using the Seismon Application Programming Interface (API), apply your algorithms and send the data back to Seismon which visualize them for you - it's almost as easy as it sounds.

Go for it and enjoy!

Chapter 2. Tracedisplay Tools

Stefan Mertl

2010-04-02

Introduction

Seismon provides a wide variety to add new functionality. On of the most popular ways is to add tools to the tracedisplay module. With these tools you can use the tracedisplay for visualizing the data and apply your algorithm to the data currently displayed. Within the tracedisplay allmost all available functionality is provided as tools.

Tools can be added and removed without having any effect to the overall tracedisplay module. You can find the tools in the pkg_tracedisplay/tools folder.

The tracedisplay modules can be grouped according to their development state or author (or whatever you like). A common grouping is for example the division into stable and still experimental tools. In the tracedisplay window you can decide which groups of tools you want to work with. According to your selected groups, the available menus will change.

To control the currently shown tools you can use the menu file → tool preferences which will open the tool preferences dialog window (see Figure 2.1 and Figure 2.2). The tools discussed in this guide will all be placed in the example group. To work with these tools you therefore have to select the example group in the tool preferences as shown in Figure 2.2.

The tool preferences menu.

Figure 2.1. The tool preferences menu.


The tool preferences dialog.

Figure 2.2. The tool preferences dialog.


Creating Tracedisplay Tools

Creating Seismon Tracedisplay tools and adding them to the tracedisplay window is a simple task involving only a few steps. Basically you have to create one interface function (the init function) which lets Seismon know what kind of tool you provide and a set of callback interface functions which depend on the type of your tool and which control the user interaction.

The basic steps to do to get a working tool in the tracedisplay window are:

  1. Create a new directory in the pkg_trace_display/tools folder holding your tool functions. The folder has to start with the prefix +tool_ followed by your tool name (e.g. +tool_exampleCommandTool).

  2. Inside this directory create an m-file named init.m which is the initialization file for your tool. This file has to contain the init function. The init function is executed every time the tracedisplay module is started and lets Seismon know what kind of tool you provide.

  3. Implement the init function in the init.m file according to your needs. The init function has to return an instance of a tdToolRoot class. Take a look at the tool examples below to find out more about the coding guidelines.

  4. Create and implement the functions that are going to be called by the tool (e.g. a command tool will require one function, the callback function to be created). This point will get clearer when going through the example tools below.

One important thing that you will need when placing your tool root in the existing tracedisplay menu is the menu tag of the parent menu (the menu where you like your tool to appear). The tags of the menus in the tracedisplay window are named as m_MENUNAME. For example, the tag of the Analyze menu is m_analyze, the tag for the Localize menu is m_localize, and so on.... .

I didn't include an automatic creation of these parent menus, because I don't think that it's needed that often and if needed, it's very easy to add by editing the tdTraceDisplay.buildmenu function.

This chapter will guide you through the creation of tools using some example tools. You can find the example tools in the seismon examples (SEISMONROOT/examples) folder. Just copy the corresponding +tool_TOOLNAME folder into your pkg_trace_display/tools folder, start the tracedisplay module and the example tools will appear in the tracedisplay menu after selecting the example category in the tool preferences as described in the section called “Introduction”.

Note

If you have downloaded the Seismon source using the SVN client, than there is a hidden directory called .svn in each of the example tool directories. To avoid possible troubles with the SVN updates, please delete the .svn folder from the example tool directory after you have copied it to the pkg_trace_display/tools directory.

The following sections will guide you through some of the tool examples.

A simple command tool example

A command tool is the most simple tool which executes the tool's callback function once after the tool uimenu has been clicked. These type of tools can be used to perform computations based on the currently displayed data (e.g. computing the spectrum, exporting data, ...). The command tool example is contained in the folder SEISMON_ROOT/examples/seismonTools/+tool_exampleCommandTool.

The init.m file for a command tool looks like this:

function toolRoot = init
% The init function has to return toolRoot, an instance of the tdToolRoot
% class.

% Set the tool root properties.
parentMenuTag = 'm_analyze';            % The parent menu where to place the tool's uimenu. In this case this would be the analyze menu.
position = 1;                           % The position of the tool menu in the analyze menu.
name = 'commandExample';                % The name of the menu.
type = 'command';                       % This tool is a command tool. This means when clicking the tool menu, the callback function handle will be executed once.
menu = 'example command tool';          % The uimenu label.
menuTag = 'tce_exampleCommandTool';     % The uimenu tag. Try to make this as unique as possible using some kind of prefix for your tool.
callback = @tool_exampleCommandTool.commandExample;    % The tool callback function.
callbackParameter = {};                 % No parameter is passed to the function.
windowButtonDownFcn = '';               % The command tool doesn't use the windowButtonDownFcn. 
windowButtonMotionFcn = '';             % The command tool doesn't use the windowButtonMotionFcn. 
updateTracePlotFcn = '';                % The command tool doesn't use the updateTracePlotFcn. 
deactivateFcn = '';                     % The command tool doesn't use the deactivateFcn.
pointer = 'arrow';                      % The default pointer of the tool.
keyPress = '';                          % We don't use a keyboard shortcut.
keyPressModifier = {};                  % We don't use a keyboard shortcut.
devState = 'example';                   % The tool's development state.   

% Create the tool root object using the tdToolRoot constructor.
toolRoot = tdToolRoot(parentMenuTag, position, name, type, menu, menuTag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);

In this init file we define one tool root which acts as command tool and executes the callback function tool_exampleCommandTool.commandExample when the uimenu element is clicked by the user. The last step to create a working tool is to implement the callback function tool_exampleCommandTool.commandExample. This callback function has to accept two parameters (toolNode and tdObject) which are passed by default to this function by Seismon. You have to specify these two parameters, otherwise an error will be thrown.

The next code listing shows the tool's callback function:

function commandExample(toolNode, tdObject) 
% The editParameters function has to accept the two parameters toolNode and
% tdObject which are passed by default to these function by Seismon.

% Use the tdObject to get the currently displayed channels.
activeChannels = tdObject.activeStations.getActiveChannels;

% Check if any channel is active.
if(isempty(activeChannels))
    return;
end

% Create a figure.
figure('color', 'white');
axes;
hold on;

% Process each active channel.
for k=1:numel(activeChannels)
    CurChannel = activeChannels(k);
    
    % Get the continuous data of the channel using the
    % tdChannel.getContPlotData method.
    curData = CurChannel.getContPlotData;
    
    % Plot the channel data.
    plot(curData(:,1), curData(:,2));
end





This callback does a very simple task. It gets all the currently active (displayed) channels and plots the data of each channel in a common figure. This function doesn't do that useful things but it highlights how easy it is to access the tracedata from within Seismon to include your custom-built analysis tools.

The output of this example tool is shown in ???.

The result of the simple command tool example. All the traces visible in the tracedisplay window are plotted in the second window.

Figure 2.3. The result of the simple command tool example. All the traces visible in the tracedisplay window are plotted in the second window.


A command tool example using the tool configData property

Tools which rely on some user selectable settings can use the tdToolNode.configData property. This property allows to set default settings and to save the user changes to these settings. They are saved in the tool root node and don't get lost when deactivating the tool.

I will show you how to extend the simple command tool example to use a user selectable parameter. To change the tool we are going to set up the menus as shown in Figure 2.4

The config data example menu configuration.

Figure 2.4. The config data example menu configuration.


As you can see, our tool will have a root menu called config data example which holds two sub-menus, the execute and the edit parameters menu.

The command tool example using the tool configData property is contained in the folder SEISMON_ROOT/examples/seismonTools/+tool_exampleCommandTool.

The init function

The init function to create the menu layout as shown above looks like this:

function toolRoot = init
% The init function has to return toolRoot, an instance of the tdToolRoot
% class.

% =========================================================================
% Set the tool root properties.
% This tool root acts as a simple container to hold some tool node
% children.
parentMenuTag = 'm_analyze';            % The parent menu where to place the tool's uimenu. In this case this would be the analyze menu.
position = 1;                           % The position of the tool menu in the analyze menu.
name = 'configDataExample';             % The name of the menu.
type = 'no callback';                   % This tool root is just a container for some tool nodes which do implement the tool functionality.
menu = 'config data example';           % The uimenu label.
menuTag = 'tce_configDataExample';      % The uimenu tag. Try to make this as unique as possible using some kind of prefix for your tool.
callback = '';                          % This is a 'no callback' tool, so we don't need to specify a callback function handle.
callbackParameter = {};                 % No parameter is passed to the function.
windowButtonDownFcn = '';               % The command tool doesn't use the windowButtonDownFcn. 
windowButtonMotionFcn = '';             % The command tool doesn't use the windowButtonMotionFcn. 
updateTracePlotFcn = '';                % The command tool doesn't use the updateTracePlotFcn. 
deactivateFcn = '';                     % The command tool doesn't use the deactivateFcn.
pointer = 'arrow';                      % The default pointer of the tool.
keyPress = '';                          % We don't use a keyboard shortcut.
keyPressModifier = {};                  % We don't use a keyboard shortcut.
devState = 'example';                   % The tool's development state.

% Create the tool root object using the tdToolRoot constructor.
toolRoot = tdToolRoot(parentMenuTag, position, name, type, menu, menuTag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);



% =========================================================================
% Create and set the default config data of the root Node.
% Define a structure holding the tool options.
configData{1} = struct('lowerCutoff', 1, ...        % The lower cutoff frequency.
    'upperCutoff', 5);                              % The upper cutoff frequency.
toolRoot.setConfigData(configData);                 % Set the tool root config data.



% =========================================================================
% Define the first submenu, the 'execute' menu.
name = 'execute';
tag = 'tce_executeConfigDataExample';
type = 'command';
menu = 'execute';
callback = @tool_exampleConfigDataTool.execute;
callbackParameter = {};
windowButtonDownFcn = '';
windowButtonMotionFcn = '';
updateTracePlotFcn = ''; 
deactivateFcn = '';
pointer = 'arrow';
keyPress = '';
keyPressModifier = {};
devState = 'example';

% Create the tool node and add it to the tool root.
% Pay attention, that all the submenus have to be of type tdToolNode.
toolNode = tdToolNode(name, type, menu, tag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);
toolRoot.addNode(toolNode);



% =========================================================================
% Define the second submenu, the 'edit parameters' menu.
name = 'edit parameters';
tag = 'tce_editConfigDataExample';
type = 'command';
menu = 'edit parameters';
callback = @tool_exampleConfigDataTool.editParameters;
callbackParameter = {};
windowButtonDownFcn = '';
windowButtonMotionFcn = '';
updateTracePlotFcn = ''; 
deactivateFcn = '';
pointer = 'arrow';
keyPress = '';
keyPressModifier = {};
devState = 'example';

% Create the tool node and add it to the tool root.
% Pay attention, that all the submenus have to be of type tdToolNode.
toolNode = tdToolNode(name, type, menu, tag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);
toolRoot.addNode(toolNode);

As you can see, there are some changes in the init file compared to the simple command tool example. We have added some children tool nodes to build the sub-menu structure that we'd like to have and we have set the configData property of the tool root node.

To complete the tool, we now have to implement the two callback functions of the sub-menus:

  • tool_exampleConfigDataTool.execute

  • tool_exampleConfigDataTool.editParameters

The editParameters function

We gonna start with the tool_exampleConfigDataTool.editParameters callback which should open a user dialog in which the tool options can be edited. This callback function will be evaluated whenever the user clicks the configDataExample → edit parameters menu. The tool options should be loaded from the tool root configData and the changed options should be saved to the tool root configData property.

See the code listing of tool_exampleConfigDataTool.editParameters how this is done:

function editParameters(toolNode, tdObject)
% The editParameters function has to accept the two parameters toolNode and
% tdObject which are passed by default to these function by Seismon.
    
configData = toolNode.getConfigData;        % Call the tdToolNode.configData method to get the tool's configData.

Options = configData{1};                    % We know, that we have saved a structure in the first cell element of the configData property.

% Create a user dialog asking for the tool paramters.
% This is done using the predefined dialog inputdlg, but of course you can
% create your own dialog windows to get edit the tool parameters.
% There's a Matlab bug with .fig files in a package directory, please read
% the developers guide section of this example for more info.
%
prompt = {'lower cutoff [Hz]:', 'upper cutoff [Hz]:'};
dlg_title = 'Filter parameters';
num_lines = 1;
def = {num2str(Options.lowerCutoff), num2str(Options.upperCutoff)};
answer = inputdlg(prompt,dlg_title,num_lines,def);
if(isempty(answer))
    return;
end

Options.lowerCutoff = str2double(answer{1});
Options.upperCutoff = str2double(answer{2});


% Set the tool's config data.
configData{1} = Options;
toolNode.setConfigData(configData);

Note

You just have to be aware, that due to a Matlab but, it seems that dialog windows which have been created with the guide tool don't work inside a Matlab package directory (those directories with the "+" sign in front of the name. So if you create a custom dialog using guide, you right now have to place the dialog files outside the +tool_TOOLNAME package directory. The polarization analysis tool and the select pick set tool have such kind of external dialog windows. See the functions polarizationAnalysisTool_editParameters.m and pickTool_pickSetSelectionDlg.m respectively.

Note

If you like to create a more sophisticated user input dialog you can use the Seismon class smInputDlg which provides the possibility to add listbox and popup elements to the dialog. See the editParameters function of the tool localizeCircle2D for an example how to use the smInputDlg class.

The editParameters function will open a dialog window (see Figure 2.5) and query the filter inputs from the user. The new filter parameters are saved in the tool's configData property.

The edit parameters dialog.

Figure 2.5. The edit parameters dialog.


The execute function

Next we gonna implement the tool execute function which is called whenever the config data example -> execute menu is clicked. The execute function should filter all the active channels using the filter parameters that can be changed using the edit parameters menu and display the filtered data in a new window.

Here is the code listing of the tool_exampleConfigDataTool.execute function:

function execute(toolNode, tdObject) 

% Use the tdObject to get the currently displayed channels.
activeChannels = tdObject.activeStations.getActiveChannels;

% Check if any channel is active.
if(isempty(activeChannels))
    return;
end

% Get the tool configuration parameters.
configData = toolNode.getConfigData;
Options = configData{1};


% Create a figure.
figure('color', 'white');
axes;
hold on;

maxChannels = numel(activeChannels);

% Process each active channel.
for k=1:maxChannels
    CurChannel = activeChannels(k);
    
    % Get the continuous data of the channel using the
    % tdChannel.getContPlotData method.
    curData = CurChannel.getContPlotData;
    
    % Get the sps from the channel traces.
    sps = unique(CurChannel.traces.sps);
    if(numel(sps) > 1)
        error('The sampling rate of the individual traces contained in the channel is not equal.');
    end
    
    % Create a bandpass filter using the tool options.
    curNyquist = sps / 2;
    [b, a] = butter(2, [Options.lowerCutoff/curNyquist, Options.upperCutoff/curNyquist]);
    
    % Filter the data.
    curData(:,2) = filter(b, a, curData(:,2));
    
    % Plot the channel data.
    subplot(maxChannels, 1, k);
    plot(curData(:,1), curData(:,2));
end





Once you have implemented all three functions of this tool example (or just copy the according folder from the SEISMON_ROOT/examples folder into the pkg_trace_display/tools folder) than you should be able to execute the tool analyze->config data->execute. As a result you will get something as shown in Figure 2.6. The small window in the foreground is the window created by the tool with the two filtered traces plotted in blue.

The result of the config data example tool.

Figure 2.6. The result of the config data example tool.


An addon tool example

Addon tools are tools that are not only executed once like the command tools, but are executed every time, that data shown in the tracedisplay window is changed. The data is changed for example when zooming or navigating back and forth in time. So every time that you change the displayed time-span, the addon tool is again evaluated. This is done using the tool's updatedCallback. A good example of an addon tool is the spectrogram tool (+tool_spectrogram).

The addon tool example builds on the configData example above and will use the editParameters function as described in this example. So please go there and read all about using the configData in a tool. The addon tool which we are going to create will, as in the example above, filter the displayed data, but will display the filtered data along with the original data in the channel's special axes.

The menu structure that we are going to create for this tool is shown in Figure 2.7.

The addon tool menu structure.

Figure 2.7. The addon tool menu structure.


The addon example is contained in the folder SEISMON_ROOT/examples/seismonTools/+tools_exampleAddonTool.

The init function

The init function for this tool setup looks like this:

function toolRoot = init
% The init function has to return toolRoot, an instance of the tdToolRoot
% class.

% =========================================================================
% Set the tool root properties.
% This tool root acts as a simple container to hold some tool node
% children.
parentMenuTag = 'm_analyze';            % The parent menu where to place the tool's uimenu. In this case this would be the analyze menu.
position = 1;                           % The position of the tool menu in the analyze menu.
name = 'addonExample';                  % The name of the menu.
type = 'no callback';                   % This tool root is just a container for some tool nodes which do implement the tool functionality.
menu = 'addon example';                 % The uimenu label.
menuTag = 'tce_addonExample';           % The uimenu tag. Try to make this as unique as possible using some kind of prefix for your tool.
callback = '';                          % This is a 'no callback' tool, so we don't need to specify a callback function handle.
callbackParameter = {};                 % No parameter is passed to the function.
windowButtonDownFcn = '';               % The command tool doesn't use the windowButtonDownFcn. 
windowButtonMotionFcn = '';             % The command tool doesn't use the windowButtonMotionFcn. 
updateTracePlotFcn = '';                % The command tool doesn't use the updateTracePlotFcn. 
deactivateFcn = '';                     % The command tool doesn't use the deactivateFcn.
pointer = 'arrow';                      % The default pointer of the tool.
keyPress = '';                          % We don't use a keyboard shortcut.
keyPressModifier = {};                  % We don't use a keyboard shortcut.
devState = 'example';                   % The tool's development state.   

% Create the tool root object using the tdToolRoot constructor.
toolRoot = tdToolRoot(parentMenuTag, position, name, type, menu, menuTag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);



% =========================================================================
% Create and set the default config data of the root Node.
% This config data will hold two double values that are used for filtering
% the data.
% Define a structure holding the tool options:
configData{1} = struct('lowerCutoff', 1, ...        % The lower cutoff frequency.
    'upperCutoff', 5);                              % The upper cutoff frequency.
toolRoot.setConfigData(configData);                 % Set the tool root config data.



% =========================================================================
% Define the first submenu, the 'execute' menu.
name = 'show';
tag = 'tce_showAddonExample';
type = 'addon';                                     % Make this tool node an addon tool!!!!!
menu = 'show';
callback = @tool_exampleAddonTool.show;
callbackParameter = {};
windowButtonDownFcn = '';
windowButtonMotionFcn = '';
updateTracePlotFcn = @tool_exampleAddonTool.updateTracePlot;   % The addon tool uses the updateTracePlotFcn.
deactivateFcn = @tool_exampleAddonTool.deactivate;             % Specify a deactivate function which is called when deactivating the tool.
pointer = 'arrow';
keyPress = '';
keyPressModifier = {};
devState = 'example';

% Create the tool node and add it to the tool root.
% Pay attention, that all the submenus have to be of type tdToolNode.
toolNode = tdToolNode(name, type, menu, tag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);
toolRoot.addNode(toolNode);



% =========================================================================
% Define the second submenu, the 'edit parameters' menu.
name = 'edit parameters';
tag = 'tce_editConfigDataExample';
type = 'command';                                               % The edit parameters tool node is a command tool.
menu = 'edit parameters';
callback = @tool_exampleAddonTool.editParameters;          % This function is called whenever the uimenu item is clicked.
callbackParameter = {};
windowButtonDownFcn = '';
windowButtonMotionFcn = '';
updateTracePlotFcn = ''; 
deactivateFcn = '';
pointer = 'arrow';
keyPress = '';
keyPressModifier = {};
devState = 'example';

% Create the tool node and add it to the tool root.
% Pay attention, that all the submenus have to be of type tdToolNode.
toolNode = tdToolNode(name, type, menu, tag, callback, callbackParameter, windowButtonDownFcn, windowButtonMotionFcn, updateTracePlotFcn, deactivateFcn, pointer, keyPress, keyPressModifier, devState);
toolRoot.addNode(toolNode);

You can see, that the tool root and the edit parameters menu stay the same as in the configData example. The only tool node that changes is the second node which is now named show. This tool node is now of type addon.

Additional to the callback function, the addon tool uses the updateTracePlotFcn which is the function called every time the data displayed in the tracedisplay window changes. As a further enhancement, I have added a deactivateFcn which is the function that is called when the tool is deactivated. You can use this function for example to clean up your tool data.

The functions that have to be defined by the addon tool are called in the following order:

  • When the user clicks the show menu, the tool is activated and the callback function is evaluated. This activates the addon tool.

  • When the addon tool has been activated, the updateTracePlotFcn is called every time the data displayed in the tracedisplay window is changed.

  • When the user clicks a second time the show menu, the tool is deactivated and the deactivateFcn function is called.

The edit parameters function

The edit parameters function stays the same as in the configData example. For more details on this function please see the example above.

Here is the code listing of tool_exampleAddonTool.editParameters:

function editParameters(toolNode, tdObject)
% The editParameters function has to accept the two parameters toolNode and
% tdObject which are passed by default to these function by Seismon.
    
configData = toolNode.getConfigData;        % Call the tdToolNode.configData method to get the tool's configData.

Options = configData{1};                    % We know, that we have saved a structure in the first cell element of the configData property.

% Create a user dialog asking for the tool paramters.
% This is done using the predefined dialog inputdlg, but of course you can
% create your own dialog windows to get edit the tool parameters.
% There's a Matlab bug with .fig files in a package directory, please read
% the developers guide section of this example for more info.
%
prompt = {'lower cutoff [Hz]:', 'upper cutoff [Hz]:'};
dlg_title = 'Filter parameters';
num_lines = 1;
def = {num2str(Options.lowerCutoff), num2str(Options.upperCutoff)};
answer = inputdlg(prompt,dlg_title,num_lines,def);
if(isempty(answer))
    return;
end

Options.lowerCutoff = str2double(answer{1});
Options.upperCutoff = str2double(answer{2});


% Set the tool's config data.
configData{1} = Options;
toolNode.setConfigData(configData);

The callback function

Now we gonna implement the tool callback function (called show) which is called when the user clicks the show menu to activate the tool. Inside this function we gonna initialize the tool, which means showing the special axes of the active channels. We will use the special axes to plot the filtered data.

Here is the code listing of the tool_exampleAddonTool.show function:

function [isError, msg] = show(toolNode, tdObject) 
% The show function has to accept the two parameters toolNode and
% tdObject which are passed by default to these function by Seismon.

% Tools can also return their error status to indicate if the tool has been
% started successfully.
isError = 0;
msg = '';


% Use the tdObject to get the currently displayed channels.
activeChannels = tdObject.activeStations.getActiveChannels;


% We are going to use the channel's special axes.
% The special axes are additional channels that will be shown above the
% channel data axes and can be used by addon tools to plot their data.

% Check if the special axes are already in use. Only continue if the 
% special axes are not used.
if(any([activeChannels.showSpecial]))   
    isError = 1;
    msg = 'The special axes are already in use.';
    return;
end

% % Activate the special axes of the active channels and refresh the axes to 
% % show the special axes.
% activeChannels.setShowSpecial;
% activeChannels.refreshAxes;
% 
% 
% % Get the tool configuration parameters.
% configData = toolNode.getConfigData;
% Options = configData{1};
% clear configData;


% Call the tool's updateTracePlot function to compute the tool algorithm.
tool_exampleAddonTool.updateTracePlot(toolNode, tdObject);

The updateTracePlot function

Now it's time to take care of the updateTracePlotFcn which actually does all the computation. The updateTracePlot function (in our example init file it's named updateTracePlot is called by the tracedisplay window every time the displayed data changes (e.g. when changing the displayed time-span).

Like the callback function, the updateTracePlotFcn has to accept two input parameters which are passed by default to this function by Seismon.

Note

Don't forget to call the updateTracePlotFcn at the end of the according callback function (in our case this is the show function).

As mentioned earlier, our example tool will take the channel's data, filter it using the tool's options in the configData property and show the filtered data in the channel's special axes.

The code listing of the function that does this job is here:

function updateTracePlot(toolNode, tdObject)

% Update the active channel special axes in case the displayed stations
% have changed.
activeChannels = tdObject.activeStations.getActiveChannels;
activeChannels.setShowSpecial;
activeChannels.refreshAxes;

% Get the tool configuration parameters.
configData = toolNode.getConfigData;
Options = configData{1};
clear configData;


for k=1:numel(activeChannels)
    CurChannel = activeChannels(k);
    
    % Clear the data in the special axes.
    CurChannel.clearSpecialData;
    
    % Get the continuous data of the channel using the
    % tdChannel.getContPlotData method.
    curData = CurChannel.getContPlotData;
    
    % Get the sps from the channel traces.
    sps = unique(CurChannel.traces.sps);
    if(numel(sps) > 1)
        error('The sampling rate of the individual traces contained in the channel is not equal.');
    end
    
    % Create a bandpass filter using the tool options.
    curNyquist = sps / 2;
    [b, a] = butter(2, [Options.lowerCutoff/curNyquist, Options.upperCutoff/curNyquist]);
    
    % Filter the data.
    curData(:,2) = filter(b, a, curData(:,2));
    
    % Plot the filtered data in the special axes.
    plot(CurChannel.specialAxes, curData(:,1), curData(:,2));
end

The deactivate function

Finally we are going to implement the tool's deactivate function. This function is called whenever the addon tool is deactivated. It can be used to clean up the tool settings and variables.

In our example tool we are going to use the deactivate function to reset and hide the special axes of the channels.

The code listing of the tool_exampleAddonTool.deactivate function is:

function deactivate(toolNode, tdObject)
% The addon tool deactivation function.
% This function does some cleaning up before the tool is finally
% deactivated.

fprintf('Deactivating tool: %s\n', toolNode.name);

% Reset the special axes of ALL channels to inactive state.
allChannels = tdObject.stations.getActiveChannels;  % Get the active channels of all stations.
allChannels.resetShowSpecial;            % Deactivate the special axes of all channels.

% Refresh the axes of the ACTIVE channels only.
activeChannels = tdObject.activeStations.getActiveChannels;  % Get the active channels of all stations.
activeChannels.refreshAxes;                    % Refresh the channel axes. Hide the special axes.

Executing the addon tool

If you have finished implementing all the functions of this example (or just copied the according folder from the SEISMON_ROOT/examples folder into the pkg_trace_display/tools folder), than you are now ready to use the tool.

Run a Seismon collection opening some kind of tracedata in the tracedisplay window. You can now edit your filter parameters using the edit parameters menu. To activate the addon tool, select the tool's show menu and the filtered data should be plotted above the original tracedata as shown in Figure 2.8.

The addon tool activated showing the filtered data (in blue) in the special axes of the channel.

Figure 2.8. The addon tool activated showing the filtered data (in blue) in the special axes of the channel.


Once the addon tool has been activated, the according tool root menu will be plotted in bold and the tool menu will be checked (see Figure 2.9).

The addon tool menu when the tool is active.

Figure 2.9. The addon tool menu when the tool is active.


To deactivate the addon tool, click the checked show button again, and the special axes will be hidden by the deactivate function.