• Antelope Release 5.9 Mac OS X 10.13.2 2019-05-01

 

NAME

BQTraceview - BRTT Qt graphics extension for drawing waveform traces and editing arrivals

SYNOPSIS


$(QTNATIVELIBS) -lbqplot_native -lbanner -lbrttutil -lbumapdata $(DBLIBS) $(TRLIBS)

#include "BQ.h"

DESCRIPTION

BQTraceview objects are used to display seismic waveform traces, arrival flags, detections, predicted arrivals, seismic event associations and residuals. As well, BQTraceview objects support interactive editing of seismic arrivals. This class is meant to provide the same functionality as dbpick(1) but in a Qt-based c++ class object that can be used in a variety of application programs. In addition this class provides much advanced functionality when compared to dbpick(1) and will provide a basis for other more advanced display and editing capabilities in the future.

An attempt has been made to make BQTraceview objects to behave as much like dbpick(1) as is reasonably possible. Most of the trace display interaction has been preserved. Arrival editing interaction has also been preserved as much as reasonably possible. In addition many new capabilities and interactions have been introduced. In particular, the user typein interface from dbpick(1) and the ability to send commands through the typein interface have been preserved and enhanced using the BQCommandConsole(3) class along with a helper BQTraceviewCommands class.

The BQTraceview class has been designed to eventually provide waveform display functionality for a variety of input data sources, including databases and real-time ORB data sources. In this first implementation only database sources are supported. Database sources are supported through the use of EV(3) server and class objects. This provides the capability to display and edit dynamically changing data in a completely safe manner.

This class inherits the BQConfigure class which is itself a subclass of the BUConfigure class with extensions to process Qt colors and fonts. The configure methods are implemented in the BUConfigure parent (see BUConfigure(3)).

DISPLAY COMPONENTS AND LAYOUT

The BQTraceview object display looks similar to the dbpick(1) display. Seismic waveforms are drawn horizontally and are arranged vertically for the individual channels. Each BQTraceview object is a proper BQViewport(3) item and requires the BQViewport object in its constructor. The horizontal X-axis is time and the parent BQViewport is automatically configured so that its xmode configuration parameter is set to time (see BQViewport(3)). The parent viewport's margins are also set automatically. All of the parent viewport's xleft, xright, ybottom and ytop world coordinate scales are all slaved to the BQTraceview object and should not be set by the calling program.

A simple non-dimensional Y-axis scaling is implemented internally to draw the waveform traces. This Y-axis variable ranges from 0.0 for the bottom of the display to 1.0 for the top of the display. Each waveform trace is automatically scaled to fit within this 0.0 to 1.0 range in a manner that determines its vertical position in the display. Once the waveform sample values have been transformed into the non-dimensional Y-axis scaling, then the normal viewport-based plot rendering is performed. Zooming and panning of the display in the vertical direction is done by setting the parent viewport ybottom and ytop world coordinate scales, all done automatically. In addition a vertical scrollbar has been added to the display for control of Y-axis panning. Trace labels are automatically generated and displayed along with amplitude units strings and scales which are displayed if there is enough vertical space, similar to dbpick(1).

Arrival flags, detections, predicted arrivals and residual bars are all implemented using BQPolypoint(3) glyph objects. Each of these glyphs are automatically scaled and displayed within the parent viewport and should not be manipulated by the calling program. There are copious display configuration parameters, set through the standard configure methods and parameters defined below, relating to component colors, linewidths, the various display modes and other parameters. There are status display lines, implemented as BQText(3) objects, to show the current mouse cursor coordinates, arrival information and event information. The mouse cursor is implemented with a set of crosshairs that can be used to determine feature alignment in both time and amplitude.

When the data source is coming from an EVServer object, the BQTraceview object can display detailed event information through the various glyphs and through the status display lines. A particular origin of a particular event can be put into a selected state, in which case the associated arrival glyphs are color coded according to their associations within the database.

There are two basic display modes; "normal" mode and "edit" mode. In normal display mode, interaction allows time-axis panning and zooming, trace-axis panning and zooming, selection and ordering of traces to display, waveform filtering, selection of events and origins, P-alignment, automatic trace selection based on existence of arrivals and/or detections, waveform amplitude scaling and units to display and other configure options such as show/hide of arrivals, detections and predicted arrivals. However, in normal display mode all arrival editing is disabled. In edit mode certain of the display mouse interactions are usurped from the normal mode to be used for arrival editing. All interactive arrival editing must be done in edit mode. Many of the configuration parameters, such as colors, can be specified with mode-dependent values. For instance the basic background and foreground colors can be (and usually are) different for normal and edit display modes. In edit mode arrivals can be "tagged" as being defining or non-defining to specify the associations for a new location to be determined.

An optional taskbar, implemented with BQTaskbar(3), can be specified and assigned to either the BQTraceview object's parent viewport or to any other programmer defined viewport. This taskbar is configured through the BQTraceview object configuration parameters defined below. This taskbar has been enhanced so that its actions can be to send BQTraceview commands as defined below.

INDIVIDUAL TRACE REPRESENTATION

Each individual trace in a BQTraceview object is represented as a BQTrace(3) object. The BQTrace class is a helper class and its objects currently can only be used from within BQTraceview objects. BQTrace objects are created automatically by BQTraceview objects as needed. Each of the BQTrace object pointers can be determined through several methods described below. These single trace object pointers can then be used to execute public methods described in BQTrace(3).

Each trace within the BQTraceview display is assigned a trace label when it is created. This trace label is displayed to the left of the trace. For database data sources, the trace label is in the form <sta> <chan>[;<copy>], where <sta> and <chan> are the CSS sta and chan codes and <copy> is an optional copy number. Individual traces within a BQTraceview object can be duplicated as many times as desired. A duplicated trace will have an ordinal <copy> number starting with 1 for the first copy. The original trace is assigned a copy numbr of 0. The automatically generated trace labels will only show the <copy> numbers for numbers >= 1. The trace labels can be used to determine individual BQTrace object pointers, as described below, which can then be used to set different parameters for individual traces. For instance, a trace can be duplicated n times and each of the duplicated traces can be assigned different filters.

TRACE EXPRESSIONS

A trace expression language has been developed to allow the programmer and user to specify an ordered set of traces to be subject to various actions. Ordering traces in the display is the simplest of these actions. A trace expression is of the form <expression1>[,<expression2>[,<expression3>[,...]]], where each of the <expressionN> strings is of the form <sta_expr>[:<chan_expr>[;<copy_expr>]]. Each trace is compared against the expressions in the comma separated list. If a trace satisfies one of the expressions in the comma separated list, then that trace is given an order number based on its position in the comma separated list. Each of the expressions in the comma separated list are evaluated against each trace in the BQTraceview object as follows. The CSS sta code is compared against <sta_expr> which can be *, matching all sta codes, or a normal datascope-style expression to match against sta. The trace continues to match against the optional <chan_expr> and <copy_expr> strings. If these expressions are not specified, then all channels and all copies will match. A single * character will also match all channels or copies. Trace matches with the same order number from the original comma separated list are ordered alphabetically according to their trace labels. Note that if only original traces are desired, then the <copy_expr> should be specified and set to 0. For instance, an expression that matches all stations and channels but only for the original traces would be *:*;0. As another example, the expression that would produce an ordered list of traces in which all of the Z components were first followed by all of the N components then all of the E components would be *:..Z.*,*:..N.*,*:..E.*. Note that with this expression all copies match as well.

INTERACTIONS WITH DATA SOURCES

For database data sources from EVServer and EVClient, notifications of BQTraceview objects are made by EVServer objects through the EVClient::responseCallback and the EVClient::checkDatabaseCallback methods defined in a special EVClient sub-class (see EV(3)) that gets automatically created whenever the EVServer version of BQTraceview::createTraces is called (see below). BQTraceview objects respond to these notifications by immediately updating the display. This provides a mechanism for spontaneous dynamic display updates due to changing databases. In order for spontaneous dynamic display updates to be realized, the application programmer must arrange for the EVServer object to be updated through calls to EVServer::autoRefreshEvents, for automatic periodic refreshes of the event-oriented tables, or EVServer::autoCheckDatabase, for automatic periodic refreshes of the non-event-oriented tables, such as the wfdisc table. Alternatively the application programmer can control exactly when EVServer refreshes are done, or not done, through calls to EVServer::refreshEvents, EVClient::refreshEvents, EVClient::refreshEventsForce and EVClient::checkDatabase.

GRAPHICAL USER INTERACTION

Other than direct user typein interaction through the attached command console, there are various user graphical interfaces that are configured at run time through OBJECT CONFIGURATION PARAMETERS defined below. These configurable interactions include hotkeys, popup arrival menus and taskbar buttons, all defined below.

Most mouse interactions are currently hardwired and are meant to mimic the dbpick(1) mouse interactions as much as possible. In particular, single arrival editing by a single click on an arrival flag without previously selecting that arrival, as it is in dbpick(1) is supported. There are differences between some of the mouse interactions when the main display is in edit mode relative to when it is not in edit mode. Following is a list of mouse interactions in normal, non-edit, mode.

There is a confusion factor that is caused by the Qt graphics engine relating to various keyboard keys used in the graphical user interface. On Apple systems running MacOS, key modifier combinations are internally mapped so that a Control modifier is actually mapped to the Apple Command keyboard key, an Alt modifier is mapped to the Apple Option keyboard key and a Meta modifier is mapped to the Apple Control key. This mapping is done automatically by the Qt engine for Apple systems running MacOS. For Linux systems, the Control modifier uses the Control keyboard key, the Alt modifier uses the Alt keyboard key (the Option keyboard key on an Apple keyboard) and the Meta modifier uses the Meta keyboard key (the Command keyboard key on an Apple keyboard.

The Trace Display Region is the area, excluding the arrival flags, where the traces are displayed. Within this region, while in non-edit mode, the mouse acts as follows:

Following is a list of mouse interactions when the display is in edit mode.

The Trace Label Region is the area to the left of the traces where the trace labels and amplitude annotations are displayed. Within this region the mouse acts as follows:

EDIT QUEUE

Whenever arrivals are edited, a record of that edit is kept in an internal edit queue. The edit queue is a single threaded history of arrival edits made during the running of a BQTraceview object. If a set of arrivals are edited, then the edit queue treats those together as a single edit. Arrival edits can be rolled back to previous states using the arrivals edit_queue undo command described below. Arrival edits can then be redone using the arrivals edit_queue redo command described below. Note that the edit queue is single threaded. This means that if edits are undone and then a new edit is made, then the edit queue history from that new edit is erased.

An arrival edit state can be set using the arrivals edit_queue setstate command described below. When a state has been set, it is possible to roll back/forward arrival edits to that state using the arrivals edit_queue setstate command described below.

INHERITS FROM

BQViewportItem, BQConfigure

CONSTRUCTOR

BQTraceview(BQViewport *master, BQCommandConsole *cc=NULL, int make_taskbar=1, BQViewport *vptaskbar=NULL);

Where master is the BQViewport master for this object. An interactive user typein interface is provided through the cc pointer to a previously assigned BQCommandConsole(3) object. A BQCommandConsole object can be assigned later using the setCommandConsole method defined below. An optional BQTaskbar(3) object, enhanced to support commands through the BQTaskview command interface defined below, will be created if make_taskbar is specified as non-zero. If make_taskbar is non-zero, then if vptaskbar is non-NULL, then the taskbar is assigned to that viewport. Otherwise the taskbar is assigned to the master viewport.

METHODS INHERITED FROM BQConfigure

METHODS INHERITED FROM BQViewportItem

BQTraceview METHODS

Automatic callbacks are blocked whenever the internal nofeedback flag is set. This provides a mechanism for the application programmer to avoid undesired event processing recursion loops. The internal nofeedback can be set or unset with a call to setNofeedback defined following.

OBJECT CONFIGURATION PARAMETERS

COMMANDS

BQTraceview objects can be configured through a set of string commands that can be typed in through a command console object, or programmatically using the sendCommand method, or through the taskbar buttons, hotkeys or arrivals menus defined previously. This command interface provides similar functionality to the typein interface for dbpick(1). Note that commands typed into the command console object or programmatic commands that have been routed through the command console object can generate text output that will be shown in the command console.

Simple command aliases can be defined. The aliases are all evaluated against the first word in a command. Arguments after the aliased command are appended to the unaliased command. Alias substitutions are evaluated recursively providing aliases of aliases functionality. Certain tokens in the commands will automatically be substituted by current display values. Substitution tokens are define below.

  • %time_start
    This token will be substituted with the current epoch time at the left edge of the display.
  • %time_end
    This token will be substituted with the current epoch time at the right edge of the display.
  • %time_middle
    This token will be substituted with the current epoch time at the middle of the display.
  • %time_window
    This token will be substituted with the current display time window.

Following is a list of the commands.

EXAMPLE

Following is a simple c++ example.


#include "BQ.h"

void
usage() {
  fprintf (stderr, "usage: bqplot_test_traceview dbname\n");
}

int
main (int argc, char **argv)

{
  if (argc != 2) {
    usage();
    exit (1);
  }

  char *dbname = argv[1];

  QApplication qapp(argc, argv);

  qapp.setApplicationName("bqplot_test_traceview");

  QWidget *widget = new QWidget();
  widget->setWindowTitle("bqplot_test_traceview");
  widget->show();

  QGridLayout *layout = new QGridLayout (widget);
  layout->setSpacing (0);
  layout->setContentsMargins (0, 0, 0, 0);
  widget->setLayout (layout);

  QSplitter *splitter = new QSplitter (Qt::Vertical, widget);
  layout->addWidget (splitter, 0, 0, 1, 1);

  QFrame *trframe = new QFrame (widget);

  BQViewport *vp = new BQViewport (trframe);

  BQCommandConsole *cc = new BQCommandConsole (widget);

  BQTraceview *traceview = new BQTraceview (vp, cc);

  EVServer *evserver = new EVServer(dbname);
  traceview->createTraces (evserver);
  traceview->configure ("max_traces", "40", NULL);
  traceview->setTimeWindow (BQ_TIME_NULL, 1800.0);
  traceview->sendCommand ("event show 0", NULL);

  splitter->addWidget (trframe);
  splitter->addWidget (cc);

  QList<int> sizes({700, 100});
  splitter->setSizes (sizes);
  widget->setGeometry (50, 0, 1200, 800);

  qapp.exec();

  exit (0);
}


SEE ALSO

bqplot(3), BQViewport(3), BQConfigure(3), BQCommandConsole(3), BQTrace(3), EV(3)

AUTHOR

Danny Harvey, BRTT
Printer icon