Brain Vision Analyzer

Brain Vision Analyzer

OLE Automation

Reference Manual

Version 1.05

The content of this document is the intellectual property of Brain Products GmbH, and is subject to change without specific notification. Brain Products GmbH does not grant warranty or assume liability for the correctness of individual statements herein. Nor does Brain Products GmbH enter into any obligation with regard to this document.

Any trademarks mentioned in this document are the protected property of their rightful owners.

Contents

1. Overview 4

2. Object hierarchy 5

3. Object classes 6

3.1. Application 6

3.2. Channel 7

3.3. ChannelPosition 8

3.4. Channels 9

3.5. CurrentWorkspace 9

3.6. Dataset 9

3.7. FastArray 12

3.8. HistoryExplorer 16

3.9. HistoryFile 16

3.10. HistoryFiles 17

3.11. HistoryNode 18

3.12. HistoryNodes 20

3.13. HistoryTemplateNode 20

3.14. Landmark 20

3.15. Landmarks 20

3.16. Marker 21

3.17. Markers 21

3.18. NewHistoryNode 21

3.19. Progress bar 25

3.20. Segment 26

3.21. Segments 26

3.22. Transformation 27

3.23. Window 28

3.24. Windows 29

3.25. Workspace 30

3.26. Workspaces 30

4. Callable transforms 31

4.1. Band-rejection filters 32

4.2. Filters 33

4.3. Formula Evaluator 34

5. Enumerator types 35

5.1. VisionDataType 35

5.2. VisionDataUnit 35

5.3. VisionSegType 35

5.4. VisionLayerIncFunction 35

6. Error codes 36

1. Overview

The Vision-Analyzer can be controlled via OLE Automation either by means of the built-in Basic interpreter or by external programs.

The program ID (ProgID) for external access to the Analyzer is VisionAnalyzer.Application. The Analyzer incorporates a registered type library which is stored in Analyzer.exe. The entry for the type library in the Registry is Vision Analyzer x.x Type Library where x.x stands for the current version.

2. Object hierarchy

The following figure shows the object hierarchy in the Analyzer. It acts as a guide in relation to the description of object classes in the next chapter.

3. Object classes

Object classes are described in the usual Basic syntax. However, that does not mean that they cannot be accessed with other programming languages.

Collections act as containers for objects. The objects can be indexed via an index number. The first index is always 1 and not zero. Some collections also permit indexing via the name or title of the object in question. That is only feasible, however, when the name occurs just once in the collection. Another way of running through collections is the For Each statement in Basic.

The first index in arrays is also 1.

Most objects have a so-called default element. This is a method or property which does not need to be mentioned explicitly. As far as the Channel object is concerned, for example, it is the DataPoint property. Consequently the two statements below are equivalent:

fValue = Channels(1).DataPoint(1)

fValue = Channels(1)(1)

3.1. Application

Description

Of the Application class there is only one object which represents the program as a whole. It is the default object, which means that the methods and properties of this object can be addressed directly, i.e. Visible corresponds to Application.Visible, for example.

Methods

Function Ask(Text as String) as Long

Asks a question that can be answered with yes or no. Returns vbYes (6) or vbNo (7). This function is useful for Basic scripts in history templates, because the input/output of these messages will be redirected if log files are used (Analyzer, Apply Template...) in opposite to the built-in function MsgBox.

Sub ExecuteMenuItem(MenuItem as String)

Runs a menu command. This is entered as text. For example, the filter transformation can be called using

ExecuteMenuItem "transformations\filters"

ExecuteMenuItem "Transformations\Filters"

The function is not case-sensitive, and spaces/full stops in the menu text are ignored.

Function Message(Text as String) as Long

Shows a text that can be answered with ok or cancel. Returns vbOk (1) or vbCancel (2). This function works similar to Ask when messages are redirected.

Sub MessageStatus(Text as String)

Outputs a text in the status bar.

Sub Quit()

Terminates the program.

Properties

ActiveTemplateNode As HistoryTemplateNode

Write-protected

If the Analyzer is processing a template, this object describes the template node that is currently being processed.

ActiveWindow As Window

Write-protected

The active window in the Analyzer's workspace. If no window is open, this value is Nothing (NULL or NIL, among other things, in other programming languages).

CurrentWorkspace As CurrentWorkspace

Write-protected

The current workspace.

HistoryExplorer As HistoryExplorer

Write-protected

The History Explorer.

HistoryFiles As HistoryFiles

Write-protected

Collection of all history files.

InstalledComponents as String

Write-protected

Installed components as text

TemplateMode As Boolean

Flag if "True" (-1), the program is in the process of running a template.

Version As Double

Write-protected

Specifies the current version of the program.

Visible As Boolean

Flag: If False (0), then the program is not visible.

Windows As Windows

Write-protected

Collection of all work windows.

WorkFileFolder As String

Write-protected

Directory containing the work files.

Workspaces As Workspaces

Write-protected

Collection of all the workspaces in the directory containing the work files

3.2. Channel

Description

This object describes a channel in a history node. Since DataPoint is the default element, it is very easy to access an individual data point.

Example:

Dim fValue As Single

Dim hn As HistoryNode

Dim hf As HistoryFile

Dim ch As Channel

Set hf = HistoryFiles(1) ' First history file

hf.Open

Set hn = hf(1) ' First data set

Set ch = hn.Dataset(1) ' First channel

f Value = ch(1) ' First data point

Set ch = hn.Dataset("FP1") ' Alternative access using the channel name

f Value = ch(1) ' First data point

hf.Close

Alternative short version:

Dim fValue As Single

HistoryFiles(1).Open

fValue = HistoryFiles(1)(1).Dataset(1)(1)

HistoryFiles(1).Close

If larger amounts of data are to be read, it is advisable to read in a vector using GetData() in order to improve speed.

Example:

Dim fVector() As Single

ch.GetData(1, 1000, fVector)

You can read in several channels much quicker with Dataset.GetData(). You will find more information on this under Dataset.

Methods

Sub GetData(Position As Long, Points As Long, Data() As Single)

Reads a data vector into Data() starting from Position. The number of data points to be read in is defined by Points.

If the data set involves complex data, every data point has two values. The first value is the real part and the second is the imaginary part of the number, i.e. Data(1) is the real part of the first data point and Data(2) is its imaginary part. The second data point is assigned to Data(3) and Data(4), etc.

Properties

DataPoint(Index As Long) As Single

Default element, write-protected

Data point: The index specifies the position in the data set (1-...).

If the data set involves complex data, this variable specifies the real part of the complex number.

DataPointLayered(Index As Long, Layer As Long) As Single

Write-protected

This property is the same as DataPoint except that for data with several layers (as in the case of continuous wavelets, for example), the layer can be specified as well.

ImgPoint(Index As Long) As Single

Write-protected

Imaginary part of a complex number if the data type is complex. The index specifies the position in the data set.

ImgPointLayered(Index As Long, Layer As Long) As Single

Write-protected

This property is the same as ImgPoint except that for data with several layers (as in the case of continuous wavelets, for example), the layer can be specified as well.

Name As String

Write-protected

Channel name.

Position As ChannelPosition

Write-protected

Head position of the channel.

ReferenceChannel As String

Write-protected

Reference channel name.

Unit As VisionDataUnit

Write-protected

Unit of data in this channel, e.g. μV, μV2 etc. Also refer to VisionDataUnit in the "Enumerator types" chapter.

3.3. ChannelPosition

Description

This object describes the position of a channel.

Methods

Properties

Phi As Single

Write-protected

Phi in degrees.

Radius As Single

Write-protected

Radius in millimeters. 0 means an invalid position specification. 1 takes the head as the ideal sphere with a uniform radius.

Theta As Single

Write-protected

Theta in degrees.

3.4. Channels

Description

This object is a collection of Channel objects.

Methods

Properties

Count As Long

Write-protected

Number of channels in the collection.

Item(NameOrIndex As Variant) As Channel

Default element, write-protected

Returns a Channel object when the channel name or index (1-...) is specified.

3.5. CurrentWorkspace

Description

This object represents the current workspace.

Methods

Sub Load(FileName As String, [SingleHistoryFile As String])

Loads the specified workspace file FileName.

SingleHistoryFile is an optional parameter which enables a single history file to be loaded.

Sub Save()

Saves the current workspace file.

Sub SaveAs(FileName As String)

Saves the current workspace file under a new name.

Properties

ExportFileFolder As String

Write-protected

Standard folder for exported files.

FullName As String

Write-protected

Name of the workspace file including the full path.

HistoryFileFolder As String

Write-protected

Folder for history files.

Name As String

Write-protected

Base name of the workspace file without the folder and file name extension.

RawFileFolder As String

Write-protected

Folder for raw data.

3.6. Dataset

Description

This object represents a data set – either the data in a history node in its entirety or the data of a single segment within the overall data set.

Properties prefixed by Layer are only used with data that has several levels (with what you might call three-dimensional data sets). Continuous wavelets are an example of data sets with several layers.

Methods

Function GetData(Position As Long, Points As Long, [ChannelList as Variant]) as Single()

Returns as a matrix the data of a section beginning at Position. The number of data points read in is defined by Points. The optional ChannelList parameter can contain either an array of channels or a single channel. The channel specifications can be made as indices or names.

If this parameter is not used, the data of all channels is returned.

The data is multiplexed when it is returned. In other words, all the data of the first sampling point is returned first, followed by that of the second sampling point, and so on. This format corresponds to that of the internal data management in the history nodes. Consequently, it is much quicker than using Channel.GetData().

If the data set involves complex data, every data point has two values. The first value is the real part, and the second is the imaginary part of the number (i.e. Data(1) is the real part of the first data point, and Data(2) is its imaginary part).

Examples

Dim Data() as Single

' The first 2000 points, all channels

Data = ds.GetData(1, 2000)

' The first 2000 points, channels "Fp1" and "Fp2"

Data = ds.GetData(1, 2000, Array("FP1", "Fp2"))

' The first 2000 points, 1st and 12th channels

Data = ds.GetData(1, 2000, Array(1, 12))

' The first 2000 points, channel "F3"

Data = ds.GetData(1, 2000, "F3")

Dim a(1 to 2) as Long

a(1) = 12

a(2) = 24

' The first 2000 points, 12th and 24th channels

Data = ds.GetData(1, 2000, a)

Properties

Averaged As Boolean

Write-protected

Flag: If True (-1), then the data set is a direct or indirect result of averaging.

AverageCount As Long

Write-protected

Number of segments included in averaging. Only valid if the Averaged flag is True (-1).

Channels As Channels

Default element, write-protected

Collection of channel objects in the data set.

LayerFunction As VisionLayerIncFunction

Write-protected

Increment function between the layers of a data set. Such layers occur with three-dimensional data (continuous wavelets, for example). You will find the possible values of this property in the chapter entitled "Enumerator types".

LayerLowerLimit As Long

Write-protected

The value of the lowermost layer of a multilayer data set.

Layers As Long

Write-protected

Number of layers in the data set. Data with several layers is used with continuous wavelets, for example).

LayerUpperLimit As Long

Write-protected

The value of the uppermost layer of a multilayer data set.

Length As Long

Write-protected

Length of the data set in data points.

Markers As Markers

Write-protected

Collection of markers in the data set.

SamplingInterval As Double

Write-protected

Resolution in microseconds for data in the time domain and in hertz for data in the frequency domain.

The following formula converts resolution for data in the time domain to the sampling frequency:

Frequency = 1000000.0 / SamplingInterval

SegmentationType as VisionSegType

Write-protected

Specifies the type of segmentation for this data set (see section 5.2).

Type As VisionDataType

Write-protected

Type of data in this data set. Also refer to VisionDataType in the "Enumerator types" chapter.

3.7. FastArray

This object is a help class for accelerating access to arrays. In fact, using it only makes sense in the built-in Basic. Although this Basic can quite easily perform several hundreds of thousands of array manipulations within one second, it may be worthwhile using "FastArray" object types under certain circumstances. Given skilful structuring, it is then possible to perform several hundreds of millions of manipulations within one second.

The manipulations consist of assignments and simple computation operations. In the computations, the target field ("TargetData" variable) is also the left-hand operand at the same time.

The source field ("SourceData" variable) remains unchanged.

Example of a division: TargetData = TargetData / SourceData.

In operations with only one operand, the TargetData is the source field at the same time.

Example of an absolute value calculation ("RectifyData"): TargetData = abs(TargetData)

All indices that are used in manipulations relate to the start of an array, i.e. a array that was declared with "Dim Data(12 to 24) As Single" has its first data point at "Data(12)". An index parameter of 1 will now relate to this starting point. For reasons of clarity, we therefore recommend declaring an array as "Dim Data(1 to …) As Single".

All arrays that are transferred must be one-dimensional and must already have a defined field length.

Extracting / defining array subsets

The three parameters "StartIndex", "Step" and "Count" are used in most functions for describing a subset of elements of an array. The resulting subset is determined as follows: