CIVA

UT data import plugin

Developer’s guide

CIVA - UT data import plugin - Developer’s guide 1

Contents
1 General description 3

2 DLL implementation 4

3 Plug-in install process 5

3.1 Create the plugin directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 Create the XML description of the input . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 Create the XML description of the plugin . . . . . . . . . . . . . . . . . . . . . . . 6
3.4 Create the plugin launcher (batch file) . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5 Launch CIVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Debugging 8
4.1 Debugging out of CIVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2 Debugging in CIVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5 Annex 10
5.1 Skew and refraction angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2 Optional methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.3 String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.4 Signals and peaks import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

CIVA - UT data import plugin - Developer’s guide 2

1 General description
CIVA provides the ability to read any UT file format through the UT Data Import Plugin.

Developing an UT Data Import Plugin consists in:

− Developing a DLL (Dynamic Link Library) which implements the interface provided by the
plugin : CIVA provides a full development environment with Visual C++,
− Setting 2 XML configuration files,
− Setting a “.bat” file that will contain some runtime settings.

CIVA calls the ImportUTDataFile[32|64].exe file, provided in the “Plug-in” subdirectory of

CIVA. By interpreting XML configuration files, this executable loads the specific DLL that you have
to produce.

The role of this DLL is to provide all information to convert your UT Data Format to a CIVA native
format. Writing the CIVA native format file is managed by the executable ImportUTDataFile[32|64].exe.

CIVA - UT data import plugin - Developer’s guide 3

2 DLL implementation
A complete development environment is provided including these files :

− SampleImportPluginDllProject.sln
Visual C++ solution to start your project (compatible with Visual Studio 2010 and later
versions).

− PluginDataImporter.h
Header file composed of the definitions of all methods and types required for the plugin to
work.

− SampleDataImport.c
Simple implementation of the PluginDataImporter. You can start with this example and
change each function according to your own format. This example is based on a trivial
format (see File.sample). The structure of this file is as follows :
• First line (header) : number of increments, number of scannings, number of
sequences, number of shots, and number of samples in a signal,
• Content : signal values.

Compiling this project will generate a DLL named SampleImportPluginDll[32|64].dll. To

debug your DLL, see Section 4 (page 8).

CIVA - UT data import plugin - Developer’s guide 4

 3 Plug-in install process
All CIVA plugins are installed in [CIVA install dir]/PlugIn[32|64]. In this directory, you will
find ImportUTDataFile/bin/ImportUTDataFile[32|64].exe. These executables will connect to
your DLL to import data and generate files on CIVA format.

To ensure that CIVA recognises the plugin, follow these steps.

3.1 Create the plugin directory

In [CIVA install dir]/PlugIn[32|64], create a [PluginName].plugin directory.

3.2 Create the XML description of the input

In [PluginName].plugin directory, create the file descfiles.xml with the following template:

1 <? xml version ="1.0" encoding =" ISO -8859 -1" standalone =" no " ? >
2
3 < FilesDesc >
4 < listFileDesc >
5 < FileDesc >
6 < extension >
7 [ extension1 ]
8 </ e x t e n s i o n >
9 < isDirectory >
10 [ isDirectory1 ]
11 </ i s D i r e c t o r y >
12 </ F i l e D e s c >
13 < FileDesc >
14 < extension >
15 [ extension2 ]
16 </ e x t e n s i o n >
17 < isDirectory >
18 [ isDirectory2 ]
19 </ i s D i r e c t o r y >
20 </ F i l e D e s c >
21 [ ... ]
22 </ l i s t F i l e D e s c >
23 < description >
24 [ P l u g i n N a m e ] Files (*. [ e x t e n s i o n 1 ] , *. [ e x t e n s i o n 2 ] , ...)
25 </ d e s c r i p t i o n >
26 </ F i l e s D e s c >

Here is an explanation of the fields of this template:

− [extension1] : the first extension compatible with the plugin (for example civa),
− [extension2] : your plugin might be able to read several format, in this case list all the
compatible extensions through <extension/>,
− [isDirectory1] is false if the input is a file and true if the input is a directory,
− [PluginName] Files (*.[extension1], *.[extension2], ...) : a suggestion of de-
scription, where [PluginName] is the name of the plugin. This description will be shown in
the file chooser of CIVA.

CIVA - UT data import plugin - Developer’s guide 5

 3.3 Create the XML description of the plugin
In [PluginName].plugin directory, create the file [PluginName].xml with the following template:

1 <? xml version ="1.0" encoding =" ISO -8859 -1" standalone =" no " ? >
2
3 <! DOCTYPE DescPlugIn PUBLIC " -// fr . cea // DTD descplugin . resources . dtd . DescPlugIn // FR
" " DescPlugIn . dtd " >
4
5 < D e s c P l u g I n Auteur =" CEA " withGUI =" true " Type =" I mp or t UT Ac qF i le " Nom =" [ P l u g i n N a m e ] "
Version ="0" >
6 < Lanceur LigneCommande ="% PLUGIN_FOLDER %\ [ P l u g i n N a m e ] . plugin \ [ P l u g i n N a m e ] . bat " / >
7 < DescIHM keyDescIHM =" KeyDescIHM " / >
8 < Option tagOption =" TESTMODEL " value =" true " / >
9 < Option tagOption =" DEBUG " value =" false " / >
10 </ D e s c P l u g I n >

[PluginName].bat is the batch that effectively launches the import process (described below).

3.4 Create the plugin launcher (batch file)

In [PluginName].plugin directory, create the file [PluginName].bat. It may look like this:

1 @ REM CIVA 32 bits will never be installed on a 64 bits machine

2 @ REM = > a CIVA 32 bits will never launch a 64 bits plugin
3 @ REM = > no need to handle the case where % P R O C E S S O R _ A R C H I T E C T U R E % is x86 , whereas
CIVA is in the SysWOW64 emulator
4
5 @ SET IMPORT_EXE_32 = %P LU G IN _F OL D ER % \ I m p o r t U T D a t a F i l e \ bin \ I m p o r t U T D a t a F i l e 3 2 . exe
6 @ SET IMPORT_EXE_64 = % PL UG IN _ FO LD ER % \ I m p o r t UT D a t a F i l e \ bin \ I m p o r t U T D a t a F i l e 6 4 . exe
7 @ SET UNAVAILABLE =2
8
9 @ if " % P R O C E S S O R _ A R C H I T E C T U R E % " == " x86 " (
10 @ REM OS 32 bits = > launch I m p o r t U T D a t a F i l e 3 2 . exe
11
12 % IM PO RT _ EX E_ 32 % % * %P LU GI N_ F OL DE R% \ [ P l u g i n N a m e ] . plugin \ [ D l l N a m e 3 2 ] . dll [ args ]
13 ) else (
14 @ REM OS 64 bits = > launch I m p o r t U T D a t a F i l e 6 4 . exe first . If it fails , launch
I m p o r t U T D a t a F i l e 3 2 . exe .
15
16 % IM PO RT _ EX E_ 6 4% % * %P L UG IN _F OL D ER % \ [ P l u g i n N a m e ] . plugin \ [ D l l N a m e 6 4 ] . dll [ args ]
17 if errorlevel %UNAVAILABLE% (
18 % IM PO RT _ EX E_ 32 % % * %P LU GI N_ F OL DE R% \ [ P l u g i n N a m e ] . plugin \ [ D l l N a m e 3 2 ] . dll [ args ]
19 )
20 )

The [args] are optional. They are collected by ImportUTDataFile[32|64].exe, and passed as
they stand to the last argument of before() method, if implemented in the DLL.

We suggest locating the DLL in the plugin directory, but it is not mandatory.

CIVA - UT data import plugin - Developer’s guide 6

3.5 Launch CIVA
Once all is well configured, launch CIVA, then click File -> Open..., and you should see your
plugin entry in the filechooser, like this:

Select a file, click Open: the import process of your file should be launched.

CIVA - UT data import plugin - Developer’s guide 7

 4 Debugging
4.1 Debugging out of CIVA
There are 2 execution modes for a plugin :
− Model testing: (TESTMODEL property set to true) used to test first that all is ready to
proceed to the import,
− Import: (TESTMODEL property set to false) used to proceed to the actual import.

If you want to debug your DLL, you can parameterize the command and arguments in the Visual
Studio Project Properties (Configuration Properties -> Debugging) as follows :
− Command: [CivaPlugInDir]/ImportUTDataFile/bin/ImportUTDataFile[32|64]D.exe (D
standing for Debug),
− Command Arguments:
[ArgsDir]\[PluginName].properties
[ArgsDir]\[PluginName].ihm
[ArgsDir]\result\[PluginName].result
[ [ArgsDir]\[PluginName].properties ] (only in model testing mode)
[PluginDllPath]

These properties, ihm and result files are generated by CIVA when it invokes the plugin. Out of
CIVA, you can create them easily :

[PluginName].properties

1 DEBUG = false
2 TESTMODEL = [ true | false ]

[PluginName].ihm

1 options . files . input_file = [ P a t h T o I n p u t F i l e ]

2 options . files . output_file = [ P a t h T o O u t p u t F i l e ]

[PluginName].result

Created by the plugin if the file does not exist.

Once Visual Studio is configured, you can set breakpoints, and launch the plugin (F5).

CIVA - UT data import plugin - Developer’s guide 8

 4.2 Debugging in CIVA
It is possible to debug your DLL when importing a file in CIVA. After installing your plugin (see
Section 3 page 5), you should set the value of DEBUG in [PluginName].xml to true.

In [PluginName].plugin directory, create the file [PluginName]_debug.bat. It may look like

this:

1 @ REM CIVA 32 bits will never be installed on a 64 bits machine

2 @ REM = > a CIVA 32 bits will never launch a 64 bits plugin
3 @ REM = > no need to handle the case where % P R O C E S S O R _ A R C H I T E C T U R E % is x86 , whereas
CIVA is in the SysWOW64 emulator
4
5 @ SET IMPORT_EXE_32 = %P LU G IN _F OL D ER % \ I m p o r t U T D a t a F i l e \ bin \ I m p o r t U T D a t a F i l e D 3 2 . exe
6 @ SET IMPORT_EXE_64 = % PL UG IN _ FO LD ER % \ I m p o r t UT D a t a F i l e \ bin \ I m p o r t U T D a t a F i l e D 6 4 . exe
7 @ SET UNAVAILABLE =2
8
9 @ if " % P R O C E S S O R _ A R C H I T E C T U R E % " == " x86 " (
10 @ REM OS 32 bits = > launch I m p o r t U T D a t a F i l e D 3 2 . exe
11
12 % IM PO RT _ EX E_ 32 % % * %P LU GI N_ F OL DE R% \ [ P l u g i n N a m e ] . plugin \ [ D l l N a m e 3 2 ] . dll [ args ]
13 ) else (
14 @ REM OS 64 bits = > launch I m p o r t U T D a t a F i l e D 6 4 . exe first . If it fails , launch
I m p o r t U T D a t a F i l e D 3 2 . exe .
15
16 % IM PO RT _ EX E_ 6 4% % * %P L UG IN _F OL D ER % \ [ P l u g i n N a m e ] . plugin \ [ D l l N a m e 6 4 ] . dll [ args ]
17 if errorlevel %UNAVAILABLE% (
18 % IM PO RT _ EX E_ 32 % % * %P LU GI N_ F OL DE R% \ [ P l u g i n N a m e ] . plugin \ [ D l l N a m e 3 2 ] . dll [ args ]
19 )
20 )

The DLL used to debug your plugin has to be generated in Debug Mode in Visual Studio (as opposed
to the Release Mode).

You can now open the file to import in CIVA (see Section 3.5 page 7). You should see this dialog
opening when the import starts :

The importUTDataFile executable sleeps as long as this dialog remains open. You can then attach
a debugger to the executable (in Visual Studio, the debugger can be attached to a process with
Tools -> Attach to process...).

CIVA - UT data import plugin - Developer’s guide 9

5 Annex
5.1 Skew and refraction angles
These angles may be tricky to understand. Their values describe the vector of the raypath for
each shot.

The skew is a rotation of the ~x axis around the ~z axis.

In the new system, (x~0 , y~0 , ~z), a rotation of refraction ◦ is applied on ~z around the y~0 axis. The
resulting vector (the red arrow) is the vector of the raypath.

5.2 Optional methods

Some methods are not mandatory, those that are tagged Implementation not mandatory:
− before()
− checkPreconditions()
− after()

5.3 String
Several methods allow providing strings:
− getPluginNameLength(), getPluginName()
− getPluginAPIVersionLength(), getPluginAPIVersion(),
− getSalvoNameLength(), getSalvoName()
− getGateNameLength(), getGateName()

CIVA - UT data import plugin - Developer’s guide 10

CIVA proceeds as follows to get a string:
1. asks for the length of a string with get*NameLength(),
2. allocates a string of size length + 1,
3. invokes get*Name() with, as arguments, the allocated string and the size (length + 1).

5.4 Signals and peaks import

To import peaks or signals, CIVA proceeds in the following imposed order:
1. imports all sequences,
2. for each sequence, imports all shots,
3. for each shot, imports all increments,
4. for each increment, imports all scanning.

This information can be used to optimize the data access. More precisely:

− to import peaks, for each sequence, and for each shot, CIVA imports the CScan of ampli-
tudes (method loadPeaksCScanAmp()) and the CScan of TOF (Time Of Flight) (method
loadPeaksCScanTOF())

− to import signals, CIVA firstly estimates the size of a BScan (scanningCount * sampleCount
* sizeof(float)):
• If CIVA decides to allocate this amount of memory, CIVA will proceed as following:
for each sequence, for each shot, and for each increment, CIVA imports the BScan of
amplitudes (method loadSignalsBScan()).
• otherwise, the import will be done AScan by AScan: for each sequence, for each shot,
for each increment, and for each scanning, CIVA imports the AScan of amplitudes
(method loadSignalAScan()).

CIVA - UT data import plugin - Developer’s guide 11