SDK - DATA IO 

API

Trimble eCognition Suite
for Windows operating system

Version 10.3.0
Revision 1.0
November 2022
 7,574,053 B2; US 7,146,380; US 7,467,159 B; US
Trimble Documentation 7,873,223; US 7,801,361 B2.
eCognition 10.3 SDK
Data IO API Acknowledgments
Imprint and Version Portions of this product are based in part on third-
Document Version 10.3.0 party software components.

Copyright © 2022 Trimble Germany GmbH. All eCognition Developer © 2022 Trimble Germany
rights reserved. This document may be copied and GmbH, Arnulfstrasse 126, 80636 Munich, Germany.
printed only in accordance with the terms of the All rights reserved. © 2022 Trimble Documentation,
Frame License Agreement for End Users of the Munich, Germany.
related eCognition software.
Published by: Last updated: November 29, 2022
Trimble Germany GmbH, Arnulfstrasse 126,
D-80636 Munich, Germany
Phone: +49–89–8905–710;
Fax: +49–89–8905–71411
Web: eCognition.com

Dear User,
Thank you for using eCognition software. We
appreciate being of service to you with image
analysis solutions. At Trimble we constantly strive
to improve our products. We therefore appreciate
all comments and suggestions for improvements
concerning our software, training, and
documentation. Feel free to contact us via the web
form on support.ecognition.com. Thank you.

Legal Notes
Trimble® and eCognition® are registered
trademarks of Trimble Germany GmbH in Germany
and other countries. All other product names,
company names, and brand names mentioned in
this document may be trademark properties of
their respective holders.
Protected by patents EP0858051; WO0145033;
WO2004036337; US 6,832,002; US 7,437,004; US
Contents
1 Overview SDK - Data IO API 1
1.1 Related Reference 1

2 Building a Driver 2
2.1 Anatomy of a Driver 2
2.2 Your First Driver – the ‘Hello World’ of Driver Development 2
2.2.1 The Driver Implementation 3
2.2.2 Suggested Design Patterns 10

3 Installation and Setup 12

3.1 Files and Install Directory Structure 12
3.1.1 Help Files 12
3.1.2 API Header Files 12
3.1.3 Samples 12

4 Sample Cases and Troubleshooting 13

4.1 Use Case Samples 13
4.1.1 Read Raster File Format Capapibility 13
4.1.2 Read/Write – Raster File Format Capability 13
4.1.3 Text File Format Data Storage Access 13
4.1.4 Hierarchical Data Storage Access 13
4.1.5 Accessing Vector Images 13
4.2 Debugging Techniques and Troubleshooting 14
4.2.1 Debug Drivers or Plug-ins in Microsoft Visual Studio 14
4.2.2 Symptoms and Possible Causes 16

5 The eCognition Driver API 18

5.1 Integration of the Engine Plug-ins into eCognition Software 18
5.1.1 Add-ins: Drivers and Plug-ins 18
5.1.2 Loading Add-in Modules 18
5.1.3 Loading DataIO Drivers 19
5.1.4 Configurations 19

6 Acknowledgments 21

eCognition Documentation | i
 1
Overview SDK - Data IO API
The DataIO API (application programming interfaces) is a component of the eCognition Developer software
development kit (SDK). The DataIO API can be used to develop drivers, or plug-ins for data connectivity and
integration. You can build a connector to many kinds of things; a particular kind of file system, a binary
image format, database, and more.
This DataIO API User Guide provides general instruction about using the DataIO API.

1.1 Related Reference

In the related DataIO API reference help file you find detailed information about classes and functions that
make up drivers and connectors, including some guidance.
Go to the folder SDK, which is installed in the eCognition Developer installation directory. The default path
is C:\Program Files\eCognition Developer [Version Number]\SDK\DataIO\Help\DataIOAPI_Help.chm.

eCognition Documentation | 1
 2
Building a Driver
2.1 Anatomy of a Driver
There are four different types of DataIO Drivers – RDI, VDI, ADI, and BDI:
l RDI (Raster Data Interface) allow eCognition software access to raster data image files such as .gif or
.tif.
l VDI (Vector Data Interface) provide an interface to vector file access.
l ADI (Attribute Data Interface) allows access to tabular data, usually read from text file formats such as
.CSV.
l BDI (Browsing Data Interface) is also a similar driver to ADI but was designed to provide repository
support. These drivers are used for interfacing all data that can be represented in a tree structure. This
includes meta-data, composite image files etc.
While all these driver types provide different things to eCognition software, they are all implemented in a
similar fashion. Unlike the eCognition Engine API, there is no class structure to use, no base classes to
derive. This API simply provides the means by which to implement a passive set of function exports which
eCognition applications can use for DATA I/O. It is passive in that the eCognition application initiates all
actions. Never, from the driver, are calls made to the application, and never is an action initiated from the
driver. It is the application which always contacts the driver and requests information or data.
For every driver type, there is a concrete list of functions to be implemented. The implementation of
certain functions Driver DLL is mandatory. They MUST be implemented. If they are not implemented and
exported the application will fail to load the driver and the functionality will not be available. If in some
case, there is no functionality to a particular Function for the driver in question, NULL can be returned (or
empty string – "" – in the case of the return type being const char*).
Other functions are not required for the driver to be useable, but provide however extra functionality to
the driver or opportunities at key events to manage the state of the driver for purposes such as memory
management.
Use the DataIO API help reference to determine which interface function is mandatory, or optional in your
case.

2.2 Your First Driver – the ‘Hello World’ of Driver

Development
Unfortunately, our ‘hello world’ cannot be as simple as your first printf or cout statement. However,
given that you have a reasonable understanding of the C++ language and you know what you want to do,
getting started will provide no challenge.

eCognition Documentation | 2
2   Building a Driver

Our first ‘hello world’ will be a raster data driver implementation. It can create, read and write a simple 8
bit image format.
Please investigate a related sample to review and build the source code.

2.2.1 The Driver Implementation

The DataIO-API enables functionality through the completion of a skeleton of simple C style function
exports. There is no class hierarchy, and no calls made to the engine from a driver. All calls are made from
the Application to the drivers. Therefore, in order to create our Raster File Driver ,we simply fill out all
required functions, returning the information that the application would be requesting at that stage abou
the format which the driver will allow eCognition software to support. In this sample, we will implement all
Mandatory functions which are required for the implementation of a a Read/Write RDI Driver. Those
functions which are Mandatory or Optional are described in the DataIO HTML Help Reference
Documentation.

Generally Mandatory Implementations

RDI_DRIVER_API const char* RDI_DRIVER_GetAttrString(
const char *attr,
RDIFileH hFile,
unsigned int chnl)
{
if (attr && !strcmp(attr,RDI_DRVR_INFO))
return "Simple bin driver";
else return "";
}

RDI_DRIVER_API double RDI_DRIVER_GetAttrDouble(

const char *attr,
RDIFileH hFile,
unsigned int chnl)
{
if (attr && !strcmp(attr,RDI_DRVR_INFO))
return 1.0;
else return RDI_ATTR_DBL_NONE;
}

RDI_DRIVER_API int RDI_DRIVER_GetAttrInt(

const char *attr,
RDIFileH hFile,
unsigned int chnl)
{
if (attr && !strcmp(attr,RDI_FILE_CS_UNIT))
return RDI_CS_UNIT_UNKNOWN;
else return RDI_ATTR_INT_NONE;
}

RDI_DRIVER_API const char* RDI_DRIVER_GetFormatID(unsigned int i)

{
if (i<0 || i>=NUM_FORMATS) return NULL;

eCognition Documentation | 3
2   Building a Driver

else return vFormat[i].pszID;

}

RDI_DRIVER_API const char* RDI_DRIVER_GetFormatName(unsigned int i)

{
if (i<0 || i>=NUM_FORMATS) return NULL;
else return vFormat[i].pszName;
}

RDI_DRIVER_API const char* RDI_DRIVER_GetFormatExtn(unsigned int i)

{
if (i<0 || i>=NUM_FORMATS) return NULL;
else return vFormat[i].pszExtn;
}

RDI_DRIVER_API RDIDataType RDI_DRIVER_GetFormatCaps

(unsigned int i, int mode)
{
if (i<0 || i>=NUM_FORMATS)
return RDI_Unknown;

switch(mode)
{
case RDI_READ:
return vFormat[i].read;
break;

case RDI_WRITE:
return vFormat[i].write;
break;

default:
return RDI_Unknown;
};
}

RDI_DRIVER_API void RDI_DRIVER_Close(void *hFile)

{
CBin8 *pBin8 = (CBin8 *)hFile;

if(pBin8!=NULL)
{
fclose(pBin8->m_hFile);
delete pBin8;
}
}

RDI_DRIVER_API RDIDataType RDI_DRIVER_GetDataType(void *hFile,

unsigned int chnl)
{
return RDI_Byte;

eCognition Documentation | 4
2   Building a Driver

!!!!Mandatory for Read Enabling Drivers

RDI_DRIVER_API int RDI_DRIVER_GetNumChnl(void *hFile)

{
return 3; // we support only 3 channels
}

RDI_DRIVER_API int RDI_DRIVER_GetSizeX(void *hFile, unsigned int chnl)

{
CBin8 *pBin8 = (CBin8 *)hFile;
return pBin8->m_nSizeX;
}

RDI_DRIVER_API int RDI_DRIVER_GetSizeY(void *hFile, unsigned int chnl)

{
CBin8 *pBin8 = (CBin8 *)hFile;
return pBin8->m_nSizeY;
}

RDI_DRIVER_API void* RDI_DRIVER_Open (const char *path,

const char *options)
{
CBin8 *pBin8 = NULL;

//-------------------------------------------------------------
// Open the file
//-------------------------------------------------------------
FILE* hFile = fopen(path,"rb");
if(hFile)
{
//---------------------------------------------------------------
// Create a bin8 file header object
//---------------------------------------------------------------
pBin8 = new CBin8;

//---------------------------------------------------------------
// Read image size in the header
//---------------------------------------------------------------
DWORD dwRead = 0;
CBin8Header *pHdr = (CBin8Header *)pBin8;
size_t nBytes = sizeof(CBin8Header);
if(fread(pHdr,nBytes,1,hFile)==1)
{

//------------------------------------------------------------
// Save WIN file header in bin8 file header
//------------------------------------------------------------
pBin8->m_hFile = hFile;
}

eCognition Documentation | 5
2   Building a Driver

else
{
delete pBin8;
fclose(hFile);
pBin8 = NULL;
}
}

return pBin8;
}

RDI_DRIVER_API int RDI_DRIVER_ReadBlock(void *hFile, unsigned int chnl,

int x, int y, int sx, int sy, void *buf, bool useClrTbl)
{
//---------------------------------------------------------------
// cast to bin8 file header
//---------------------------------------------------------------
CBin8 *pBin8 = (CBin8 *)hFile;

//---------------------------------------------------------------
// Check input data
//---------------------------------------------------------------
if(hFile==NULL)
return 1;
if (sx<=0) return 1;
if (sy<=0) return 1;
if (x<0) return 1;
if (y<0) return 1;
if (x+sx>pBin8->m_nSizeX) return 1;
if (y+sy>pBin8->m_nSizeY) return 1;

int iRet = RDI_SUCCEEDED; // return value

//---------------------------------------------------------------
// Length of a channel
//---------------------------------------------------------------
int iChnlLng = pBin8->m_nSizeX*pBin8->m_nSizeY;

//---------------------------------------------------------------
// Channel offset from the begginning of the file
//---------------------------------------------------------------
int iChnlOfst = sizeof(CBin8Header) + iChnlLng*chnl;

//---------------------------------------------------------------
// Loop by Y co-ordinate, in each iteration a horizontal line of
// the rectanngle is filled
//---------------------------------------------------------------
for(int iY = y; iY<(y+sy); iY++)
{

//----------------------------------------------------------

eCognition Documentation | 6
2   Building a Driver

// Compute offset of the next line from the beginning of the

// file and move file pointher to the position
//----------------------------------------------------------
int iPos = iChnlOfst + iY*pBin8->m_nSizeX + x;
if(fseek(pBin8->m_hFile,iPos,SEEK_SET)!=0)
{
iRet = RDI_FAILED;
break;
}

//----------------------------------------------------------
// Compute offset of the next line from the beginning of the
// buffer and read the line from the file
//----------------------------------------------------------
BYTE *pBuff = (BYTE*)buf+(iY-y)*sx;
DWORD dwRead = 0;
size_t pos = ftell(pBin8->m_hFile);
dwRead = (DWORD)fread (
pBuff,1,sx,pBin8->m_hFile);
if(dwRead!=sx)
{
iRet = RDI_FAILED;
}
}

return iRet;
}

Mandatory for Write Enabling Drivers

RDI_DRIVER_API void* RDI_DRIVER_Create(
const char *path, unsigned int num_chnl, int sx, int sy,
RDIDataType type, const char* frmt,
double llx, double lly,double res, const char *coo_sys,
int unit, const char *projection_str, bool them_data)
{
CBin8 *pBin8 = NULL; // Return value

//---------------------------------------------------------------
// Check input data
//---------------------------------------------------------------
if (sx<=0) return NULL;
if (sy<=0) return NULL;
if (num_chnl!=3) return NULL;
if (type!=RDI_Byte) return NULL;
if (frmt == NULL) return NULL;
if (_stricmp(frmt,"BIN8")!=0) return NULL;

//---------------------------------------------------------------
// Create a new file
//---------------------------------------------------------------
FILE* hFile = fopen(path,"wb");

eCognition Documentation | 7
2   Building a Driver

if(hFile)
{
//---------------------------------------------------------------
// Compute file size
//---------------------------------------------------------------
int iLng = sizeof(CBin8Header) + sx*sy*3;

//---------------------------------------------------------------
// Alloc a buffer for image data
//---------------------------------------------------------------
BYTE *pBytes = (BYTE *)calloc(sizeof(BYTE),iLng);

//---------------------------------------------------------------
// Save image size information in header of the file buffer
//---------------------------------------------------------------
CBin8Header *pHeader = (CBin8Header*)pBytes;
pHeader->m_nSizeX = sx;
pHeader->m_nSizeY = sy;

//---------------------------------------------------------------
// Initialize the file
//---------------------------------------------------------------
DWORD dwWritten = 0;
dwWritten = (DWORD)fwrite(pBytes,iLng,1,hFile);

//---------------------------------------------------------------
// Free buffer
//---------------------------------------------------------------
free(pBytes);

//---------------------------------------------------------------
// Create a bin8 file header and fill it and return as file
// header
//---------------------------------------------------------------
pBin8 = new CBin8;
pBin8->m_hFile = hFile;
pBin8->m_nSizeX = sx;
pBin8->m_nSizeY = sy;
}
return pBin8;
}

RDI_DRIVER_API int RDI_DRIVER_WriteBlock(void *hFile, unsigned

int chnl, int x, int y, int sx, int sy, void *buf)
{
//---------------------------------------------------------------
// cast to bin8 file header
//---------------------------------------------------------------
CBin8 *pBin8 = (CBin8 *)hFile;

//---------------------------------------------------------------

eCognition Documentation | 8
2   Building a Driver

// Check input data

//---------------------------------------------------------------
if(hFile==NULL)
return 1;
if (sx<=0) return 1;
if (sy<=0) return 1;
if (x<0) return 1;
if (y<0) return 1;
if (x+sx>pBin8->m_nSizeX) return 1;
if (y+sy>pBin8->m_nSizeY) return 1;

int iRet = RDI_SUCCEEDED; // return value

//---------------------------------------------------------------
// Length of a channel data
//---------------------------------------------------------------
int iChnlLng = pBin8->m_nSizeX*pBin8->m_nSizeY;

//---------------------------------------------------------------
// Channel offset from the begginning of the file
//---------------------------------------------------------------
int iChnlOfst = sizeof(CBin8Header) + iChnlLng*chnl;

//---------------------------------------------------------------
// Loop by Y co-ordinate, in each iteration a horizontal line of
// the rectanngle is written
//---------------------------------------------------------------
for(int iY = y; iY<(y+sy); iY++)
{

//----------------------------------------------------------
// Compute offset of the next line from the beginning of the
// file and move file pointher to the position
//----------------------------------------------------------
int iPos = iChnlOfst + iY*pBin8->m_nSizeX + x;
if(fseek(pBin8->m_hFile,iPos,SEEK_SET)!=0)
{
iRet = RDI_FAILED;
break;
}

//----------------------------------------------------------
// Compute offset of the next line from the
// beginning of the buffer
// and write the line to the file
//----------------------------------------------------------
BYTE *pBuff = (BYTE*)buf+(iY-y)*sx;
DWORD dwWritten = 0;
dwWritten = (DWORD)fwrite (pBuff,sizeof(BYTE)*sx,1,
pBin8->m_hFile);
if(dwWritten!=1)

eCognition Documentation | 9
2   Building a Driver

{
iRet = RDI_FAILED;
break;
}
}

return iRet;
}

2.2.2 Suggested Design Patterns

A useful data structure not found in the actual SDK (but in the samples) is the tFormatInfo structure. It
can be useful in organizing correct responses to the driver caller, and is instantiated as seen below
We can use this structure in maintaining a common design pattern over all RDI drivers developed. This
helps to make the code more readable and usable, and therefore, helps to prevent and/or reduce the
occurrences of mistakes.

Data Structures

tFormatInfo
Structure that describes the formats supported by the plug-in
struct tFormatInfo
{
const char *pszID; // Format ID - any unique string that can
// identify a file format
const char *pszName; // Human readable name of a file format
const char *pszExtn; // File extension for the format
RDIDataType read; // Datatype for reading
RDIDataType write; // Datatype for writing
const char *pszDrvID;
bool adi_read; // Can the driver read files with the
// format?
bool adi_write; // Can the driver write files with the
// format?
};

List of supported Formats can be implemented as an array of

tFormatInfo Structure objects (in this case, only one format):
static tFormatInfo vFormat[] =
{
{ "BIN8", "BIN8 Files","*.bin8", RDI_Byte, RDI_Byte, NULL }
}

The Number of formats that are supported by the plug-in.

static const int NUM_FORMATS = sizeof(vFormat)/sizeof(vFormat[0]);

eCognition Documentation | 10
2   Building a Driver

Example Usage

Example Usage 1
//-------------------------------------------------------
//!RDI_DRIVER_GetFormatID
//-------------------------------------------------------
/*!
\brief enumerate all available formats
\return the rdi format id or NULL
\param indx index of the supported Format
*/
RDI_DRIVER_API const char* RDI_DRIVER_GetFormatID(int indx)
{
if (indx<0)
return NULL;
else if (indx>=NUM_FORMATS)
return NULL;
else
return vFormat[indx].pszID;
}

Example Usage 2
//-------------------------------------------------------
//!RDI_DRIVER_GetFormatCaps (mandatory)
//-------------------------------------------------------
/*!
\param mode 0 means read access 1 means write access
\param indx index of the supported Format
*/
RDI_DRIVER_API RDIDataType RDI_DRIVER_GetFormatCaps(int indx,int mode)
{
if (indx<0)
return RDI_Unknown;
if (indx>=NUM_FORMATS)
return RDI_Unknown;
if (mode==RDI_READ)
return vFormat[indx].read;
if (mode==RDI_WRITE)
return vFormat[indx].write;

return RDI_Unknown;
}

eCognition Documentation | 11
 3
Installation and Setup
This API is a component of the eCognition Developer software development kit (SDK). The SDK installation
is an optional part of the eCognition installation. If the SDK is not yet installed on your machine, rerun the
eCognition Developer installation. During the installation sequence on the Choose Components dialog box,
you have to activate the SDK checkbox only.

3.1 Files and Install Directory Structure

Below are listed the files included in the eCognition Developer installation that are relevant to use of the
Data IO API. Go to the folder SDK, which is installed in the eCognition Developer installation directory. The
default path is C:\Program Files\eCognition Developer [version number]\SDK\

3.1.1 Help Files

l \DataIO\Help\DataIOAPI_Help.chm

3.1.2 API Header Files

l .\DataIO\Include\*.h
l .\DataIO\Include\Dbase\*.h
l .\DataIO\Include\DMI\*.h
l .\DataIO\Include\OSWrapper\*.h

3.1.3 Samples
l .\DataIO\Samples\RDIPlugins\SampleRDIPluginRO
l .\DataIO\Samples\RDIPlugins\SampleRDIPluginRW
l .\DataIO\Samples\SampleADIPlugin
l .\DataIO\Samples\SampleBDIPlugin
l .\DataIO\Samples\SampleVDIPlugin
l For x86 platforms, Shapefile C Library v1.2 or higher is also required
l For x64 platforms, GDAL Library v1.5 or higher is necessary.

eCognition Documentation | 12
 4
Sample Cases and Troubleshooting
4.1 Use Case Samples
4.1.1 Read Raster File Format Capapibility
Description: RDIDrivers access raster data
Sample: SampleRDIPluginRO

4.1.2 Read/Write – Raster File Format Capability

Description: RDIDrivers access raster data.
Sample: SampleRDIPluginRW

4.1.3 Text File Format Data Storage Access

Description: There are cases where eCognition software requires additional information linked to raster
data. Often this is stored in the CSV Format for example. To access such files, we use an ADI Driver.
Sample: SampleADIPlugin

4.1.4 Hierarchical Data Storage Access

Description: There are cases where eCognition software requires additional information linked to raster
data, or when the storage of raster data is organized in a particular fashion that can be explained by a rule,
such as a Hierarchical directory system on a File system, or a database. To allow eCognition software access
to such locations, it uses BDI Drivers.
Sample: SampleBDIPlugin

4.1.5 Accessing Vector Images

Description: Aside from Raster images, there is also a type of image called Vector Images. This is where the
image is made up rather than intensities on a grid, vector co-ordinates on a grid. For example, a line in a
Vector Image could be made up of the 2 co-ordinates p1(12,15) and p2(133,500). For eCognition software
to read such data, it uses VDI Drivers.
Sample: SampleVDIPlugin

eCognition Documentation | 13
4   Sample Cases and Troubleshooting

4.2 Debugging Techniques and Troubleshooting

The implementation of automation applications can be a rewarding experience. However, when things go
wrong one can be often completely in the dark as to why. Here are some tips and helpful hints on how to
go about debugging your application problems.

4.2.1 Debug Drivers or Plug-ins in Microsoft Visual Studio

As you are running your driver or plug-in through another ‘code-closed’ application, you cannot simply start
your driver or plug-in in visual studio and follow the program flow from the start. You have to allow
eCognition software to load it first before you can debug it.
How can you do this? Through the functionality of the Microsoft Visual Studio compiler macros, you can
arrange for your driver or plug-in to gracefully crash. At this point you are able to pick up the program flow
and debug your driver or plug-in. This is done through the function call DebugBreak(). Wherever placed,
the application will halt and windows will ask the user (if visual studio is installed) if they wish to debug the
application. Your driver or plug-in will be debuggable (if you built a debug version with symbol information
available).
It is suggested that you place your DebugBreak() command in the XXX_DRIVER_INIT function of
your driver or in the constructor of a component of your plug-in to ensure you are able to debug at the
earliest possible point. For example, below we use a static variable to ensure our DebugBreak() is called
only once the first time. This allows smoother flow later on.
static bool _bOurDebugFirstTimeOnlylFlag = false;
RDI_DRIVER_API bool RDI_DRIVER_Init(const char* home_path)
{
if (!_bOurDebugFirstTimeOnlylFlag )
{
// ensure we don't break again
_bOurDebugFirstTimeOnlylFlag = true;
DebugBreak();
}
return true;
}

Once we have broken in our constructor, we can set breakpoints wherever we like within our driver.
Program flow will stop at these points allowing us to investigate any functionality where we suspect
problems.
1. First we start the application. If we set our DebugBreak in the _INIT function as suggested, the
application will crash quite soon, displaying a crash dialog box.
2. When given the choice, click the Debug button. The Just-In-Time Debugging dialog box opens.
3. Simply select the Yes button to debug using Visual Studio, whatever your favorite tool is

eCognition Documentation | 14
4   Sample Cases and Troubleshooting

4. When asked to Attach to Process, the eCognition application should already be selected. Just reconfirm
with OK.
5. Now you are given a choice to debug again, or simply continue without breaking.
l Here you should click the Break button.
6. When you finally click through all the pop-up dialogs of Windows, you shall come to the code point
where the application had halted. It should be the point of your DebugBreak, if this is what caused the
crash.
7. Often, immediately the assembly code is first shown. Here you can use the context menu and ask to
see the source-code only. Right-click for the context-menu and choose Go to source code. You should
now be able to see your source.
8. At this point you have control of the program flow. Now is the time where you can set breakpoints
throughout your plug-in code. The eCognition application will gracefully halt at these points. Being able
to debug like this is essential to problem solving, and is—unless things are really bad, or the problem
does not appear in debug—much better than analyzing the result of many debug fprintf
statements.

Figure 4.1. The Just In Time Debugging Box

Figure 4.2. Attach to Process dialog box

eCognition Documentation | 15
4   Sample Cases and Troubleshooting

Figure 4.3. Break Dialog Box

Figure 4.4. Debug break within Microsoft Visual Studio

Figure 4.5. Debug break in source code within Microsoft Visual Studio

4.2.2 Symptoms and Possible Causes

Check the following symptoms to learn about possible causes.

Application Crashes in Strange Ways

You are developing on Microsoft windows. It is probably Microsoft Visual Studio which is not updating your
project correctly. You probably need to rebuild your project.
If the previous step didn’t work, it is probably need to reboot the machine.

Your Driver is not Available for Use in the Custom Import Utility
Your drivers implementation of _GetAttrString does not correctly implement the _DRVR_ID
attribute.

eCognition Documentation | 16
4   Sample Cases and Troubleshooting

Driver DLL is Listed in the Application ‘System Inf’ Dialog (from the Help Menu)
as ‘NOT OK’
Plug-in does not correctly implement the mandatory export functions as specified in the API.

No Projection String is Written to Export File

Your drivers implementation of _GetAttrString does not correctly implement the _FILE_PRJ_STR
attribute.

eCognition Documentation | 17
 5
The eCognition Driver API
5.1 Integration of the Engine Plug-ins into eCognition
Software
The application uses several drivers to read and write files and databases, and manipulate the data. These
are loaded at Start-up. These are implemented as DLLs and can be conceptually divided into two categories:
Drivers and Plug-ins.

5.1.1 Add-ins: Drivers and Plug-ins

There are two kinds of Add-ins: Drivers and Plug ins. The main conceptual difference between the two is
that drivers deal mainly with hardware operations, such as file access (open, close, read and write), and use
of formats, whereas Plug-ins provide functionality such as the features and Engine Algorithms available in
the application which can perform operations on the images which are loaded through the drivers.

5.1.2 Loading Add-in Modules

When the application attempts to start up it first loads the drivers, and then the plug-ins.
Each of the 4 groups of drivers (RDI, VDI, ADI, BDI) are loaded from a single drivers directory, and the
Engine Plug-ins from the plugins directory. Each of these locations contains an XML configuration file which
specifies add-ins to load, in which order, with which arguments. Once the XML file has been read and the
specified add-ins loaded, the search directories (bin/drivers or bin/plugins) are searched for further add-ins
to load. If files are found that are not already loaded via configuration, they are queried, and if valid in the
context, loaded. In this way, if no load-order or special arguments are required, add-ins can be used by
simply placing them in the appropriate directory. However, if the add-in must be loaded in a particular
order, or must be passed certain arguments in the init function, or a certain load path should be used, the
add-in should be mentioned in the configuration file.
If no drivers are loaded for a particular group a warning is displayed.

Figure 5.1. Displayed warning message if no RDI drivers were available to load

eCognition Documentation | 18
5   The eCognition Driver API

5.1.3 Loading DataIO Drivers

The DataIO Drivers allow access to files and data in structured repositories. These drivers are loaded from
the DIOPluginMngr object. An example of the configurations of the DataIO Drivers can be seen in the
Configurations section. Drivers are successfully loaded if all their mandatory export functions exist and are
successfully located. Each driver group (RDI, VDI, BDI, ADI) have different sets of Mandatory and Non-
Mandatory functions. These are detailed later in the section ‘Using the SDKs’.

5.1.4 Configurations
The load order of add-ins is as mentined in the XML Configuration file. That is; the first <Load> tag
encountered will be the first add-in loaded, the last <Load> tag will specify the last configured add-in to be
loaded. There are two attributes of the <Load> tag. These are optional.
l use_path – this attribute specifies that the add-in should be loaded from the context of the given
use_path. This can be an absolute path, or a relative path to the driver itself. If no use_path is specified,
the add-in is loaded from the context of the add-in path.
l init_args – this attribute specifies the string argument that should be passed to the add-in in the
Init function (XDI_Driver_Init with DataIO drivers, and EPIInit with Engine Plug-ins).
<LoadOrder>
<RDI>
<Load>rdidrvr_asc</Load>
<Load>rdidrvr_b16</Load>
<Load>rdidrvr_dib</Load>
<Load use_path="extras">rdidrvr_gdal</Load>
<Load use_path="extras/BundleErdas/bin/NTx86"
init_args="../../../">rdidrvr_erdas</Load>
<Load>rdidrvr_pix</Load>
<Load use_path="extras">rdidrvr_lead</Load>
<Load>rdidrvr_frm</Load>
<Load use_path="extras">rdidrvr_aci</Load>
<Load>rdidrvr_aperio</Load>
<Load use_path="extras">rdidrvr_sar</Load>
<Load use_path="extras">rdidrvr_applied</Load>
<Load use_path="extras">rdidrvr_bacus</Load>
<Load use_path="extras">rdidrvr_flex</Load>
<Load>rdidrvr_dcm</Load>
<Load>rdidrvr_3dhis</Load>
</RDI>

<VDI>
<Load use_path="extras">vdidrvr_shp</Load>
</VDI>

<BDI>
<Load>bdidrvr_meta</Load>
<Load>rdidrvr_flex</Load>
<Load>rdidrvr_3dhis</Load>
<Load>rdidrvr_gdal</Load>
<Load>rdidrvr_bacus</Load>

eCognition Documentation | 19
5   The eCognition Driver API

</BDI>

<ADI>
<Load>adidrvr_csv</Load>
</ADI>
</LoadOrder>

eCognition Documentation | 20
 6
Acknowledgments
Portions of this product are based on third-party software components. Trimble is required to include the
following text, related to software and distributions. The most recent version of this document can be
found in the installation folder of eCognition (C:\Program Files\Trimble\eCognition Developer
10.3\bin\third-party-acknowledgements.txt).

OpenCV, The Open Source Computer Vision Library

Version 4.5.1 
Copyright (c) 2020, Intel Corporation
https://opencv.org/  
License: Apache 2 License   

Snappy 
Version 1.0.5
Copyright (c) 2005 Google Inc. 
https://github.com/google/snappy  
License: Snappy License  

ZLIB Data Compression Library 

Versions 1.2.3 and 1.2.11
Copyright (c) 1995-2017 Jean-Loup Gailly and Mark Adler  
https://zlib.net/ 
License: GNU Lesser General Public License  

CPPREST 
Versions 2.9.1 and 2.10.6 
Copyright (c) 2019 Microsoft Corporation 
https://github.com/microsoft/cpprestsdk 
License: MIT License 

eCognition Documentation | 21
6   Acknowledgments

GLEW 
Version 2.1.0 
Copyright (c) 2002-2007, Milan Ikits  Copyright (c)  2002-2007, Marcelo E. Magallon
Copyright (c) 2002, Lev Povalahev 
http://glew.sourceforge.net/ 
License: BSD License and MIT License 

Mesa 3-D graphics library 

Version 7 
Copyright (c) 2015 The Android Open Source Project 
https://www.mesa3d.org/ 
License: Apache 2.0 

Geogram 
Version 1.3.9 
Copyright (c)  2012-2014 Bruno Levy 
http://alice.loria.fr/software/geogram/doc/html/geogram_license.html 
License: BSD License 

LASZIP 
Version 3.1.0 and 3.4.3
Copyright(c) 2007-2017, Martin Isenburg 
https://laszip.org/ 
License: LGPL  

DEVIL 
Version 1.7.8 
Copyright (c) Project Contributors 2019 
http://openil.sourceforge.net/ 
License: LGPL 2.1

Nanoflann 
Versions 1.3.0  and 1.4.2
Copyright 2008-2009  Marius Muja  Copyright  
Copyright 2008-2009  David G. Lowe (lowe@cs.ubc.ca). All rights reserved.

eCognition Documentation | 22
6   Acknowledgments

Copyright 2011-2022 Jose Luis Blanco (joseluisblancoc@gmail.com). All rights reserved.

https://github.com/jlblancoc/nanoflann 
License: BSD License 

Ifcplusplus
Version 1.1
Copyright 2010-2015 Fabian Gerold
https://github.com/ifcquery/ifcplusplus
License: MIT License

Boost
Version 1.79
Copyright Beman Dawes, Daniel Frey, David Abrahams, 2003-2004.
Copyright Rene Rivera 2004-2005.
https://boost.org
License: Boost Software License, Version 1.0

Crypto++
Version 7.0.0
Compilation Copyright (c) 1995-2018 by Wei Dai.  All rights reserved.
https://cryptopp.com
License: Boost Software License, Version 1.0

CUDA & cuDNN

Version 11.2
Copyright © 2020 NVIDIA Corporation
https://developer.nvidia.com/cuda-toolkit
https://developer.nvidia.com/cudnn
License: Boost Software License, Version 1.0

DejaVu
Version 2.30
Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is trademark of Bitstream,
Inc.
Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.

eCognition Documentation | 23
6   Acknowledgments

https://dejavu-fonts.github.io/
License: DejaVu Fonts — License

File-geodatabase (FileGDB)
Version 1.5.1
Copyright 2017 Esri 
https://github.com/Esri/file-geodatabase-api
License: Apache License 2.0

PGR Ladybug
Version 2.12.3
Copyright © 2017 FLIR Integrated Imaging Solutions, Inc. All Rights Reserved. 
http://www.ptgrey.com
License: PGR Ladybug® SDK License

Ffmpeg codec
Version N-78758-g5156578
Copyright © 2000-2016 FFmpeg Project
https://ffmpeg.org
License: LGPL 2.1+

Freetype
Version 2.9
http://www.freetype.org
Copyright 1996-2002, 2006 by David Turner, Robert Wilhelm, and Werner Lemberg
License: The FreeType Project LICENSE

GDAL
Version 3.2.3
https://gdal.org
© 1998-2022 Frank Warmerdam, Even Rouault, and others
License: GDAL License (https://gdal.org/license.html)

GeoGram

eCognition Documentation | 24
6   Acknowledgments

Version 1.3.9 
https://github.com/BrunoLevy/geogram
Copyright (c) 2012-2014, Bruno Levy All rights reserved.
License: BSD 3-Clause "New" or "Revised" License

Graphic gems
Version 1.0
"Graphics Gems" (editor, Andrew S. Glassner, published by
Academic Press, Cambridge, MA, 1990, ISBN 0-12-286165-5, 833 pgs.).
License: Graphic gems license

Graphic gems
Version 1.0
"Graphics Gems" (editor, Andrew S. Glassner, published by
Academic Press, Cambridge, MA, 1990, ISBN 0-12-286165-5, 833 pgs.).
License: Graphic gems license

gSOAP
Version 2.7.9
https://www.genivia.com/dev.html
Copyright (C) 2000-2005 Robert A. van Engelen, Genivia, Inc. All Rights Reserved.
License: gSOAP Public Open Source License (Version 1.3a)

Info-Zip
Version 1.01e
http://www.info-zip.org
Copyright (c) 1990-2007 Info-ZIP.  All rights reserved.
License: Info-Zip license (BSD-based)

Intel® Integrated Performance Primitives

Version 2018.0.2
https://www.intel.com/
Copyright (c) 2018 Intel Corporation.
License: Intel Simplified Software License (Version January 2018)

eCognition Documentation | 25
6   Acknowledgments

Jasper
Version 2.0.14
https://github.com/jasper-software/jasper
Copyright (c) 2001-2016 Michael David Adams
Copyright (c) 1999-2000 Image Power, Inc.
Copyright (c) 1999-2000 The University of British Columbia
License: JasPer License Version 2.0

LASZip
Version 3.1.0
https://laszip.org/
Copyright (c) 2007-2017, Martin Isenburg, rapidlasso - fast tools to catch reality
License: LGPL 2.1

libGeoTiff
Version 1.2.5
https://github.com/OSGeo/libgeotiff
Copyright (c) 1995 Niles D. Ritter
Copyright (c) 1999, Frank Warmerdam
License: libgeotiff license

Libjpeg
Version 9b, 17-Jan-2016
http://libjpeg.sourceforge.net/
Copyright (C) 1991-2016, Thomas G. Lane, Guido Vollbeding.
License: Libjpeg License

Libpng
Version 1.6.37
http://www.libpng.org/pub/png/libpng.html
Copyright (c) 1995-2019 The PNG Reference Library Authors.
Copyright (c) 2018-2019 Cosmin Truta.
Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson.
Copyright (c) 1996-1997 Andreas Dilger.

eCognition Documentation | 26
6   Acknowledgments

Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.

License: PNG Reference Library License version 2

Libpng
Version 1.6.37
http://www.libpng.org/pub/png/libpng.html
Copyright (c) 1995-2019 The PNG Reference Library Authors.
Copyright (c) 2018-2019 Cosmin Truta.
Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson.
Copyright (c) 1996-1997 Andreas Dilger.
Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
License: PNG Reference Library License version 2

Mesa 3-D
Version  7.0
https://www.mesa3d.org/
Copyright (c) 2015 The Android Open Source Project 
License: Apache 2.0

MrSid DSDK
Version 9.5.4
Copyright (c) 2010 - 2017 Celartem Inc. d.b.a. LizardTech.
LizardTech Computer Software License Agreement for MrSID Decode SDKs
License: LizardTech Computer Software License Agreement for MrSID Decode SDKs

NSIS
Version 3.6.1.0
https://nsis.sourceforge.io/
Copyright (c) 1999-2020 Contributors
License: Common Public License version 1.0

OpenGL Extension Wrangler Library

Version 1.1
http://glew.sourceforge.net/
Copyright (c) 2007 The Khronos Group Inc. All rights reserved.

eCognition Documentation | 27
6   Acknowledgments

License: Modified BSD License, the Mesa 3-D License (MIT) and the Khronos License (MIT).

Pybind11
Version 2.9.2
https://github.com/pybind/pybind11
Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>, All rights reserved.
License: pybind free license

OpenMP
Version 5.0 (part of IPP)
https://www.openmp.org/
Copyright (c) 2005-2014 Intel Corporation. All rights reserved.
License: Intel Simplified Software License (Version January 2018)

Shapelib
Version 1.92 (part of GDAL)
https://gdal.org
Copyright (c) Frank Warmerdam
License: GDAL License (https://gdal.org/license.html)

SQLite
Version 3.3.03.3.0
https://www.sqlite.org/
Copyright: Public Domain
License: doesn’t require a license

TensorFlow
Version 2.5
https://www.tensorflow.org/
Copyright (c) Google Inc., Yuan Tang <terrytangyuan@gmail.com>, Arm Ltd
License: Apache 2 License

Tesseract library
Version 5.1.0

eCognition Documentation | 28
6   Acknowledgments

https://github.com/tesseract-ocr/tesseract
Copyright (c) Tesseract authors
License: Apache 2 License

wkhtmltopdf executable
version: 0.12.3.2
https://wkhtmltopdf.org/
Copyright (c) 2010-2014 wkhtmltopdf authors
License: LGPL v3

Python
Version: 3.9.12
https://www.python.org/
Copyright (c) 2001-2022.  Python Software Foundation
License: Python Software Foundation Version 2

pip
Version: 22.0.4
https://pip.pypa.io/en/stable/
Copyright (c) 2008-present The pip developers
License: MIT License

Setuptools (Python library)

Version: 58.1.0
https://github.com/pypa/setuptools
Copyright Jason R. Coombs
License: MIT License

python-dateutil (Python library)

Version: 2.8.2
https://github.com/dateutil/dateutil
Copyright (c) 2003-2011 - Gustavo Niemeyer <gustavo@niemeyer.net>
Copyright (c) 2012-2014 - Tomi Pieviläinen <tomi.pievilainen@iki.fi>
Copyright (c) 2014-2016 - Yaron de Leeuw <me@jarondl.net>
Copyright (c) 2015- - Paul Ganssle <paul@ganssle.io>

eCognition Documentation | 29
6   Acknowledgments

Copyright (c) 2015- - dateutil contributors (see AUTHORS file)

License: Apache License Version 2 and BSD 3-Clause License

numpy (Python library)

Version: 1.22.4
https://numpy.org/
Copyright (c) 2005-2022, NumPy Developers
License: BSD 3-Clause

pandas (Python library)

Version: 1.4.2
https://pandas.pydata.org/
Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData
Development Team All rights reserved.
Copyright (c) 2011-2021, Open source contributors.
License: BSD 3-Clause

pytz (Python library)

Version: 2022.1
https://pythonhosted.org/pytz/
Copyright (c) 2003-2019 Stuart Bishop <stuart@stuartbishop.net>
License: MIT License

Shapely (Python library)

Version: 1.8.2
https://github.com/shapely/shapely
Copyright (c) 2007, Sean C. Gillies
License: BSD 3-Clause

six (Python library)

Version: 1.16.0
https://github.com/benjaminp/six
Copyright (c) 2010-2020 Benjamin Peterson
License: MIT License

eCognition Documentation | 30
6   Acknowledgments

debugpy (Python library)

Version: 1.6.3
https://github.com/microsoft/debugpy/
Copyright (c) Microsoft Corporation
License: MIT License

SciPy (Python library)

Version: 1.9.3
https://scipy.org/
Copyright (c) 2001-2002 Enthought, Inc. 2003-2022, SciPy Developers.
License: BSD 3-Clause

eCognition Documentation | 31