OpendTect Plugins

Intro

Background

Making your own software within OpendTect is in principle pretty easy. You could change the software by modifying existing classes and functions, and adding your own stuff to the libs. The advantage is total control. The problem with this approach, however, is that you have to keep the OpendTect sources in sync with new releases. Furthermore, if you cannot convince the opendtect.org people to also make those changes, OpendTect users may not be happy with your work.

An easy way to overcome this is to make your own plugins. Plugins make use of all the facilities of OpendTect but are loaded at run-time and can therefore be developed in a completely independent way. If you then find things that can't be done without modifying the OpendTect environment, it should be much easier to convince the opendtect.org people to take over or even implement those things themselves.

One thing you cannot do, is use another compiler than gcc/g++. OpendTect is built with it, if you want to use another compiler (why?) you'll have to make all libs and supporting libs (Qt, COIN, fftw) yourself. The make itself should be pretty easy to get started, but there will probably be some porting to do, too.

The concept

Dynamic loading

All modern Operating systems nowadays have ways to dynamically load libraries into a running program. The basic idea is:

• Open the library
• Query the contents for a certain routine using a string key
• Call the routine returned
• The routine then does the things needed to make itself useful.

As an example, a 'hello world' program could conceptually look like this:

dynlib = OpenDynamicLib( "libc.so" );
PrintfTypeFunction fn = (PrintfTypeFunction)GetDynLibFn( dynlib, "printf" );
fn( "Hello world\n" );

In this very simple case calling the function has no other effect than printing a string. In OpendTect, you'd want to add an attribute, create a menu item in the Opendtect menu, start horizon tracking, that sort of thing.

OpendTect plugins

In OpendTect, all of the dynamic lib querying etc. is already programmed. A plugin just needs to contain a few standard functions that will be called automatically when the dynamic library is loaded. There are three functions, of which only one is really required. Let's say the name of the plugin is MyMod, these functions will be:

GetMyModPluginType
GetMyModPluginInfo
InitMyModPlugin

Realistic examples

Menu and Dialog

Intro

Adding menu items popping up your own dialogs is pretty easy once you get the hang of it. Although we fear that you might be scared by this code when you first see it, we hope that after the explanations below you will see some beauty in it and start to like it.

Look in uihellopi.cc - the else of the PLAN_A part. First of all, we nicely define the other standard plugin functions:

extern "C" int GetuiHelloPluginType()
{
    return PI_AUTO_INIT_LATE;
}

extern "C" PluginInfo* GetuiHelloPluginInfo()
{
    static PluginInfo retpi = {
        "uiHello plugin - plan B",
        "Bert",
        "1.1.1",
        "This is the more extensive variant of the uiHello example.\n"
        "See the plugin manual for details." };
    return &retpi;
}

The Tutorial plugin

Intro

Now that we've seen some basic plugin stuff, and some basic GUI stuff, we can move on to a real plugin that looks like something that could actually be useful. For this purpose, we have created the Tutorial plugins. As is common in OpendTect, there is a plugin 'Tut' for non-ui, real-work stuff, and the 'uiTut' for the GUI part.

The idea of the tutorial plugins is to show a variety of common things that one might want to do, rather than make something useful for end-users. For that we'll make the following tools:

• Manipulating some seismic data (read, process, write)
• The same, but now using an Attribute
• Do some work with horizons
• Do some work with wells

• Create menu items and toolbar icons
• Make right-click tree item menus
• Work in the COIN 'vis' world
• Work with DataPack's and create flat displays

The uiTut plugin

The Tut plugin

The responsibility of uiTut is limited to talking to the user and getting the input parameters. The real work is done behind the scene by the non-UI Tut plugin. And that is the reason why it is of type EARLY. This particular plugin tells OpendTect's application manager that it wants to be loaded early - i.e. before any build of tables, data structures or user interfaces are made. That is typical of 'Real Work' plugins. The alternatives are NONE (which is default so in that case a GetxxxxPluginType() need not be defined) and LATE, which is typical for UI plugins that want to start working when all objects have already been created.

extern "C" int GetTutPluginType()
{
    return PI_AUTO_INIT_EARLY;
}

SeisTools

Let us first look at the direct seismic operations, that are handled by the class SeisTools, which in turn is a subclass of class Executor. 'Real work' is done by the function nextStep() which is typical of class Executor. Here, three different operations are possible: Scaling, where you can multiply the data values by a certain factor and apply a shift; Squaring, where as the name suggests, you can take a square of the data values; and Smoothening, where you can take the arithmatic average of 3 or 5 samples depending on the filter strength. Traces are read one-by-one by a SeisTrcReader and supplied to the function handleTrace() where the actual computation is done. Then a SeisTrcWriter writes the output traces on-by-one to the output cube.

int Tut::SeisTools::nextStep()
{
    if ( !rdr_ )
        return createReader() ? Executor::MoreToDo : Executor::ErrorOccurred;

    int rv = rdr_->get( trcin_.info() );
    if ( rv < 0 )
        { errmsg_ = rdr_->errMsg(); return Executor::ErrorOccurred; }
    else if ( rv == 0 )
        return Executor::Finished;
    else if ( rv == 1 )
    {
        if ( !rdr_->get(trcin_) )
            { errmsg_ = rdr_->errMsg(); return Executor::ErrorOccurred; }

        trcout_ = trcin_;
        handleTrace();

        if ( !wrr_ && !createWriter() )
            return Executor::ErrorOccurred;
        if ( !wrr_->put(trcout_) )
            { errmsg_ = wrr_->errMsg(); return Executor::ErrorOccurred; }
    }

    return Executor::MoreToDo;
}

Scaling and squaring are single-sample operations. But as you can see in the implementation of the function handleTrace() below, smoothening involves multi-sample computation. It requires separate input and output traces. Otherwise, if we did the operation on the same trace, we would be taking the modified values of samples preceding the current sample. For the sake of simplicity, we make a copy of the input trace to store the output values. This is not a good practice as it results in duplication of data. But since it is a tutorial, our aim is to keep the code as simple as possible and leave the efficiency part for serious programming.

void Tut::SeisTools::handleTrace()
{
    switch ( action_ )
    {

    case Scale: {
        SeisTrcPropChg stpc( trcout_ );
        stpc.scale( factor_, shift_ );
    } break;

    case Square: {
        for ( int icomp=0; icomp < trcin_.nrComponents(); icomp++ )
        {
            for ( int idx=0; idx < trcin_.size(); idx++ )
            {
                const float v = trcin_.get( idx, icomp );
                trcout_.set( idx, v*v, icomp );
            }
        }
    } break;

    case Smooth: {
        const int sgate = weaksmooth_ ? 3 : 5;
        const int sgate2 = sgate/2;
        for ( int icomp=0; icomp < trcin_.nrComponents(); icomp++ )
        {
            for ( int idx=0; idx < trcin_.size(); idx++ )
            {
                float sum = 0;
                int count = 0;
                for( int ismp=idx-sgate2; ismp <= idx+sgate2; ismp++)
                {
                    const float val = trcin_.get( ismp, icomp );
                    if ( !mIsUdf(val) )
                    {
                        sum += val;
                        count++;
                    }
                }
                if ( count )
                    trcout_.set( idx, sum/count, icomp );
            }
        }

    } break;

    }

    nrdone_++;
}

Similar to SeisTools, HorTool performs some simple operations on horizons: thickness computation and smoothening. Each of these operations is handled by a subclass of HorTool which is a subclass of Executor and as expected the computation is performed by the function nextStep(). You may notice here that no object of class HorTool is defined anywhere. It is only used as the base class for classes ThicknessCalculator and HorSmoothener. Let us have a look at the nextStep() function in class ThicknessCalculator to see how the data values are accessed in a Horizon3D:

int Tut::ThicknessCalculator::nextStep()
{
    if ( !iter_->next(bid_) )
        return Executor::Finished();

    int nrsect = horizon1_->nrSections();
    if ( horizon2_->nrSections() < nrsect ) nrsect = horizon2_->nrSections();

    for ( EM::SectionID isect=0; isectgetPos( isect, subid ).z;
        const float z2 = horizon2_->getPos( isect, subid ).z;

        float val = mUdf(float);
        if ( !mIsUdf(z1) && !mIsUdf(z2) )
            val = fabs( z2 - z1 ) * usrfac_;

        posid_.setSubID( subid );
        posid_.setSectionID( isect );
        horizon1_->auxdata.setAuxDataVal( dataidx_, posid_, val );
    }

    nrdone_++;
    return Executor::MoreToDo();
}

Please note the difference in the function dataSaver in the two classes. In ThicknessCalculator, it saves the auxilary data, whereas in HorSmoothener, it saves the geometry.

initClass()

This static function initializes the attribute: sets up the parameters and the number and type of the inputs and outputs. You can compare this to what you see in Opendtect in the attribute definition window after loading the uiTut plugin.

If you look at the parts of the implementation carefully, ( tutorialattrib.cc ) you'll see that each parameter is built up following this example:

EnumParam* action = new EnumParam( actionStr() );
    action->addEnum( "Scale" );
    action->addEnum( "Square" );
    action->addEnum( "Smooth" );
    desc->addParam( action );

Every parameter is required by default, to overrule this use setRequired(false)"