CIBC:Project:Matlab
From NCRR Biomedical Software Development, Engineering, and Dissemination Wiki
1) How to load Matlab Code into SCIRun?
First ensure that your system has access to Matlab and cmake. To built SCIRun with the MatlabInterface enabled. In the configuration stage ensure that the cmake variable LOAD_PACKAGE = SCIRun,BioPSE,Teem,MatlabInterface using ccmake.
For example,
cd /path/to/SCIRun/bin
ccmake /path/to/SCIRun/src
For ASCII Matlab files with the extension .m do the following.
Start a SCIRun application.
Move the mouse pointer on the title bar and left click on the MatlabInterface tab. This should open up an option box directly below, click on the Interface tab and then click on the InterfaceWithMatlab tab. This will then create a module within the main SCIRun application window. On the InterfaceWithMatlab module click on the UI (user interface) tab, which opens the InterfaceWithMatlab GUI see Figure 1.
Figure 1
To load a particular Matlab .m file left click on the load tab found at the bottom left of the InterfaceWithMatlab module GUI, which opens up a directory structure GUI that enables the user to traverse the directory structure to find the required Matlab file see Figure 2.
Figure 2
Once the required Matlab .m file is selected the code appears within the main InterfaceWithMatlab GUI window as illustrated in Figure 3.
Figure 3
For binary Matlab files with the extension .mat do the following.
Move the mouse pointer onto the title bar and left click on the Matlabinterface tab. This opens up an option box directly below, click on the DataIO tab and then click on the ImportDatatypesFromMatlab tab. This will create a module within the main SCIRun application window. On The ImportDatatypesFromMatlab module click on the UI tab, which opens a GUI. Then click on the browse tab to find the required Matlab .mat file as illustrated in Figure 4.
Figure 4
2) How to execute and visualize Matlab code within SCIRun?
To execute and visualize Matlab code within SCIRun you first must connect a network of modules that load, process the Matlab data from the file and then visualize the results. Figure 5 illustrates a simple SCIRun module network that perform these tasks.
Figure 5
3) How to automatically load a Matlab file within the InterfaceWithMatlab module? There are several ways to automatically load a Matlab file into SCIRun.
One method involves inserting the path to the desired file using addpath and then the name of the function into the main text box as shown in Figure 6
Figure 6
Another method involves passing the data as a string from a user defined interface module as illustrated in Figure 7. The data passed into string1 contains the absolute filename. For example, /path/to/filename.extension, which is then subdivided into pathname and filename using [pn,fn]=fileparts(string1) and using a similar approach as described above the path is added using addpath. The data passed into string2 contains the function name and is called using eval or some derivative of eval. For example, eval(string2).
Figure 7
4) How to pass a function and parameters to the InterfaceWithMatlab Module within SCIRun? The ability to pass a series of parameters to Matlab from within SCIRun is essential.
The example that is given here involves setting the parameters within a user defined SCIRun module that are subsequently passed to the InterfaceWithMatlab module using the string input and output ports. The InterfaceMultiPhaseCVWithMatlab module is a user defined SCIRun module that enable the setting of parameters for the a particular Matlab code that are exported by two string output ports see Figure 8. Where the first output string contains the absolute filename, and the second output string contains the function name and parameters that are to be executed by Matlab.
For example,
string 1 value is : /scratch/ActiveContours/ActiveContours.m
string 2 value is : ActiveContours('Explicit', 'Grad', 'a1', 'a1_explicit_grad.avi', 0.1 * 255 * 255, 0, 1, 1, 160, 0, 10)
Figure 8
The next step involves inserting Matlab code into the main window to interprete the input strings and executing the code within the InterfaceWithMatlab module See Figure 9.
Figure 9
where,
[pn,fn]=fileparts(string1) subdivides the absolute filename into the path and file name,
addpath(pn); adds the path.
eval(string2); evalutes the function and parameters stored in string2 using eval or some derivative of the eval function.
5) How to access and dynamically modifying Matlab variables and function parameters from within SCIRun?
The ability to interact with the execution of the Matlab code within SCIRun requires a mechanism that enables the indivdual parameter to be modified by a user from within the user defined InterfaceMultiPhaseCVWithMatlab module, which are then passed to the InterfaceWithMatlab module for processing.
For example,
% Psuedo Matlab code
% Matrices X, Y and Z
X = DoSomething(X, ...);
Y = DoSomething(Y, ...);
Z = DoSomething(Z, ...);
What we want to do is to be able to modify the parameters to the function DoSomething(Matrix, ...) then visualize the resultant matrix within SCIRun.
6) How to convert Matlab data types into corresponding SCIRun data types?
For example,
We are interested in the result of the application of a series of mathematical function within Matlab to a particular dataset such as an MRI scan. So we need a method to convert the results from a Matlab data format to a format that is recognized by SCIRun.
Figure 10
7) How to combine scientific visualization data representation with additional information described within the Matlab code?
An important aspect of creating a compelling visual representation of scientific data is the ability to incorporate additional information such as titles, axis, labels, etc into the visualization.
8) How to create a SCIRun visualization from Matlab data processing?
For example,
The main driving force for integrating Matlab with SCIRun is the ability to incorporate the advance visualization functionality that is available within SCIRun (See Figure 5).
9) How to create a SCIRun visualization networks the are equivalent to the Matlab visualization functionality?
For example,
Although we are primarily concerned with utilizing the advanced vizualization functionality available within SCIRun. It is important to be able to replicate the existing visualization functionality available within Matlab, such as contour(...), surf(...), mesh(...) etc.
One method of mimicking the contour function within SCIRun is to use the ExtractIsosurface module.
10) How to execute existing Matlab code within the SCIRun environment with little of no modification?
For example, we have some existing Matlab code as shown below.
function DoSomething(...) {
% perform data processing
process_data;
% call function data_visualization
output = data_visualization(X,Y,Z,T,...);
}
function data_visualization(X,Y,Z,T, ...) {
% generates a series of different contour plots
subplot(2, 2, 1);
contourf(X, Y, Z, T);
subplot(2, 2, 2);'
contour(X, Y, inv(Z), T);
subplot(2, 2, 3);
contour3(X, Y, fliplr(Z), T);
subplot(2, 2, 4);
contourc(X, inv(Y), Z, T);
}
Ideally we don't want to modify the existing Matlab code to enable it to be executed and visualized within SCIRun. However, to be able to access data from within an executing Matlab program. The existing Matlab code must be modified to either allow a socket connection or be able to write the data to a file. Otherwise, SCIRun cannot access the data generated from within separate program.
11) Performing the same task using the InterfaceWithMatlabViaBundles module.
For certain applications it is desireable to store several SCIRun objects into a single bundle object, similar to an array in C. This can reduce the number of input and output connections between SCIRun modules and enables a cleaner dataflow network to be created.
For example, while executing some process within a module several matrices are generated, which in turn need to be passed to another module for further processing. Rather than create a connection between the two SCIRun modules for each matrix generated. It would be better to store the matrices within a bundle and create a single connection between the two SCIRun modules.
Figure 11
Figure 11 illustrates how two string objects string1 & string2 are inserted into a bundle object using the InsertStringsIntoBundle module. The resulting bundle object is then passed to the InterfaceWithMatlabViaBundles module and the two strings are extracted from the bundle using the command bundle1.string1 & bundle1.string2 within the InterfaceWithMatlab code window. The data extracted from the input bundle bundle1 are then used to execute some Matlab function (see above examples). The file test_matrix.mat contains several matrices generated by the executed Matlab code was loaded into the SCIRun InterfaceWithMatlab module using the command sample_matrix = load('/path/to/file/test_matrix.mat'); . The variable sample_matrix is similar to a structure in C and the data stored within it can be accessed in the same way. For example, field1 = sample_matrix.X; .
Figure 12
The InterfaceWithMatlab code window in Figure 12 illustrates how SCIRun objects are inserted into an output bundle using the command
out_bundle1.field1 = field1; . The variable out_bundle1 was declared
within output bundles section of the input/output window. Although the default variable name for the first output bundle is bundle1, which happens to be the same as the variable name for the equivalent input bundle.
12) Extracting SCIRun objects that are stored within a bundle.
Once data has been stored within a bundle it is essential that the data can be accessed easily. To accomplish this SCIRun contains several modules under the tabs SCIRun > Bundle > . As shown in Figure 13.
Figure 13
In Figure 14 the modules GetMatricesFromBundle and ReportBundleInfo are attached to the module InterfaceWithMatlabViaBundles using the bundle commuication ports. Clicking the UI button on the ReportBundleInfo module launches a GUI that displays the variable names and datatypes of the objects stored with the bundle. For example, field1(matrix) where field1 is the variable name and matrix is the datatype.
Figure 14
Although the output bundle tabs on the user interface only show prefer nrrds and prefer matrices. The InterfaceWithMatlabViaBundles module can implicitly export fields, strings, nrrds and matrices within a bundle (see Figure 18).
13) The loading of image files for processing and subsequent visualization can be achieved within the InterfaceWithMatlab and InterfaceWithMatlabViaBundles modules, as illustrated in Figure 15.
Figure 15
In Figure 15 an image file is loaded into the InterfaceWithMatlabViaBundles modules using the command image_file = imread(output_image);, where output_image contains the path and name of the image file (/path/to/file.extension). The image file is then incorporated into a bundle using the command bundle2.image1 = image_file;. The data stored within bundle2 is then converted to the nrrd datatype by changing the output type tab that is associated with the output port bundle 2 from prefer matrices to prefer nrrds.
To extract the nrrd data stored in the bundle. The GetNrrdsFromBundle module was attached to the bundle output port of the InterfaceWithMatlabViaBundles module as illustrated by the SCIRun dataflow network (See Figure 15).
Once the image data has been exported from the InterfaceWithMatlabViaBundles module to the GetNrrdsFromBundle module. It is then possible to convert the nrrd image into a different SCIRun datatype for additional processing and subsequent visualization. Figure 16 illustrates how a nrrd image stored within a bundle is converted into a SCIRun field datatype using the ConvertNrrdToField module, which is attached to the GetNrrdsFromBundle module. To ensure that the correct nrrd image is extracted from the bundle using the GetNrrdsFromBundle module and passed onto the ConvertNrrdToField module. Open the GUI shown at the top right of Figure 16 appears, then select the appropriate image (image1) so that appears in the top text box.
Figure 16
Once the nrrd image has been converted into a field datatype using the ConvertNrrdToField module. It is possible to extract information about the convert field datatype by attaching the ReportFieldInfo module to the ConvertNrrdToField module and clicking on the UI button. That launches a GUI (see bottom of Figure 16), which enables the user to verify the structure and type of data stored within the field.
14) Visualization of the nrrd image.
It is possible to visualize the image generated by the matlab program within SCI.
Figure 17
In Figure 17 the SCIRun dataflow network from Figure 16 was modified to remove the ConvertNrrdToField and ReportFieldInfo modules. While incorporating the ViewSlices module, which is attached to the GetNrrdsFromBundle module. It is now possible to display the image created by the Matlab program within the SCIRun software environment by launching the ViewSlices GUI (See Figure 17).
15) Extracting and modify data stored with the image.
Now that we are able to display the image data generated by the Matlab program. The next step is to enable the user to extract or modify data stored within the image displayed within SCIRun.
Title and axis labels are important components of data visualization, which helps the user to obtain useful details from the visual representation of the data. This information can be extracted from the user defined parameters passed to the Matlab function via the InterfaceMultiPhaseCVWithMatlab module using the regular expression functionality available within Matlab. The next step is to incorporate the information extracted into a bundle, which is then passed to another SCIRun module (see Figure 18).
Figure 18
In Figure 18 a dataflow connection is made between the third bundle output port of the InterfaceWithMatlabViaBundles module and the GetStringsFromBundle module. The strings extracted from the bundle are then passed to the ShowString module. which are attached to the ViewScene module and combined with the processed image. The result of combining the string and image information can be seen in the view scene window at the top right corner of Figure 18.
Figure 19
Figure 19 shows a simpler dataflow network than that depicted in Figure 18. In the GetStringFromBundle user interface window shows three string variables in the main text box, which are assigned to different output ports String1 = title, String2 = method and String3 = timesteps. These string variable where incorporated into a bundle within the InterfaceWithMatlabViaBundles module using the commands within the Matlab code window:
bundle3.title = title;
bundle3.method = method;
bundle3.timesteps = timesteps;
To verify that the string variables passed from the InterfaceWithMatlabViaBundles contain the correct data. The ReportStringInfo module was attached to the output port of the GetStringFromBundle module, which displays the string value within the user interface window (see the top of Figure 19). Now that we have verified that the strings are correct we can incorporate the string information within the visualization by attaching the output ports from the GetStringsFromBundle modules to the input port of the ShowString modules. The position of the strings can be modified within the ShowString modules and then combined with the image by connecting the ShowString modules to the ViewScene module as illustrated in Figure 18.
