Automation and scripting

BrainVoyager 2000 supports an open interface via COM-based automation. Information about COM and scripting can be found on the Microsoft web sites http://www.microsoft.com/com and http://www.microsoft.com/scripting/. With the open interface implemented in BrainVoyager you can:

  • Write scripts to perform sequences of commands. Three major scripting languages are supported: Visual Basic (VBScript), Java (JScript) and Perl (PerlScript). An important application of scripting is to run a set of preprocessing steps and statistical analysis routines in batch mode across data sets from many subjects.

  • Write your own C/C++ code and interoperate with BrainVoyager. In combination with the knowledge of the documented BrainVoyager file formats, this is the most efficient way to access the internal routines of BrainVoyager and to combine own programs with the tools provided by BrainVoyager.

  • Launch BrainVoyager on remote machines in your local area network and control them from a single computer.

  • Exchange scripts with other user's as a clear and precise description of performed data analysis steps.

  • Setting up demonstrations, explanations and tutorials for you and others using methods controlling the Graphical User Interface (GUI).

In order to be able to use BrainVoyager routines "from outside", the routines have been made available through defining a set of dual COM interfaces. These interfaces are exposed by BrainVoyager acting as a COM server. The set of interfaces provide an object model consisting of a growing number of methods and properties which can be called by the client (the user's script or C++ code). Another way to view the situation is that the exposed routines are "added" to the supported scripting languages resulting in a kind of "high-level neuroimaging programming language". The VBScript and JScript scripting languages are provided by Microsoft. If your system does not have the necessary files installed, BrainVoyager 2000 will install them during setup. PerlScript is provided by ActiveState (see http://www.activestate.com) and can be also installed directly from the BrainVoyager 2000 CD.

Chapter overview

The next topic introduces the basics of automation using a very simple script. The simple script demonstrates the use of all three supported scripting languages. Then it is described how you can modify and run scripts from within BrainVoyager. After that, a more elaborate and useful script is presented which you can use as a template for own batch processing scripts. The script shows how to run preprocessing steps across multiple subjects and runs.
It follows a description of two small C++ programs which demonstrate how to interoperate with BrainVoyager including direct access of BrainVoyager files. The two programs perform exactly the same task but use two different appraoches to access a COM server, the first program uses a universal but complicated approach while the second program uses an easy approach which is, however, only possible with the Microsoft Visual C++ compiler.
Then follows the largest section of this chapter which consists of a description of exposed methods and properties which you can use to (remotely) control BrainVoyager. Since this list will be further expanded in the future, check http://www.BrainVoyager.com/HelpUpdate to obtain always the latest version of this document. In future versions of this document, some advanced topics will be described, i.e. registering callback routines which enable BrainVoyager to call routines in your code.

Additional documentation and references

This chapter describes the COM objects and methods provided by BrainVoyager. It assumes, however, basic programming knowledge sufficient to write scripts or C/C++ programs. This section provides you with further informations about documentation and references which will help you to get started quickly.

Excellent online documentation for VBScript and JScript is provided by Microsoft. For your conveniency, we have included this documentation on the BrainVoyager 2000 CD. Simply double-click the files "vbsdoc.exe" and "jsdoc.exe" to install the online documentation. After installation, you will find the documentation in the "Start->Programs ->Microsoft Windows Script" menu.
Excellent documentation for PerlScript is provided by Active State Tools Inc. The online documentation is installed automatically when you install Perl which can be found on their Web page (http://www.activestate.com). You can also install Perl directly from the BrainVoyager 2000 CD. After installation, you will find the documentation in the "Start->Programs->ActivePerl" menu. Documentation for automation can be found in the "Win32::OLE" section which is located in the "Module Docs" section.

If you want to use other objects then those provided by BrainVoyager, i.e. to manipulate your files or registry from your scripts, you should read documentation on the Microsoft "Windows Script Host". We have put the Word file "wshobj.doc" produced by Microsoft on the BrainVoyager 2000 CD which details the object model and methods of the Windows Script Host.

If you are a C/C++ or Java programmer and you want to interoperate with BrainVoyager, we recommend to read a couple of books on COM / DCOM programming. From our own experience, we can highly recommend the following books:

  • Guy Eddon & Henry Eddon (1998). Inside Distributed COM, Microsoft Press

  • Thuan L. Thai (1999). Learning DCOM, O'Reilly & Associates, Inc.

  • David S. Platt (1998). The essence of COM with ActiveX. Prentice Hall.


A simple script

The following simple VBScript script demonstrates the general approach for writing your own script files. After explaining the most essential aspects of the script, a JScript version and a PerlScript version are presented. Colour-coding is used in a smilar way as in the Script Editor (see next topic): colour blue marks methods provided by BrainVoyager, colour red marks keywords and functions provided by the scripting language and colour purple marks methods provided by the WScript.Shell object (see below).

1: ' LoadDoc.vbs
2:
3: Set BrainVoyager = CreateObject("BrainVoyager.1")
4: Set doc = BrainVoyager.OpenDocument("cg2_tal.vmr")
5: MsgBox("Document loaded !")
6: doc.SetZoomLevel(2)
7: MsgBox("Document zoomed !")
8: doc.Close
9: BrainVoyager.Exit

The line numbers on the left do not belong to the script itself but are used to refer to parts of the script. Line 3 is usually the first executed line in your script since it provides access to BrainVoyager. If BrainVoyager is not running yet, the CreateObject function of VBScript will start BrainVoyager as if you have double-clicked it in Windows Explorer. This works only if BrainVoyager has been registered itself in the registry which normally happens during installation, otherwise CreateObject will report an error. In the latter case, run the "EnableBrainVoyagerScriptServer.bat" file which has been installed in your BrainVoyager folder. If the CreateObject function is successful, it returns a reference to BrainVoyager which is stored in the provided variable, here called "BrainVoyager". If the CreateObject function is executed and there is already an instance of BrainVoyager running, then only a reference to the running BrainVoyager is returned.

Having a reference to a running BrainVoyager now allows to call all methods which are supported by the BrainVoyager Application object. All available methods are described in the "Methods" section of this chapter. One important method of the BrainVoyager application object is OpenDocument which can be used to open any existing BrainVoyager project file. This method is used in line 4 to load the file "C:\cg2_recons\cg2_tal.vmr" or any other file you provide here as input. If the referenced file could be opened successfully, another reference is returned, this time a reference to a BrainVoyager Document object which is stored in the variable "doc". Note that the assignment of both object variables use the VBScript keyword Set. This keyword is not necessary for assignments of standard variables but it must be present when setting object variables. Having a reference to a Document object provides access to many Document methods.

In lines 5 and 7, simple message boxes are shown using the VBScript function MsgBox. The message box is used here to state the successfull execution of script commands. The message box interrupts the execution of the script until the user clicks its OK button.

In lines 6 and 8 two methods of the Document object are called. The SetZoomLevel method is used to change the view of the loaded VMR file. Calling the Close method in line 8 closes the document. If you would not call the Close method (and the Exit method), the script would leave BrainVoyager active with the loaded document. You could then go on working with the loaded file or invoke another script which works with the loaded document.

The final line invokes the Exit method of the Application object which closes BrainVoyager. This command should be the last within a script. As pointed out above, it might be advantageous in some circumstances not to close BrainVoyager, i.e. if a script is used to load a number of files as a starting point for further analysis and visualization steps.

The following script shows how to access BrainVoyager with JScript. In JScript scripts, variables must be declared which is optional in VBScript. The new ActiveXObject statement is the equivalent of the CreateObject function in VBScript. Note that directories within pathes have to be separated in strings with a double "\\" as opposed to a single "\" in VBScript. Since JScript does not have a MsgBox function, the messages for the user are now displayed using the Popup method of the WScript.Shell object. You can, of course, also use this method in VBScript scripts. The Popup method allows to present a message box for a limited amount of time only. The duration has to be specified in seconds, in our example script, a value of 5 seconds is set. Controlling the duration for showing a message box is a nice feature since it is not necessary that a user responds to messages with a button click. This is particular useful in the context of scripts which run demonstrations.

1:  // LoadDoc.js
2:
3:  var BrainVoyager // Declare variables
4:  var doc
5:  BrainVoyager = new ActiveXObject("BrainVoyager.1");
6:  doc = BrainVoyager.OpenDocument("C:\\cg2_recons\\cg2_tal.vmr");
7:  WshShell = new ActiveXObject("WScript.Shell");
8:  WshShell.Popup("Document loaded !", 5, "BrainVoyager Script");
9:  doc.SetZoomLevel(2);
10: WshShell.Popup("Document zoomed !", 5, "BrainVoyager Script");
11: doc.Close();
12: BrainVoyager.Exit();

The final script shows how to access BrainVoyager from PerlScript. To allow automation, the special statement use Win32::OLE must occur prior to access COM servers. The Win32::OLE->new function is the equivalent of the CreateObject function in VBScript. Note, that all (scalar) variables in Perl must begin with a "$" sign.

1:  # LoadDoc.pl
2:
3:  use Win32::OLE; # use special module to enable automation
4:
5:  $BrainVoyager = Win32::OLE->new("BrainVoyager.1");
6:  $doc = $BrainVoyager->OpenDocument("C:\\cg2_recons\\cg2_tal.vmr");
7:  $WshShell = Win32::OLE->new("WScript.Shell");
8:  $WshShell->Popup("Document loaded !", 5, "BrainVoyager
 Script");
9:  $doc->SetZoomLevel(2);
10: $WshShell->Popup("Document zoomed !", 5, "BrainVoyager
 Script");
11: $doc->Close();
12: $BrainVoyager->Exit();


The BrainVoyager Object Model

The set of interfaces exposed by the BrainVoyager COM server are organized within the following simple object model:

An object can provide methods and/or properties. The top-level object of BrainVoyager's object model is the application object which is returned when launching the BrainVoyager COM server, i.e. using the CreateObject function in VBScript:

Set BrainVoyager = CreateObject("BrainVoyager.1")

The variable "BrainVoyager" now contains a reference to the application object. In the method descriptions, the variable for the application object is called objBrainVoyager. The application object currently provides two properties, ActiveDocument and Documents, and the following methods: CreateProjectFMR , CreateProjectMosaicFMR , CreateProjectVMR , CreateProjectAMR , OpenDocument, Exit , GetTime , GetCurrentFolder , ScriptLaunchedByBV . The first property and the first five methods create and/or return a document object which is the most important object providing most methods of the COM server (see "Alphabetical Listing of Methods" ). The last four methods of the application document provide useful utility functions. The property Documents returns the third available object, the document collection object. The collection object can be used to enumerate all projects currently existing within the launched BrainVoyager instance. The accessed individual document objects can be used to invoke document methods. A simple example is shown below which closes all open documents before exiting BrainVoyager.

Set docs = BrainVoyager.Documents
For Each doc In docs
  doc.Close
Next
BrainVoyager.Exit


Working with scripts in BrainVoyager

Although you can define and run your scripts completely outside of BrainVoyager, we provide special scripting support in form of a sizeable, colour-coding script editor, debugging help by localization of the code line producing a script error and a dialog to organize and manipulate scripts from all three currently supported scripting languages. To call the Scripts dialog, either click the "File->Scripts..." menu item or click the Scripts icon [image] in the Toolbar.

The Scripts dialog shows all script files in the current folder; the path of the current folder is shown in the dialog's title bar. To select files from a different directory, use the Browse... button. You can create an empty new script using the New... button and you can delete a script from the current folder using the Delete button. You can also run the script selected in the dialog directly from BrainVoyager using the Run button. You can also inspect and modify a selected script in the Script Editor dialog. To invoke the editor, select a script and then click the Edit... button. The figure below shows the Script Editor dialog containing a simple script. The yellow arraw in the left margin points to a line which produced an error when the script was started. The error is a simple typographic one, i.e the line should be "doc.ShowGLM". If you would correct the error, the correct name would immediaely coloured blue as are all methods and properties exposed by BrainVoyager.

You can edit your script within this editor as with any other text editing program, i.e. you can cut, copy and paste text using the standard Windows keys or you right in the editor to get a local file menu containing menu items for cut, copy and paste. In the right column, the position of the cursor in the text is shown in the Line and Col fields. You can quit the editor without saving modifications made by clicking the Cancel button. To save modifications, use either the Save button or the Save As... button. If you want to save the current script as well as immediately executing it, use the Save & Run button.
The script editor uses colour-coding to highlight different types of information; keywords of the scripting language are coloured red as default while methods and properties (called "functions" in the options dialog) of COM servers like BrainVoyager are coloured blue. You can change these colors as well as colours for other categories like stings, numbers and comments using the Script Editor Options dialog which you can invoke by clicking the Options... button.


A script for batch mode processing

The script presented in this section is already a really useful script for the repeated application of basic fMRI analysis steps. You might want to use the script as a template for developing your own scripts. You find the script in the xx folder under the name "PreprocessSubjects.vbs". Only the VBScript version is presented but you should have no problems to transform it into JScript or PerlScript.

This script demonstrates the most important steps for preprocessing fMRI data. It runs across several subjects each having several runs. It finds the data of each subject by building the correct pathes and filenames by using information about subjects and runs. This requires, of course, that a consistent scheme for saving data to disk must exist. The script starts with FMR files and produces preprocessed FMR files as well as VTC files. You will find other scripts which demonstrate how FMR files and other documents are created from raw data. Files which can not yet be created via scripts (i.e. stimulation protocol files, spatial transformation files) must be created first and are here provided as input.

TIP You might want to load the actual script file into BrainVoyager in order to get a more readable colour-coded version.

' PreprocessSubjects.vbs

Set BrainVoyager = CreateObject("BrainVoyager.1")

' Get the path to the script file (function defined below)
path_root = GetScriptPath()

Dim SubjectList
SubjectList = Array("IG", "JB", "JW", "MW")

' Outer loop runs across subjects in array "SubjectList"
For Each Subject In SubjectList
  path = path_root + Subject + "\"

  ' Inner loop runs across all runs of a subject within a session
  For run = 1 To 4
    ' Create the file name to an fmr file
    FMR_file = Subject + "_Run" + CStr(run) + ".fmr"
    Set doc = BrainVoyager.OpenDocument(path + FMR_file)
    doc.LinkStimulationProtocol path + "allgemein.prt"
    doc.SetZoomLevel 2
    'Create the file name for the new preprocessed FMR file
    NewFMRfile = Subject + "_Run" + Cstr(run) + "_sc.fmr"
    NewSTCprefix = "R" + CStr(run) + "_slice_sc-"
    doc.SliceTimeCorrection 2081, 100, 0, NewFMRfile, NewSTCprefix
    doc.Close

    pathToVMR = path + "3DT1\"
    VMRfile = Subject + "_3DT1.vmr"
    Set docVMR = BrainVoyager.OpenDocument(pathToVMR + VMRfile)
    VTCfile = Subject + "_Run" + CStr(run) + "_sc.vtc"
    TRF2D3Dfile = Subject + "_2D3D_Run" + CStr(run) + ".trf"
    TRFACPCfile = Subject + "_3DT1_acpc.trf"
    TALfile = Subject + "_3DT1_tal.tal"
    Call docVMR.CreateVTC(path + NewFMRfile, pathToVMR + TRF2D3Dfile, _
    Call docVMR.CreateVTC(pathToVMR + TRFACPCfile, pathToVMR + TALfile, path + VTCfile)
    docVMR.Close

    VMRfile = Subject + "_3DT1_tal.vmr"
    Set doc = BrainVoyager.OpenDocument(pathToVMR + VMRfile)
    Call doc.LinkVTC(path + VTCfile, 0)
    Call doc.MotionCorrection3D()
    Call doc.TemporalSmoothingFD3D(3, 260)
    Call doc.SpatialSmoothingFD3D(1, 14)
    doc.Close
  Next
Next

BrainVoyager.Exit

' A function to retrieve the path to the script
 file
' using either BrainVoyager or the WScript object
Function GetScriptPath()
If BrainVoyager.ScriptLaunchedByBV()
 Then
GetScriptPath = BrainVoyager.GetCurrentFolder()
Else
ScriptName = WScript.ScriptFullName
GetScriptPath = Left(ScriptName,
 InstrRev(ScriptName, "\"))
End If
End Function


A simple C++ program

The simple C++ program shows how you can interoperate with BrainVoyager. The program accesses the BrainVoyager COM server to start it, to load a document and to invoke methods of the document object. It then goes beyond simple scripts by reading into memory a VMR file, inverting it's intensity values and then saving it under a new file name. It, thus, implements a simple new function which does not exist in BrainVoyager. Finally, BrainVoyager is called to load the new file for visualization.

Although it would be possible to access a loaded VMR file directly in BrainVoyager, the repeated reading and setting of intensity values via (out-of-process) COM access would take too much time. This simple program therefore shows how to mix calls to BrainVoyager with own program routines. See the chapter on "BrainVoyager file formats" for a description of all major file formats.

In the folder BrainVoyagerDemoClient, you find the source and executables for this simple demo program. You might want to use this project as the start for your own projects. If you work with Microsoft Visual C++ 5.0/6.0, you can use the provided project file to load and compile the demo program. The program is commented to explan the most important steps. To fully understand the code, you should consult a book on COM programming.

The way how BrainVoyager is accessed in the present example should work with any C++ compiler under Windows operating systems. If you are using Microsoft Visual C++, there is a much simpler way to access COM servers. This other method is highly recommend for its simplicity and is shown in the "BrainVoyagerEasyClient" program.

The code below also shows how to execute BrainVoyager on a remote computer from C++. To run this code, you must replace "REMOTEPC" with the actual name of your target computer.

// BrainVoyagerDemoClient.cpp
//

#define _WIN32_DCOM	   // needed for CoCreateInstanceEx in Win95/98
#include <objbase.h>          // for CoCreateInstanceEx
#include <fstream.h>
#include <comdef.h>	          // for _bstr_t data type (Microsoft specific)
#include "BrainVoyagerIDL.h"  // includes definition of BrainVoyager's COM interfaces
// Forward declarations
BOOL MyLoadVMR(const char *filename);
BOOL MySaveVMR(const char *filename);
void ConvertCharToBSTR(char *char_string, BSTR *bstr_string);
BYTE *Vol;             // Pointer to VMR data set, global in this example
int DimX, DimY, DimZ;  // Dimensions of loaded VMR data set, global in this example
IApplication *pApplication = NULL;	  // Variable for the basic IApplication interface
IDocument *pDoc  = NULL;              // Variables for interfaces to two documents
IDocument *pDoc2 = NULL;
void main()
{
    CoInitialize(NULL);  // Initialize COM
    IUnknown *pUnknown = NULL;
    BOOL RemoteServer = FALSE;
    HRESULT hr;
    if(RemoteServer)
    {
        WCHAR *RemoteComputer = L"REMOTEPC";
        COSERVERINFO si;
        si.pwszName = RemoteComputer;
        si.dwReserved1 = 0;
        si.pAuthInfo = NULL;
        si.dwReserved2 = 0;
        MULTI_QI mqi[1];
        mqi[0].pIID = &IID_IUnknown;
        mqi[0].pItf = NULL;
        mqi[0].hr = 0;
        hr = CoCreateInstanceEx(CLSID_BrainVoyager, NULL, CLSCTX_REMOTE_SERVER, &si, 1, mqi);
        if(hr == S_OK)
            pUnknown = mqi[0].pItf;
    }
    else
    {
        // Create instance of BrainVoyager and retrieve basic IUnknown interface
        hr = CoCreateInstance(CLSID_BrainVoyager, NULL, CLSCTX_SERVER, IID_IUnknown, reinterpret_cast<void**>(&pUnknown));
        if(!SUCCEEDED(hr))
        {
            MessageBox(NULL, "ERROR: Unable to invoke BrainVoyager via COM !", "BrainVoyager demo client", MB_OK);
            return;
        }
    }
    // BrainVoyager is now running, now get the IApplication interface via the IUnknown interface
    hr = pUnknown->QueryInterface(IID_IApplication, reinterpret_cast<void**>(&pApplication));

    pUnknown->Release(); // IUnknown no longer needed
    if(!SUCCEEDED(hr))
        return;
    struct IDispatch *pDocDisp;  // Get IDispatch interface first, then get the IDocument interface

    BSTR pathname;
    char path[_MAX_PATH], filename[_MAX_PATH];
    // Adjust the following path if necessary !!
    strcpy(path, "C:\\cg2_recons\\");
    strcpy(filename, path);
    strcat(filename, "cg2_tal.vmr");
    ConvertCharToBSTR(filename, &pathname);	// We have to convert C strings to Automation BSTR strings
    // Use the IApplication interface to call its OpenDocument method
    hr = pApplication->OpenDocument(pathname, &pDocDisp);

    SysFreeString(pathname);  // free resources
    if(!SUCCEEDED(hr))
        return;
    // Get IDocument from the IDispatch interface, then we can call document methods
    hr = pDocDisp->QueryInterface(IID_IDocument, reinterpret_cast<void**>(&pDoc));
    if(!SUCCEEDED(hr))
        return;
    pDocDisp->Release();
    // Call document methods
    //pDoc->SetZoomLevel(2);
    pDoc->Hide3DVolumeTools();
    // Now let's work on a BrainVoyager file format: a VMR file
    int new_val;
    if(MyLoadVMR(filename))  // load the VMR file into memory, for details see function definition below
    {
        // Loop through all voxels and invert intensity
        int x, y, z;
        for(x=0; x<DimX; x++)
        {
            for(y=0; y<DimY; y++)
            {
                for(z=0; z<DimZ; z++)
                {
                    new_val = Vol[z*DimY*DimX + y*DimX + x];
                    if((new_val > 30) && (new_val < 226))  // > 10
                        new_val = 225 - new_val + 10;
                    Vol[z*DimY*DimX + y*DimX + x] = (BYTE)max(0, new_val);
                }
            }
        }
        // Now we save the inverted data set under a new file name:
        strcpy(filename, path);
        strcat(filename, "cg2_tal_inv.vmr");
        MySaveVMR(filename); // for details, see function definition below
        free(Vol);  // free memory
        // Now we tell BrainVoyager to show the new file
        _bstr_t pathname2 = filename; // Simpler handling of C to BSTR conversion, but Microsoft specific!
        //ConvertCharToBSTR(filename, &pathname);
        hr = pApplication->OpenDocument(pathname2, &pDocDisp);
        //SysFreeString(pathname);
        // Finally, we call methods for the new document (as shown above)
        hr = pDocDisp->QueryInterface(IID_IDocument, reinterpret_cast<void**>(&pDoc2));
        if(!SUCCEEDED(hr))
            return;
        pDocDisp->Release(); // no longer needed
        // pDoc2->SetZoomLevel(2);
        pDoc2->Hide3DVolumeTools();
        // If you want to clean up:
        // Sleep(2000);
        // pDoc2->Close();
        pDoc2->Release();
    }

    // If you want to clean up:
    // Sleep(2000);
    // pDoc->Close();
    pDoc->Release();
    // If you want to clean up:
    // Sleep(1000);
    // pApplication->Exit();
    pApplication->Release();
    CoUninitialize(); // Uninitialize COM
}
// Helper function to convert a C string to a COM automation BSTR string
//
void ConvertCharToBSTR(char *char_string, BSTR *bstr_string)
{
    WCHAR wchar_string[256];
    for(int i=0; i<(int)strlen(char_string); i++)
    {
        wchar_string[i] = char_string[i];
    }
    wchar_string[i] = '\0';
    *bstr_string = SysAllocString(wchar_string);
}
// Accessing a BrainVoyager file format: the VMR file
//
BOOL MyLoadVMR(const char *filename)
{
    ifstream VMRFile( filename, ios::binary | ios::nocreate );
    if( !VMRFile )
    {
        cout << "ERROR: Cannot open VMR file." << endl;
        return FALSE;
    }
    unsigned short Nx, Ny, Nz;

    VMRFile.read((char *)(&Nx), sizeof(unsigned short));
    VMRFile.read((char *)(&Ny), sizeof(unsigned short));
    VMRFile.read((char *)(&Nz), sizeof(unsigned short));
    DimX = (int)Nx;
    DimY = (int)Ny;
    DimZ = (int)Nz;
    cout << Nx << " " << Ny << " " << Nz << endl;
    // Allocate memory for a data block with the dimensions read from the file
    if((Vol = (BYTE *)malloc(Nz*Ny*Nx*sizeof(BYTE))) == NULL)
    {
        cout << "ERROR: Cannot allocate memory for VMR file." << endl;
        return FALSE;
    }
    // Now read the data into memory
    VMRFile.read(Vol, Nx*Ny*Nz*sizeof(BYTE));
    return TRUE;
}
BOOL MySaveVMR(const char *filename)
{
    ofstream VMRFile( filename, ios::binary | ios::trunc );
    if( !VMRFile )
    {
        cout << "ERROR: Cannot open VMR file." << endl;
        return FALSE;
    }
    unsigned short Nx, Ny, Nz;
    Nx = (unsigned short)DimX;
    Ny = (unsigned short)DimY;
    Nz = (unsigned short)DimZ;
    cout << Nx << " " << Ny << " " << Nz << endl;

    VMRFile.write((char *)(&Nx), sizeof(unsigned short));
    VMRFile.write((char *)(&Ny), sizeof(unsigned short));
    VMRFile.write((char *)(&Nz), sizeof(unsigned short));
    VMRFile.write(Vol, Nx*Ny*Nz*sizeof(BYTE));
    return TRUE;
}


An easy C++ program

Access to COM servers using C++ can be as easy as with scripts as you can see if you compare the program in this topic with the version in the previous topic - both performing the same task (for details, see the previous topic). The easy approach presented here is possible by exploiting the informations in the type library which is stored in BrainVoyager.exe. The informations in the type library are accessed with the "#import" statement in one of the first lines of the program. The #import-technique also provides "smart pointers" to interfaces. With these smart pointers, you do not have to care about calling "Release" to release a reference of a particular interface when you no longer need the reference. This and other "bookkeeping" operations are done automatically with smart pointers. To use a smart pointer, append "Ptr" after the interface name, i.e. IApplicationPtr is used below to access the IApplication interface.
Note, however, that the type library technique presented here works only with the Microsoft Visual C++ compiler. If you use another compiler, you must use the general approach as described in the previous topic.

// BrainVoyagerEasyClient.cpp
// Adjust the following path if your BV is not in "C:\Program Files\BrainVoyager"
#import "C:\Program Files\BrainVoyager\BrainVoyager.exe" no_namespace
#include <fstream.h>

BOOL MyLoadVMR(const char *filename);
BOOL MySaveVMR(const char *filename);
BYTE *Vol;  // Pointer to VMR data set
int DimX, DimY, DimZ;

void main()
{
    CoInitialize(NULL);
    // direct access to IApplication interface
    IApplicationPtr BVApplication(__uuidof(BrainVoyager));
    char path[_MAX_PATH], filename[_MAX_PATH];
    // Adjust the following path if necessary
    strcpy(path, "D:\\Program Files\\Samples\\ObjectsRawData\\");
    strcpy(filename, path);
    strcat(filename, "cg2_tal.vmr");

    // Easy and direct access to IDocument interface
    // OpenDocument works like in scripts: it returns the Document object
    IDocumentPtr BVDoc = BVApplication->OpenDocument(filename);

    // Call document methods
    //BVDoc->SetZoomLevel(2);
    BVDoc->Hide3DVolumeTools();
    // Now let's work on a BrainVoyager file format: a VMR file
    int new_val;
    if(MyLoadVMR(filename))
    {
        int x, y, z;
        for(x=0; x<DimX; x++)
        {
            for(y=0; y<DimY; y++)
            {
                for(z=0; z<DimZ; z++)
                {
                    new_val = Vol[z*DimY*DimX + y*DimX + x];
                    if((new_val > 30) && (new_val < 226))  // > 10
                        new_val = 225 - new_val + 10;
                    Vol[z*DimY*DimX + y*DimX + x] = (BYTE)max(0, new_val);
                }
            }
        }
        strcpy(filename, path);
        strcat(filename, "cg2_tal_inv.vmr");
        MySaveVMR(filename);
        free(Vol);

        IDocumentPtr BVDoc = BVApplication->OpenDocument(filename);
        //BVDoc->SetZoomLevel(2);
        BVDoc->Hide3DVolumeTools();
    }

    BVDoc = NULL;
    BVApplication = NULL;
    CoUninitialize();
}
BOOL MyLoadVMR(const char *filename)
{
    ifstream VMRFile( filename, ios::binary | ios::nocreate );
    if( !VMRFile )
    {
        cout << "ERROR: Cannot open VMR file." << endl;
        return FALSE;
    }
    unsigned short Nx, Ny, Nz;

    VMRFile.read((char *)(&Nx), sizeof(unsigned short));
    VMRFile.read((char *)(&Ny), sizeof(unsigned short));
    VMRFile.read((char *)(&Nz), sizeof(unsigned short));
    DimX = (int)Nx;
    DimY = (int)Ny;
    DimZ = (int)Nz;
    cout << Nx << " " << Ny << " " << Nz << endl;
    if((Vol = (BYTE *)malloc(Nz*Ny*Nx*sizeof(BYTE))) == NULL)
    {
        cout << "ERROR: Cannot allocate memory for VMR file." << endl;
        return FALSE;
    }
    VMRFile.read(Vol, Nx*Ny*Nz*sizeof(BYTE));
    return TRUE;
}
BOOL MySaveVMR(const char *filename)
{
    ofstream VMRFile( filename, ios::binary | ios::trunc );
    if( !VMRFile )
    {
        cout << "ERROR: Cannot open VMR file." << endl;
        return FALSE;
    }
    unsigned short Nx, Ny, Nz;
    Nx = (unsigned short)DimX;
    Ny = (unsigned short)DimY;
    Nz = (unsigned short)DimZ;
    cout << Nx << " " << Ny << " " << Nz << endl;

    VMRFile.write((char *)(&Nx), sizeof(unsigned short));
    VMRFile.write((char *)(&Ny), sizeof(unsigned short));
    VMRFile.write((char *)(&Nz), sizeof(unsigned short));
    VMRFile.write(Vol, Nx*Ny*Nz*sizeof(BYTE));
    return TRUE;
}


Running BrainVoyager on remote computers

In the last topic, a script template has been presented which shows how to run many preprocessing and/or analysis steps across multiple subjects. If you have access to several computers in your local area network (LAN), you might want to run BrainVoyager on many workstations, i.e. each computer analyzing a subset of a large subject population. As an extension of COM, DCOM provides an elegant way to control the combined computer power of a network cluster from one single PC. Without any change in the code of the COM server (BrainVoyager) and only a small change in your clients (scripts or C++ programs), DCOM allows to execute BrainVoyager on any remote computer in your LAN on which it is installed. The following simple VBScript script is almost identical to the previously presented "simple script":

1: ' LoadDocRemote.vbs
2:
3: Set BrainVoyager = CreateObject("BrainVoyager.1", "RemoteComputer")
4: Set doc = BrainVoyager.OpenDocument("C:\cg2_recons\cg2_tal.vmr")
5: MsgBox("Document loaded !")
6: doc.SetZoomLevel(2)
7: MsgBox("Document zoomed !")
8: doc.Close
9: BrainVoyager.Exit

The only change is in the call of the CreateObject function in line 3 which now has a second argument location, which is set to "RemoteComputer". If this second argument is provided, BrainVoyager is started on the specified remote computer and not on the local one. The name of a remote computer is the same as the machine name portion of a sharename. For a network share named "\\myserver\public", the servername is "myserver". In addition, you can specify servername using DNS format or an IP address. You can also run BrainVoyager interactively on the remote machine and then invoke the System Information dialog by clicking the Help->System information... menu item. The appearing dialog shows the name of the machine under the entry "Computer name:" as shown in the figure below.

Note that the extended CreateObject function accepting the location parameter requires VBScript V5.1 or higher. Version 5.1 is the version installed with Windows 2000 and it is the version which you can install from the BrainVoyager CD for Windows NT 4.0 and Windows 98.

The tool DCOMCNFG.EXE

To change your scripts to run BrainVoyager on a remote machine is straitgthforward. Running these scripts might, however, at first lead to an error message because you probably do not have the rights to launch programs on the remote machine. Windows NT 4.0 / 2000 provide the program dcomcnfg.exe which can be used to do the necessary settings.This is mostly a matter of administration, not programming. Note that this tool modifies the registry and thus can only be run from an account with administrator privileges.

If you start dcomcnfg.exe interactively on the remote machine, the dialog shown above will appear which allows you to change default settings for security and other DCOM properties on various tabs. If you are only concerned about launching BrainVoyager on this machine from another PC, we recommend to change the settings only for BrainVoyager. Select BrainVoyager from the Application tab as shown above and then click on the Properties... button. In the appearing dialog, the most important setting to be done is to specify the users or groups that are allowed or forbidden to launch BrainVoyager. Click on the Security tab and then edit the custom launch permissions (see figure below). The default settings grant launch permission to administrators, the system user, and the interactive user. A group or individual user can be added by clicking the Add... button in the Registry Value Permissions dialog. Make sure that you are included in the people who have launch permission for BrainVoyager.

Another important setting concerns the identitiy under which BrainVoyager is started on the machine when launched by the remote client (your script or C/C++ program). Suppose a script on Paul's machine calls CreateObject to run BrainVoyager remotely on Mary's machine. Depending on the settings on Mary's machine, BrainVoyager might be launched on her machine with Paul's identity. In this case, the launched server process (BrainVoyager) is said to be "running as the activator". Any operations (for example opening files) that Paul would have been unable to perform on Mary's machine via other channels, he will be unable to accomplish via DCOM either. This makes sense from security considerations. The identity under which a process is launched remotely has, however, also another important consequence. When you launch a process as the activator, Windows NT 4.0 / 2000 creates an entirely new window station which runs completely hidden with no access to input or output devices. The standard window station which is created when a user logs on to NT and it is called the interactive window station. Only this window station gets access to the keyboard, mouse, and display device. This means that you don't see any BrainVoyager window when BrainVoyager is run as the activator. You will, however, see a "trace" of the running BrainVoyager in the Task Manager's process list. There is another way to launch a COM server, remotely, namely as a specific user or as the interactive user, the one who is currently logged in via the user interface. You can specify the identity under which the program is launched by clicking on the Identity tab in the Properties dialog which shows the following dialog:

You typically check "The interactive user" if you want to see the output of the running BrainVoyager launched by a remote client. In this case, you will be most likely logged in yourself in both machines, the local and the remote one. If you want, however, that other people can work on the machine without disturbances from a remotely controlled BrainVoyager, you should run either as a specific user (check "This user") or run as the activator (check "The launching user" ).

Since you do see nothing on the remote machine when running BrainVoyager as the activator or a specific user, your client script or program should be known to run successfully. If BrainVoyager pops up an error message, i.e. due to missing information, there is no way to continue your client code (the only "exit" then is to exit BrainVoyager). However, the output produced by your script or program are visible on the local (launching) machine which allows to get feedback about the ongoing script(s). In the example above, the MsgBox calls would pop up dialogs on the local machine thus providing feedback about the remotely running BrainVoyager. A better way to provide information about the remotely running application(s) is the Popup method of the WScript.Shell object which allows to show a dialog for a specified number of seconds only (see JScript example in "A simple script"). In a C/C++ program, the easiest way to get feedback about the remotely running BrainVoyager(s) would be to send informations to the console. It is then easily possible to run several scripts on several remote computers and to view feedback about the ongoing processes in several consoles on the local machine.

At the beginning of this topic it was shown that a small modification is sufficient to let any script run BrainVoyager on a remote computer. It is also very easy to enable remote invocation for C/C++ programs. Here the CoCreateInstance function has to be replaced with the CoCreateInstanceEx function. The following line of code is from the listing shown in the topic "A simple C++ program":

  HRESULT hr = CoCreateInstance(CLSID_BrainVoyager, NULL, CLSCTX_SERVER, IID_IUnknown, reinterpret_cast<void**>(&pUnknown));

If successful, this function invokes BrainVoyager on the local machine and returns a pointer to the IUnknown interface from which a pointer to the appliction interface can be queried. To create an instance of BrainVoyager on a remote computer, the code has to be modified slightly (see also BrainVoyagerDemoClient.cpp):

  COSERVERINFO si;
  si.pwszName = L"RemoteComputer";
  si.dwReserved1 = 0;
  si.pAuthInfo = NULL;
  si.dwReserved2 = 0;

  MULTI_QI mqi[1];
  mqi[0].pIID = &IID_IUnknown;
  mqi[0].pItf = NULL;
  mqi[0].hr = 0;

  HRESULT hr = CoCreateInstanceEx(CLSID_BrainVoyager, NULL, CLSCTX_REMOTE_SERVER, &si, 1, mqi);

  if(hr == S_OK) pUnknown = mqi[0].pItf

The first three arguments of the CoCreateInstanceEx function are identical to the CoCreateInstance function. The flag CLSCTX_SERVER has been, however, exchanged by the flag CLSCTX_REMOTE_SERVER which specifies that we want to run BrainVoyager on a remote computer. Information about the remote computer is specified with the fourth argument, a pointer to a COSERVERINFO structure. This structure has to be filled with the name of the remote computer, in our example this is "RemoteComputer". These are all the changes necessary to run the subsequent code on a remote machine. The CoCreateInstanceEx function uses, however, another method to query for an interface pointer than the CoCreateInstance function. It uses an array of structures of type MULTI_QI which allows you to call for more than one interface with one function call. Each structure contains a pointer to the ID of the requested interface, which you must set before making the call. Each structure also contains an HRESULT field (.hr) and an interface pointer which are filled on output. Since we ask only for one interface pointer (IUnknown), only one structure (mqi[0]) is filled as needed. The pointer to the mqi array is provided as the last argument of the CoCreateInstanceEx function. The fifth argument is set to the number of queried interfaces, i.e. "1" in our example. If the call to CoCreateInstanceEx is successful, we can retrieve the pUnknown pointer from the pItf field of the mqi[0] structure. From this point we can proceed exactly in the same way as in the example "A simple C++ program". Note, however, that your C++ code runs on the local (launching) machine. If you load any files for processing in you code, be aware that this might require network access. Since fMRI data analysis has to deal with large data sets, you should try to avoid file operations across the network unless you have a very fast one (at least a 100 MBit net). Generally it is recommended to first distribute the data of several subjects across the local hard disks of your machines and then to control several remote instances of BrainVoyager from one machine to work with data sets local to the respective machine. For multi-subject GLM analysis, you might want to copy (interactively or via a script) the preprocessed VTC files from the different computers into a folder of your most powerful machine.


Sample scripts and programs

You can find several scripts and C++ programs on the BrainVoyager 2000 CD. These samples are briefly described below and might serve as the starting point for your own scripts and programs. Most scripts require data sets which should be present within the same folder. To allow running the scripts successfully from any folder, pathes are not coded in a fixed manner but relative with respect to the folder where the script itself resides. Therefore in most scripts the function GetScriptPath() is defined ensuring that the folder where the script resides is used as the default path.
Some scripts also use the "WshShell" object, for example to use the "Popup method" which allows to present message boxes to the user for a certain amount of time. Details of the "WshShell" object as well as other useful Windows objects (i.e. WshNetwork, WshSpecialFolders), see the file WshObj.doc on the BrainVoyager CD which is part of Microsoft's documentation of the Windows Script Host.

Script / C++ program | Location | Short description
GetScriptPath.vbs GetScriptPath.js GetScriptPath.pl | <SampleData> | Shows how to obtain the path to the folder of the launched script. The described approach is used in most subsequent scripts encapsulated in the function GetScriptPath()
LoadDoc.vbs LoadDoc.js LoadDoc.pl | <SampleData>\ObjectsAnalyzed | This script is similar to the simple script described earlier. It shows how to access the BrainVoyager COM server, how to open a document and how to access document methods.
LoadDocRemote.vbs | <SampleData> | Same as above but launches BrainVoyager on a remote computer
CycleThroughDocuments.vbs CycleThroughDocuments.js CycleThroughDocuments.ps | <SampleData>\ObjectsAnalyzed | Shows how to access all documents currently existing in BrainVoyager. Load some douments before calling this script. For details, see Documents property.
NewWindowPosSize.vbs | <SampleData> | Change the position and size of the BrainVoyager window
DynamicThreshold.vbs | <SampleData>\ObjectsAnalyzed | Dynamically thresholding a statistical map
DemoGLM.vbs | <SampleData>\ObjectsAnalyzed | Loads a GLM file and shows statistical maps; it also shows how you can produce simple explanatory demos of your data.
TimeCourses.vbs | <SampleData>\ObjectsAnalyzed | Invokes and manipulates ROI Time Course windows.
EventRelatedAveraging.vbs | <SampleData>\ObjectsAnalyzed | Invokes and manipulates an AVG window.
Meshes.vbs | <SampleData>\VolumesAndMeshes | Shows and animates head and cortex meshes
CheckOpenGLSpeed.vbs CheckOpenGLSpeed.js CheckOpenGLSpeed.pl | <SampleData>\VolumesAndMeshes | Loads meshes, animates them and measures the speed of OpenGL rendering.
OpenGLRecordMovie.vbs | <SampleData>\VolumesAndMeshes | Based on script above and shows in addition how animations can be recorded and stored in a AVI movie file.
ReconstructHead.vbs | <SampleData>\VolumesAndMeshes | Reconstructs a skin mesh by iterative morphing
ReconstructCortex.vbs | <SampleData>\VolumesAndMeshes | Reconstructs cortex mesh of a segmented hemisphere and shows mesh smoothing and cortex inflation.
CreateProjects.vbs | <SampleData>\ObjectsRawData | Creates all types of projects, creates VTC files and preprocesses data. Run this script on your hard disk to produce useful files for further processing.
PreprocessSubjects.vbs | <SampleData> | Similar as the script above but can run across many subjects and runs. The script can not be run on the data provided with BrainVoyager. Use this script as a template for batch processing.
BrainVoyagerDemoClient.cpp |  | The described simple C++ program
BrainVoyagerEasyClient.cpp |  | The described easy C++ program


Methods by Category

Creation and access of projects
CreateProjectFMR, CreateProjectFMR2, CreateProjectMosaicFMR, CreateProjectMosaicFMR2,
CreateProjectVMR, PathName, CreateProjectAMR, OpenDocument,
Save, SaveAs, Close, ActiveDocument, Documents

Creation of stimulation protocol

Preprocessing
SliceTimeCorrection, SliceTimeCorrectionEx, ConvertFuncToAMR
TemporalSmoothingFD2D, TemporalSmoothingFD2DEx, SpatialSmoothingFD2D, SpatialSmoothingFD2DEx,
MotionCorrection3D, MotionCorrection3DEx, SpatialSmoothingFD3D,
SpatialSmoothingFD3DEx, TemporalSmoothingFD3D, TemporalSmoothingFD3DEx

Linking files to projects
LinkAMRFile, LinkStimulationProtocol, LinkVTC

Spatial transformations
CreateVTC

Statistical analysis and visualization
LoadGLM, DeselectAllPredictors, SelectAllPredictors, SelectPredictorInSet1, SelectPredictorInSet2,
EnableTwoSetPredictorContrast, EnableTwoSetPredictorColours, ShowGLM, MapThreshold, MapClusterSize,
ShowTimeCourseOfVoxel, ShowTimeCourseOfVoxelEx, MoveTimeCoursePlot, CloseTimeCoursePlot,
CloseAllTimeCoursePlots, ShowEventRelatedAverage, ShowEventRelatedAverageEx, MoveEventRelatedAveragePlot

Volumes
SetCrossPosition, SetVoxelValue

Meshes
CreateSphereMesh, ReconstructBoundary,
LoadMesh, SaveMesh, AddMesh, LoadViewingSettings,
SetViewpointAngles, SetViewpointPosition,
SliceMeshAxial, SliceMeshCoronal, SliceMeshSagittal, MeshSlicesOff,
MorphMesh, InflateMesh

Graphical User Interface (GUI)
NewMainWindowPosition, NewMainWindowSize, Show3DVolumeTools, Hide3DVolumeTools,
RefreshSurfaceWindow, SwitchToSurfaceModule, RefreshSurfaceWindow,
RefreshView, SetLayoutRowsCols, SetZoomLevel

Miscelleaneous methods
Exit, GetTime, GetCurrentFolder, ScriptLaunchedByBV, Sleep
BeginRecordingSurfaceWindowMovie, EndRecordingSurfaceWindowMovie


Alphabetical Listing of Methods

The methods and properties supported in BrainVoyager are listed in the table below. Simply click on a command to get a detailed description. The right column of the table shows the version of BrainVoyager since a method has been made available or modified. The first documentation of scripting and automation was available with BrainVoyager 2000, version 4.0.5 and included about 60 methods and properties. [Version 4.0.5 was the version on the first BrainVoyager 2000 CD which was released in April 2000.] The first update of scripting and automation commands arrived with BrainVoyager v4.2.5 in October 2000. A major update was introduced with version 4.6 in December 2001 including more than 50 new methods and properties.
Note: You can check the version of your BrainVoyager 2000 program by simply right-clicking the BrainVoyager.exe file in Windows Explorer. In the appearing local menu, click the Properties menu item and then select the Version tab.

Method / Property | BrainVoyager Version
ActiveDocument | 4.0.5
AddCondition | 4.6.0
AddInterval | 4.6.0
AddMesh | 4.0.5
AddPredictor | 4.6.0
AddStudyAndDesignMatrix | 4.6.0
ApplyHemodynamicResponseFunctionToPredictor | 4.6.0
BeginRecordingSurfaceWindowMovie | 4.0.5
ClearContrast | 4.6.0
ClearDesignMatrix | 4.6.0
ClearMultiStudyGLMDefinition | 4.6.0
ClearStimulationProtocol | 4.6.0
Close | 4.0.5
CloseAllTimeCoursePlots | 4.2.5
CloseTimeCoursePlot | 4.2.5
ComputeMultiStudyGLM | 4.6.0
ComputeSingleStudyGLM | 4.6.0
ConvertFuncToAMR | 4.0.5
CreateProjectAMR | 4.0.5
CreateProjectFMR | 4.0.5
CreateProjectFMR2 | 4.6.0
CreateProjectMosaicFMR | 4.0.5
CreateProjectMosaicFMR2 | 4.6.0
CreateProjectVMR | 4.0.5
CreateSphereMesh | 4.2.5
CreateVTC | 4.0.5
DeselectAllPredictors | 4.0.5
Documents | 4.0.5
EnableTwoSetPredictorColours | 4.0.5
EnableTwoSetPredictorContrast | 4.0.5
EndRecordingSurfaceWindowMovie | 4.0.5
Exit | 4.0.5
FileNameOfPreprocessdFMR | 4.6.0
GapThickness | 4.6.0
GetCurrentFolder | 4.0.5
GetTime | 4.0.5
Hide3DVolumeTools | 4.0.5
InflateMesh | 4.2.5
InterSliceTime | 4.6.0
LinearTrendRemoval | 4.6.0
LinearTrendRemovalEx | 4.6.0
LinkAMRFile | 4.0.5
LinkStimulationProtocol | 4.0.5
LinkVTC | 4.0.5
LoadGLM | 4.0.5
LoadMesh | 4.0.5
LoadMultiStudyGLMDefinitionFile | 4.6.0
LoadSingleStudyGLMDesignMatrix | 4.6.0
LoadViewingSettings | 4.0.5
MapThreshold | 4.0.5
MapClusterSize | 4.0.5
MatrixSizeX | 4.6.0
MatrixSizeY | 4.6.0
MeshSlicesOff | 4.0.5
MorphMesh | 4.2.5
MotionCorrection3D | 4.0.5 / 4.6.0
MotionCorrection3DEx | 4.0.5
MoveEventRelatedAveragePlot | 4.2.5
MoveTimeCoursePlot | 4.2.5
NegativeStatisticalValues | 4.6.0
NewMainWindowPosition | 4.0.5
NewMainWindowSize | 4.0.5
NrOfSkippedVolumes | 4.6.0
NrOfSlices | 4.6.0
NrOfStimulationProtocolConditions | 4.6.0
NrOfVolumes | 4.6.0
PathName | 4.0.5
PixelSizeOfInplaneX | 4.6.0
PixelSizeOfInplaneY | 4.6.0
OpenDocument | 4.0.5
PositiveStatisticalValues | 4.6.0
ReconstructBoundary | 4.2.5
RefreshSurfaceWindow | 4.0.5
RefreshView | 4.0.5
Remove | 4.6.0
ReverseSliceOrder | 4.6.0
Save | 4.0.5
SaveAs | 4.0.5
SaveGLM | 4.6.0
SaveMesh | 4.2.5
SaveMultiStudyGLMDefinitionFile | 4.6.0
SaveSingleStudyDesignMatrix | 4.6.0
SaveStimulationProtocol | 4.6.0
ScriptLaunchedByBV | 4.0.5
SelectAllPredictors | 4.0.5
SelectPredictorInSet1 | 4.0.5
SelectPredictorInSet2 | 4.0.5
SeparationOfStudyPredictors | 4.6.0
SeparationOfSubjectPredictors | 4.6.0
SetConditionColor | 4.6.0
SetContrastValue | 4.6.0
SetCrossPosition | 4.0.5
SetLayoutRowsCols | 4.0.5
SetPredictorValues | 4.6.0
SetPredictorValuesFromCondition | 4.6.0
SetViewpointAngles | 4.0.5
SetViewpointPosition | 4.0.5
SetVoxelValue | 4.0.5
SetZoomLevel | 4.0.5
Show3DVolumeTools | 4.0.5
ShowEventRelatedAverage | 4.2.5
ShowEventRelatedAverageEx | 4.2.5
ShowGLM | 4.0.5
ShowTimeCourseOfVoxel | 4.2.5
ShowTimeCourseOfVoxelEx | 4.2.5
Sleep | 4.0.5
SliceMeshAxial | 4.0.5
SliceMeshCoronal | 4.0.5
SliceMeshSagittal | 4.0.5
SliceThickness | 4.6.0
SliceTimeCorrection | 4.0.5 / 4.6.0
SliceTimeCorrectionEx | 4.0.5 / 4.6.0
SpatialGaussianSmoothing | 4.6.0
SpatialGaussianSmoothingEx | 4.6.0
SpatialSmoothingFD2D | 4.0.5
SpatialSmoothingFD2DEx | 4.0.5
SpatialSmoothingFD3D | 4.0.5
SpatialSmoothingFD3DEx | 4.0.5
StimulationProtocolBackgroundColorB | 4.6.0
StimulationProtocolBackgroundColorG | 4.6.0
StimulationProtocolBackgroundColorR | 4.6.0
StimulationProtocolExperimentName | 4.6.0
StimulationProtocolResolution | 4.6.0
StimulationProtocolTextColorB | 4.6.0
StimulationProtocolTextColorG | 4.6.0
StimulationProtocolTextColorR | 4.6.0
StimulationProtocolTimeCourseColorB | 4.6.0
StimulationProtocolTimeCourseColorG | 4.6.0
StimulationProtocolTimeCourseColorR | 4.6.0
StimulationProtocolTimeCourseThickness | 4.6.0
SwitchToSurfaceModule | 4.0.5
TemporalGaussianSmoothing | 4.6.0
TemporalGaussianSmoothingEx | 4.6.0
TemporalHighPassFilter | 4.6.0
TemporalSmoothingFD2D | 4.0.5
TemporalSmoothingFD2DEx | 4.0.5
TemporalSmoothingFD3D | 4.0.5
TemporalSmoothingFD3DEx | 4.0.5
TimeResolutionVerified | 4.6.0
TR | 4.6.0
TwoSetContributionMaps | 4.6.0
VoxelResolutionVerified | 4.6.0
ZTransformationOfStudies | 4.6.0


CreateProjectFMR Method

Description

Creates a FMR project file. FMR projects consist of a set of functional data in the original "slice space". For each slice a stack of repeated measurements of that slice is stored in an STC file.

Syntax

objDocument objBrainVoyager.CreateProjectFMR(strFileType, strFirstFile, intNrOfVolumes, intNrOfSlices, strSlicePrefix, intSwapBytes, intXRes, intYRes, intBytesPerPixel, strTargetPath)

Remarks

If successful, objDocument is returned. Use this object to access document methods. If the project creation operation fails, the return value is x. The parameter strFileType can be one of the following strings: "IMA" (native Siemens format), "DICOM", "DCxVR" (explicit value coding version of DICOM format), "ANALYZE" and "GE_MR" (a native GE format). The strFirstFile parameter must contain the full path information. In most cases, the intSwapBytes and intBytesPerPixel parameters should be set to 1 and 2, respectively. You may want to check proper reading of your data using the New Project Wizard or Create Project dialog before using this command in your scripts.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
path = "C:\My Documents\SampleData\"
Set docVMR = BrainVoyager.CreateProjectFMR("IMA",
 path + "5807-4-34.ima", 126, 15, "slice-", 1, 128,
 128, 2, path)

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
path = "C:\\My Documents\\SampleData\\";
docVMR = BrainVoyager.CreateProjectFMR("IMA",
 path + "5807-4-34.ima", 126, 15, "slice-", 1, 128,
 128, 2, path);

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$path = "C:\\My Documents\\SampleData\\";
$docVMR = $BrainVoyager->CreateProjectFMR("IMA",
 $path . "5807-4-34.ima", 126, 15, "slice-", 1, 128,
 128, 2, $path);


CreateProjectMosaicFMR Method

Description

Creates a FMR project file. FMR projects consist of a set of functional data in the original "slice space". For each slice a stack of repeated measurements (images) is stored in an STC file. The "Mosaic" version of FMR creation is necessary when reading Siemens files from scanning sequences which store several slices within a single image. The format of such "mosaic-images" is not a stack of slices (i.e. as in ANALYZE files), therefore special treatment is required.

Syntax

objDocument objBrainVoyager.CreateProjectMosaicFMR(strFileType, strFirstFile, intNrOfVolumes, intNrOfSlices, strSlicePrefix, intSwapBytes, intImageXRes, intImageYRes, intBytesPerPixel, strTargetPath, intSliceXRes, intSliceYRes)

Remarks

If successful, objDocument is returned. Use this object to access document methods. If the project creation operation fails, the return value is x. The parameter strFileType can be one of the following strings: "IMA" (native Siemens format), "DICOM" and "DCxVR" (explicit value coding version of DICOM format). The strFirstFile parameter must contain the full path information. In most cases, the intSwapBytes and intBytesPerPixel parameters should be set to 1 and 2, respectively. The parameters intImageXRes and intImageYRes describe the resolution of a single image (i.e. 256 x 256) whereas intSliceXRes and intSliceYRes (i.e. 64 x 64) describe the resolution of the actual slices within an image. You may want to check proper reading of your data using the New Project Wizard or Create Project dialog before using this command in your scripts.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
path = "C:\My Documents\SampleData\"
Set docVMR = BrainVoyager.CreateProjectMosaicFMR("IMA", path + "5807-4-34.ima",
 126, 16, "slice-", 1, 256, 256, 2, path, 64, 64)

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
path = "C:\\My Documents\\SampleData\\";
docVMR = BrainVoyager.CreateProjectMosaicFMR("IMA", path + "5807-4-34.ima",
 126, 16, "slice-", 1, 256, 256, 2, path, 64, 64);

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$path = "C:\\My Documents\\SampleData\\";
$docVMR = $BrainVoyager->CreateProjectFMR("IMA",
 $path . "5807-4-34.ima", 126, 16, "slice-", 1, 256,
 256, 2, $path, 64, 64);


CreateProjectVMR Method

Description

Creates a VMR project file. VMR projects consist of three-dimensional high-resolution scans used to overlay statistical maps, i.e. in Talairach space. VMR files are also used for head and surface reconstructions.

Syntax

objDocument objBrainVoyager.CreateProjectVMR(strFileType, strFirstFile, intNrOfSlices, intSwapBytes, intXRes, intYRes, intBytesPerPixel)

Remarks

If successful, objDocument is returned. Use this object to access document methods. If the project creation operation fails, the return value is x. The parameter strFileType can be one of the following strings: "IMA" (native Siemens format), "DICOM", "DCxVR" (explicit value coding version of DICOM format), "ANALYZE" and "GE_MR" (a native GE format). The strFirstFile parameter must contain the full path information. In most cases, the intSwapBytes and intBytesPerPixel parameters should be set to 1 and 2, respectively. You may want to check proper reading of your data using the New Project Wizard or Create Project dialog before using this command in your scripts.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
path = "C:\My Documents\SampleData\"
Set docVMR = BrainVoyager.CreateProjectVMR("IMA",
 path + "5807-130-1924.ima", 170, 1, 256, 256, 2)

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
path = "C:\\My Documents\\SampleData\\";
docVMR = BrainVoyager.CreateProjectVMR("IMA",
 path + "5807-130-1924.ima", 170, 1, 256, 256, 2);

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$path = "C:\\My Documents\\SampleData\\";
$docVMR = $BrainVoyager->CreateProjectVMR("IMA",
 $path . "5807-130-1924.ima", 170, 1, 256, 256, 2);


CreateProjectAMR Method

Description

Creates an AMR project file. AMR projects consist of a set of two-dimensional anatomical scans used to overlay statistical maps in the original "slice space".

Syntax

objDocument objBrainVoyager.CreateProjectAMR(strFileType, strFirstFile, intNrOfSlices, intSwapBytes, intXRes, intYRes, intBytesPerPixel)

Remarks

If successful, objDocument is returned. Use this object to access document methods. If the project creation operation fails, the return value is x. The parameter strFileType can be one of the following strings: "IMA" (native Siemens format), "DICOM", "DCxVR" (explicit value coding version of DICOM format), "ANALYZE" and "GE_MR" (a native GE format). The strFirstFile parameter must contain the full path information. In most cases, the intSwapBytes and intBytesPerPixel parameters should be set to 1 and 2, respectively. You may want to check proper reading of your data using the New Project Wizard or Create Project dialog before using this command in your scripts.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
path = "C:\My Documents\SampleData\"
Set docVMR = BrainVoyager.CreateProjectAMR("IMA",
 path + "5807-2-4.ima", 15, 1, 256, 256, 2)

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
path = "C:\\My Documents\\SampleData\\";
docVMR = BrainVoyager.CreateProjectAMR("IMA",
 path + "5807-2-4.ima", 15, 1, 256, 256, 2);

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$path = "C:\\My Documents\\SampleData\\";
$docVMR = $BrainVoyager->CreateProjecAVMR("IMA",
 $path . "5807-2-4.ima", 15, 1, 256, 256, 2);


OpenDocument Method

Description

Opens a BrainVoyager project file. Project files constitute the three basic document types in BrainVoyager: FMR, VMR, and AMR. All other data files (i.e. VTC, GLM) can be used only if one of the basic document types has been loaded or created.

Syntax

objDocument objBrainVoyager.OpenDocument(strProjectFileName)

Remarks

If successful, the object document objDocument is returned. Use this object to access document methods. If the load operation fails, the return value is ?.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
Set doc = BrainVoyager.OpenDocument("subject.vmr")

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
doc = BrainVoyager.OpenDocument("subject.vmr");

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$doc = $BrainVoyager->OpenDocument("subject.vmr");


Save Method

Description

Saves a BrainVoyager project file using the current file name.

Syntax

objDocument.Save()

Remarks

Saves the referenced document to disk using the file name in the PathName property of objDocument.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.LinkStimulationProtocol "cg_exp_r1.prt"
doc.Save

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LinkStimulationProtocol("cg_exp_r1.prt");
doc.Save();

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LinkStimulationProtocol("cg_exp_r1.prt");
$doc->Save();


SaveAs Method

Description

Saves a BrainVoyager project file under a specifed file name.

Syntax

objDocument.SaveAs(strFileName)

Remarks

Saves the referenced document object objDocument to disk with the provided file name strFileName.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.SaveAs("copy_of_subject.vmr")

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.SaveAs("copy_of_subject.vmr");

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->SaveAs("copy_of_subject.vmr");


Close Method

Description

Closes a BrainVoyager project file.

Syntax

objDocument.Close()

Remarks

Closing a project file also deletes the associated objDocument. You can no longer invoke methods using the respective document variable.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.Close

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.Close();

#
 PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->Close();


ActiveDocument Property

Description

Retrieves a reference to the active document of the accessed BrainVoyager instance.

Syntax

objDocument objBrainVoyager.ActiveDocument()

Remarks

If successful, the document object objDocument is returned. Use this object to access document methods. If the operation fails, i.e. if there is no document open in BrainVoyager, the return value is ?.

Example

' VBScript
Set doc = BrainVoyager.ActiveDocument

// JScript
doc = BrainVoyager.ActiveDocument();

# PerlScript
$doc = $BrainVoyager->ActiveDocument();


Documents Property

Description

Provides access to all projects within an instance of BrainVoyager.

Syntax

objDocumentCollection objBrainVoyager.Documents()

Remarks

This method retrieves a collection of all documents available in the accessed BrainVoyager instance. You can loop through the set of objects by using the "For each" control structure or access documents via the item command. There are some differences between the scripting languages about how collections are accessed (see script language documentation).

Example

' VBScript - full code in file "CycleThroughDocuments.vbs"
Set docs = BrainVoyager.Documents
MsgBox "Press OK to iterate through all " & docs.Count & " documents"
For Each doc In docs
  MsgBox "doc.PathName=" & doc.PathName
Next

// JScript - full code in file "CycleThroughDocuments.js"
count = BrainVoyager.Documents.Count
d ocs = new Enumerator(BrainVoyager.Documents);
message = "Press OK to iterate through all " + count + "
 documents";
WshShell.Popup(message, 2, "BrainVoyager Script");
for ( ; !docs.atEnd();
 docs.moveNext())
{
doc = docs.item();
WshShell.Popup("doc.PathName
 = " + doc.PathName
 + " ", 2, "BrainVoyager Script");
}

# PerlScript - full code in file "CycleThroughDocuments.pl"
$docs = $BrainVoyager->Documents();
$message = "Press OK to iterate through all " . $docs->Count() . " documents";
$WshShell->Popup($message, 2, "BrainVoyager Script");
foreach my $doc (in $docs)
{
  $WshShell->Popup($doc->PathName(), 2, "BrainVoyager Script");
}


PathName Property

Description

Gets or sets the name of a project.

Syntax

strPathFileName objDocument.PathName()

Remarks

Works with all three project types. This property keeps internally the full path plus file name of objDocument. If you specify a filename without a path, the current pathway is used to define the full file name.
If you assign a new file name for this property and then save the document (see below), the dcoument is saved under the new name. An alternative method would be to call the SaveAs method

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.LinkStimulationProtocol "cg_exp_r1.prt"
MsgBox doc.Pathname
doc.Pathname = "cg_objects_prt.fmr"
doc.Save

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LinkStimulationProtocol("cg_exp_r1.prt");
doc.Pathname = "cg_objects_prt.fmr";
doc.Save();

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LinkStimulationProtocol("cg_exp_r1.prt");
$doc->Pathname = "cg_objects_prt.fmr";
$doc->Save();


Show3DVolumeTools Method

Description

Shows the 3D Volume Tools dialog. If the Surface Module window is shown maximized, this method also switches to the VMR window thereby hiding the Surface Module window.

Syntax

objDocument.Show3DVolumeTools()

Remarks

Valid only if objDocument is of type VMR.

Example

' VBScript
doc.Show3DVolumeTools

// JScript
doc.Show3DVolumeTools();

# PerlScript
$doc->Show3DVolumeTools();


Hide3DVolumeTools Method

Description

Hides the 3D Volume Tools dialog.

Syntax

objDocument.Hide3DVolumeTools()

Remarks

Valid only if objDocument is of type VMR.

Example

' VBScript
doc.Hide3DVolumeTools

// JScript
doc.Hide3DVolumeTools();

# PerlScript
$doc->Hide3DVolumeTools();


RefreshView Method

Description

Repaints the document's view which is a window showing an FMR, VMR or AMR project.

Syntax

objDocument.RefreshView()

Remarks

Most document methods are defined to operate without updating the document's view. Use this method to refresh the respective document window to render the effect of an operation visible.

Example

' VBScript
doc.RefreshView

// JScript
doc.RefreshView();

# PerlScript
$doc->RefreshView();


NewMainWindowPosition Method

Description

Changes the position of the BrainVoyager window on screen.

Syntax

objBrainVoyager.NewMainWindowPosition(intPosX, intPosY)

Remarks

The position arguments intPosX and intPosY refer to the left, upper corner of the window. The values are interpreted as pixels on the screen. The (0, 0) coordinates refer to the left upper corner of the screen.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
BrainVoyager.NewMainWindowPosition 10, 10

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
BrainVoyager.NewMainWindowPosition(10, 10);

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$BrainVoyager->NewMainWindowPosition(10, 10);


NewMainWindowSize Method

Description

Changes the widht and height of the BrainVoyager window on screen.

Syntax

objBrainVoyager.NewMainWindowSize(intWidth, intHeight)

Remarks

The values are interpreted as pixels. One useful application of this method is to reduce the size of the window prior to recording a mesh movie.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
BrainVoyager.NewMainWindowPosition 10, 10
BrainVoyager.NewMainWindowSize 400, 350

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
BrainVoyager.NewMainWindowPosition(10, 10);
BrainVoyager.NewMainWindowSize(400, 350);

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$BrainVoyager->NewMainWindowPosition(10, 10);
$BrainVoyager->NewMainWindowSize(400,
 350);


Sleep Method

Description

Stops running BrainVoyager for a specified amount of milliseconds.

Syntax

objBrainVoyager.Sleep(intDurationInMS)

Remarks

One application of this function would be to slow down animations which would run to fast otherwise. An example is shown below where the statistical threshold is gradually changing over time.

Example

' VBScript
For thresh = 0.2 To 0.6 Step 0.05
  doc.MapThreshold = thresh
  doc.RefreshView
  BrainVoyager.Sleep(300)
Next

// JScript
for(thresh = 0.2; thresh < 0.6; thresh += 0.05)
{
  doc.MapThreshold = thresh;
  doc.RefreshView();
  BrainVoyager.Sleep(300);
}

# PerlScript
for($thresh = 0.2; $thresh<=0.6; $thresh += 0.05)
{
$doc->MapThreshold =
 thresh;
$doc->RefreshView();
$BrainVoyager->Sleep(300);
}


LinkStimulationProtocol Method

Description

Links a stimulation protocol PRT file to an FMR project or a 3D volume time course VTC file.

Syntax

objDocument.LinkStimulationProtocol(strStimulationProtocolFileName)

Remarks

Valid only if objDocument is a) of type FMR or b) of type VMR and if a VTC file has been linked. In the latter case, the specified stimulation protocol is linked to the VTC file. To establish a permanent link, save the FMR project or the VTC file.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.LinkStimulationProtocol "cg_exp_r1.prt"
doc.Save

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LinkStimulationProtocol("cg_exp_r1.prt");
doc.Save();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LinkStimulationProtocol("cg_exp_r1.prt");
$doc->Save();


ConvertFuncToAMR Method

Description

Converts the first functional volume of an FMR project into an AMR file.

Syntax

objDocument.ConvertFuncToAMR(strAMRFileName)

Remarks

Valid only if objDocument is of type FMR. This method is useful to produce a "pseudo-anatomical" representation within the same space as the functional data. When short TR's are used (i.e. in event-related paradigms), the first measurement of the functional slices produces images with high T1-saturation, i.e. high signal level and good tissue contrast. The high signal drops rapidly with further measurements reaching a steady state. Since this signal change presents a problem for showing and analyzing time series data, the first few measurements are normally not read in when creating an FMR project. Because of good tissue contrast, It is, however, desirable to use the very first measurement as the images on which statistical maps should be shown. This is where the present method is useful: create an FMR project of the first volume only, then apply the method to produce a respective AMR file which can then be linked to the "real" FMR file containing the full time series data (except the very first measurements). Another advantage of using a pseudo-AMR file is that spatial smoothing does not change the AMR so that the anatomical location of functional clusters can be better visualized.
Another possibility to obtain a pseudo-AMR file would be to create an AMR project from the images of the first functional volume. Although this is possible, the presented method is recommended since it produces an FMR file which can be transformed to a VTC file of the first volume. This again can be used in stereotactic space to show statistical maps not only on T1-weighted data sets but also on the original EPI data.
The method corresponds to the function invoked by the Options->Convert func to AMR menu item. The transformation uses all default settings of the Rescale Images dialog which appears in the GUI version: the AMR will transform the original FMR slices (of the first volume) to a resolution of 256 x 256, it uses bilinear interpolation, it does not invert the intensity values and it does not invert the background. A method which allows to specify these settings will be provided shortly (ConvertFuncToAMREx).

Example

' VBScript
Set doc_firstvol = BrainVoyager.OpenDocument("first_vol.fmr")
doc_firstvol.ConvertFuncToAMR "func_as_anat.amr"
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.LinkAMRFile "func_as_anat.amr"
doc.Save

// JScript
doc_firstvol = BrainVoyager.OpenDocument("first_vol.fmr");
doc_firstvol.ConvertFuncToAMR("func_as_anat.amr");
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LinkAMRFile("func_as_anat.amr");
doc.Save();

# PerlScript
$doc_firstvol = $BrainVoyager->OpenDocument("first_vol.fmr");
$doc_firstvol->ConvertFuncToAMR("func_as_anat.amr");
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LinkAMRFile("func_as_anat.amr");
$doc->Save();


LinkAMRFile Method

Description

Links a (pseudo-) anatomical AMR file to an FMR document.

Syntax

objDocument.LinkAMRFile(strAMRFileName)

Remarks

Valid only if objDocument is of type FMR. To establish a permanent link to the AMR file, save the FMR file using the Save method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.LinkAMRFile "func_as_anat.amr"
doc.Save

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LinkAMRFile("func_as_anat.amr");
doc.Save();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LinkAMRFile("func_as_anat.amr");
$doc->Save();


SetLayoutRowsCols Method

Description

Defines a grid of rows and columns in which multiple images of an FMR or AMR project are shown.

Syntax

objDocument.SetLayoutRowsCols(intRows, intCols)

Remarks

Only valid if objDocument is of type FMR or AMR. If an FMR project is saved, the current layout is stored with the file; when the file is reloaded, the previously stored layout (number of rows and columns) is used to display the project's images. This kind of persistence is not supported by AMR files.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.SetLayoutRowsCols 3, 5
doc.Save

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.SetLayoutRowsCols(3, 5);
doc.Save();

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->SetLayoutRowsCols(3, 5);
$doc->Save();


SetZoomLevel Method

Description

Sets the zoom level of the view of a BrainVoyager project file (FMR, VMR, AMR).

Syntax

objDocument.SetZoomLevel(intZoomLevel)

Remarks

Valid for all doument types: objDocument can be a VMR, FMR or AMR project. If an FMR project is saved, the current zoom level is stored with the file; when the file is reloaded, the previously stored zoom level is used to display the project's images. This kind of persistence is not supported by AMR AMR and VMR files.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.SetZoomLevel 2
doc.Save

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.SetZoomLevel(2);
doc.Save();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->SetZoomLevel(2);
$doc->Save();


SliceTimeCorrection Method

Description

Most EPI sequences measure the slices of a functional volume in succession but one often would like to treat the data of one volume as if it were acquired at the same time, particularly in the context of event-related studies. Using linear interpolation, the present method resamples the time series for the different slices in such a way that the resulting slice time courses can be treated as if they were obtained simultaneously.

Syntax

objDocument.SliceTimeCorrection(intTR, intInterSliceTime, intSliceSamplingType)

Remarks

Valid only if objDocument is of type FMR. Slice time correction can only be done in FMR projects because these projects contain the time series data separated with respect to the individually measured slices (STC files); this information is lost in VTC files after spatial transformation.
Slices typically are scanned ascending (i.e., slice 1, slice 2, slice 3 ...) or interleaved (i.e., slice 1, slice 3, slice 5 .. slice 2, slice 4, slice 6 ...). If your data had been scanned interleaved, specify "1" as the third argument, if it had been scanned ascending, specify "0". The first two parameters are necessary to perform the correct resampling of the data. The intTR argument must be specified in msecs; it is the time interval between two successive measurements of the same slice (time-to-repeat, TR). The intInterSliceTime argument has also be specified in msecs; it is the time interval between two successive slices within one volume. While the TR value should be easily obtained from the scanner protocol or from a file header, the inter slice time might be more difficult to get. If scanning ran continously, i..e. if there is no pause between scanning the last slice of volume N and the first slice of volume N+1, then you can simply divide the TR value by the number of slices per volume to get the inter slice time. If scanning ran not continously, you must either get the information about the duration of acquiring all slices or the duration of the pause between volumes. An alternative possibility (used by our group) is to read slice trigger pulses from the scanner measuring the time point when each slice is scanned; by subtracting, for example the time point of slice 1 from the time point of slice 2 results in the inter slice time.
The resulting corrected data is automatically saved to disk. The names for the new FMR project and the new STC prefix is determined as in the GUI version, i.e., if the FMR project "cg_objects.fmr" is used, the resulting new file on disk will be "cg_objects_pp.fmr". In addition, a set of new STC files, actuallly containing the time series data, is stored to disk. If, for example, the prefix in the source FMR project was "slice-" (referencing file slice-1.stc, slice-2.stc etc.), the STC prefix of the new FMR file will be "slice_pp-". If you do not want to use this implicit naming scheme, you might want to use the method SliceTimeCorrectionEx which allows to specify the name of the resulting FMR project and STC prefix.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.SliceTimeCorrection 2081, 100, 0

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.SliceTimeCorrection(2081, 100, 0);

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->SliceTimeCorrection(2081, 100, 0);


SliceTimeCorrectionEx Method

Description

Most EPI sequences measure the slices of a functional volume in succession but one often would like to treat the data of one volume as if it were acquired at the same time, particularly in the context of event-related studies. Using linear interpolation, the present method resamples the time series for the different slices in such a way that the resulting slice time courses can be treated as if they were obtained simultaneously.

Syntax

objDocument.SliceTimeCorrectionEx(intTR, intInterSliceTime, intSliceSamplingType, strNewFMRFileName, strNewSTCPrefix)

Remarks

Valid only if objDocument is of type FMR. The method operates identical as the SliceTimeCorrection version. In addition to the specification of the intTR, intInterSliceTime and intSliceSamplingType, the name of the resulting FMR project (strNewFMRFileName) and the resulting STC prefix (strNewSTCPrefix) must be specified.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.SliceTimeCorrectionEx 2081, 100, 0, "cg_objects_sc.fmr", "slice_sc-"

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.SliceTimeCorrectionEx(2081, 100, 0, "cg_objects_sc.fmr", "slice_sc-");

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->SliceTimeCorrectionEx(2081, 100, 0, "cg_objects_sc.fmr", "slice_sc-");


TemporalSmoothingFD2D Method

Description

Filters in the frequency domain the time series of each voxel in the STC files of an FMR project. Can be used to remove linear and non-linear drifts (high-pass) and/or to smooth the time series (low-pass).

Syntax

objDocument.TemporalSmoothingFD2D(intHighPass, intLowPass)

Remarks

Valid only if objDocument is of type FMR. The high- and low pass values are interpreted in cycles per lenght of the time course measured in volumes. A high pass value of "3" removes frequency components below 3 cycles within the time series. A low pass value equal to or greater than half the length of the time series will have no effect (Nyquist theorem), i.e. the low-pass filter is turned off. If the time series data, for example, contains 256 measurements, then a low pass value of 128 or greater lets everything pass, i.e. it has no effect and is turned off. In the GUI version, BrainVoyager sets the default value of the low pass to one-third of the lenght of the time series which proved to produce good results, i..e. it results in slightly smoothed time series. It is, however, recommended, not to use low pass filtering at all when preprocessing data sets from event-related designs. This is also the reason, why low pass filtering is turned off in the GUI version (2D Data Preprocessing dialog) as default.
The resulting filtered data is automatically saved to disk. The names for the new FMR project and the new STC prefix is determined as in the GUI version, i.e., if the FMR project "cg_objects.fmr" is used, the resulting new file on disk will be "cg_objects_pp.fmr". In addition, a set of new STC files, actuallly containing the time series data, is stored to disk. If, for example, the prefix in the source FMR project was "slice-" (referencing file slice-1.stc, slice-2.stc etc.), the STC prefix of the new FMR file will be "slice_pp-". If you do not want to use this implicit naming scheme, you might want to use the method TemporalSmoothingFD2DEx which allows to specify the name of the resulting FMR project and STC prefix.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.TemporalSmoothingFD2D 3, 200

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.TemporalSmoothingFD2D(3, 200);

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->TemporalSmoothingFD2D(3,
 200);


TemporalSmoothingFD2DEx Method

Description

Filters the time series of each voxel in the STC files of an FMR project. Can be used to remove linear and non-linear drifts (high-pass) and/or to smooth the time series (low-pass).

Syntax

objDocument.TemporalSmoothingFD2DEx(intHighPass, intLowPass, strNewFMRFileName, strNewSTCPrefix)

Remarks

Valid only if objDocument is of type FMR. The method operates identical as the TemporalSmoothingFD2D version. In addition to the specification of the high-pass and low pass filter values, the name of the resulting FMR project (strNewFMRFileName) and the resulting STC prefix (strNewSTCPrefix) must be specified.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.TemporalSmoothingFD2DEx 3, 200, "cg_objects_TSFD-3-200.fmr", "slice_TSFD-"

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.TemporalSmoothingFD2DEx(3, 200, "cg_objects_TSFD-3-200.fmr", "slice_TSFD-");

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->TemporalSmoothingFD2DEx(3,
 200, "cg_objects_TSFD-3-200.fmr", "slice_TSFD-");


SpatialSmoothingFD2D Method

Description

Spatially filters each recorded image in the STC files of an FMR project in the frequency domain.

Syntax

objDocument.SpatialSmoothingFD2D(intHighPass, intLowPass)

Remarks

Valid only if objDocument is of type FMR. The high- and low pass values are interpreted in cycles per spatial dimension measured in voxels (i.e. matrix size). In the rare case of a non-square matrices, the largest dimension is chosen as reference. A low pass value equal to or greater than half of the dimension (i.e. > 32 in the case of a 64 x 64 matrix) lets everyghing pass, it will have no effect (Nyquist theorem). In the GUI version (2D Data Preprocessing dialog), BrainVoyager sets the default value of the low pass filter to half of this value (i.e. 16 in case of a 64 x 64 matrix, 32 in case of a 128 x 128 matrix) which produces a modest spatial smoothing roughly equal to spatial smoothing with a FWHM of 4mm in the spatial domain. In the GUI version, the low-pass filter is turned off completely for 64 x 64 matrices and is only turned on by greater matrices. The high-pass filter is also turned off in the GUI version since such a spatial filter is not useful in the context of fMRI data analysis. To turn the high-pass filter off, specify "1" as the intHighPass argument.
The resulting filtered data is automatically saved to disk. The names for the new FMR project and the new STC prefix is determined as in the GUI version, i.e., if the FMR project "cg_objects.fmr" is used, the resulting new file on disk will be "cg_objects_pp.fmr". In addition, a set of new STC files, actuallly containing the smoothed data, is stored to disk. If, for example, the prefix in the source FMR project was "slice-" (referencing file slice-1.stc, slice-2.stc etc.), the STC prefix of the new FMR file will be "slice_pp-". If you do not want to use this implicit naming scheme, you might want to use the method SpatialSmoothingFD2DEx which allows to specify the name of the resulting FMR project and STC prefix.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.Spatial SmoothingFD2D 1, 32

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.S patialSmoothingFD2D(1, 32);

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->S patialSmoothingFD2D(1,
 32);


SpatialSmoothingFD2DEx Method

Description

Spatially filters each recorded image in the STC files of an FMR project in the frequency domain.

Syntax

objDocument.SpatialSmoothingFD2DEx(intHighPass, intLowPass, strNewFMRFileName, strNewSTCPrefix)

Remarks

Valid only if objDocument is of type FMR. The method operates identical as the SpatialSmoothingFD2D version. In addition to the specification of the high-pass and low pass filter values, the name of the resulting FMR project (strNewFMRFileName) and the resulting STC prefix (strNewSTCPrefix) must be specified.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_objects.fmr")
doc.Spatial SmoothingFD2DEx 1, 32, "cg_objects_SSFD-1-32.fmr", "slice_SSFD-"

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.Spatial SmoothingFD2DEx(1, 32, "cg_objects_SSFD-1-32.fmr", "slice_SSFD-");

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->Spatial SmoothingFD2DEx(1,
 32, "cg_objects_SSFD-1-32.fmr", "slice_SSFD-");


SetCrossPosition Method

Description

Sets the current voxel. The current voxel is shown as the center of the red cross in the SAG, COR and TRA window.

Syntax

objDocument.SetCrossPosition(intX, intY, intZ)

Remarks

Valid only if objDocument is of type VMR. The method is executed independen of whether the red cross is turned on (visible) or off (invisible). To update the SAG, COR and TRA window, call RefreshView after execution of this method.

Example

' VBScript
doc.SetCrossPosition 100, 185, 120
doc.RefreshView

// JScript
doc.SetCrossPosition(100, 185, 120);
doc.RefreshView();

# PerlScript
$doc->SetCrossPosition(100, 185, 120);
$doc->RefreshView();


SetVoxelValue Method

Description

Sets the intensity value of the specified voxel in an VMR data set.

Syntax

objDocument.SetVoxelValue(intX, intY, intZ, intIntensity)

Remarks

Valid only if objDocument is of type VMR. Intensity values in VMR files are stored in bytes. The values for intIntensity should be in the range of 10 - 245 since the colors indices below 10 and above 245 are reserved for the Windows system palette. The range of values normally interpreted as grey scale is from 10 to 225. To update the SAG, COR and TRA window, call RefreshView after execution of this method.
Note that the method is quite slow, i.e. it is not appropriate to use this method to loop across all data points. If you want to work efficiently with VMR files, you should follow the method described in the topics "A simple C++ program" and "An easy C++ program". The method has been developed mainly for internal use, i.e. to test the speed of data access using scripts. If in a later release a so called in-process COM server is provided (basically BrainVoyager as a DLL), the speed might be as fast as with using C++. If this turns out to be the case, we will provide further methods for setting and retrieving intensity and dimension values from VMR files.

Example

' VBScript
doc.SetVoxelValue 100, 185, 120, 200
doc.RefreshView

// JScript
doc.SetVoxelValue(100, 185, 120, 200);
doc.RefreshView();

# PerlScript
$doc->SetVoxelValue(100, 185, 120, 200);
$doc->RefreshView();


CreateVTC Method

Description

Transforms the time course data of an FMR project into a defined 3D space, typically Talairach space. The result of this transformation is a VTC file.

Syntax

objDocument.CreateVTC(strFileFMR, strFile2D3DTRF, strFileACPCTRFF, strFileCerebrumTAL, strFileVTC)

Remarks

Valid only if objDocument is of type VMR. FMR projects contain functional data in the originally recorded slices without any knowledge about where these slices are located with respect to a 3D reference frame, i.e. Talairach space. Transforming the functional data in Talairach space allows to analyze data from the same subject across different scanner sessions as well as to analyze data coming from different subjects. The resulting 4D VTC file consists of a series of 3D volumes aligned in stereotactic space. The file is saved to disk under the name strFileVTC entered as the last parameter. The first parameter strFileFMR specifies the FMR project whose functional data should be transformed in 3D space (the functional data actually resides in STC files which are referenced by the FMR project). The spatial transformation into Talairach space is controlled by three files which must exist prior to calling this method. The strFile2D3DTRF is responsible to align the stack of 2D slices at the correct position of a 3D VMR data set which is typically recorded in the same session as the functional data. If this is the case, the alignment can be done automatically based on the header information of the functional and anatomical data sets (assuming no or only minimal motion between the two data sets). The automatic alignment is currently only possible for Siemens IMA and DICOM files but should be available soon also for Philips and GE scanners (for further information, contact Brain Innovation). If the necessary header information is not available, the alignment has to be performed interactively within BrainVoyager. If the functional data has been registered with a 3D VMR data set, the further alignment information can be obtained from anatomical transformations. The 3D data set to which the functional data has been aligned can be rotated into the AC-PC plane as specified in chapter ?. If you have already once rotated a 3D data set of the same subject into the AC-PC plane, you can use BrainVoyager's automatic 3D-3D alignment routine to do this step. In both cases, a TRF file is produced which transforms the source 3D data set into the AC-PC plane. Since the functional data should undergo exactly the same transformation, you mus enter the obtained file as the strFileACPCTRFF file for the present method. The AC-PC plane space is not Talairach space. The final step is to apply a non-linear scaling operation to bring the data in stereotactic space. This is done for the 3D VMR data set in AC-PC space and results in a TAL file. In order to apply the same transformatio to the functional data, enter the obtained file as the strFileCerebrumTAL file.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DMPR.vmr")
doc.CreateVTC "cg_objects_sc.fmr", "cg_2D3D.trf", "cg_ACPC.trf", "cg.tal", "cg_objects_sc.vtc"

// JScript
doc = BrainVoyager.OpenDocument("cg_3DMPR.vmr");
doc.CreateVTC("cg_objects_sc.fmr", "cg_2D3D.trf", "cg_ACPC.trf", "cg.tal", "cg_objects_sc.vtc");

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_3DMPR.vmr");
$doc->CreateVTC("cg_objects_sc.fmr", "cg_2D3D.trf",
 "cg_ACPC.trf", "cg.tal", "cg_objects_sc.vtc");


LinkVTC Method

Description

Links a 3D time course file (VTC) to a 3D anatomical project (VMR).

Syntax

objDocument.LinkVTC(strVTCFileName, intLoadInMemory)

Remarks

Valid only if objDocument is of type VMR. The VMR and VTC file must be in the same space, normally Talairach space. After linking the VTC file, statistical tests can be performed across the data set and time courses and event-related averages can be shown. If the second parameter is set to "1", the VTC file is load into working memory, if it is set to "0", a file reference is created and used to access the file when necessary.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.LinkVTC "cg_objects_SC.vtc", 0
doc.TemporalSmoothingFD3D 3, 200

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.LinkVTC("cg_objects_SC.vtc", 0);
doc.TemporalSmoothingFD3D(3, 200);

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->LinkVTC("cg_objects_SC.vtc",
 0);
$doc->TemporalSmoothingFD3D(3,
 200);


TemporalSmoothingFD3D Method

Description

Filters in the frequency domain the time series of each voxel in a VTC file. Can be used to remove linear and non-linear drifts (high-pass) and/or to smooth the time series (low-pass).

Syntax

objDocument.TemporalSmoothingFD3D(intHighPass, intLowPass)

Remarks

Valid only if objDocument is of type VMR and if a VTC file has been linked. If the VTC file is referenced but not in memory, BrainVoyager will load the VTC file prior to running the temporal filter. The high- and low pass values are interpreted in cycles per lenght of the time course measured in volumes. A high pass value of "3" removes frequency components below 3 cycles within the time series. A low pass value equal to or greater than half the length of the time series will have no effect (Nyquist theorem), i.e. the low-pass filter is turned off. If the time series data, for example, contains 256 measurements, then a low pass value of 128 or greater lets everything pass, i.e. it has no effect and is turned off. In the GUI version, BrainVoyager sets the default value of the low pass to one-third of the lenght of the time series which proved to produce good results, i..e. it results in slightly smoothed time serieses. It is, however, recommended, not to use low pass filtering at all when preprocessing data sets from event-related designs. This is also the reason, why low pass filtering is turned off in the GUI version (3D Data Preprocessing dialog).
As in the GUI version, the temporal filter produces a new VTC file which is saved to disk automatically under a new file name. The new file name is based on the name of the linked VTC file prior to starting the filter and adds a substring describing the preprocessing performed. If, for example, the name of the linked VTC file was "cg_objects_SC_3DMC.vtc", the new name will be "cg_objects_SC_3DMC_FTS-3-126.vtc". The added substring "_FTS-3-126" describes that temporal smoothing (TS) has been performed in the frequency domain (FTS) using a high-pass filter of "3" and a low-pass filter of "126". All 3D preprocessing steps add such descriptive substrings which makes it easy to get the information about the sequence of steps which has been performed to produce a particular VTC file. If you do not want to use the implicit naming scheme, you might want to use the method TemporalSmoothingFD3DEx which allows to specify the source VTC file and the target VTC file.
Note also that the resulting VTC file is linked automatically to objDocument which allows to run a cascade of preprocessing commands without having to link intermediate files.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.LinkVTC "cg_objects_SC.vtc"
doc.TemporalSmoothingFD3D 3, 200

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.LinkVTC("cg_objects_SC.vtc");
doc.TemporalSmoothingFD3D(3, 200);

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->LinkVTC("cg_objects_SC.vtc");
$doc->TemporalSmoothingFD3D(3, 200);


TemporalSmoothingFD3DEx Method

Description

Filters the time series of each voxel in a VTC file. Can be used to remove linear and non-linear drifts (high-pass) and/or to smooth the time series (low-pass).

Syntax

objDocument.TemporalSmoothingFD3DEx(intHighPass, intLowPass, strVTCFileNameIn, strVTCFileNameOut)

Remarks

Valid only if objDocument is of type VMR. The method operates identical as the TemporalSmoothingFD3D version. In addition to the specification of the high-pass and low pass filter values, the source VTC file (strVTCFileNameIn) and a file name for the resulting VTC file (strVTCFileNameOut) must be specified. The source VTC file will be linked to objDocument and loaded into memory prior to temporal smoothing. The filtered file will be saved to disk under the specified "Out" file name. The resulting VTC file is linked automatically to objDocument.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.TemporalSmoothingFD3DEx 3, 200, "cg_objects_SC.vtc", "cg_objects_SC_FFTofTime.vtc"

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.TemporalSmoothingFD3DEx(3, 200, "cg_objects_SC.vtc", "cg_objects_SC_FFTofTime.vtc");

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->TemporalSmoothingFD3DEx(3, 200, "cg_objects_SC.vtc", "cg_objects_SC_FFTofTime.vtc");


SpatialSmoothingFD3D Method

Description

Spatially filters each 3D volume of a VTC file in the frequency domain.

Syntax

objDocument.SpatialSmoothingFD3D(intHighPass, intLowPass)

Remarks

Valid only if objDocument is of type VMR and if a VTC file has been linked. If the VTC file is referenced but not in memory, BrainVoyager will load the VTC file prior to running the spatial filter. The high- and low pass values are interpreted in cycles per spatial dimension measured in voxels. Since there are three spatial dimensions, the largest dimension is chosen as reference. Since VTC files normally are in Talairach space, the largest dimension is the YTAL-dimension corresponding to 174 mm or 174 voxels in a 1mm3 VMR data set (for details about the dimensions of VTC files, see chapter "BrainVoyager File Formats"). Since the functional data in VTC files consists typically of 3mm3 voxels, this results in a value of 174/3 = 58 when measured in voxels. A low pass value equal to or greater than half of this value (> 26) lets everyghing pass, it will have no effect (Nyquist theorem). In the GUI version (3D Data Preprocessing dialog), BrainVoyager sets the default value of the low pass filter to roughly half of this value (14) which produces a modest spatial smoothing roughly equal to spatial smoothing with a FWHM of 4mm in the spatial domain. In the GUI version the high-pass filter is turned off since it is not useful in the context of fMRI data analysis. To turn the high-pass filter off, specify "1" as the intHighPass value.
As in the GUI version, the spatial filter produces a new VTC file which is saved to disk automatically under a new file name. The new file name is based on the name of the linked VTC file prior to starting the filter and adds a substring describing the preprocessing performed. If, for example, the name of the linked VTC file was "cg_objects_SC_3DMC.vtc", the new name will be "cg_objects_SC_3DMC_FSS-1-14.vtc". The added substring "_FSS-1-14" describes that spatial smoothing (SS) has been performed in the frequency domain (FSS) using a high-pass filter of "1" and a low-pass filter of "14". All 3D preprocessing steps add such descriptive substrings which makes it easy to get the information about the sequence of steps which has been performed to produce a particular VTC file. If you do not want to use the implicit naming scheme, you might want to use the method SpatialSmoothingFD3DEx which allows to specify the source VTC file and the target VTC file.
Note also that the resulting VTC file is linked automatically to objDocument which allows to run a cascade of preprocessing commands without having to link intermediate files.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.LinkVTC "cg_objects_SC.vtc"
doc.TemporalSmoothingFD3D 3, 200 ' produces "cg_objects_SC_FTS-3-200.vtc"
doc.SpatialSmoothingFD3D 1, 14 ' produces "cg_objects_SC_FTS-3-200_FSS-1-14.vtc"

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.LinkVTC("cg_objects_SC.vtc");
doc.TemporalSmoothingFD3D(3, 200);
doc.SpatialSmoothingFD3D (1, 14);

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->LinkVTC("cg_objects_SC.vtc");
$doc->TemporalSmoothingFD3D(3, 200);
$doc->SpatialSmoothingFD3D (1, 14);


SpatialSmoothingFD3DEx Method

Description

Spatially filters each 3D volume of a VTC file in the frequency domain.

Syntax

objDocument.SpatialSmoothingFD3DEx(intHighPass, intLowPass, strVTCFileNameIn, strVTCFileNameOut)

Remarks

Valid only if objDocument is of type VMR. The method operates identical as the SpatialSmoothingFD3D version. In addition to the specification of the high-pass and low pass filter values, the source VTC file (strVTCFileNameIn) and a file name for the resulting VTC file (strVTCFileNameOut) must be specified. The source VTC file will be linked to objDocument and loaded into memory prior to spatial smoothing. The filtered file will be saved to disk under the specified "Out" file name. The resulting VTC file is linked automatically to objDocument.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.TemporalSmoothingFD3DEx 3, 200, "cg_objects.vtc", "cg_objects_FFTofTime.vtc"
doc.SpatialSmoothingFD3DEx 1, 14, "cg_objects_FFTofTime.vtc", "cg_objects_FFTOfTime_FFTOfSpace.vtc"

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.TemporalSmoothingFD3DEx(3, 200, "cg_objects.vtc", "cg_objects_FFTofTime.vtc");
doc.SpatialSmoothingFD3DEx( 1, 14, "cg_objects_FFTofTime.vtc", "cg_objects_FFTOfTime_FFTOfSpace.vtc");

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->TemporalSmoothingFD3DEx(3, 200, "cg_objects.vtc", "cg_objects_FFTofTime.vtc");
$doc->SpatialSmoothingFD3DEx( 1, 14, "cg_objects_FFTofTime.vtc", "cg_objects_FFTOfTime_FFTOfSpace.vtc");


MotionCorrection3D Method

Description

Detects and corrects rigid-body motion within a VTC file. The first volume serves as the reference to which all other 3D volumes are aligned.

Syntax

objDocument.MotionCorrection3D()

Remarks

Valid only if objDocument is of type VMR and if a VTC file has been linked. If the VTC file is referenced but not in memory, BrainVoyager will load the VTC file prior to running the spatial filter. This version uses the default settings as shown in the GUI version (3D Data Preprocessing dialog): trilinear interpolation to perform the rigid-body translation/rotation, a reduced data set (every second voxel in each dimension = one eighth of a full volume = 12.5%), a maximum of 100 iterations to fit a volume to the reference, creation of pre- and post AVI movie files and a standard log file. If you want to change any of these default settings, you can use the MotionCorrection3DEx version.
As in the GUI version, the spatial filter produces a new VTC file which is saved to disk automatically under a new file name. The new file name is based on the name of the linked VTC file prior to starting the filter and adds a substring describing the preprocessing performed. If, for example, the name of the linked VTC file was "cg_objects.vtc", the new name will be "cg_objects_3DMC.vtc". The added substring "_3DMC" describes that motion correction (MC) has been performed in 3D (3DMC), i.e. fitting 3 translation and 3 rotation parameters. All 3D preprocessing steps add such descriptive substrings which makes it easy to get the information about the sequence of steps which has been performed to produce a particular VTC file. If you do not want to use the implicit naming scheme, you might want to use the method MotionCorrection3DEx which allows to specify the source VTC file and the target VTC file.
Note also that the resulting VTC file is linked automatically to objDocument which allows to run a cascade of preprocessing commands without having to link intermediate files.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.LinkVTC "cg_objects_SC.vtc"
doc.MotionCorrection3D
doc.TemporalSmoothingFD3D 3, 200

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.LinkVTC("cg_objects_SC.vtc");
doc.MotionCorrection3D();
doc.TemporalSmoothingFD3D(3, 200);

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->LinkVTC("cg_objects_SC.vtc");
$doc->MotionCorrection3D();
$doc->TemporalSmoothingFD3D(3, 200);


MotionCorrection3DEx Method

Description

Detects and corrects rigid-body motion within a VTC file. The first volume serves as the reference to which all other 3D volumes are aligned.

Syntax

objDocument.MotionCorrection3DEx(strVTCFileNameIn, strVTCFileNameOut, intInterpolationMethod,
objDocument.MotionCorrection3DEx(boolReducedDataSet, intMaxIterations, boolMovies, boolExtendedLogFile)

Remarks

Valid only if objDocument is of type VMR and if a VTC file has been linked. If the VTC file is referenced but not in memory, BrainVoyager will load the VTC file prior to perform motion detection and correction. The method operates identical as the MotionCorrection3D version but allows to specify all available parameters. The source VTC file (strVTCFileNameIn) and a file name for the resulting VTC file (strVTCFileNameOut) must be specified. The source VTC file will be linked to objDocument and loaded into memory prior to spatial smoothing. The processed file will be saved to disk under the specified "Out" file name. The resulting VTC file is linked automatically to objDocument. Two interpolation methods are available, trilinear interpolation if intInterpolationMethodand is set to "0" and sinc interpolation if it is set to "1". The latter method is extremely slow and appears not to improve the result as compared to trilinear interpolation. For the alignment of a volume with the reference, all voxels can be used if boolReducedDataSet is set to "0" or only one eighth of the data if it is set to "1". Our tests have shown that using the reduced data set produces results indistinguishable from the one obtained when using the full data set. Each volume is individually fitted to the reference volume until an optimum has been achieved which does normally require 10-50 iterations. A good value for intMaxIterations proved to be "100". Set the boolMovies parameter to "1", if you want to let BrainVoyager create two AVI movie files, one before and one after motion correction. To better see possible motion, you should zoom the size of the movie when playing it. During motion correction, a standard log file is saved to disk (see below) which shows for each volume the number of iterations to obtain an optimal fit as well as the 3 translation and 3 rotation parameters. If you want to see information of the change in goodness of fit across the iterations of fitting a volume to the reference, you must set boolExtendedLogFile to "1".

The beginning of a standard motion correction log file:

InterpolationMethod: Trilinear
FullDataSet: No
MaxNrOfLevMarqIterations: 100
-> volume: 2 n_its: 3 dx: -0.0015 dy: 0.0017 dz: -0.0012 rx: -0.0005 ry: -0.0002 rz: 0.0002
-> volume: 3 n_its: 4 dx: -0.0044 dy: -0.0042 dz: -0.0022 rx: 0.0035 ry: -0.0022 rz: -0.0036
-> volume: 4 n_its: 11 dx: 0.0058 dy: -0.0165 dz: -0.0140 rx: 0.0053 ry: -0.0046 rz: -0.0165
-> volume: 5 n_its: 8 dx: 0.0053 dy: -0.0142 dz: -0.0104 rx: 0.0069 ry: -0.0060 rz: -0.0123
:

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.MotionCorrection3DEx "cg_objects_SC.vtc", "cg_objects_SC_MC.vtc", 0, 1, 100, 1, 1

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.MotionCorrection3DEx("cg_objects_SC.vtc", "cg_objects_SC_MC.vtc", 0, 1, 100, 1, 1);

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->MotionCorrection3DEx("cg_objects_SC.vtc", "cg_objects_SC_MC.vtc",
 0, 1, 100, 1, 1);


LoadGLM Method

Description

Loads a file containg the results of a multiple regression (GLM) analysis.

Syntax

objDocument.LoadGLM(strGLMFileName)

Remarks

Valid only if objDocument is of type FMR or VMR. If it is of type VMR, all three dimensions currently must be 256. The specified GLM file strGLMFileName is loaded into memory and can be shown superimposed on anatomical images by selecting predictors (i.e. using the SelectAllPredictors method) and then calling the ShowGLM method. During loading of the GLM, BrainVoyager also tries to find all VTC files referenced by the GLM file.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.SelectAllPredictors
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.SelectAllPredictors();
doc.ShowGLM();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->SelectAllPredictors();
$doc->ShowGLM();


DeselectAllPredictors Method

Description

Deselects all predictors of a multiple regression (GLM) result allowing to start a new predictor selection process.

Syntax

objDocument.DeselectAllPredictors()

Remarks

Valid only if objDocument is of type FMR or VMR. and a GLM has been run or loaded from disk. Deselect all predictors before defining a new statistical map using the SelectPredictorInSet1 and/or SelectPredictorInSet2 method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.SelectAllPredictors
doc.ShowGLM
doc.DeselectAllPredictors
doc.SelectPredictorInSet1 2
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.SelectAllPredictors();
doc.ShowGLM();
doc.DeselectAllPredictors();
doc.SelectPredictorInSet1(2);
doc.ShowGLM();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->SelectAllPredictors();
$doc->ShowGLM();
$doc->DeselectAllPredictors();
$doc->SelectPredictorInSet1(2);
$doc->ShowGLM();


SelectAllPredictors Method

Description

Selects all predictors of a multiple regression (GLM) result for display.

Syntax

objDocument.SelectAllPredictors()

Remarks

Valid only if objDocument is of type FMR or VMR. and a GLM has been run or loaded from disk. Selecting all predictors produces a statistical map which is identical to the overall multiple R value, i.e. the amount of variance explained by the full model. After selecting the predictors, call the ShowGLM method to visualize the resulting statistical map.
The generated statistical map is internally stored in a VMP (volume map) data set which you can save to disk (currently only interactively using the Analysis->Overlay maps->Save 3D Map... menu item).

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.SelectAllPredictors
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.SelectAllPredictors();
doc.ShowGLM();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->SelectAllPredictors();
$doc->ShowGLM();


SelectPredictorInSet1 Method

Description

Adds a predictor into set1 of two sets available for display of multiple regression (GLM) results.

Syntax

objDocument.SelectPredictorInSet1(intPredictorNumber)

Remarks

Valid only if objDocument is of type FMR or VMR. and a GLM has been run or loaded from disk. You can put more than one predictor into set1 by calling the method repeatedly. Set1 is the standard set for showing the explained variance of a subset of the full model, i.e. one or more predictors. If you want to show contrasts or the relative contribution of explained variance between two sets of predictors, you must use the SelectPredictorInSet2 method in addition to the present method. The set of selected predictors produces a statistical map which represents the amount of variance explained by the selected partial model. After selecting the predictors, call the ShowGLM method to visualize the resulting statistical map.
The generated statistical map is internally stored in a VMP (volume map) data set which you can save to disk (currently only interactively using the Analysis->Overlay maps->Save 3D Map... menu item).

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.SelectPredictorInSet1 1
doc.ShowGLM
doc.DeselectAllPredictors
doc.SelectPredictorInSet1 2
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.SelectPredictorInSet1(1);
doc.ShowGLM();
doc.DeselectAllPredictors();
doc.SelectPredictorInSet1(2);
doc.ShowGLM();

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->SelectPredictorInSet1(1);
$doc->ShowGLM();
$doc->DeselectAllPredictors();
$doc->SelectPredictorInSet1(2);
$doc->ShowGLM();


SelectPredictorInSet2 Method

Description

Adds a predictor into set2 of two sets available for display of multiple regression (GLM) results.

Syntax

objDocument.SelectPredictorInSet2(intPredictorNumber)

Remarks

Valid only if objDocument is of type FMR or VMR. and a GLM has been run or loaded from disk. You can put more than one predictor into set2 by calling the method repeatedly. Set2 can only be used in addition to set1 in order to show contrasts between two sets of predictors or to show the relative contribution of the combined variance explained by the two sets of predictors. After selecting predictors, call the ShowGLM method to visualize the resulting statistical map.
The generated statistical map is internally stored in a VMP (volume map) data set which you can save to disk (currently only interactively using the Analysis->Overlay maps->Save 3D Map... menu item).

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.SelectPredictorInSet1 1
doc.ShowGLM
doc.DeselectAllPredictors
doc.SelectPredictorInSet1 2
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.SelectPredictorInSet1(1);
doc.ShowGLM();
doc.DeselectAllPredictors();
doc.SelectPredictorInSet1(2);
doc.ShowGLM();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->SelectPredictorInSet1(1);
$doc->ShowGLM();
$doc->DeselectAllPredictors();
$doc->SelectPredictorInSet1(2);
$doc->ShowGLM();


EnableTwoSetPredictorContrast Method

Description

Sets the status of a flag to show the contrast between two sets of predictors in a multiple regression (GLM).

Syntax

objDocument.EnableTwoSetPredictorContrast()

Remarks

Valid only if objDocument is of type FMR or VMR. and a GLM has been run or loaded from disk. The flag set internally by this method has only an effect if predictors are selected into both set1 and set2 using the SelectPredictorInSet1 and SelectPredictorInSet2 method. In this case, the contrast between the two sets of predictors is computed, i.e. how much variance is explained by predictor set 1 over and above the variance explained by predictor set 2.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.EnableTwoSetPredictorContrast
doc.DeselectAllPredictors
doc.SelectPredictorInSet1 1
doc.SelectPredictorInSet2 2
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.EnableTwoSetPredictorContrast();
doc.DeselectAllPredictors();
doc.SelectPredictorInSet1(1);
doc.SelectPredictorInSet2(2);
doc.ShowGLM();

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->EnableTwoSetPredictorContrast();
$doc->DeselectAllPredictors();
$doc->SelectPredictorInSet1(1);
$doc->SelectPredictorInSet2(2);
$doc->ShowGLM();


EnableTwoSetPredictorColours Method

Description

A flag is set to show the relative contribution of the combined variance explained by two sets of predictors in a multiple regression (GLM).

Syntax

objDocument.EnableTwoSetPredictorColours()

Remarks

Valid only if objDocument is of type FMR or VMR. and a GLM has been run or loaded from disk. The flag set internally by this method has only an effect if predictors are selected into both set1 and set2 using the SelectPredictorInSet1 and SelectPredictorInSet2 method. In this case, the relative contribution of the combined explained variance in the time series of each voxel is visualized.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.EnableTwoSetPredictorColours
doc.DeselectAllPredictors
doc.SelectPredictorInSet1 1
doc.SelectPredictorInSet2 2
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.EnableTwoSetPredictorColours();
doc.DeselectAllPredictors();
doc.SelectPredictorInSet1(1);
doc.SelectPredictorInSet2(2);
doc.ShowGLM();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->EnableTwoSetPredictorColours();
$doc->DeselectAllPredictors();
$doc->SelectPredictorInSet1(1);
$doc->SelectPredictorInSet2(2);
$doc->ShowGLM();


ShowGLM Method

Description

Shows statistical map based on selected predictors of a GLM superimposed on (anatomical) reference images.

Syntax

objDocument.ShowGLM()

Remarks

Valid only if objDocument is of type FMR or VMR. After performing or loading a GLM file, predictors can be selected and then shown as statistical maps on reference images of an FMR or VMR project. To select predictors, use one of the following methods: SelectAllPredictors, SelectPredictorInSet1, SelectPredictorInSet2. You can also deselect all currently selected predictors by using the DeselectAllPredictors method. To show a contrast between two predictor sets, select the desired predictors in set 1 and set 2 and make sure to call DisableTwoSetPredictorColours prior to the ShowGLM method. If you want to visualize the relative contribution of explained variance between two predictor sets, call EnableTwoSetPredictorColours prior to the ShowGLM method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg_3DT1_TAL.vmr")
doc.LoadGLM "cg_objects.glm"
doc.SelectAllPredictors
doc.ShowGLM

// JScript
doc = BrainVoyager.OpenDocument("cg_objects.fmr");
doc.LoadGLM("cg_objects.glm");
doc.SelectAllPredictors();
doc.ShowGLM();

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg_objects.fmr");
$doc->LoadGLM("cg_objects.glm");
$doc->SelectAllPredictors();
$doc->ShowGLM();


ShowTimeCourseOfVoxel Method

Description

Shows a time course from a Region-Of-Interest of the currently linked VTC file.

Syntax

objDocument.ShowTimeCourseOfVoxel(intX, intY, intZ, strTimeCourseWindowName)

Remarks

Valid only if objDocument is of type VMR. A VTC file must be linked to the VMR. The voxel is specified by system coordinates intX, intY and intZ. The name for the window (strTimeCourseWindowName) can be used to move the window to a new position using the MoveTimeCoursePlot method and to close the window using the CloseTimeCoursePlot method.
The function behaves exactly like clicking with the right mouse button at a position in the VMR viewing window. If no statistical map (VMP) has been computed, a ROI Time Course window appears showing the time course of the respective voxel. If a map has been computed, the ROI Time Course window shows the time course of the Region-Of-Interest to which the selected voxel belongs. No window will appear in the latter case if the specified voxel does not hit a "hot" voxel. You can control this behavior by using the ShowTimeCourseOfVoxelEx method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg2_TAL.vmr")
doc.LinkVTC "CG_OBJECTS_SC.vtc", 0
doc.ShowTimeCourseOfVoxel 100, 180, 145, "TC window"

// JScript
doc = BrainVoyager.OpenDocument("cg2_TAL.vmr");
doc.LinkVTC("CG_OBJECTS_SC.vtc", 0);
doc.ShowTimeCourseOfVoxel(100, 180, 145, "TC window");

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg2_TAL.vmr");
$doc->LinkVTC("CG_OBJECTS_SC.vtc",
 0);
$doc->ShowTimeCourseOfVoxel(100, 180, 145, "TC window");


ShowTimeCourseOfVoxelEx Method

Description

Shows a time course from a Region-Of-Interest of the currently linked VTC file.

Syntax

objDocument.ShowTimeCourseOfVoxelEx(intX, intY, intZ, strTCWindowName, boolSingleVoxel, intXPos, intYPos, intWidth, intHeight, boolNewTCWindow, boolAddToWindow)

Remarks

Valid only if objDocument is of type VMR. A VTC file must be linked to the VMR. In contrast to the ShowTimeCourseOfVoxel version, this function allows to specify whether the invoked time course window shows the time course of a single voxel (boolSingleVoxel = 1) or of a functional cluster (boolSingleVoxel = 0). In the latter case, a statistical map has to be present and the specified voxel must hit a "hot" (significant) voxel.
This version allows to specify the position of the invoked ROI Time Course window on screen as well as its width and height (see MoveTimeCoursePlot method). The position is specified with respect to the left corner (intXPos = 0, intYPos = 0) of the corresponding VMR window.
If boolNewTCWindow is set to "1" (or "True"), a new ROI Time Course window is invoked for the specified time course. If this parameter is set to "0" (or "False"), a new window is only shown if no ROI Time Course window has been invoked previously for the corresponding VMR document. If there is already a ROI Time Course window, the last parameter specifies whether the time course shown in the existing window is replaced (boolAddToWindow = 0) by the new one or whether it is added to the existing window (boolAddToWindow = 1).

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg2_TAL.vmr")
doc.LinkVTC "CG_OBJECTS_SC.vtc", 0
doc.ShowTimeCourseOfVoxelEx 100, 180, 145, "TC window", False, 523, 0, 500, 181, True, False

// JScript
doc = BrainVoyager.OpenDocument("cg2_TAL.vmr");
doc.LinkVTC("CG_OBJECTS_SC.vtc", 0);
doc.ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window", false, 523, 0, 500, 181, true, false);

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg2_TAL.vmr");
$doc->LinkVTC("CG_OBJECTS_SC.vtc",
 0);
$doc->ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window", 0,
 523, 0, 500, 181, 1, 0);


MoveTimeCoursePlot Method

Description

Moves a previously created time course window to a new screen position and changes its width and height.

Syntax

objDocument.MoveTimeCoursePlot(strTCWindowName, intXPos, intYPos, intWidth, intHeight)

Remarks

Valid only if objDocument is of type VMR. The window name (strTCWindowName) refers to the name specified when the ROI Time Course window has been created using the ShowTimeCourseOfVoxel or ShowTimeCourseOfVoxelEx method. The referred window is moved to a new position and gets width intWidth and height intHeight. The position is specified with respect to the left corner (intXPos = 0, intYPos = 0) of the corresponding VMR window.

Example

' VBScript
doc.ShowTimeCourseOfVoxelEx 100, 180, 145, "TC window", False, 523, 0, 500, 181, True, False
doc.MoveTimeCoursePlot "TC window", 523, 181, 500, 181
doc.CloseTimeCoursePlot "TC window"

// JScript
doc.ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window", false, 523, 0, 500, 181, true, false);
doc.MoveTimeCoursePlot("TC window", 523, 181, 500, 181);
doc.CloseTimeCoursePlot("TC window");

# PerlScript
$doc->ShowTimeCourseOfVoxelEx(100,
 180, 145, "TC window", 0, 523, 0, 500, 181, 1, 0);
$doc->MoveTimeCoursePlot("TC
 window", 523,
 181, 500, 181);
$doc->CloseTimeCoursePlot("TC
 window");


CloseTimeCoursePlot Method

Description

Closes a previously created time course window.

Syntax

objDocument.CloseTimeCoursePlot(strTCWindowName)

Remarks

Valid only if objDocument is of type VMR. The window name (strTCWindowName) refers to the name specified when the ROI Time Course window has been created using the ShowTimeCourseOfVoxel or ShowTimeCourseOfVoxelEx method.

Example

' VBScript
doc.ShowTimeCourseOfVoxelEx 100, 180, 145, "TC window", False, 523, 0, 500, 181, True, False
doc.MoveTimeCoursePlot "TC window", 523, 181, 500, 181
doc.CloseTimeCoursePlot "TC window"

// JScript
doc.ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window", false, 523, 0, 500, 181, true, false);
doc.MoveTimeCoursePlot("TC window", 523, 181, 500, 181);
doc.CloseTimeCoursePlot("TC window");

# PerlScript
$doc->ShowTimeCourseOfVoxelEx(100,
 180, 145, "TC window", 0, 523, 0, 500, 181, 1, 0);
$doc->MoveTimeCoursePlot("TC
 window", 523,
 181, 500, 181);
$doc->CloseTimeCoursePlot("TC
 window");


CloseAllTimeCoursePlots Method

Description

Closes all previously created time course windows.

Syntax

objDocument.CloseAllTimeCoursePlots()

Remarks

Valid only if objDocument is of type VMR. All ROI Time Course windows previously created with the ShowTimeCourseOfVoxel or ShowTimeCourseOfVoxelEx method are closed at once.

Example

' VBScript
doc.ShowTimeCourseOfVoxelEx 100, 180, 145, "TC window 1", False, 523,   0, 500, 181, True, False
doc.ShowTimeCourseOfVoxelEx 100, 180, 145, "TC window 2", False, 523, 181, 500, 181, True, False
doc.CloseAllTimeCoursePlots

// JScript
doc.ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window 1", false, 523,   0, 500, 181, true, false);
doc.ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window 2", false, 523, 181, 500, 181, true, false);
doc.CloseAllTimeCoursePlots();

# PerlScript
$doc->ShowTimeCourseOfVoxelEx(100,
 180, 145, "TC window 1", 0, 523,   0,
 500, 181, 1, 0);
$doc->ShowTimeCourseOfVoxelEx(100,
 180, 145, "TC window 2", 0, 523, 181, 500, 181, 1, 0);
$doc->CloseAllTimeCoursePlots();


ShowEventRelatedAverage Method

Description

Averages events as specified in an AVG file and shows the event-related averaging results in a window.

Syntax

objDocument.ShowEventRelatedAverage(strTimeCourseWindowName, strAVGFileName)

Remarks

Valid only if objDocument is of type VMR or FMR. A ROI Time Course window must be created with the ShowTimeCourseOfVoxel or ShowTimeCourseOfVoxelEx method before the ShowEventRelatedAverage method can be used. The window name (strTimeCourseWindowName) refers to the name specified when the ROI Time Course window has been created. The event-related averaging runs across time courses at the ROI of the corresponding time course window. The position and size of the created window can be controlled by using the ShowEventRelatedAverageEx method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("cg2_TAL.vmr")
doc.LinkVTC "CG_OBJECTS_SC.vtc", 0
doc.ShowTimeCourseOfVoxel 100, 180, 145, "TC window"
doc.ShowEventRelatedAverage "TC window", "CG_OBJECTS_SECS.avg"

// JScript
doc = BrainVoyager.OpenDocument("cg2_TAL.vmr");
doc.LinkVTC("CG_OBJECTS_SC.vtc", 0);
doc.ShowTimeCourseOfVoxel(100, 180, 145, "TC window");
doc.ShowEventRelatedAverage("TC window", "CG_OBJECTS_SECS.avg");

# PerlScript
$doc = $BrainVoyager->OpenDocument("cg2_TAL.vmr");
$doc->LinkVTC("CG_OBJECTS_SC.vtc",
 0);
$doc->ShowTimeCourseOfVoxel(100,
 180, 145, "TC window");
$doc->ShowEventRelatedAverage("TC
 window", "CG_OBJECTS_SECS.avg");


ShowEventRelatedAverageEx Method

Description

Averages events as specified in an AVG file and shows the event-related averaging results in a window.

Syntax

objDocument.ShowEventRelatedAverageEx(strTimeCourseWindowName, strAVGFileName, intXPos, intYPos, intWidth, intHeight)

Remarks

Valid only if objDocument is of type VMR or FMR. A ROI Time Course window must be created with the ShowTimeCourseOfVoxel or ShowTimeCourseOfVoxelEx method before the ShowEventRelatedAverageEx method can be used. The window name (strTimeCourseWindowName) refers to the name specified when the ROI Time Course window has been created. The event-related averaging runs across time courses at the ROI of the corresponding time course window. The position and size of the created window can be controlled by specifying values for the intXPos, intYPos, intWidth and intHeight parameters. The position is specified with respect to the left corner (intXPos = 0, intYPos = 0) of the corresponding ROI Time Course (RTC) window.
If a AVG window has been invoked and if a new ROI (voxel) for the corresponding RTC window is specified, the event-related averaging will be performed for the new ROI and the AVG window will be updated automatically.

Example

' VBScript
doc.ShowTimeCourseOfVoxelEx 141, 197, 135, "TC window", False, 523, 0, 500, 200, True, False
doc.ShowEventRelatedAverageEx "TC window", "CG_OBJECTS_SECS.avg", 0, 0, 500, 542
BrainVoyager.Sleep 3000  ' Wait 3 secs, then specify new ROI which will also update the AVG window
doc.ShowTimeCourseOfVoxelEx 118, 200, 142, "TC window", False, 523, 0, 500, 200, FALSE, False

// JScript
doc.ShowTimeCourseOfVoxelEx(141, 197, 135, "TC window", false, 523, 0, 500, 200, true, false);
doc.ShowEventRelatedAverageEx("TC window", "CG_OBJECTS_SECS.avg", 0, 0, 500, 542);
BrainVoyager.Sleep(3000);
doc.ShowTimeCourseOfVoxelEx(118, 200, 142, "TC window", false, 523, 0, 500, 200, true, false);

# PerlScript
$doc->ShowTimeCourseOfVoxelEx(141,
 197, 135, "TC window", 0, 523, 0, 500,2001, 1, 0);
$doc->ShowEventRelatedAverageEx("TC
 window", "CG_OBJECTS_SECS.avg",
 0, 0, 500, 542);
$BrainVoyager->Sleep(3000);
$doc->ShowTimeCourseOfVoxelEx(118,
 200, 142, "TC window", 0, 523, 0, 500, 200, 1, 0);


MoveEventRelatedAveragePlot Method

Description

Moves a previously created event-related averaging window to a new screen position and changes its width and height.

Syntax

objDocument.MoveEventRelatedAveragePlot(strTCWindowName, intXPos, intYPos, intWidth, intHeight)

Remarks

Valid only if objDocument is of type VMR. The window name (strTCWindowName) refers to the name specified when the ROI Time Course (RTC) window to which the event-related averaging (AVG) window is linked has been created. The referred AVG window is moved to a new position and gets width intWidth and height intHeight. The position is specified with respect to the left corner (intXPos = 0, intYPos = 0) of the corresponding RTC window. The AVG window is closed when the linked RTC window is closed with the CloseTimeCoursePlot method..

Example

' VBScript
doc.ShowTimeCourseOfVoxelEx 100, 180, 145, "TC window", False, 523, 0, 500, 181, True, False
doc.ShowEventRelatedAverageEx "TC window", "CG_OBJECTS_SECS.avg", 0, 0, 500, 542
doc.MoveEventRelatedAveragePlot "TC window", 50, 50, 500, 542
doc.CloseTimeCoursePlot "TC window"

// JScript
doc.ShowTimeCourseOfVoxelEx(100, 180, 145, "TC window", false, 523, 0, 500, 181, true, false);
doc.ShowEventRelatedAverageEx("TC window", "CG_OBJECTS_SECS.avg", 0, 0, 500, 542);
doc.MoveEventRelatedAveragePlot("TC window", 50, 50, 500, 542);
doc.CloseTimeCoursePlot("TC window");

# PerlScript
$doc->ShowTimeCourseOfVoxelEx(100,
 180, 145, "TC window", 0, 523, 0, 500, 181, 1, 0);
$doc->ShowEventRelatedAverageEx("TC
 window", "CG_OBJECTS_SECS.avg",
 0, 0, 500, 542);
$doc->MoveEventRelatedAveragePlot("TC
 window", 50,
 50, 500, 542);
$doc->CloseTimeCoursePlot("TC
 window");


MapThreshold Property

Description

Gets or sets the statistical threshold used in subsequent commands visualizing statistical maps.

Syntax

objDocument.MapThreshold()

Remarks

Valid only if objDocument is of type FMR or VMR. The method sets or retrieves the value used by a document to threshold statistical maps.

Example

' VBScript
doc.LoadGLM "cg_objects.glm"
doc.SelectAllPredictors
doc.ShowGLM
For thresh = 0.2 To 0.6 Step 0.05
  doc.MapThreshold = thresh
  doc.RefreshView
Next

// JScript
doc.LoadGLM("cg_objects.glm");
doc.SelectAllPredictors();
doc.ShowGLM();
for(thresh = 0.2; thresh<=0.6; thresh += 0.05)
{
  doc.MapThreshold = thresh;
  doc.RefreshView();
}

#
 PerlScript
$doc->LoadGLM("cg_objects.glm");
$doc->SelectAllPredictors();
$doc->ShowGLM();
for($thresh = 0.2; $thresh<=0.6; $thresh += 0.05)
{
$doc->MapThreshold =
 thresh;
$doc->RefreshView();
}


MapClusterSize Property

Description

Gets or sets the statistical threshold used in subsequent commands visualizing statistical maps.

Syntax

objDocument.MapClusterSize()

Remarks

Valid only if objDocument is of type FMR or VMR. The property sets or retrieves the cluster size used by objDocument to filter out all activated clusters which do not reach the statistical threshold when a map is visualized, i.e. by calling ShowGLM. The statistical threshold can be modified or inspected using the MapThreshold property.

Example

' VBScript
doc.LoadGLM "cg_objects.glm"
doc.SelectAllPredictors
doc.ShowGLM
doc.MapClusterSize = 200
For thresh = 0.2 To 0.6 Step 0.05
  doc.MapThreshold = thresh
  doc.RefreshView
Next

// JScript
doc.LoadGLM("cg_objects.glm");
doc.SelectAllPredictors();
doc.ShowGLM();
doc.MapClusterSize = 200;
for(thresh = 0.2; thresh<=0.6; thresh += 0.05)
{
  doc.MapThreshold = thresh;
  doc.RefreshView();
}

# PerlScript
$doc->LoadGLM("cg_objects.glm");
$doc->SelectAllPredictors();
$doc->ShowGLM();
$doc->MapClusterSize = 200;
for($thresh = 0.2; $thresh<=0.6; $thresh += 0.05)
{
$doc->MapThreshold =
 thresh;
$doc->RefreshView();
}


SwitchToSurfaceModule Method

Description

Activates the Surface Module window.

Syntax

objDocument.SwitchToSurfaceModule()

Remarks

Valid only if objDocument is of type VMR. Each VMR project can call exactly one Surface Module window. If the Surface Module window has not been activated before, the window is created showing the 3D string "BrainVoyager". If the Surface Module window has been created, you can access surface-related document methods like LoadMesh.

Example

' VBScript
doc.SwitchToSurfaceModule

// JScript
doc.SwitchToSurfaceModule();

# PerlScript
$doc->SwitchToSurfaceModule();


LoadMesh Method

Description

Loads a surface mesh file. Surface mesh file names have extension ".srf".

Syntax

objDocument.LoadMesh(strMeshFileName)

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. The loaded mesh is not shown automatically in the Surface Module window. To update it, call the RefreshSurfaceWindow method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.SwitchToSurfaceModule
doc.LoadMesh "subject.srf"
doc.RefreshSurfaceWindow

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.SwitchToSurfaceModule();
doc.LoadMesh("subject.srf");
doc.RefreshSurfaceWindow();

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->SwitchToSurfaceModule();
$doc->LoadMesh("subject.srf");
$doc->RefreshSurfaceWindow();


SaveMesh Method

Description

Saves a surface mesh file to disk. Surface mesh file names have extension ".srf".

Syntax

objDocument.SaveMesh(strMeshFileName)

Remarks

Valid only if objDocument is of type VMR and at least one mesh is present in the Surface Module window. If multiple meshes exist, the current mesh is saved. The last loaded or created mesh automatically gets the "current" status. The current mesh can be specified interactively by using the "Select Mesh icon"; a script command for this purpose will be added in a later release.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.SwitchToSurfaceModule
doc.RefreshSurfaceWindow
doc.CreateSphereMesh
doc.MorphMesh 500, 10, 0.05, 0.3, 50, False
doc.SaveMesh "head.srf"

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.SwitchToSurfaceModule();
doc.RefreshSurfaceWindow();
doc.CreateSphereMesh();
doc.MorphMesh(500,
 10, 0.05, 0.3, 50, false)
doc.SaveMesh("head.srf");

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->SwitchToSurfaceModule();
$doc->RefreshSurfaceWindow();
$doc->CreateSphereMesh();
$doc->MorphMesh(500,
 10, 0.05, 0.3, 50, 0);
$doc->SaveMesh("head.srf");


AddMesh Method

Description

Reads a surface mesh file and adds it to the Surface Module window of the referenced VMR document. This method allows to compose scenes of surface meshes, i.e. loading the mesh file of the reconstructed head of a subject and adding the reconstructed meshes of the cortical hemispheres of that subject.

Syntax

objDocument.AddMesh(strMeshFileName)

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. The loaded mesh is not shown automatically in the Surface Module window. To update it, call the RefreshSurfaceWindow method.

Example

' VBScript
doc.LoadMesh "subject_head.srf")
doc.AddMesh "subject_LH.srf"
doc.AddMesh "subject_RH.srf"
doc.RefreshSurfaceWindow

// JScript
doc.LoadMesh("subject_head.srf");
doc.AddMesh("subject_LH.srf");
doc.AddMesh("subject_RH.srf");
doc.RefreshSurfaceWindow();

#
 PerlScript
$doc->LoadMesh("subject_head.srf");
$doc->AddMesh("subject_LH.srf");
$doc->AddMesh("subject_RH.srf");
$doc->RefreshSurfaceWindow();


CreateSphereMesh Method

Description

Creates a new spherical mesh which can be used to reconstruct the skin of a subject's head by iterative morphing.

Syntax

objDocument.CreateSphereMesh()

Remarks

Valid only if objDocument is of type VMR and the Surface Module window.has been invoked using the SwitchToSurfaceModule method. Any meshes in the surface module are deleted when this function is executed. The created sphere possesses a standard mesh resolution (20480 vertices), a radius of 140 mm and it is centred at the midpoint of the underlying VMR data set.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.SwitchToSurfaceModule
doc.RefreshSurfaceWindow
doc.CreateSphereMesh
doc.MorphMesh 500, 10, 0.05, 0.3, 50, False
doc.SaveMesh "head.srf"

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.SwitchToSurfaceModule();
doc.RefreshSurfaceWindow();
doc.CreateSphereMesh
doc.MorphMesh(500,
 10, 0.05, 0.3, 50, false)
doc.SaveMesh("head.srf");

# PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->SwitchToSurfaceModule();
$doc->RefreshSurfaceWindow();
$doc->CreateSphereMesh
$doc->MorphMesh(500,
 10, 0.05, 0.3, 50, 0);
$doc->SaveMesh("head.srf");


ReconstructBoundary Method

Description

Creates a new triangle mesh by reconstructing the boundary of a segmented data set. A typical application is the reconstruction of the cortical sheet from a segmented hemisphere.

Syntax

objDocument.ReconstructBoundary()

Remarks

Valid only if objDocument is of type VMR and the Surface Module window.has been invoked using the SwitchToSurfaceModule method. Any meshes in the surface module are deleted when this function is executed. The new mesh is created by tesselation of the outer boundary of a segmented VMR data set. The initial surface representation shows the voxelated nature of the underlying segmented data set. To remove this, the triangle mesh can be smoothed by using the MorphMesh method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("NN_TAL_WM_LH_BL2.vmr")
doc.SwitchToSurfaceModule
doc.RefreshSurfaceWindow
doc.ReconstructBoundary
doc.MorphMesh 50, 10, 0.3, 0.0, 50, False  ' smooth triangle mesh
doc.SaveMesh "NN_LH_RECOSM.srf"

// JScript
doc = BrainVoyager.OpenDocument("NN_TAL_WM_LH_BL2.vmr");
doc.SwitchToSurfaceModule();
doc.RefreshSurfaceWindow();
doc.ReconstructBoundary();
doc.MorphMesh(50, 10, 0.3, 0.0,
 50, false)
doc.SaveMesh("NN_LH_RECOSM.srf");

# PerlScript
$doc = $BrainVoyager->OpenDocument("NN_TAL_WM_LH_BL2.vmr");
$doc->SwitchToSurfaceModule();
$doc->RefreshSurfaceWindow();
$doc->ReconstructBoundary();
$doc->MorphMesh(50,
 10, 0.3, 0.0, 50, 0);
$doc->SaveMesh("NN_LH_RECOSM.srf");


MorphMesh Method

Description

Morphs a created or loaded mesh; typical applications are surface smoothing or skin reconstruction..

Syntax

objDocument.MorphMesh(intNrOfIterations, intUpdateScreen, floatSmoothFactor, floatFindSurfFactor, intFindIntensity, boolSmoothingMode)

Remarks

Valid only if objDocument is of type VMR and and at least one mesh is present in the Surface Module window. If multiple meshes exist, morphing is apllied to the current mesh. Individual morphing steps producing small changes can be repeated as specified by the intNrOfIterations parameter. The screen is not necessarily updated after each morphing step but after several steps as specified by the intUpdateScreen parameter. The changes performed by a single morphing step are controlled by several forces. The smoothing force is specified by the floatSmoothFactor which typically has values between 0.05 and 0.8. Another force is the surface finding force which is specified by the intFindSurfFactor parameter which typically has values between 0.0 and 0.5. The surface finding force lets a vertex move in the direction of its normal vector until it finds an intensity value in the underlying VMR data set as specified by the intFindIntensity parameter. The surface finding force can be turned off by spcifiying a intFindSurfFactor of '0.0' or by setting the boolSmoothingMode parameter to 'True'..

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("NN_TAL_WM_LH_BL2.vmr")
doc.SwitchToSurfaceModule
doc.RefreshSurfaceWindow
doc.ReconstructBoundary
' Smooth mesh: Perform 50 iterations, update screen every 10th step
doc.MorphMesh 50, 10, 0.3, 0.0, 50, True
doc.SaveMesh "NN_LH_RECOSM.srf"

// JScript
doc = BrainVoyager.OpenDocument("NN_TAL_WM_LH_BL2.vmr");
doc.SwitchToSurfaceModule();
doc.RefreshSurfaceWindow();
doc.ReconstructBoundary();
doc.MorphMesh(50, 10, 0.3, 0.0,
 50, true)
doc.SaveMesh("NN_LH_RECOSM.srf");

# PerlScript
$doc = $BrainVoyager->OpenDocument("NN_TAL_WM_LH_BL2.vmr");
$doc->SwitchToSurfaceModule();
$doc->RefreshSurfaceWindow();
$doc->ReconstructBoundary();
$doc->MorphMesh(50,
 10, 0.3, 0.0, 50, 1);
$doc->SaveMesh("NN_LH_RECOSM.srf");


InflateMesh Method

Description

Unfolds the sulci of a folded mesh representing the cortical sheet of a hemisphere. During the inflation process, the hemisphere grows because the surface area is kept constant with respect to a linked reference mesh.

Syntax

objDocument.InflateMesh(intNrOfIterations, intUpdateScreen, floatSmoothFactor, strReferenceMesh)

Remarks

Valid only if objDocument is of type VMR and and at least one mesh is present in the Surface Module window. If multiple meshes exist, the inflation process is apllied to the current mesh. This is a specialized version of mesh morphing using only the smoothing force. Individual morphing steps producing small changes can be repeated as specified by the intNrOfIterations parameter. The screen is not necessarily updated after each morphing step but after several steps as specified by the intUpdateScreen parameter. The smoothing force is specified by the floatSmoothFactor which typically has values between 0.3 and 0.8 for inflation. In the strReferenceMesh parameter, a mesh is specified which is used for the computation of the reference surface area. This mesh is typically the same mesh used at the start of the inflation process.

Example

' VBScript
doc.ReconstructBoundary
doc.MorphMesh 50, 10, 0.3, 0.0, 50, True  ' smooth triangle mesh
doc.SaveMesh "NN_LH_RECOSM.srf"
' Perform 500 iterations, update screen every 30th step, smooth force = 0.8
doc.InflateMesh 500, 30, 0.8, "NN_LH_RECOSM.srf"
doc.SaveMesh "NN_LH_INFL.srf"

// JScript
doc.ReconstructBoundary();
doc.MorphMesh(50, 10, 0.3, 0.0, 50, true)
doc.SaveMesh("NN_LH_RECOSM.srf");
doc.InflateMesh(500, 30, 0.8, "NN_LH_RECOSM.srf")
doc.SaveMesh("NN_LH_INFL.srf");

# PerlScript
$doc->ReconstructBoundary();
$doc->MorphMesh(50,
 10, 0.3, 0.0, 50, 1);
$doc->SaveMesh("NN_LH_RECOSM.srf");
$doc->MorphMesh(500,
 30, 0.8, "NN_LH_RECOSM.srf");
$doc->SaveMesh("NN_LH_INFL.srf");


LoadViewingSettings Method

Description

Restores surface module settings about the viewing position, angles, lightning conditions previously stored to disk.

Syntax

objDocument.LoadViewingSettings(strViewpointFileName)

Remarks

Valid only if objDocument is of type VMR and and if the Surface Module window for this VMR project has been created. Viewpoint files possess the extension "vwp". To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
Set doc = BrainVoyager.OpenDocument("subject.vmr")
doc.SwitchToSurfaceModule
doc.LoadMesh "subject.srf"
doc.LoadViewingSettings "NiceLights.vwp"
doc.RefreshSurfaceWindow

// JScript
doc = BrainVoyager.OpenDocument("subject.vmr");
doc.SwitchToSurfaceModule();
doc.LoadMesh("subject.srf");
doc.LoadViewingSettings("NiceLights.vwp");
doc.RefreshSurfaceWindow();

#
 PerlScript
$doc = $BrainVoyager->OpenDocument("subject.vmr");
$doc->SwitchToSurfaceModule();
$doc->LoadMesh("subject.srf");
$doc->LoadViewingSettings("NiceLights.vwp");
$doc->RefreshSurfaceWindow();


RefreshSurfaceWindow Method

Description

Repaints the Surface Module window which is a window showing one or more surface mesh files.

Syntax

objDocument.RefreshSurfaceWindow()

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. Most surface-related document methods are defined to operate without updating the Surface Module window. Use this method to refresh this window to render the effect of an operation visible.

Example

' VBScript
doc.RefreshSurfaceWindow

// JScript
doc.RefreshSurfaceWindow();

# PerlScript
$doc->RefreshSurfaceWindow();


SetViewpointPosition Method

Description

Sets the 3D position of the viewpoint from which the scene in the Surface Module window is "seen".

Syntax

objDocument.SetViewpointPosition(intX, intY, intZ)

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. This method sets only the position of the viewpoint; use the method SetViewpointAngles to also set the viewing direction. To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
doc.SetViewpointPosition 0, 30, -550
doc.RefreshSurfaceWindow

// JScript
doc.SetViewpointPosition(0, 30, -550);
doc.RefreshSurfaceWindow();

# PerlScript
$doc->SetViewpointPosition(0, 30, -550);
$doc->RefreshSurfaceWindow();


SetViewpointAngles Method

Description

Sets the viewing direction from which the scene in the Surface Module window is "seen".

Syntax

objDocument.SetViewpointAngles(intAngleX, intAngleY, intAngleZ)

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. This method sets the angles [in degrees] of the viewpoint with respect to the three coordinate axes; use the method SetViewpointPosition to also set the position of the viewpoint. To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
doc.SetViewpointAngles 180, -75, -25
doc.RefreshSurfaceWindow

// JScript
doc.SetViewpointAngles(180, -75, -25);
doc.RefreshSurfaceWindow();

# PerlScript
$doc->SetViewpointAngles(180, -75, -25);
$doc->RefreshSurfaceWindow();


SliceMeshAxial Method

Description

Slices a surface mesh parallel to the XY-plane at the specified Z-level.

Syntax

objDocument.SliceMeshAxial(intSlice)

Remarks

Valid only if objDocument is of type VMR and if a mesh has been loaded or created. The slice shows the data contained at that level in the respective VMR document. If multiple surface meshes are present, the method is applied to the current mesh. If a mesh is created or loaded/added, it automatically becomes the current mesh. In the case of multiple meshes, you can specify the current mesh using the XXX method. To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
For i = 30 To 230 Step 2
  doc.SliceMeshAxial i
  doc.RefreshSurfaceWindow
Next

// JScript
for(i=30; i<=230; i+=2)
{
  doc.SliceMeshAxial(i);
  doc.RefreshSurfaceWindow();
}

#
 PerlScript
for($i=30; $i<=230; $i+=2)
{
$doc->SliceMeshAxial($i);
$doc->RefreshSurfaceWindow();
}


SliceMeshCoronal Mehod

Description

Slices a surface mesh parallel to the XZ-plane at the specified Y-level.

Syntax

objDocument.SliceMeshCoronal(intSlice)

Remarks

Valid only if objDocument is of type VMR and if a mesh has been loaded or created. The slice shows the data contained at that level in the respective VMR document. If multiple surface meshes are present, the method is applied to the current mesh. If a mesh is created or loaded/added, it automatically becomes the current mesh. In the case of multiple meshes, you can specify the current mesh using the XXX method. To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
For i = 30 To 230 Step 2
  doc.SliceMeshCoronal i
  doc.RefreshSurfaceWindow
Next

// JScript
for(i=30; i<=230; i+=2)
{
  doc.SliceMeshCoronal(i);
  doc.RefreshSurfaceWindow();
}

#
 PerlScript
for($i=30; $i<=230; $i+=2)
{
$doc->SliceMeshCoronal($i);
$doc->RefreshSurfaceWindow();
}


SliceMeshSagittal Mehod

Description

Slices a surface mesh parallel to the YZ-plane at the specified X-level.

Syntax

objDocument.SliceMeshSagittal(intSlice)

Remarks

Valid only if objDocument is of type VMR and if a mesh has been loaded or created. The slice shows the data contained at that level in the respective VMR document. If multiple surface meshes are present, the method is applied to the current mesh. If a mesh is created or loaded/added, it automatically becomes the current mesh. In the case of multiple meshes, you can specify the current mesh using the XXX method. To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
For i = 30 To 230 Step 2
  doc.SliceMeshSagittal i
  doc.RefreshSurfaceWindow
Next

// JScript
for(i=30; i<=230; i+=2)
{
  doc.SliceMeshSagittal(i);
  doc.RefreshSurfaceWindow();
}

#
 PerlScript
for($i=30; $i<=230; $i+=2)
{
$doc->SliceMeshSagittal($i);
$doc->RefreshSurfaceWindow();
}


MeshSlicesOff Method

Description

Removes all activated slices from the current mesh.

Syntax

objDocument.MeshSlicesOff()

Remarks

Valid only if objDocument is of type VMR and if a mesh has been loaded or created. If multiple surface meshes are present, the method is applied to the current mesh. If a mesh is created or loaded/added, it automatically becomes the current mesh. In the case of multiple meshes, you can specify the current mesh using the XXX method. To update the Surface Module window, call the RefreshSurfaceWindow method.

Example

' VBScript
For i = 30 To 230 Step 2
  doc.SliceMeshAxial i
  doc.RefreshSurfaceWindow
Next
doc.MeshSlicesOff

// JScript
for(i=30; i<=230; i+=2)
{
  doc.SliceMeshAxial(i);
  doc.RefreshSurfaceWindow();
}
doc.MeshSlicesOff();

# PerlScript
for($i=30; $i<=230; $i+=2)
{
  $doc->SliceMeshAxial($i);
  $doc->RefreshSurfaceWindow();
}
$doc->MeshSlicesOff();


BeginRecordingSurfaceWindowMovie Method

Description

Starts recording every updated view in the Surface Module window and saves it to a movie file.

Syntax

objDocument.BeginRecordingSurfaceWindowMovie(strMovieFileName)

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. The method must be completed by a matching call to EndRecordingSurfaceWindowMovie, otherwise the movie file can not be used. The "grabbed" frames are stored in a movie file with the provided filename which should have the extension ".avi" since it is stored in Microsoft's format. Note, that the frames are stored uncompressed, i.e. each pixel of each frame is stored using 3 bytes (RGB values). This means that movie files become very large. Use the NewMainWindowSize method to reduce the size of the main window and thus also the size of the Surface Module window. You might use other software to compress the saved movie further, i.e. by converting the uncompressed AVI into GIF animation files.
Any command that updates the Surface Module window will result in grabbing the windows content as a frame which is saved in the file. In most cases this will be triggered by the RefreshSurfaceWindow method.

Example

' VBScript
BrainVoyager.NewMainWindowSize 400, 350
doc.LoadMesh "cg_head.srf"
doc.BeginRecordingSurfaceWindowMovie "demo.avi"
For i = 0 To 360 Step 5
  doc.SetViewpointAngles 180, i, 0
  doc.RefreshSurfaceWindow
Next
doc.EndRecordingSurfaceWindowMovie

// JScript
BrainVoyager.NewMainWindowSize(400, 350);
doc.LoadMesh("cg_head.srf");
doc.BeginRecordingSurfaceWindowMovie("demo.avi");
for(i = 0; i<=360; i += 5)
{
doc.SetViewpointAngles(180,
 i, 0);
doc.RefreshSurfaceWindow();
}
doc.EndRecordingSurfaceWindowMovie();

#
 PerlScript
$BrainVoyager->NewMainWindowSize(400,
 350);
$doc->LoadMesh("cg_head.srf");
$doc->BeginRecordingSurfaceWindowMovie("demo.avi");
for($i = 0; $i<=360; $i += 5)
{
$doc->SetViewpointAngles(180,
 i, 0);
$doc->RefreshSurfaceWindow();
}
$doc->EndRecordingSurfaceWindowMovie();


EndRecordingSurfaceWindowMovie Method

Description

Stops recording Surface Module window movie and closes the movie file.

Syntax

objDocument.EndRecordingSurfaceWindowMovie()

Remarks

Valid only if objDocument is of type VMR and if the Surface Module window for this VMR project has been created. The method should be the matching call to an earlier call of the BeginRecordingSurfaceWindowMovie method. The present method closes the opened AVI file properly. If it is omitted, the movie file can not be used.

Example

' VBScript
BrainVoyager.NewMainWindowSize 400, 350
doc.LoadMesh "cg_head.srf"
doc.BeginRecordingSurfaceWindowMovie "demo.avi"
For i = 0 To 360 Step 5
  doc.SetViewpointAngles 180, i, 0
  doc.RefreshSurfaceWindow
Next
doc.EndRecordingSurfaceWindowMovie

// JScript
BrainVoyager.NewMainWindowSize(400, 350);
doc.LoadMesh("cg_head.srf");
doc.BeginRecordingSurfaceWindowMovie("demo.avi");
for(i = 0; i<=360; i += 5)
{
doc.SetViewpointAngles(180,
 i, 0);
doc.RefreshSurfaceWindow();
}
doc.EndRecordingSurfaceWindowMovie();

# PerlScript
$BrainVoyager->NewMainWindowSize(400,
 350);
$doc->LoadMesh("cg_head.srf");
$doc->BeginRecordingSurfaceWindowMovie("demo.avi");
for($i = 0; $i<=360; $i += 5)
{
$doc->SetViewpointAngles(180,
 i, 0);
$doc->RefreshSurfaceWindow();
}
$doc->EndRecordingSurfaceWindowMovie();


GetTime Method

Description

Provides a time value in milliseconds. A pair of calls to this method can be used to measure the duration of computations.

Syntax

intTimeInMS objBrainVoyager.GetTime()

Remarks

The method internally calls the Windows multimedia API function timeGetTime which possesses millisecond precision.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
path = "C:\My Documents\SampleData\"
t_start = BrainVoyager.GetTime
Set docVMR = BrainVoyager.CreateProjectFMR("IMA",
 path + "5807-4-34.ima", 126, 15, "slice-", 1, 128,
 128, 2, path)
t_end = BrainVoyager.GetTime
Duration = t_end - t_start

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
path = "C:\\My Documents\\SampleData\\";
t_start = BrainVoyager.GetTime();
docVMR = BrainVoyager.CreateProjectFMR("IMA",
 path + "5807-4-34.ima", 126, 15, "slice-", 1, 128,
 128, 2, path);
t_end = BrainVoyager.GetTime();
Duration = t_end - t_start;

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$path = "C:\\My Documents\\SampleData\\";
$t_start = $BrainVoyager->GetTime();
$docVMR = $BrainVoyager->CreateProjectFMR("IMA",
 $path . "5807-4-34.ima", 126, 15, "slice-", 1, 128,
 128, 2, $path);
$t_end = $BrainVoyager->GetTime();
$Duration = $t_end - $t_start;


Exit Method

Description

Terminates BrainVoyager.

Syntax

objBrainVoyager.Exit()

Remarks

Before using this method, all open documents should be closed first. The method should be the last statement in a script, otherwise an error message might occur. You might want not to use this method in cases where you want that a script prepares a certain "setting" from which you want to start to work interactively.

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
Set docVMR = BrainVoyager.OpenDocument("cg_objects.fmr")
docVMR.SetZoomLevel 3
docVMR.Close
BrainVoyager.Exit

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
docVMR = BrainVoyager.OpenDocument("cg_objects.fmr");
docVMR.SetZoomLevel(3);
docVMR.Close();
BrainVoyager.Exit();

# PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
$docVMR = $BrainVoyager->OpenDocument("cg_objects.fmr");
$docVMR->SetZoomLevel(3);
$docVMR->Close();
$BrainVoyager->Exit();


ScriptLaunchedByBV Method

Description

Determines of running script was launched by BrainVoyager or from outside, i.e. by double-clicking the script in Windows Explorer.

Syntax

intScriptLaunchedByBV objBrainVoyager.ScriptLaunchedByBV()

Remarks

Scripts run faster if they are launched by BrainVoyager. One disadvantage is, however, that the "WScript" object is not available for scripts started by BrainVoyager. You can use the presented method to check whether you can access the "WScript" object or not. One important application is the determination of the folder from which a script has been started. (see GetCurrentFolder method).

Example

' VBScript
Set BrainVoyager = CreateObject("BrainVoyager.1")
If BrainVoyager.ScriptLaunchedByBV Then
  path_to_script = BrainVoyager.GetCurrentFolder
End If

// JScript
BrainVoyager = new ActiveXObject("BrainVoyager.1");
if(BrainVoyager.ScriptLaunchedByBV())
  path_to_script = BrainVoyager.GetCurrentFolder();

#
 PerlScript
$BrainVoyager = Win32::OLE->new("BrainVoyager.1");
if($BrainVoyager->ScriptLaunchedByBV())
$path_to_script = $BrainVoyager->GetCurrentFolder();


GetCurrentFolder Method

Description

Determines the folder where BrainVoyager currently looks for files.

Syntax

strCurrentFolder objBrainVoyager.GetCurrentFolder()

Remarks

For methods requiring file names as input, full path information should be provided. It is, however, more convenient to specify file names without the full path information which allows also to move folders to new locations without changing the content of moved script files. If files are specified without absolute path information, it should be known which folder is used as the current folder. The presented method allows to obtain the path to the current folder. BrainVoyager's current folder is also identical with the path to the running script file but only when the script has been launched from within BrainVoyager. If a script has been launched from outside of BrainVoyager, the current folder is not necessarily the same as the folder from which the script has been started since a freshly launched BrainVoyager sets the current folder to the one which was active when BrainVoyager was closed before.
If a script has been started from outside of BrainVoyager via the Windows Script Host, BrainVoyager has no knowledge about the folder from where the script has been started. In this case, however, the "WScript" object is available which possesses methods to determine information about the folder from which the script was started.

Example

' VBScript - full
 code in file "GetScriptPath.pl"
Set BrainVoyager = CreateObject("BrainVoyager.1")
If BrainVoyager.ScriptLaunchedByBV
 Then
path_to_script = BrainVoyager.GetCurrentFolder
Else
ScriptName = WScript.ScriptFullName
path_to_script = Left(ScriptName,
 InstrRev(ScriptName, "\"))
End If

// JScript - full
 code in file "GetScriptPath.pl"
BrainVoyager = new ActiveXObject("BrainVoyager.1");
if(BrainVoyager.ScriptLaunchedByBV())
path_to_script = BrainVoyager.GetCurrentFolder();
else
{
ScriptName = WScript.ScriptFullName;
path_to_script = ScriptName.substr(0,
 ScriptName.lastIndexOf("\\") + 1);
}

# PerlScript - full code in file "GetScriptPath.pl"
use cwd; # special module allows to retrieve current working directory
$dir = getcwd;
# append "\" but not if root dir
if(length($dir) > 3)
{ $path_to_script = $dir . "\\"; }
else
{ $path_to_script = $dir; }