Ocean Developer's Guide - Ocean - Schlumberger

Getting Started with Ocean
For Geoscientists and Software Developers
Published by Schlumberger Information Solutions,
5599 San Felipe, Houston Texas 77056

Getting Started with Ocean
Copyright Notice
Copyright © 2008 Schlumberger. All rights reserved.
The information in this document is subject to change without notice. The
software described in this document is furnished under a license agreement.
This software may be used or copied only in accordance with the terms of
such agreement. It is against the law to copy the software on any medium
except as specifically allowed in the license agreement. No part of this
document may be reproduced or transmitted in any form, or by any means,
electronic or mechanical, including photocopying and recording, for any
purpose without the express written permission of Schlumberger.
Trademarks
Petrel and Ocean are trademarks of Schlumberger.
Microsoft® and Windows® are registered trademarks of Microsoft
Corporation.
ii

Table of Contents
Chapter 1 Welcome to Ocean ...................................................................... 1
Introduction .................................................................................................................. 1
Access to Petrel Data Domain ................................................................................. 4
Ocean UI Infrastructure ............................................................................................. 6
The Ocean Module ..................................................................................................... 7
IModule Interface .................................................................................................. 9
Chapter 2 Your First Application ............................................................... 12
Writing the Application ............................................................................................ 12
Starting with Visual Studio ................................................................................. 13
Inspect the Files ................................................................................................... 14
Write Algorithm Code .......................................................................................... 18
Running the Application .......................................................................................... 20
Chapter 3 The Petrel Data Domain ............................................................ 24
Ocean Exposes Petrel’s Data Model ..................................................................... 24
Entities and Properties ........................................................................................ 24
User View of the Petrel Data Model ................................................................. 26
Data Access ............................................................................................................... 32
Data Types Exposed ............................................................................................ 33
Read Access .............................................................................................................. 38
Browsing through collections ............................................................................ 38
Seismic ................................................................................................................... 39
Well and Geology ................................................................................................. 40
Static Model .......................................................................................................... 42
Simulation and Data Analysis ............................................................................ 43
Data Updates ............................................................................................................. 44
Transactions.......................................................................................................... 45
Modifying Domain Objects ................................................................................. 45
Domain Object Relationships ............................................................................. 46
Domain Object Creation ........................................................................................... 48
iii

Table of Contents
Creating New Instances ..................................................................................... 48
Creating New Collections ................................................................................... 49
Deletions ..................................................................................................................... 52
Data Access Example .............................................................................................. 52
Online Manual for Data Domain ............................................................................. 55
Opening the manual ............................................................................................. 55
Using Intellisense ................................................................................................. 56
Class Definitions ................................................................................................... 57
Chapter 4 Extending the Petrel UI ............................................................. 60
How to Add a New Menu Item ............................................................................... 60
Edit IntegratePresentation method ................................................................... 61
Creating UI Tools .................................................................................................. 61
Define the Menu Item Properties ...................................................................... 62
Add to ToolsManager .......................................................................................... 64
Results ........................................................................................................................ 64
Chapter 5 Extending the Data Domain ...................................................... 66
Basic Custom Domain Object ................................................................................. 67
Adding to Input and Models Trees ........................................................................ 68
Adding to Native Petrel Domain Objects ......................................................... 69
Adding an Object from a Context Menu ........................................................... 70
Customizing Tree Presentation .......................................................................... 72
Object Visualization .................................................................................................. 74
3D Window Display .............................................................................................. 74
Map Window Display .......................................................................................... 77
Saving Custom Domain Objects ............................................................................. 81
Serialization ........................................................................................................... 81
iv

Chapter 1
Welcome to Ocean
Introduction
Ocean is an application development framework with the capability
to work across data domains. It provides services, components,
and a common graphical user interface that enables applications to
better integrate. It also allows application developers to interact
with other Ocean Model-Centric applications such as Petrel.
Ocean Model-Centric applications are loaded dynamically as .NET
assemblies. These assemblies, the building blocks of Ocean,
contain Modules.
The Ocean architecture has three levels: the Core, the Services and
the product family. For Model-Centric applications, the product
family is Petrel. Ocean modules are managed by the Core layer.
They interact with all levels of the framework, as shown below:
1

Welcome to Ocean
Application Module
Deployed as plug-in or extension module
Schlumberger or 3rd party
Product Family
Ocean Services
Ocean Core
Figure 1-1 - Ocean Architecture
The Ocean Core plays the role of the basic infrastructure. It
manages Ocean modules, registers services, both the services preloaded
by the product family and that are added dynamically via the
API. The Ocean Core manages the data sources provided by the
product family or any external data source that could be defined by
any module. It also performs event management and basic
message logging.
The Ocean Services are a set of application independent utilities.
They are modules that benefit from being standardized across
product families. An example is the Coordinate Service – a utility for
converting between projection and geodetic co-ordinate systems.
The Ocean Services layer only depends on the Ocean Core or on
other Ocean Services.
2

Welcome to Ocean
The product family is the host for Ocean applications, and is the
environment the Ocean module needs to run in. The product family
provides:
• the domain objects and their data source
• the graphical environment in which the applications will
display their data
• a common look and feel for all application user interface
components
Application modules connect to all software layers as well as to the
.NET framework. Application modules can register their own
services with the Ocean Core and benefit from services registered
by other modules. All applications built on the Ocean framework are
designed in a similar fashion but they rely on a product family to
build and run.

Welcome to Ocean
Access to Petrel Data Domain
The application can access data in the following domains provided
by Ocean:
Well (for Petrophysics and Geology applications)
Seismic (for Geophysics)
Shapes (for Structural modeling)
PillarGrid (for Geomodeling)
Simulation (for Reservoir Evaluation)
4

Figure 1-2 Surface with fault model and seismic data
Welcome to Ocean

Welcome to Ocean
Ocean UI Infrastructure
6
Ocean provides the capability to extend Petrel’s user interface
functionality. The Ocean Application Programming Interface (API)
supports:
• Windows: adding custom windows.
• Renderers:
o Adding renderers for domain objects (native and
custom) in different windows.
• Interactions:
o Adding custom window modes to define interactions
in different windows.
o Object picking in different windows for its
manipulation.
• Menus and toolbars:
o Adding new menus to Petrel window or extending
Petrel menus.
o Adding new toolbars with custom tools
o Extending Petrel toolbars with custom tools.
• Petrel project explorer:

Welcome to Ocean
o Adding custom objects in Petrel tree in a particular
hierarchy.
o Adding Processes and workflows in Petrel process
diagram and Workflow editor.
The Ocean Module
An Ocean module is an extension to the product family. Application
programmers create modules that behave just like any standard
part of Petrel. The modules are compiled into assemblies that are
placed in the Petrel installation directory and registered with the
application through the configuration file. Petrel uses the
configuration file to load all registered modules during startup.

Welcome to Ocean
Figure 1-3 - Ocean Modules
The Ocean module has a defined lifecycle with certain
requirements and restrictions that allow the clean integration into
the product family. Its lifecycle phases serve to license the module,
initialize and integrate it into the product family, add presentation
interfaces, and remove all these when the module is unloaded. The
appearance and interaction is seamlessly allows the product family
to treat the module as native code.
An Ocean module uses the functionalities provided by the product
family, the Ocean Services, the Ocean Core, and also the .NET
architecture. It may also use 3rd party application assemblies and
other modules.
Ocean modules are built with Visual Studio 2005 for .NET with the
help of the Ocean wizard. The wizard takes care of the interaction
with the Core and some low-level access to functionality provided
by the product family.
8

Welcome to Ocean
IModule Interface
An Ocean module implements the IModule interface. The product
family is responsible for loading the module. IModule is defined in
the Slb.Ocean.Core namespace.
The IModule interface defines five methods of the module
lifecycle phases and inherits from IDisposable. The phases and
their methods are:
• construction (default constructor)
• initialization (Initialize)
• integration (Integrate)
• presentation integration (IntegratePresentation)
• disintegration (Disintegrate)
• disposal (Dispose)
Default Constructor
During the product startup the Ocean Core will load modules as
defined in the configuration file for the product family. The Ocean
Core will call the default constructor to instantiate each module.
The constructor could be used to acquire any licenses, initialize any
private fields and acquire any resources the module needs.
Initialization
The second phase of the module lifecycle is the execution of the
Initialize method. The main purpose of Initialize is
registration of the services provided by the module with the Ocean
ServiceLocator class. When initialization is complete the

Welcome to Ocean
services registered are available for consumption by all Ocean
modules.
Integrate
The Integrate method is the first point at which a module may
consume services registered with Ocean. This is because all
modules have been through the initialize phase where their
services are registered with Ocean. The Ocean Core
ServiceLocator class is used to look up services.
Integrate Presentation
The IntegratePresentation method of IModule is the phase
in the module lifecycle in which user interface components (menus,
toolbars, context menus, windows etc.) are added to the product
family.
Disintegrate
When the product family begins to shut down the IModule
Disintegrate method is called on each module. Disintegrate
has the responsibility of cleaning up any presentation elements
installed by the module.
Dispose
Dispose comes from the IDisposable pattern and must be
implemented as part of your IModule implementation. The purpose
of Dispose is to free any unmanaged resources and free any
licenses acquired by the module.
10

Welcome to Ocean
Example
The following is an example module.
public class MyModule : IModule
{
// Perform initializations, acquire licenses if any
public Module ()
{
...
}
// Initialize services provided by the module
public Initialize ()
{
// Create the service
object FooBar = new FooBarService();
}
// Add the service by its type
CoreSystem.Services.AddService(typeof(FooBarService), FooBar);
...
// Integrate services provided by other modules
public Integrate ()
{
// Find the coordinate system service
ICoordSysService coordService;
coordService = CoreSystem.GetService() as
ICoordSysService;
...
}
// Add to user interface of product family
public IntegratePresentation ()
{
// Define the button to add
ToolbarItem btn = new ToolbarItem(WellKnownUI.Menus.Insert,
“MyButton”, ButtonClick);
}
// Add the button to the Insert menu of the Petrel menubar
PetrelSystem.Tools.Add(btn);
...
// Remove components added to the user interface. Remove services
public Disintegrate ()
{
// Remove the button added to the Insert menu
PetrelSystem.Tools.Remove(btn);
}
// Remove our service
CoreSystem.Services.RemoveService(typeof(FooBarService));
...
// Dispose of any unmanaged resources
public Dispose ()
{
...
}

Your First Application
Ocean allows application developers to extend the Petrel
functionality with new custom processes and workflows. In this
chapter, we will walk through the procedure of creating a simple
Ocean process.
Writing the Application
For our first application we will write an Ocean module that adds a
process to Petrel. The process will print the names of all Seismic
cubes in the current project.
A Process in Petrel is an interactive operation performed on data.
The Process is available from the Petrel Process diagram. The
operation could create new data or update existing data. For
example, the operation of using a set of points to create a well path
would be referred to as a process. In this example the set of points
is the input and the well path is the output.
A Workstep is a single processing step. It differs from a Process in
that it does not require manual interaction when executing. This is
why it can take part in a workflow. Worksteps are available from
12

Your First Application
the Petrel Workflow editor; they also take input data and
parameters, perform some processing, and produce output data.
A Process can be created from a Workstep, so you can write code
one time that is available in both the Process diagram and the
Workflow editor.
We will use the Ocean Wizard to create an Ocean process from a
workstep for our first application.
These are the steps to create your first application:
1. Run the Ocean Wizard in Visual Studio to create the
application module and process.
2. Inspect the files created by the Wizard.
3. Modify the code to add the processing logic.
For details on the installation and use of the Ocean Wizard please
refer to the Ocean Wizard Help manual.
For details on processes and worksteps, please see the Workflow
chapter in the Ocean Developers Guide.
Starting with Visual Studio
Start up Visual Studio.
Create a new project using File-> New Project option. Select Ocean
Petrel Module template from Ocean under Visual C# project type.

Your First Application
Ocean
Project
Type
Ocean Module
Project Name
Create an Ocean module with a process that has no arguments and
an auto-generated UI.
Provide the name “ListSeismic” for the project. It’s generally a good
practice to use the name “Module” for the application module.
Add a new process and add to the process a workstep with the
name “ListSeismicCubes” with its own process wrapper. See the
Ocean Wizard help for details. Do not specify any workstep
argument.
Inspect the Files
The Ocean Wizard will create a solution named “ListSeismic” with
a project named “ListSeismic” in the Visual Studio Solution
Explorer. The project will contain source files for the Module class
14

Your First Application
that was created, and the ListSeismicCubes process that is added
to the Process diagram.
workstep
source file
module
source file
Figure 0-1: Example project source files in Solution Explorer
The wizard configures the ListSeismic project to help debugging.
The assembly is output to the Petrel installation directory. The
project command line property is set up to start Petrel. So
debugging is simply a matter of building and starting the debugger.
The wizard writes the basic code needed for the ListSeismicCubes
application. We will need to add code for our specialized algorithm
in order to print the names of all Seismic Cubes in the current
project.
Module
The Module class implements the IModule interface. Our new
process is added to the Process manager in the Integrate
method automatically by the Wizard.
First the new ListSeismicCubes workstep is created.
public void Integrate()
{
// Registrations:
ListSeismicCubes sWorkstep = new ListSeismicCubes();

Your First Application
Then it is added to the Workflow editor.
PetrelSystem.WorkflowEditor.Add(sWorkstep);
Finally, the process is created from the workstep using the
WorkstepProcessWrapper convenience class. The new
process is added to the Process diagram using the
PetrelSystem.ProcessDiagram API.
IProcessDiagram procDiag = PetrelSystem.ProcessDiagram;
procDiag.Add(new WorkstepProcessWrapper(sWorkstep),"Plugins");
}
Putting the pieces together, the wizard generated the following
Integrate method:
public void Integrate()
{
// Registrations:
ListSeismicCubes sWorkstep = new ListSeismicCubes();
PetrelSystem.WorkflowEditor.Add(sWorkstep);
IProcessDiagram procDiag = PetrelSystem.ProcessDiagram;
procDiag.Add(new WorkstepProcessWrapper(sWorkstep),"Plugins");
}
ListSeismicCubes
16
The ListSeismicCubes class is the workstep class that holds
the processing algorithm. We saw how a process was created
from it in the module.
ListSeismicCubes derives from Workstep, a generic class
that includes the description of the arguments.
public abstract class Workstep : Workstep
where TArgPack : new ();
{
protected abstract void CopyArgumentPackageCore (
TArgPack fromArgPackage,
TArgPack toArgPackage);
protected virtual TArgPack CreateArgumentPackageCore();
protected abstract void InvokeSimpleCore(TArgPack argPackage);
}
The wizard implements nearly all of the class for you. Arguments
copy can be done with the DescribedArgumentsHelper static
class.

Your First Application
public class ListSeismicCubes :
Workstep
{
protected override void InvokeSimpleCore(
ListSeismicCubes.Arguments argPackage)
{
...
// TODO: finish the Invoke method implementation
return;
}
}
protected override void CopyArgumentPackageCore(
ListSeismicCubes.Arguments fromArgPackage,
ListSeismicCubes.Arguments toArgPackage)
{
DescribedArgumentsHelper.Copy(fromArgPackage, toArgPackage);
}
...
The wizard also implements two interfaces, IPresentation (for
its appearance in the Process diagram) and
IDescriptionSource (to display information in the Process UI).
public class ListSeismicCubes : IPresentation, IDescriptionSource
{
#region IPresentation Members
}
public event EventHandler PresentationChanged;
public string Text { ... }
public System.Drawing.Bitmap Image { ... }
#endregion
#region IDescriptionSource Members
public IDescription Description { ... }
#endregion
...
ListSeismicCubes also contains an Arguments class created
by the wizard, which in our case is empty since our algorithm has
no arguments.
public class ListSeismicCubes:Workstep
...
{
public class Arguments : DescribedArgumentsByReflection
}
{
}
...

Your First Application
Write Algorithm Code
The wizard wrote nearly all of our ListSeismicCubes class
except for the custom algorithm code. We will add this code in the
InvokeSimpleCore method, which will be called when the
workstep or process is executed.
To access the APIs from the Seismic namespace, add a reference
in your project to the Slb.Ocean.Petrel.DomainObject.dll.
This assembly is available in the Public folder of the Petrel
installation directory.
Next we need to add using statements for the required
namespaces. Add the following statements at the top along with the
other using statements.
using Slb.Ocean.Petrel.DomainObject;
using Slb.Ocean.Petrel.DomainObject.Seismic;
The work for the process is done in the InvokeSimpleCore
method. We will add our code here:
protected override void InvokeSimpleCore(
ListSeismicCubes.Arguments argPackage)
{
if (argPackage == null)
throw new ArgumentNullException("argPackage must ...");
18
}
// TODO: finish the Invoke method implementation
return;
Our first step is to read the current project using the
PetrelProject.PrimaryProject API.
Project project = PetrelProject.PrimaryProject;
The static class SeismicRoot is used to find the root of all domain
objects in the seismic domain.
SeismicRoot seismicRoot = SeismicRoot.Get(project);
It exposes a property SeismicProject which provides navigation
to all seismic collections and interpretation collections in the
project.

Your First Application
SeismicProject seismicProj = seismicRoot.SeismicProject;
Next we parse through all the seismic collections and print the
names of all seismic cubes within them using the
InfoOutputWindow method of the PetrelLogger class.
We build a dynamic list of surveys (SeismicCollection) to
avoid recursive calls while providing a breadth traversal of the
survey tree.
List listCol = new List(
seismicProj.SeismicCollections);
for (int idx = 0; idx < listCol.Count; idx++)
{
SeismicCollection current = listCol[idx];
foreach (SeismicColl sCol in current.SeismicCollections)
{
// append to the list to replace tail recursion
listCol.Add(sCol);
}
}
foreach (SeismicCube cube in current.SeismicCubes)
{
// Print name of Seismic cube
PetrelLogger.InfoOutputWindow(current.Name +
" contains Seismic Cube " + cube.Name);
}
The PetrelLogger static convenience class provides static
methods to show a textual display of information to users. The
InfoOutputWindow is used to issue an information message
intended for all end users to see, but which is not highly
interrupting.
The complete example follows:
using Slb.Ocean.Petrel.DomainObject;
using Slb.Ocean.Petrel.DomainObject.Seismic;
protected override void InvokeSimpleCore(
ListSeismicCubes.Arguments x)
{
// Get current primary project
Project proj = PetrelProject.PrimaryProject;
// Get the root of all domain objects in the seismic domain
SeismicRoot root = SeismicRoot.Get(proj);
SeismicProject sProj = root.SeismicProject;
// Find all seismic collections in the current project
IEnumerable col = sProj.SeismicCollections;
List listCol =
new List(col);
for(int idx = 0; idx < listCol.Count; idx++)

Your First Application
}
{
SeismicCollection curr = listCol[idx];
foreach (SeismicCollection sCol in curr.SeismicCollections)
{
listCol.Add(sCol);
}
// Find all Seismic cubes in the current collection
foreach (SeismicCube cube in curr.SeismicCubes)
{
PetrelLogger.InfoOutputWindow(curr.Name +
" contains Seismic Cube " + cube.Name);
}
}
return;
Running the Application
After modifying the InvokeSimpleCore method, build the
solution and start Petrel. When Petrel comes up, open the demo
project deployed with the Ocean SDK. Then go to the Process
diagram window and look for “ListSeismicCubes”.
20

Your First Application
Figure 0-2: ListSeismicCubes selected in Process diagram
Double click on it to start the process and display the
ListSeismicCubes dialog. The short and long descriptions are
displayed in the top section of the dialog. There are no arguments
for our process so the lower section is empty.

Your First Application
Figure 0-3: ListSeismicCubes dialog
Click Apply in the dialog to run the process; the ListSeismicCubes
process will display the seismic cubes in the Petrel message log.
22

Your First Application
Figure 0-4: ListSeismicCubes output messages
Exit Petrel. You have now written, built, and run your first Ocean
application.

The Petrel Data Domain
Ocean Exposes Petrel’s Data
Model
Ocean accesses data stored in Petrel Projects. The API exposes
the data objects contained in the current primary Project.
Entities and Properties
A Project built by Petrel contains data elements representing earth
entities (a Well, a Surface, a Reservoir). These entities are
characterized by Properties (such as Logs along a well bore, Height
24

The Petrel Data Domain
fields across a surface, Porosity distributions in a reservoir). Both
types of data are exposed in Ocean by classes, called Domain
Objects.
The entity instance carries the geometry of the object it represents.
The property object only carries property values.
Property Versions
Each Property object in Ocean has a Property Version attached to
it, so that an application working with that Property has a way to:
1 Distinguish between two properties with the same
characteristics (versioning)
2 Knows how to display the property values by applying the
proper template (unit, scale and color table)
Every Property type object in the Petrel Project has a Property
Version member. When creating a Property with the API, a Property
Version also has to be supplied, by extracting it from an existing
object or by creating it with
PetrelSystem.PropertyVersionService.
IUnitMeasurement
PropertyVersion
ITemplate
Figure 3-1 - Property Version, Unit Measurement and Template
Classes
To find or create a Property Version, we can refer to a Template
which is known to Petrel. A list of such templates is available from
the PetrelUnitSystem static class.

The Petrel Data Domain
public void CreateProperty(...)
{
IPropertyVersionService pvs;
pvs = PetrelSystem.PropertyVersionService;
ITemplate templ = PetrelUnitSystem.TemplateGroupVolume.HCPVGas;
IPropertyVersionContainer pvc =
PetrelSystem.GetGlobalPropertyVersionContainer();
PropertyVersion pv = pvs.FindOrCreate(pvc, templ);
// Create Property instance with Property Version pv
...
return;
}
For more details on Property Versions (and Log Property Versions)
refer to the Ocean Developer’s Guide.
User View of the Petrel Data Model
The Petrel Project organizes the user view of the Project in different
trees:
1 Input
2 Models
3 Results
4 Cases
All the trees are accessible via the API. Data is organized in
pseudo-folders, seen in the API as object Collections.
26

The Petrel Data Domain
Input Data
Input data gathers all data that is needed to build a static model.
This includes all data acquired and processed (well logs, geological
markers, seismic data sets, seismic attributes) and all data that is
interpreted from the field measurements (petrophysical properties,
seismic time interpretations, velocity functions).
Most domain objects visible in the Input data tree are accessible in
Ocean from the following specialized collections:
1 BoreholeCollection – This collection class contains
Boreholes, Logs and Completions, as well as nested
BoreholeCollections. See the Well data model for details.

The Petrel Data Domain
2 MarkerCollection – This is the Geology data model.
These collections contain Markers, Horizons, Zones and
Fluid Contacts.
3 SeismicCollection – for 3D and 2D Seismic.
4 InterpretationCollection – for all Seismic
interpretation.
5 Collection – Other folders are accessible as generic
collections. From these collections, the API can access
point sets, polyline sets and surfaces.
Other objects in the Input data tree are inaccessible.
28

The Petrel Data Domain
Models
The Models tree includes all elements of the Pillar grid static model
and the property objects that represent Property distributions
throughout the Pillar grid cell array.
Domain objects visible in the Model data tree are accessible from
the following collections:
1 ModelCollection. This top level container in the Model
tree enumerates all the Models (pillar grids) in the tree.
Model collections are not nested.

The Petrel Data Domain
2 Grid.PropertyCollection. Specific to each Model, the
collection of all Property and FaultProperty instances in that
Model.
3 Fault.Properties. This lists all Fault Properties, per
fault, in a pillar grid Model.
Other parts of the Model tree (filters under pillar grids and Velocity
models) are inaccessible.
Results
30
Results are simulation results imported back in Petrel to compare
the static models with its possible evolution through time. They are
cross referenced by ResultProperty (the type of property the
result lists versus time) and ResultCategory (earth model entity
filter such as the Well for which that result data series is relevant).
Results filters are organized in a hierarchy:

The Petrel Data Domain
1 AnalysisRoot.ResultCategories lists all categories.
Categories are nested. Omitting a category filter will retrieve
cumulated results at the root category level.
2 AnalysisRoot.ResultProperties lists all properties.
ResultCategory and ResultProperty objects are required to
retrieve time series results.
Cases
The Cases tree expose simulation cases based on different
hypotheses but also represent various interpretation versions
driving static model property variations. Cases contain
CaseAnalysis objects (one level nesting).
Simulation cases can be listed at the root level. Like other Analysis
cases, Simulation cases are not nested:
1 SimulationRoot.Simulations lists all cases which
carry simulation data.
Simulation results are referenced with the same result properties
and result categories as general analysis results.

The Petrel Data Domain
Data Access
The Ocean API offers the following data access types:
1 Read
2 Update
3 Create
4 Delete
The API reads existing data, browsing through data folders,
enumerating collection contents and following the parts-parts-of
relationships.
The API updates existing objects, modifying entity characteristics
(such as its geometry) and modifying Property values (like
correcting log values in chosen points).
The API creates new instances of Petrel object classes,
augmenting the Project with new data the same way Petrel
applications do.
Last the API deletes objects that are no longer needed in the
Project.
32

The Petrel Data Domain
Data Types Exposed
The following tables show the API Read, Update, Create and Delete
functionalities implemented in different parts of the Data Model.
Details are given in the compiled html manual part of the Ocean
SDK release, Ocean.chm in the Documentation subdirectory.
Seismic
Ocean classes for Seismic are found in namespace
Slb.Ocean.Petrel.DomainObject.Seismic
Object type Read Update Create Delete
3D Cube
2D line
Horizon
Interpretation
Fault Interpretation
2D line creation is restricted (to cloning a 2D survey). Virtual cubes
are accessed via class IAttribute. See developers manual for
details.
Well
Namespace Slb.Ocean.Petrel.DomainObject.Well
Object type Read Update Create Delete

The Petrel Data Domain
Borehole/Trajectory
Log
Checkshot
Completion
Different types of Logs are available, property valued well logs,
facies well logs, point logs and multitrace well logs. We cover
property valued logs in this guide, you can look for more log types
and greater details in the developers manual.
Geology
Namespace Slb.Ocean.Petrel.DomainObject.Well
Object type Read Update Create Delete
Marker
Horizon
Zone
Fault
Interface
Stratigraphy columns may be created across a number of wells.
Fault and Interface type Surfaces are just named references.
34

The Petrel Data Domain
Shapes
Namespace Slb.Ocean.Petrel.DomainObject.Shapes
Object type Read Update Create Delete
Regular Height Field
Surface
PointSet
Property
PolylineSet
Properties can be added to Point Sets and Surfaces, not to Polyline
Sets. Surfaces can be irregular or gridded (regular height field).
Both can be assigned property values.
Pillar Grid
Namespace Slb.Ocean.Petrel.DomainObject.PillarGrid
Object type Read Update Create Delete
Pillar Grid (Geometry)
Property
Horizon
Fault, Zone, Segment
Fault Property

The Petrel Data Domain
In Ocean 2008 the geometry of the pillar grid is immutable, except
for nudging a Horizon along a pillar. The structural elements of the
grid (segments, faults, horizons and zones) cannot be changed nor
removed. Properties and fault properties are fully accessible.
Pillar grid property retains some knowledge of statistical treatment
done at creation time, like which cells have been upscaled and
statistical distributions of facies values. See the developers manual
for details.
Case analysis
Namespace Slb.Ocean.Petrel.DomainObject.Analysis
Object type Read Update Create Delete
Case / Case Run
Result Property
Result Category
Result vs Time
A data analysis case has a number of case runs, each providing
time series (results vs time) for combination of result categories
(fields, wells) and result properties (oil production, water flow rate,
etc.).
36

The Petrel Data Domain
Results
Namespace Slb.Ocean.Petrel.DomainObject.Simulation
Object type Read Update Create Delete
Simulation
Streamline
Streamline Property
Streamlines can be added to various stream line sets in a
simulation case. Property values can also be read and appended
and new property types added.
Simulation cases inherit from general case analyses and are the
source of time series which are identical to data analysis results.

The Petrel Data Domain
Read Access
38
Browsing through collections
There is no query service implemented on the Petrel Project as it is
not implemented in a relational database.
Instead data browsing is done by following the non-taxonomic
hierarchy.
At the top level we have specific collections:
1 SeismicCollection, InterpretationCollection
2 BoreholeCollection
3 MarkerCollection
4 ModelCollection, PropertyCollection
5 AnalysisRoot.ResultCategories
6 AnalysisRoot.ResultProperties
7 Cases, Simulations
Collections are nested. It is possible to browse through the whole
data domain of a project by accessing the root collection of each
type.
From each collection, the API can access the entities and the
properties that are relevant to that collection type.

The Petrel Data Domain
Seismic
Seismic data is rooted in the Project’s SeismicProject instance,
which is a singleton, once it has been created. It is accessed, if it
exists, from the SeismicRoot of the project. It only exists if there
are seismic data in the project.
Below the SeismicProject, we have two separate hierarchies in
the Seismic domain, one for seismic data, with nested
SeismicCollection objects, the other for interpretation picks
with a nested hierarchy of InterpretationCollection
instances.
Project proj = PetrelProject.PrimaryProject;
SeismicRoot sr = SeismicRoot.Get(proj);
SeismicProject sp = sr.GetOrCreateSeismicProject();
// navigate the Seismic data hierarchy
foreach (SeismicCollection scol in sp.SeismicCollections)
{
...
}
// navigate the Seismic interpretation hierarchy
foreach(InterpretationCollection icol in
sp.InterpretationCollections)
{
...
}

The Petrel Data Domain
Seismic data in a SeismicCollection include either seismic
cubes or seismic 2D surveys (collections of lines).
Interpretation data include HorizonInterpretation or
FaultInterpretation instances each including 3D and 2D time
picks that can be accessed separately.
Well and Geology
40
Wells belong to a nested hierarchy of BoreholeCollection
objects that contain boreholes, trajectories and logs.
Markers are stored under stratigraphic columns or horizon, zone
and marker collections. At the top level, we find a list of such

The Petrel Data Domain
collections, implemented in the API by the MarkerCollection
class.
All well and geology objects are accessible at the root of the
project from the WellRoot class. WellRoot is unique for the
Project and retrieved from a static method in the WellRoot class.
Project proj = PetrelProject.PrimaryProject;
WellRoot wr = WellRoot.Get(proj);
// Get top level Borehole Collection
BoreholeCollection bhcol = wr.BoreholeCollections;
...
Once the WellRoot instance is retrieved, it gives access to
borehole and marker collections.
public sealed class WellRoot : ...
{
public BoreholeCollection BoreholeCollection { get; }
...
public int WellLogVersionCount { get; }
public IEnumerable WellLogVersions { get; }
...
public int MarkerCollectionCount { get; }
public IEnumerable MarkerCollections { get; }
}
Boreholes are found in nested collections, rooted at the top level
collection retrieved from WellRoot.
Marker collections are not nested. At the top level, list of
collections are found, each corresponding to a different
stratigraphic classification.

The Petrel Data Domain
Static Model
Pillar grids are in a hierarchy that contains the property hierarchies.
The hierarchy retrieval starts from the PillarGridRoot object.
PillarGridRoot grid = PillarGridRoot.Get(proj);
IEnumerable mcolls;
mcolls = ModelCollection.GetRootModelCollections(proj);
foreach (ModelCollection mcol in mcolls)
{
foreach (Grid g in gr.GetGrids(mcol)
{
...
}
}
Each Grid object interfaces a full static model with intersecting
horizons and pillar-based faults.
Grid g = ...
foreach (Fault f in g.Faults)
{
...
}
foreach (Horizon hor in g.Horizons)
{
...
42
}
The model is populated by property values, accessed in a nested
hierarchy of PropertyCollection folders.
Grid g = ...

The Petrel Data Domain
PropertyCollection pcol = g.PropertyCollection;
foreach (Property prop in pcol.Properties)
{
PropertyVersion pv = prop.PropertyVersion;
// recurse on subcollections
foreach (PropertyCollection subcol in pcol.PropertyCollections)
{
...
}
}
Simulation and Data Analysis
Case analyses, result properties and result hierarchies belong to
separate hierarchies. The time series are defined by combinations
of these.
Simulation case runs are retrieved from SimulationRoot. These
simulation cases runs give access to time series and streamlines.
For time series, the result property and category has to be supplied.
SimulationRoot root = ...
foreach (Simulation sim in root.Simulations)
{
StreamlineSet sls = sim.StreamlineSet;
if (sls != StreamlineSet.NullObject)
{
foreach (StreamlineSubset sub in sls.StreamlineSubsets)
{
foreach (Streamline sl in sub.Streamlines)

The Petrel Data Domain
}
}
}
{
}
...
Result properties and categories are retrieved from
AnalysisRoot. With a combination of property and category a
simulation case run will return the relevant time series.
AnalysisRoot aroot = ...
List cats;
cats = new List(aroot.ResultCategories);
List props;
props = new List(aroot.ResultProperties);
int pi = ...
int ci = ...
foreach (TimeSeries ts in sim.GetTimeSeries(props[pi], cats[ci]))
{
...
}
Data Updates
Data update is done by modifying the object that is seen through
the API. Updating an entity or a property object alters the Project.
After the project has been updated, it is the user who decides
whether to save the Project changes or not. But from the API
standpoint, the Project has been modified as soon as an object has
been edited.
Any such update has to be done inside a transaction and any
modified object has to be locked beforehand inside that
transaction.
44

The Petrel Data Domain
Transactions
A transaction represents a group of edits on some data (domain
objects). Transactions are required for operations on native Petrel
domain objects that will change the data: create, update, and
delete.
Transactions use the Slb.Ocean.Core.ITransaction
interface:
public interface ITransaction : IDisposable
{
void Commit();
void Lock(params object[ ] objects);
void LockCollection(IEnumerable objectCollection);
...
}
To use a transaction:
1. Create a transaction
2. Lock domain objects that are going to be changed
3. Modify the domain objects
4. Commit the transaction
5. Dispose of the created transaction
In Petrel, transactions are used to batch event notifications. Petrel
does not use a data base, so changes to domain objects made
within a transaction happen immediately.
Modifying Domain Objects
Domain objects can be modified in the transaction after having
been locked. The on-line documentation will indicate which object
property can be modified.

The Petrel Data Domain
The nature of the class members is also explicitly shown in the
class definitions that are accessible from the Visual Studio
environment.
namespace Slb.Ocean.Petrel.DomainObject.Well
{
public sealed class WellLog : ...
{
public Borehole Borehole { get; }
public string Comments { get; set; }
...
public int SampleCount { get; }
public IEnumerable Samples { get; set; }
...
}
}
The array of log values, Samples, is read-write but SampleCount
is read-only (dynamically evaluated from the array size).
Domain Object Relationships
46
Object to object relationships can also be accessed via the API. For
these relationships to be modifiable, the corresponding class
property must allow write access, which is, as a general rule, not
the case as parts-of relationships impose constraints between
parent and child. For instance a pillar grid Property cannot be
separated from the Grid object that defines its geometry.
Even when the user can modify the containment hierarchy
interactively, the API often makes the corresponding relationship
immutable.
However there are cases where it makes sense to allow write
access to parts-of relations. This is the case when object creation
does not require such a relationship to be established. For instance,
it is possible to update the reference from a Marker to a given
Surface (Fault or Horizon).
In the example below we clear the stratigraphic references of a set
of markers in a given borehole.

The Petrel Data Domain
MarkerCollection mcol = ...
Borehole bh = ...
Horizon hor = Horizon.NullObject;
foreach (Marker m in mcol.GetMarkers(bh))
{
m.Surface = hor;
}
Please refer to the on-line help to check whether the relationship is
read-only.

The Petrel Data Domain
Domain Object Creation
Creating New Instances
48
Most objects accessible via the API can be instantiated.
However, the API never allows class instantiation in the classical
manner. API classes are sealed, and some objects are even

The Petrel Data Domain
exposed simply as interfaces. To create a new class instance, the
API proposes specialized Create methods.
Using Transactions
All domain object creations have to be done inside transactions,
just like object updates. But an object creation modifies the
container that this new object will be part of. It modifies its parent
entity (in the non-taxonomic hierarchy) or the collection of similar
entities that will harbor it. That parent or collection has to be locked
in the transaction.
The newly created object can be modified until the transaction
commits. It is locked by default, only its parent had to be locked
explicitly in the transaction.
Locating the Correct Create Method
The Create method is always located in the class of the containing
object. Borehole contains WellLog collections, that is where the
Create method for logs can be found.
using (ITransaction t = DataManager.NewTransaction())
{
PropertyVersion pv = ...
Borehole bh = ...
t.Lock(bh);
WellLog wl = bh.Logs.CreateWellLog(pv);
...
}
Creating New Collections
When it does not make sense to create an entity in a predefined
collection, one has to create a new collection. Collections are often
nested, so adding a collection is adding a branch to a tree. Classes
that model nested collections allow creation of sub-collections. For

The Petrel Data Domain
example a PropertyCollection can contain sub-collections, and
carries a Create method for branching out at that point.
ITransaction t = ...
PropertyCollection pcol = ...
t.Lock(pcol);
string colName = "New Sub-Collection";
PropertyCollection subcol = pcol.CreatePropertyCollection(colName);
New top-level collections
For top-level objects (like collections) the Create methods are in
static classes. For example, the top level collection for Seismic data
is created in the SeismicProject instance.
There are few collections that can appear at the top level of Petrel
data trees. Nested collections are rooted under a top level
collection that is only created once. Un-nested collections, that can
be added at the root of Input or Models data trees are:
1 MarkerCollection
2 ModelCollection
3 Collection
These collections are created directly from the Petrel primary
Project or the WellRoot object.
ITransaction t = ...
Project proj = PetrelProject.PrimaryProject;
WellRoot root = WellRoot.Get(proj);
t.Lock(proj);
proj.CreateModelCollection("New Pillar Model");
t.Lock(root);
root.CreateMarkerCollection("New Stratigraphic Model");
Nested Collections
Collections that are always grouped under a root collection are
created using a specific container, WellRoot for boreholes and
50

The Petrel Data Domain
SeismicProject for seismic data and interpretation. These are
used for nested collections.
1 SeismicCollection
2 InterpretationCollection
3 BoreholeCollection
There is no specific object at the root of all borehole collections,
instead we have a generic BoreholeCollection called “Wells”
that can only be created once.
ITransaction t = ...
Project proj = PetrelProject.PrimaryProject;
SeismicRoot root = SeismicRoot.Get(proj);
SeismicProject sproj = root.SeismicProject;
WellRoot wroot = WellRoot.Get(proj);
t.Lock(sproj);
string colName = "New Collection";
SeismicCollection scol = sproj.CreateSeismicCollection(colName);
String iName = “New Interpretation”);
InterpretationCollection icol;
icol = sproj.CreateInterpretationCollection(iName);
...
t.Lock(wroot);
BoreholeCollection bcol = wroot. GetOrCreateBoreholeCollection();
...
We can also create collections that are placed under an object
container, like under the PillarGrid.
1 PropertyCollection
ITransaction t = ...
Grid g = ...
t.Lock(g);
PropertyCollection root = g.PropertyCollection;
String colName = “New Properties”;
Property>Collection sub = root.CreatePropertyCollection(colName);
...

The Petrel Data Domain
Deletions
Deletion of an existing instance is done by calling the Delete
method on the object itself.
Deletion is always done inside a Transaction and the object to be
deleted has to be locked first.
Data Access Example
In the following example we will browse through wells in the
project, retrieve a porosity log, browse through static models and
create a new Property for the latest modified model in the
project.
The created property will be filled with values extracted from the
well log in cells where actual log measurements exist.
52

The Petrel Data Domain
Browsing through well logs to find a Porosity measurement
Project proj = PetrelProject.PrimaryProject;
WellRoot root = WellRoot.Get(proj);
BoreholeCollection wells = root.BoreholeCollection;
WellLog poro = WellLog.NullObject;
ITemplate temp =
PetrelUnitSystem.TemplateGroupPetrophysical.Porosity;
IUnitMeasurement um = temp.UnitMeasurement;
foreach (BoreholeCollection bhc in wells.BoreholeCollections)
{
foreach (Borehole bh in bhc)
{
foreach (WellLog l in bh.Logs.WellLogs)
{
if (l.WellLogVersion.UnitMeasurement.Equals(um))
{
poro = l;
break;
}
}
if (!poro.IsGood) break;
}
if (!poro.IsGood) break;
}
if (poro == WellLog.NullObject) return;
PetrelLogger.InfoOutputWindow("Found log " + poro.Name);
Retrieving the latest model
Grid latest = Grid.NullObject;
DateTime last = new DateTime(1980, 1, 1);
PillarGridRoot proot = PillarGridRoot.Get(proj);

The Petrel Data Domain
foreach (Grid g in proot.Grids)
{
if (g.LastModified.Time.CompareTo(last) >= 0)
{
latest = g;
last = latest.LastModified.Time;
}
}
if (latest == Grid.NullObject) return;
PetrelLogger.InfoOutputWindow("Found grid " + latest.Name);
Creating a new property collection in the model
ITransaction t = DataManager.NewTransaction();
PropertyCollection pcol = latest.PropertyCollection;
t.Lock(pcol);
string pcolName = “New Collection”;
PropertyCollection newcol =
pcol.CreatePropertyCollection(pcolName);
Creating the pillar grid property
IPropertyVersionService pvs = PetrelSystem.PropertyVersionService;
PropertyVersion gpv = pvs.FindOrCreate(latest, um);
t.Lock(newcol);
Property prop = newcol.CreateProperty(gpv);
Filling values
IPillarGridIntersectionService ipgs;
ipgs = CoreSystem.GetService();
IPolyline3 traj = poro.Borehole.Trajectory.Polyline;
IEnumerable cells;
cells = ipgs.GetPillarGridPolylineIntersections(latest, traj);
foreach (SegmentCellIntersection cell in cells)
{
Index3 ijk = cell.EnteringCell;
Point3 xyz = cell.IntersectionPoint;
double index = poro.Borehole.Transform(Domain.ELEVATION_DEPTH,
xyz.Z, Domain.INDEX);
WellLogSample[] sam = new WellLogSample[](poro.Samples);
latest[ijk] = sam[(int)depth];
}
t.Commit();
t.Dispose();
54

The Petrel Data Domain
Online Manual for Data Domain
Ocean comes with an online manual exposing all the classes,
methods and class members implemented in the API.
Opening the manual
In Visual Studio 2005, the Help menu includes Ocean help. Just
select Contents.

The Petrel Data Domain
Using Intellisense
In Visual Studio, the Ocean library references (files with “.dll”
extensions) let the environment select class members and methods
from a list dynamically generated from the types of the variables in
the code.
56

The Petrel Data Domain
This helps in selecting the correct class syntax without having to
explicitly search for information in the on-line manual.
Class Definitions
It is possible, while editing code, to go directly to the class
definition of the current variable declaration. Simply right-click on
the class name and Visual Studio opens the class reference.

The Petrel Data Domain
Other class definitions can be then explored in cascade.
58

The Petrel Data Domain

Chapter 2
Extending the Petrel UI
Ocean allows application developers to customize and extend the
Petrel application UI. In this chapter, we will explore a very simple
customization: adding your own menu item to an existing Petrel
menu.
Please see the Ocean Developers Guide for details on using Ocean
to extend the Petrel UI in this and other ways.
How to Add a New Menu Item
These are the steps to create a new menu item:
1. Edit your module’s IntegratePresentation method.
2. Use the Ocean convenience class ToolbarItem to create
the menu item.
3. Define the menu item properties.
4. Add the menu item to the Petrel UI using the Ocean class
ToolsManager.
60

Adding a New Menu Item
Edit IntegratePresentation method
Add your new menu item in the module’s
IntegratePresentation method.
public void IntegratePresentation ()
{
// add your new menu item here
}
Creating UI Tools
A tool is an item that appears on menus and toolbars. When a tool
appears on a menu as a menu item, it is drawn as a list entry with
text and an optional image.
tool in menu, no image
tool in toolbar
Figure 3-1 - Tools in Petrel UI
Ocean provides the ToolbarItem convenience class to create
tools such as a menu item.
public class ToolbarItem : IToolbarItem, ...
{
public ToolbarItem();
Create an instance of the ToolbarItem convenience class:
ToolbarItem myListSeismic = new ToolbarItem();

Adding a New Menu Item
Define the Menu Item Properties
You control the basic properties of the new menu item. Text and UI
location must be specified.
public class ToolbarItem : IToolbarItem, ...
{
public string ParentKey { set; get; }
public string Text { set; get; }
You can also optionally provide an image and an event handler for a
menu click.
}
public System.Drawing.Bitmap Image { set; get; }
public event System.EventHandler Click;
...
Text
Supply the text to be shown in the menu item:
myListSeismic.Text = "List Seismic Cubes";
UI Location
To specify the UI location of the new menu item, you need to give
the parent key. In this case, the parent is the existing Petrel menu
that contains the new menu item.
Figure 3-2 – Standard Petrel Menus
62
The Ocean WellKnownUI.Menus static convenience class has a
public static string field for each existing Petrel menu.
WellKnownUI.Menus.File
WellKnownUI.Menus.Edit
WellKnownUI.Menus.View
WellKnownUI.Menus.Insert
WellKnownUI.Menus.Project
WellKnownUI.Menus.Tools
WellKnownUI.Menus.Window

Adding a New Menu Item
WellKnownUI.Menus.Help
WellKnownUI.Menus.MainMenu
Figure 3-3 - WellKnownUI.Menus Static Read-only String Properties
We want our new menu item to go in the Tools menu, so we specify
the Tools field:
myListSeismic.ParentKey = WellKnownUI.Menus.Tools;
Image
Optionally set the image for the menu item. You can use an image
from Petrel available from the static class PetrelImages, or
provide your own.
myListSeismic.Image = PetrelImages.Seismic3D;
Click Event Handler
Finally we will specify what is going to happen when the menu item
is clicked. Our menu item will run the same algorithm we wrote for
our workstep.
We need to add a click handler to our menu item instance:
myListSeismic.Click += myListSeismicToolClick;
The click event handler is a System.EventHandler and looks
like:
using Slb.Ocean.Petrel.DomainObject;
using Slb.Ocean.Petrel.DomainObject.Seismic;
private void myListSeismicToolClick(object sender, EventArgs e)
{
Project project = PetrelProject.PrimaryProject;
SeismicRoot seismicRoot = SeismicRoot.Get(project);
SeismicProject seismicProj = seismicRoot.SeismicProject;
foreach(SeismicCollection scol in
seismicProj.SeismicCollections)
{
if (scol.SeismicCubeCount > 0)
{
foreach (SeismicCube cube in scol.SeismicCubes)
{
PetrelLogger.InfoOutputWindow(scol.Name +
" contains Seismic Cube " +

Adding a New Menu Item
}
}
}
}
cube.Name);
Add to ToolsManager
At this point, we have defined the new menu item (text, image,
location and what will happen when the tool is clicked), but it is not
in the Petrel user interface yet.
The ToolsManager class provides functionality to add menu
items. Use the Add method on ToolsManager to add the new
menu item into the Petrel UI.
public sealed class ToolsManager
{
public void Add (IToolbarItem item);
...
}
We can access this Ocean service from a read only property of the
convenience class PetrelSystem.Tools. We will add our new
tool to the UI after the tool is created:
PetrelSystem.Tools.Add(myListSeismic);
Results
Putting everything together, the example to add a new menu item
into the Petrel Tools menu is as follows:
public void IntegratePresentation ()
{
ToolbarItem myListSeismic = new ToolbarItem();
64

Adding a New Menu Item
}
myListSeismic.ParentKey = WellKnownUI.Menus.Tools;
myListSeismic.Text = "List Seismic Cubes";
myListSeismic.Image = PetrelImages.Seismic3D;
myListSeismic.Click += myListSeismicToolClick;
PetrelSystem.Tools.Add(myListSeismic);
void myListSeismicToolClick(object sender, EventArgs e)
{
Project project = PetrelProject.PrimaryProject;
SeismicRoot seismicRoot = SeismicRoot.Get(project);
SeismicProject seismicProj = seismicRoot.SeismicProject;
}
foreach(SeismicCollection scol in
seismicProj.SeismicCollections)
{
if (scol.SeismicCubeCount > 0)
{
foreach (SeismicCube cube in scol.SeismicCubes)
}
}
{
}
PetrelLogger.InfoOutputWindow(scol.Name +
" contains Seismic Cube " +
cube.Name);
Now, after you rebuild your module and run Petrel, you will see a
new menu item called “List Seismic Cubes” in the Petrel Tools
menu:
Figure 3-4 - New “List Seismic Cubes” Menu Item in Petrel Tools
Menu

Chapter 3
Extending the Data Domain
Ocean allows you to customize and extend the Petrel application by
creating new data objects, called custom domain objects. Custom
domain objects can contribute implementations for, and participate
in, standard Petrel behavior. They can be:
• Added to the Input and Model trees
• Displayed in a standard Petrel window
You can decide what functionality to implement for a given custom
domain object by deciding what interfaces (services) to implement
and register with Ocean. All are optional in terms of Ocean
requirements.
This chapter will describe how to write a simple custom domain
object and have it participate in standard Petrel behavior.
For details on these topics and more, please see the Ocean
Developers Guide.
66

Extending the Data Domain
Basic Custom Domain Object
A custom domain object in Petrel is just a new class. The most
basic custom domain object is a class that inherits from the .NET
object, even when it doesn't implement any Ocean interfaces.
Consider a simple object that has a position in space and a radius
that defines its size.
public class XYZObj
{
private float m_x = 100.0f;
private float m_y = 100.0f;
private float m_z = 100.0f;
private float m_radius = 100.0f;
}
public float X
{
get { return m_x; }
set { m_x = value; }
}
public float Y
{
get { return m_y; }
set { m_y = value; }
}
public float Z
{
get { return m_z; }
set { m_z = value; }
}
public float Radius
{
get { return m_radius; }
set { m_radius = value; }
}

Extending the Data Domain
This basic object is a valid custom domain object that can
participate in Petrel behavior. It can be added to the Petrel Input
and Model trees.
Adding to Input and Models Trees
The Input tree and the Models tree support the addition of new
nodes (domain objects) using the IInput and IModels interfaces.
public interface IInput : ...
{
void Add(object item );
}
public interface IModels : ...
{
void Add(object item );
}
You can access these interfaces via the PetrelProject class.
using Slb.Ocean.Petrel;
using Slb.Ocean.Petrel.UI;
PetrelProject.Inputs.Add( new XYZObj( ) );
PetrelProject.Models.Add( new XYZObj( ) );
Figure 4-1 – XYZ object in Input and Models trees.
68

Extending the Data Domain
Adding to Native Petrel Domain
Objects
Custom domain objects may be added as children to some native
Petrel domain objects using the IExtensions interface:
public interface IExtensions : IEnumerable, IEnumerable
{
void Add( object item );
bool Remove( object item );
bool Contains( object item );
...
}
This example adds a XYZObj custom domain object to a
Borehole, a native Petrel domain object. Start with a Borehole
object.
Slb.Ocean.Petrel.DomainObject.Well.Borehole bore = ...;
You must use a transaction when adding the children. The
transaction is created by the DataManager API.
using (ITransaction txn = DataManager.NewTransaction())
We lock the Borehole since we are going to change its children.
txn.Lock(bore);
Now we add a new XYZObj using IExtensions.
bore.Extensions.Add(new XYZObj());
Finally the operation is completed by committing the transaction.
txn.Commit();
Putting it all together we have:
Slb.Ocean.Petrel.DomainObject.Well.Borehole bore = ...;
using (ITransaction txn = DataManager.NewTransaction())
{
txn.Lock(bore);
bore.Extensions.Add(new XYZObj());
txn.Commit();
}

Extending the Data Domain
70
Figure 4-2 – XYZObj added to a Borehole object (A10).
Adding an Object from a Context
Menu
All native Petrel objects have context menus that appear with a
right mouse button click on the object in the tree. We will add our
own context menu item to the Borehole context menu which will
add a XYZObj as a child. Define a context menu item using the
ContextMenuItem class:
public class ContextMenuItem : IContextMenuItem,
IPresentation where TDomainObject : class
{
public ContextMenuItem ( );
public ContextMenuItem ( string text,
ContextMenuEventHandler clickCallback );
public string Text { get; set; }
public event ContextMenuEventHandler Click;
...
}

Extending the Data Domain
Add the new context menu item in the module’s
IntegratePresentation method. First we create a Borehole
context menu item, and then add it to the Petrel UI using the
PetrelSystem.Tools service.
ContextMenuItem cItem = new ContextMenuItem(
“Insert XYZ object”, AddXYZClick );
PetrelSystem.Tools.Add( cItem );
An event handler must be provided to respond to the click of the
context menu item. The AddXYZClick event handler will add the
XYZObj object to the Borehole from the context menu.
public void AddXYZClick( object sender,
ContextMenuEventArgs e )
{
Borehole bore = e.ContextObject as Borehole;
Completing our example, the event handler is now:
public void AddXYZClick( object sender,
ContextMenuEventArgs e )
{
// Get the borehole object
Borehole bore = e.ContextObject as Borehole;
if (bore == null)
return;
}
using (ITransaction txn = DataManager.NewTransaction())
{
txn.Lock(bore);
bore.Extensions.Add(new XYZObj());
txn.Commit();
}
The new “Insert XYZ object” context menu item is added to the
bottom of the Borehole context menu.

Extending the Data Domain
Figure 4-3 – Context menu containing XYZ object.
Customizing Tree Presentation
A new custom domain object has a default presentation style when
displayed in the tree. The icon is the Ocean bubbles icon, and the
text is object.ToString.
Figure 4-4 - Default Presentation in Tree
72
An object can control its appearance in the Petrel trees by
implementing the Slb.Ocean.Petrel.UI.IPresentation
interface.

Extending the Data Domain
public interface IPresentation
{
public Bitmap Image { get; }
public string Text { get; }
public event EventHandler PresentationChanged;
}
IPresentation allows the custom domain object to provide a
bitmap and a text string to be displayed in the user interface. It also
provides an event that is raised when the presentation has
changed.
Implementing IPresentation for our XYZObj object gives us:
using Slb.Ocean.Petrel.UI;
public class XYZObj : IPresentation
{
public System.Drawing.Bitmap Image
{
get { return MyImageLibrary.XYZObjImage; }
}
}
}
public string Text
{
get { return “XYZ Object”; }
}
public event EventHandler PresentationChanged { add {} remove {}
...
In this case the object, MyImageLibrary, contains a resource for
the bitmap displayed with the object name.
Figure 4-5 - Custom Presentation of XYZ object

Extending the Data Domain
Object Visualization
A custom domain object may be rendered in standard Petrel
windows. The 3D and 2D windows render data using OpenInventor
(Oiv), while the Map and WellSection windows use .NET GDI+ to
perform the rendering.
3D Window Display
Two steps must be performed to render a custom object in the 3D
or 2D window.
5. Implement an OpenInventor factory for the object type
6. Add the factory service to Ocean
We implement the IOpenInventorFactory interface to provide
the OpenInventor factory for displaying our object.
public interface IOpenInventorFactory
{
bool CanCreate(object domainObj, OpenInventorContext c);
SoNode Create(object domainObj, OpenInventorContext c);
void Dispose(SoNode node, object dObj, OpenInventorContext c);
void Update( SoNode node, object dObj, OpenInventorContext c);
}
We start by creating a class to implement
IOpenInventorFactory.
public class MyXYZObjOivFactory : IOpenInventorFactory
74

Extending the Data Domain
Next we implement the IOpenInventorFactory methods.
CanCreate determines if the domain object can be rendered in the
window. It can use properties of the object or the context to decide.
public bool CanCreate( object o, OpenInventorContext ctx )
{
return true;
}
Create is called the first time an OpenInventor scenegraph is
needed to display an object. It creates a new root node for the
OpenInventor node structure and then calls the Update method to
handle the display.
public SoNode Create( object o, OpenInventorContext ctx )
{
SoSeparator root = new SoSeparator( );
Update( root, o, ctx );
return root;
}
The Update method actually builds the node hierarchy for the
object being displayed. The position of the XYZObj object is
translated into the window coordinates. A sphere is defined to
represent it, and is added to the node hierarchy. Refer to
OpenInventor documentation for details.
public void Update( SoNode node, object o, OpeninventorContext ctx)
{
SoSeparator root = node as SoSeparator;
root.RemoveAllChildren( );
}
// Set up the translation for our object
XYZObj xyz = (XYZObj) o;
SbVec3f v3 = ctx.WorldToWindow3D(xyz.X, xyz.Y, xyz.Z);
SoTranslation trans = new SoTranslation();
trans.translation.SetValue(v3);
root.AddChild(trans);
// Create a sphere with our objects radius
SoSphere s = new SoSphere();
s.radius.SetValue( xyz.Radius );
root.AddChild(s);
return;
Dispose should clean up any resources associated with the
scenegraph, but not the scenegraph itself.

Extending the Data Domain
public void Dispose( SoNode n, object o, OpenInventorContext ctx )
{
}
The complete OpenInventor factory class for rendering the XYZObj
object is:
using MC.Inventor;
using MC.Inventor.Nodes;
using Slb.Ocean.Petrel.DomainObject;
using Slb.Ocean.Petrel.UI;
public class MyXYZObjOivFactory : IOpenInventorFactory
{
public bool CanCreate( object o, OpenInventorContext ctx )
{
return true;
}
}
public SoNode Create( object o, OpenInventorContext ctx )
{
SoSeparator root = new SoSeparator( );
Update( root, o, ctx );
return root;
}
public void Update(SoNode n, object o, OpeninventorContext ctx)
{
SoSeparator root = n as SoSeparator;
root.RemoveAllChildren( );
// Set up the translation
XYZObj xyz = (XYZObj) o;
SbVec3f v3 = ctx.WorldToWindow3D(xyz.X, xyz.Y, xyz.Z);
SoTranslation trans = new SoTranslation( );
trans.translation.SetValue( v3 );
root.AddChild( trans );
// Create a sphere using objects radius
SoSphere s = new SoSphere( );
s.radius.SetValue( xyz.Radius );
root.AddChild( s );
return;
}
public void Dispose(SoNode n, object o, OpenInventorContext ctx )
{
}
The OpenInventor factory must be added as a service in the
module’s Initialize method to display the XYZObj object.
public void Initialize ( )
{
Type objType = typeof( XYZObj );
Type factoryType = typeof( IOpenInventorFactory );
XYZObjOivFactory factory = new XYZObjOivFactory( );
CoreSystem.Services.AddService( objType, factoryType, factory);
}
76

Extending the Data Domain
When a 3D window is active, the XYZObject object will have a
checkbox next to it indicating that it may be displayed.
Figure 4-6 – XYZ Object ready to display in 3D window.
When the end user checks the checkbox the object will be
displayed.
Figure 4-7 – XYZObj object in 3D window
Map Window Display
Two steps are required to render the custom domain object in the
Map window.
Implement the IMapWindow factory interface.
Add the factory to Ocean as a service.
We implement the IMapRenderer interface to display the
XYZObj.
public interface IMapRenderer
{
void Initialize(object domainObj, MapRendererContext ctx);
bool CanDraw (object domainObj, MapRendererContext ctx);
void Draw (object domainObj, MapRendererContext ctx);
Box2 GetBounds (object domainObj, MapRendererContext ctx);

Extending the Data Domain
}
void Dispose
(object domainObj, MapRendererContext ctx);
We start by defining the class that implements the IMapRenderer
interface. We will render our object as a filled circle.
public class XYZObjMapDisplay : IMapRenderer
Next we implement the Initialize method. Our simple XYZObj
has nothing to do.
public void Initialize ( object o, MapRendererContext ctx )
{
return;
}
The CanDraw method reports whether or not the renderer knows
how to draw the object. In our case it will always return true.
public bool CanDraw ( object o, MapRendererContext ctx )
{
return true;
}
Draw renders a representation of the object into the window using
the appropriate GDI+ drawing surfaces. It gets the world
coordinates from the context for drawing. It defines the brush style
and color and uses the properties of the XYZObj instance to draw
a filled ellipse.
public void Draw ( object o, MapRendererContext ctx )
{
// Get the World coordinates
Graphics gworld = ctx.World;
// Define the brush in blue
using (Brush br = new SolidBrush(Color.Blue))
{
XYZObj xyz = (XYZObj)o;
int x = (int)xyz.X;
int y = (int)xyz.Y;
int size = (int)xyz.Radius;
78
}
}
// Draw the circle
gworld.FillEllipse(br, x-size, y-size, size*2, size*2);
GetBounds computes the bounding box that the instance occupies
and returns a Box2.
public Box2 GetBounds ( object o, MapRendererContext ctx )
{
XYZObj xyz = (XYZObj)o;
double x = xyz.X;

Extending the Data Domain
}
double y = xyz.Y;
double size = xyz.Radius;
Point2 begin = new Point2( x - size, y - size );
Point2 end = new Point2( x + size, y + size );
return new Box2( begin, end );
Dispose has nothing to do for our simple XYZObj object.
public void Dispose ( object o, MapRendererContext ctx )
{
return;
}
The complete IMapRenderer implementation for XYZObj is:
using System.Drawing;
using System.Drawing.Drawing2D;
using Slb.Ocean.Geometry;
using Slb.Ocean.Petrel.UI;
public class XYZObjMapDisplay : IMapRenderer
{
public void Initialize ( object o, MapRendererContext ctx )
{
return;
}
public bool CanDraw ( object o, MapRendererContext ctx )
{
return true;
}
public void Draw ( object o, MapRendererContext ctx )
{
// Get the World coordinates
Graphics gworld = ctx.World;
using (Brush br = new SolidBrush(Color.Blue))
{
XYZObj xyz = (XYZObj)o;
int x = (int)xyz.X;
int y = (int)xyz.Y;
int size = (int)xyz.Radius;
}
}
// Draw the circle
gworld.FillEllipse(br, x-size, y-size, size*2, size*2);
public Box2 GetBounds ( object o, MapRendererContext ctx )
{
XYZObj xyz = (XYZObj)o;
double x = xyz.X;
double y = xyz.Y;
double size = xyz.Radius;
Point2 begin = new Point2( x - size, y - size );
Point2 end = new Point2( x + size, y + size );
}
// Return a box that describes the area the object occupies
return new Box2( begin, end );

Extending the Data Domain
}
public void Dispose ( object o, MapRendererContext ctx )
{
return;
}
The second step in rendering a custom domain object in a window
is to register the drawing service with Ocean in the module’s
Initialize method.
Type xyzType = typeof(XYZObj);
Type factoryType = typeof(IMapRenderer);
XYZObjMapDisplay mapFactory = new XYZObjMapDisplay();
CoreSystem.Services.AddService(xyzType, factoryType, mapFactory);
When the end user checks the checkbox, the XYZObject is
rendered in the Map window.
Figure 4-8 – XYZ Object in Map window
80

Extending the Data Domain
Saving Custom Domain Objects
A custom domain object may be saved into the Petrel project using
serialization.
Serialization
Serialization has four steps.
1. Mark the class with the Serializable attribute
[Serializable]
public class XYZObj : ...
2. Implement the ISerializable interface
public class XYZObj : ISerializable
3. Implement GetObjectData to serialize the object
public void GetObjectData( SerializationInfo info,
StreamingContext ctx )
{
info.AddValue( “X”, m_x );
info.AddValue( “Y”, m_y );
info.AddValue( “Z”, m_z );
info.AddValue( “Radius”, m_radius );
}
All of the properties which are serialized must be serializable.
4. Write the deserialization constructor.
public XYZObj (SerializationInfo info, StreamingContext ctx )
{
this.m_x = info.GetSingle(“X”);
this.m_y = info.GetSingle(“Y”);
this.m_z = info.GetSingle(“Z”);
this.m_radius = info.GetSingle(“Radius”);

Extending the Data Domain
}
The XYZObj class declaration therefore becomes:
[Serializable]
public class XYZObj : ISerializable
{
float m_x;
float m_y;
float m_z;
float m_radius;
...
// Deserialization Constructor
public XYZObj(SerializationInfo info, StreamingContext ctx)
{
this.m_x = info.GetSingle(“X”);
this.m_y = info.GetSingle(“Y”);
this.m_z = info.GetSingle(“Z”);
this.m_radius = info.GetSingle(“Radius”);
}
...
public void GetObjectData(SerializationInfo info,
StreamingContext context )
{
info.AddValue( “X”, m_x );
info.AddValue( “Y”, m_y );
info.AddValue( “Z”, m_z );
info.AddValue( “Radius”, m_radius );
}
}
When project is saved, the XYZObject will be saved with it.
Reopening the project will load this data back into Petrel.
82