Contact Us

tutorials-geomodeller


To create a section:
  1. Select the topography section in the 2D viewer, if it is not visible double left click it in the Project Explorer pane on the left side
  2. Select the Create Lines tool in the left icon menu
  3. Draw the new section line on the SurfaceTopography section
  4. Select the Create Section from its Trace tool in the upper icon menu to open a new window
  5. Make all necessary adjustments and then click create




Although GeoModeller is not primarily designed for this task, it is possible to model thin, (un)even, topography bound cover in GeoModeller using Dykes as a workaround.


The procedure is as follows for a cover of "relaxed" thickness <T>:

  1. Create a dyke under Geology->Dykes: Manage



    The dyke will be automatically added to a new Series and Placed at the top of the Stratigraphic pile


  2. Digitize a cloud of solo contact points for the dyke on the topography section with horizontal associated orientation data and a thickness of 200% of <T>.
    When dealing with high relief terrain, a better fit can be achieved by deriving orientation data from the topography itself using the Fit a Plane to Points tool.
    There should no lines between the points as we do not want the interpolator to consider any winding order.






Geological interfaces and/or faults may be digitized in GeoModeller using a 2D grid as reference. 


For regular raster images (png, jpeg, tiff) skip to step 4


Steps 1 to 3 are for data grids only:

  1. Import your grid into GeoModeller under Import->Grid and Mesh->2D Grid
  2. On the left panel, navigate to Grids and Meshes->YourGridName->YourChannelName->right click->Field Visualisation Manager
  3. Select View on Section for the SurfaceTopography
  4. If you have other grids/views projected to the section of interest you may manage them using the Image Manager.
    You may import regular raster images (png, jpeg, tiff) directly using the Image Manager. Note that you will have to georeference regular images to be consistent with the section's coordinate system and projection.
     
  5. Once the grid is appropriately projected to the section, use the point tool to digitize the contours/structures of interest
  6. The digitized points may then be attributed to a formation or fault using the Create Geology Data tool



Overview

GeoModeller mainly relies on foliations and interface/contact points to draw surface via cokriging interpolation of a 3D vector field. GeoModeller is able to consider the influence of foliations on the vector field anywhere in the model box. Consequently, it is possible to place foliations away from the interfaces and obtain geologically sound results (Figure 1).


Figure 1 – Foliations constrain the geometry of the interfaces regardless of their location.


However, GeoModeller is actually unable to fully incorporate this information automatically. GeoModeller discards the lithological support of observed foliations and records them as mere vectors with known orientations. The lithological support of foliations refers to the fact that foliations are taken off of actual outcrops. Therefore, foliations should not only be recorded as vector data to constrain the gradient of the vector field but also as a point data to constrain the interfaces. Not doing so can lead to absurd situations where an observed foliation is at a location where the model determines that another formation takes place (Figure 2, Figure 3 bottom right). Note that foliations orthogonally associated to interface points (Figure 3) are not concerned with this discussion as they typically are not genuine observations.


Figure 2 - Foliations of a formation may be located inside of another formation.


 

Figure 3 - Orthogonal foliations are often "miss-located", this is inconsequential.

 

The desired outcome is to somehow manage to extend the formations to their genuine foliations to honor the existence of their support.

 For the sake of conciseness and simplicity, in the following sections, the type of foliation that is of concern will be referred to as “remote foliation”. 



Single remote foliation case

 

In the case of a single remote foliation, all that is needed most of the time is to add a contact point on top of the remote foliation and recompute the model (Figure 4). This method assumes that the remote foliation is also a contact.


Figure 4 - Single remote foliation upgraded to associated contact point.

 


Multiple foliation case

 

Incorrect methods

 

When there are multiple remote foliations, applying the method described above on all remote foliations produces meaningless results regardless of assumptions (Figure 5).



 

Figure 5 - Multiple remote foliation are not solved by upgrading to associated points.

 

One might be tempted to apply the method on the remote foliation farthest to the original interface (Figure 6).

 

Figure 6 - Multiple remote foliations cannot be dealt with a single associated point.

 


However, this is ill-advised as it leads to many artefacts and doesn’t guarantee that all remote foliations be included in the formation.

 

Correct method

 

A completely different procedure is required to ensure that all remote foliations are appropriately included in the formation. The proposed method takes advantage of the fact that multiple formations share the same vector field when they are part of the same series.

 

For each remote foliation:

 

  1. Create a dummy formation
  2. Add the dummy formation to the series that contains the original formation
  3. Add a contact point on top of the remote foliation
  4. Attribute this contact point to the dummy formation
  5. Repeat for all remote foliations

 

Next all dummy formations should be ordered in the series as a function of distance to the original interface above or below the original formation (Figure 7, Bottom formation).

 


Figure 7 - Ordering of the dummy formations.

  

The next and final step is to anchor the farthest and nearest dummy formations (Figure 7, DummyBottom0 and DummyBottom6) on the existing geometry of the original formation to constrain the intercalary dummy formations. Some of the other dummy formations might need to be anchored in the same way if the geometry of the intercalary dummy formations is not constrained sufficiently.

 

Figure 8 - Successful integration of all remote foliations.

 


It is often observed that dummy formations are not visible because of the anchorage procedure described above (Figure 8). Dummy formations’ appearances may be harmonized with the original formation when it is not the case. If needed, tweaks in the variographic cokriging parameters may give a cleaner fit (Figure 9).

 

Figure 9 - Variographic parameters may be altered to achieve a cleaner fit.

 






1 Introduction

Intrepid Geophysics provides the users of GeoModeller the means to build software interaction using our API.

All of Intrepid Geophysics’ software solutions operate a file instruction API based on the Google Protocol Buffers (GPB) which functions as a scripting language/parameter file interface between plain users and/or other codes.

Because the API uses plain text files as intermediates, it is possible to write GPB compliant message files by hand and pass them to the API via command line instructions, see section 6 for more details on how to do so.

This tutorial presents the main steps required to setup, install and integrate our API into your own source code.

2 Requirements

To use GeoModeller’s API, you will need:

  • A licensed install of GeoModeller
  • Valid environment variables
  • GPB install

3 Installing and licensing GeoModeller

Download GeoModeller and install. It is recommended not to change the default installation directory.

If you do not own a license, you can request a one month fully enable trial license through the license manager.



4 Environment variables

For GeoModeller 4.1.0 and onward:

Set or add $GEOMOD_INSTALL\jre\bin and $GEOMOD_INSTALL\jre\bin\server to your environment variable Path.

For older versions:

Set or add $GEOMOD_INSTALL\bin\server to your environment variable Path.

5 The Google Protocol Buffers

The Google Protocol Buffers is a data structure serialization library published by Google as an alternative to JSON or XML files with a particular aim on speed, clarity and lightness.

The API of GeoModeller uses GPB compliant message files called .task files. These .task files are then parsed/written using GPB.

5.1 Overview

The GPB website offers free, high quality tutorials and comprehensive reference that we strongly advise prospective API users to read through.

Overall, the GPB can be described as a four staged system:

  • the data structures (not the data itself) to be serialized are written in .proto files with a message syntax defined by the GPB.
  • the .proto files are processed using the GPB’s own compiler to produce I/O classes in a given target language such as C++, C#, Python or Java.
  • the codes can then be used and compiled in another project provided that the GPB library is installed and adequately linked.
  • data structures are serialized into messages.



5.2 GPB Installation

Although installation of the GPB lib is not technically required to run GeoModeller’s API, it is strongly recommended for any reasonably complex project. You may download the GPB lib from the GitHub release page of the GPB project.

Steps for installation are fairly simple and may be found in the README.md file.

If you are developing on Windows, it is recommended to install either msys or Cygwin to emulate a Linux environment and then follow the Ubuntu specific instructions in the README.md.

5.3 GPB integration

To integrate GPB into your project, you will have to link the library’s dll into your build system.

  • $\local\lib\libprotoc.dll.a
  • $\local\lib\libprotoc.a
  • $\local\lib\libprotobuf-lite.dll.a
  • $\local\lib\libprotobuf-lite.a
  • $\local\lib\libprotobuf.dll.a
  • $\local\lib\libprotobuf.a

This will allow you to include the necessary GPB headers into your source code to parse/write the message files, for example:

#include <google/protobuf/text_format.h>
#include <google/protobuf/io/zero_copy_stream_impl.h>


5.4 GPB compilation

In GeoModeller’s install directory, under $GEOMOD_INSTALL\examples\API, you will find a number of .proto files. These proto files define a message syntax which corresponds to the data structures the API employs.

Once GPB is installed, it is possible to invoke the protoc compiler onto our proto files.

The first proto file to be compiled is the commontaskmodel.proto which contains all the low level data structures (such as 3D point) to generate code C++ code for example.

The output is a header and source file with GPB C++ I/O codes that you may then include into your project.

  • commontaskmodel.pb.h
  • commontaskmodel.pb.cc

Note that all Intrepid software use proto2 syntax with specific package names. See the first lines of the commontaskmodel.proto file.


syntax = "proto2";
 
// Here is the specification of the common low level or useful GOOGLE/Protobuf schema
// note, no XML, designed for fast message passing between processes.
// (C) 2017 Intrepid Geophysics
package ctm; // commontaskmodel
 
message PairInt32 {
    required int32 first = 1;
    required int32 second = 2;
}


Additionally, proto files may include definitions of other proto files. For example the gmtaskmodel.proto includes two.


import "commontaskmodel.proto"; // include
import "vtktasksup:proto"; // include
 
package gmtaskmodel;
 
enum GeomodellerDataSource {
    Project = 0;
    File = 1;
}


5.5 Parsing tasks

Once GPB is fully deployed, GeoModeller API .proto files can be translated into source code which is used to parse/write existing .task files (C++ example):


void ImportProtoTaskGeoModProject(const std::string &taskPath)
{
    std::ifstream inputRawTask(taskPath.c_str());
    if (!inputRawTask.good())
    {
        std::cerr << "Error while opening a .task file!" << taskPath << std::endl;
        std::exit(0);
    }
    std::string input;
    inputRawTask.seekg(0, std::ios::end);
    input.reserve(inputRawTask.tellg());
    inputRawTask.seekg(0, std::ios::beg);
    input.assign((std::istreambuf_iterator<char>(inputRawTask)), std::istreambuf_iterator<char>());
 
 
    // Declare a custom wrapper message for all GeomodellerTasks
    wrapper::WrapperForGeoTasks tasksList;
 
    // Parsing.
    google::protobuf::TextFormat::ParseFromString(input, &tasksList);
 
    // Declare container.
    gmtaskmodel::CreateProject_GMT createProjectList;
     
    // Populate container.
    for (int i = 0; i < tasksList.geomodellertask_size(); ++i)
    {
        if (tasksList.geomodellertask(i).has_createproject())
        {
            createProjectList.push_back(tasksList.geomodellertask(i).createproject());
        }
        // Convert into local class.
        Extents2D extents;
        extents.maxi.x = createProjectList.extents().xmax();
        extents.maxi.y = createProjectList.extents().ymax();
        extents.mini.x = createProjectList.extents().xmin();
        extents.mini.y = createProjectList.extents().ymin();
        return;
    }
}


5.6 Writing tasks

The same C++ I/O classes are used to write .task files. GPB specific details can be found at https://developers.google.com/protocol-buffers/docs/reference/cpp-generated

Below is an example of C++ codes which uses I/O classes derived from the commontaskmodel.proto and gmtaskmodel.proto files found at $GEOMOD_INSTALL\examples\API.


/*
Basic protobuf io module for task files.
Authors: Evren Pakyuz-Charrier.
evrenpakyuzcharrier@gmail.com
Intrepid Geophysics 2018.
*/
#ifndef TASK_IO_H
#define TASK_IO_H
 
#include <vector>
 
// Include GPB lib headers.
#include <google/protobuf/text_format.h>
#include <google/protobuf/io/zero_copy_stream_impl.h>
 
// Include automatically generated code.
#include "commontaskmodel.pb.h"
#include "gmtaskmodel.pb.h"
 
class TaskIO
{
public:
  std::string WriteSillyTask(const std::string &taskPath)
  {
    std::ofstream outputTaskFile(taskPath.c_str());
 
    if (!outputTaskFile.good())
    {
      std::cerr << "Error while opening a .task file!" << taskPath << std::endl;
      std::exit(0);
    }
 
    // Task container.
    std::vector<gmtaskmodel::GeomodellerTask> tasks;
 
    // Declare a CreateProject message.
    gmtaskmodel::CreateProject_GMT createProject;
    {
      // Locally define essential attributes for the CreateProject message, leave others default.
      gmtaskmodel::HorizontalDTM_GMT dtm;
      dtm.set_name("Topography");
      dtm.set_elevation(0.);
 
      ctm::BoundingBox extents;
      extents.set_xmin(0.);
      extents.set_ymin(0.);
      extents.set_zmin(-1000.);
      extents.set_xmax(1000.);
      extents.set_ymax(1000.);
      extents.set_zmax(0.);
 
      // Copy into the CreateProject message.
      createProject.mutable_HorizontalDTM()->CopyFrom(dtm);
      createProject.mutable_Extents()->CopyFrom(extents);
    }
 
    // Container for formations.
    std::vector<gmtaskmodel::CreateFormation_GMT> createFormationList;
 
    for (size_t i = 0; i < 2; ++i)
    {
      gmtaskmodel::CreateFormation_GMT formation;
      std::string name = "Formation_" + i;
      formation.set_name(name);
      createFormationList.push_back(formation);
    }
    gmtaskmodel::CreateFormation_GMT basement;
    basement.set_name("basement");
    createFormationList.push_back(basement);
 
    // Container for series.
    std::vector<gmtaskmodel::SetSeries_GMT> setSeriesList;
    size_t pos = 1;
 
    gmtaskmodel::SetSeries_GMT basementSeries;
    basementSeries.set_name("basement_Series");
    basementSeries.set_relation("onlap");
    setSeriesList.push_back(basementSeries);
    ++pos;
 
    for (std::vector<gmtaskmodel::CreateFormation_GMT> const_iterator formationIterator = createFormationList.begin();
         formationIterator != createFormationList.end() - 1;
         ++formationIterator)
    {
      gmtaskmodel::SetSeries_GMT series;
      series.set_name(formationIterator->name() + "_Series");
      series.set_position(pos);
      series.set_relation("erode");
      setSeriesList.push_back(series);
    }
 
    // Container for formation allocation.
    gmtaskmodel::AddFormationToSeries_GMT addToSeriesList;
 
    // Silly formation allocation.
    gmtaskmodel::AddFormationToSeries_GMT addToSeries;
    addToSeries.set_series("basement_Series");
    addToSeries.set_formation("basement");
    addToSeriesList.push_back(addToSeries);
    addToSeries.set_series("Formation_0_Series");
    addToSeries.set_formation("Formation_0");
    addToSeriesList.push_back(addToSeries);
    addToSeries.set_series("Formation_1_Series");
    addToSeries.set_formation("Formation_1");
    addToSeriesList.push_back(addToSeries);
 
    // Container for interfaces.
    std::vector<gmtaskmodel::Add3DInterfacesToFormation_GMT> add3DInterfacesList;
 
    gmtaskmodel::Add3DInterfacesToFormation_GMT interfaceAdd;
    ctm.Point3d interfaceLocation;
 
    // Silly interfaces attribution.
    interfaceAdd.set_formation("Formation_0");
    interfaceLocation.set_x(500.);
    interfaceLocation.set_y(500.);
    interfaceLocation.set_z(-200.);
    interfaceAdd.mutable_point()->CopyFrom(interfaceLocation);
    add3DInterfacesList.push_back(interfaceAdd);
    interfaceAdd.set_formation("Formation_1");
    interfaceLocation.set_x(500.);
    interfaceLocation.set_y(500.);
    interfaceLocation.set_z(-100.);
    interfaceAdd.mutable_point()->CopyFrom(interfaceLocation);
    add3DInterfacesList.push_back(interfaceAdd);
 
    // Container for foliations.
    std::vector<gmtaskmodel::Add3DFoliationToFormation_GMT> add3DFoliationList;
 
    gmtaskmodel::Add3DFoliationToFormation_GMT foliationAdd;
    gmtaskmodel::Foliation_GMT foliation;
    ctm.Point3d foliationLocation;
 
    // Silly foliations attribution.
    // Foliations can be anywhere.
    foliationLocation.set_x(1.);
    foliationLocation.set_y(1.);
    foliationLocation.set_z(-200.);
    foliation.mutable_Point3D()->CopyFrom(foliationLocation);
    // Horizontal foliations are OK.
    foliation.set_dip(0.);
    foliation.set_direction(0.);
    foliationAdd.mutable_foliation()->CopyFrom(foliation);
    foliationAdd.set_formation("Formation_0");
    add3DFoliationList.push_back(foliationAdd);
 
    foliationLocation.set_x(1.);
    foliationLocation.set_y(1.);
    foliationLocation.set_z(-50.);
    foliation.mutable_Point3D()->CopyFrom(foliationLocation);
 
    foliation.set_dip(30.);
    foliation.set_direction(270.);
    foliationAdd.mutable_foliation()->CopyFrom(foliation);
    foliationAdd.set_formation("Formation_1");
    add3DFoliationList.push_back(foliationAdd);
 
    gmtaskmodel::ComputeModel_GMT modelCreation;
 
    gmtaskmodel::CloseProjectNoGUI_GMT closeProject;
 
    for (std::vector<gmtaskmodel>::const_iterator taskIterator = tasks.begin();
         taskIterator != tasks.end();
         ++taskIterator)
    {
      std::string stringOutput;
      google::protobuf::TextFormat::PrintToString(*taskIterator, &stringOutput);
      outputTaskFile << stringOutput << std::endl;
    }
 
    return;
  }
}



We recommend using a new GeoModellerTask message for each high level message when writing your own own task files.

Consequently, it may be useful to make a wrapper for the gmtaskmodel::GeomodellerTask class and use GPB vector containers instead of STL or custom ones:


// Wrapper for GeoModellerTasks text based tasks.
syntax = "proto2";
 
import "gmtaskmodel.proto";
 
package wrapper;
 
message WrapperForGeoTasks (
    optional string name = 1;
    optional string description = 2;
    repeated gmtaskmodel.GeomodellerTask GeomodellerTask = 3;
}


This allows the use of the .add_foo() method to list GeomodellerTask messages, more at https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.repeated_field

6 Running API tasks

6.1 In command line

There are two common ways to interact with GeoModeller’s API for the moment, via command line and via GUI.

The command line syntax for GeoModeller 4.1.0 is:


$GEOMOD_INSTALL\bin\batch.bat myTask.task



or for older versions:


$GEOMOD_INSTALL\bin\geomodellerbatch.exe myTask.task


6.2 In GUI

The GUI procedure is: Navigator -> double click task file -> Left click into text editor -> Run As -> Execute



7 Example task

Example task files for GeoModeller can be found at $GEOMOD_INSTALL\examples. Below is an example task file that builds a simple 3D geological model and saves it to disk:


GeomodellerTask {
CreateProject {
name: "MyProject"
author: "Evren Pakyuz-Charrier"
Extents {
xmin: 0.
ymin: 0.
zmin: -1000.
xmax: 1000.
ymax: 1000.
zmax: 0.
}
referenceTop: true
HorizontalDTM {
name: "Topography"
elevation: 0
}
}
}
GeomodellerTask {
CreateFormation {
name: "Formation1"
}
}
GeomodellerTask {
CreateFormation {
name: "Formation2"
}
}
GeomodellerTask {
SetSeries {
name: "Series1"
position: 1
relation: "erode"
}
}
GeomodellerTask {
SetSeries {
name: "Series2"
position: 2
relation: "erode"
}
}
GeomodellerTask {
AddFormationToSeries {
series: "Series1"
formation: "Formation1"
}
}
GeomodellerTask {
AddFormationToSeries {
series: "Series2"
formation: "Formation2"
}
}
GeomodellerTask {
Add3DFoliationToFormation {
formation: "Formation2"
foliation {
Point3D {
x: 400
y: 800
z: -500
}
dip: 45
direction: 0
polarity: Normal_Polarity
}
}
}
GeomodellerTask {
Add3DFoliationToFormation {
formation: "Formation1"
foliation {
Point3D {
x: 400
y: 800
z: -500
}
dip: 45
direction: 0
polarity: Normal_Polarity
}
}
}
GeomodellerTask {
Add3DInterfacesToFormation {
formation: "Formation1"
Point3D {
x: 350
y: 700
z: -400
}
}
}
GeomodellerTask {
Add3DInterfacesToFormation {
formation: "Formation1"
Point3D {
x: 350
y: 700
z: -100
}
}
}
GeomodellerTask {
ComputeModel {
SeriesList {
node: "All"
}
}
}
GeomodellerTask {
SaveProjectAs {
filename: "./out/layer_cake.xml"
}
}


GeoModeller organizes data into projects. In terms of persistence, a project is stored in the file system as a directory, which includes the project descriptor, plus the persistence of each type of data.

It is possible and recommended to use version control systems to keep track of the changes, a version control systems provide:

  1. Backup and Redundancy;
  2. Revision control and change history tracking using the integrated client or your own third-party client;
  3. Access control;
  4. Data sharing via local or online Git repositories;

Integrated Git Client (EGit)


By default, GeoModeller v4.0 provides an integrated Git client. This article covers the basic configuration steps to activate versioning on an existing GeoModeller project and routine procedures.

However, we suggest you refer to Git's User Guide for more detailed information on repository management.


One-off Git Configuration


If Git software is installed on the computer, there is a high chance the steps in this section are not needed.

  1. Launch GeoModeller;
  2. Press CTRL-3 to bring up Quick Access dialog. Type pref in the box then choose Preferences from the commands list to open Preferences dialog;
  3. In Preferences dialog, expand to Team → Git → Configuration;



If the user has Git installed and configured then the configuration will show up in the table. Check if there are two keys called user → email and user → name.
If not, click on Add Entry... to create two key-value entries, then press OK button to save them;

Key

Value

user.name
(Example) John Doe
user.email
(Example) john.doe@example.com



Capture3.PNG


Setup an existing project for Git

  • Open a project;
  • Switch to Navigator view. The only openned project is the current project. Right click on it then choose Team → Share Project...;Capture5.PNG


  • Select Use or create repository in parent folder of project, single click on the project listed (do not tick the check box) then the gray-out Create Repository button becomes available. Click on it then click on the Finish button.

There is a tiny decorator showed up on the icons for each project file in the navigator.



  • Make the first commit into the repository. Switch to Navigator view, then right click on the project, choose Team → Commit... to open the Git Staging dialog;