Module: Calculus MATLAB ()

Description:

This module is available for MATLAB 2017a (and older) on Windows, Linux, and Mac OS X.

In order to use this module, MATLAB must be correctly installed on your computer. Please refer to the for important notes about MATLAB installation and connection with .

This module establishes a connection to MATLAB (The MathWorks, Inc.).

The module works like a compute module and allows computation on data objects in the MATLAB workspace. data objects can be attached to the module and a MATLAB script file can be specified. The following actions are performed:

There are limitations on the type of data objects used.

There is also a memory limitation with the MATLAB connection: only 2Gb of data can be send per variable. The module shows a dialog when this limitation is exceeded and stops the process.

HxLattice3 objects are stored by default as 3D/4D arrays named 'A' in MATLAB scripts. Notice that you have no control on the bounding box of these arrays when they are sent back into . Their bounding box will be [0, 1, 0, 1, 0, 1] by default. This can then be tuned thanks to the Crop Editor.

Optionally, if the lattice to struct option is checked in the Options port, the HxLattice3 objects are duplicated in MATLAB as structures named 'field'. In that case, when the input fields are copied back to , they will have the same bounding box as the input lattice.

If the storage lattice to struct is activated, the structure looks like: 

field.data - 3D/4D array of data values (scalar/vector);
field.coordsType - string indicating the type of coordinates
field.bbox - 1D array of bounding box (xmin xmax ymin ymax zmin zmax)
field.name - string of the object name
field.type - primeType of the object (HxLattice3)

If not cleared in the script, HxLattice3 structures are copied back to uniform HxLattice3 objects. If the field 'name' exists tries to use this name for the resulting object. In the other case the variable name of the structure is used.

If several HxLattice3 objects are transferred, the name includes a counter 'AID' or 'fieldID' added in the order of connection to the module.

HxSurface objects are stored in a structure named 'surf'. If several HxSurface objects are transferred, the name includes a counter 'surfID' added in the order of connection to the module.

The structure looks like: 

surf.vertices - 2D array of coordinates (numPoints x 3)
surf.faces - 2D array of vertex-IDs (numTriangles x 3)
surf.FaceVertexCData - 2D array of colors on triangles (numTriangles x 3)
surf.FaceColor - string 'flat'
surf.EdgeColor - string 'none'
surf.bbox - 1D array of bounding box (xmin xmax ymin ymax zmin zmax)
surf.name - string of the object name
surf.type - primeType of the object

If not cleared in the script, HxSurface structures are copied back to HxSurface objects. If the field 'name' exists tries to use this name for the resulting object. In the other case the variable name of the structure is used. If a color field is defined on the faces, it is copied back to three scalar HxSurfaceField objects (r, g, b) connected to the HxSurface object and postfixed ColorDataField.

HxSurfaceField objects are stored in a surface structure named 'surf'. If several HxSurfaceField objects are transferred, the name includes a counter 'surfID' added in the order of connection to the module.

The structure looks like: 

The underlying surface is transferred. The structure surf is the same as for HxSurface.
surf.data - 2D-array of data values (numPoints/numTriangles/(3 x numTriangles) x numComponents)

If not cleared in the script, HxSurfaceField structures are copied back to HxSurfaceField objects postfixed SurfaceDataField corresponding to the input field and connected to HxSurface objects corresponding to the transferred surface (with faces color fields if non empty).

HxLineSet objects are stored in a structure named 'line set'. If several HxLineSet objects are transferred, the name includes a counter 'linesetID' added in the order of connection to the module.

The structure looks like: 

lineset.points - 3D array of coordinates (3 x numPoints)
lineset.lines  - cell array of vectors describing the line
lineset.data   - (optional) data array (numDataPoints x numPoints)
lineset.type   - primeType of the object
lineset.name   - string of the object name

Note: In the numbering of points starts with 0 while the numbering in MATLAB starts with 1, since C arrays start counting with 0 while MATLAB arrays start with 1.

Data matrices with 4 or fewer dimensions are copied back to .

where X may be one of the following:

Every other object of the Project View can be mapped to a structure named the same as the object, with '.' and ':' replaced by '_'. The structure entries are 'name' and 'value' and they respectively contain the list of the object ports name and the list of the object ports current value. For an object to be mapped to a structure, it must be connected to the A input port of the module and the Buffer or Selection button must be pressed (ideally with no script).

Connections:

A [required]
You can connect any data objects to the module. Look at the description above to know how the objects are represented in MATLAB.

An [optional]
After attaching a new data icon to the module, a new port is generated which can be used to attach additional data.

Ports:

Script

You can specify a text file which contains a MATLAB script. Note that only scripts but not functions are allowed. An example script could look like this: 
% Option 'lattice to struct' must be checked
% field is the first connected HxLattice3 data object (in double precision)
% X, magnitude and amplitude are newly created and will be sent back to the application
X.data = fftn(field.data);
magnitude.data = abs(X.data);
amplitude.data = unwrap(angle(X.data));
   
% set the bounding box of the exported variables to the input bounding box
X.bbox = field.bbox;
magnitude.bbox = field.bbox;
amplitude.bbox = field.bbox; 
   
% clear all variables that you do not wish to export
clear field;

After the script is executed the 'X', 'magnitude', and 'amplitude' variables are copied back into the workspace. For this example, the lattice to struct option is checked. Therefore, the 'field' structure is used in the script.

Here is a list of the supported MATLAB data types and how to create each one in the MATLAB workspace. 

Z1  = randn(10,10,10,1);    % HxUniformScalarField3
Z11 = randn(10,10,10);      % HxUniformScalarField3
Z12 = randn(1,10,10,10);    % HxUniformScalarField3
Z2  = rand(2,10,10,10);     % HxUniformComplexScalarField3
Z3  = rand(3,10,10,10);     % HxUniformVectorField3
Z4  = uint8(rand(4,10,10,10).*255); % HxUniformColorField3
Z5  = randn(5,10,10,10);    % definition of Z5 will 
                            % produce an error
Z6  = randn(6,10,10,10);    % HxUniformComplexVectorField3

A minimal field as structure could be 

F1.data = rand(10,10,10);
F1.bbox = [0 1 0 1 0 1];

A minimal line set could be 

LS1.points = [0 0 0; 1 1 1]';
LS1.lines{1} = [1 2];

describing one line from (0, 0, 0) to (1, 1, 1). Be aware of transposing the point array. The optional data array behaves the same, e.g. 

LS1.data = [1 2 3; 4 5 6]';

would add 3 data values for the two points of the above line set.

Here is an example of working with non-scalar data. The lattice to struct option must be disabled. Therefore, 'A' array is used in the script. In this case, we have a colorfield attached to input A. 

useimage=1;                   % which image from the stack
if exist('A') == 1,           % input exists?
   if size(size(A),2) == 4,   % input is 4D?
      if size(A,1) == 4,      % the first dimension 
                              % should be 4 (RGBA)
         ima(:,:,1) = reshape(A(1,:,:,useimage),
                              size(A,2),
                              size(A,3));
         ima(:,:,2) = reshape(A(2,:,:,useimage),
                              size(A,2),
                              size(A,3));
         ima(:,:,3) = reshape(A(3,:,:,useimage),
                              size(A,2),
                              size(A,3));
         mi = min(min(min(ima))); ma = max(max(max(ima)));
         ima = (float(ima)-mi)./(ma-mi);
         imagesc(ima);        % display the color image
      end;
   end;
end;
clear mi ma ima useimage A field    % remove local variables

You will find more examples in the section.

Execute

Starts the execution of the MATLAB script. All generated messages will be printed in the console window.

You can either execute the contents of the text buffer below (Script) or execute a selection of the text in the buffer (Selection).

You can specify whether the MATLAB workspace should be cleared before running the script (Clear Workspace). If activated, all variables in the workspace will be deleted. Otherwise, all variables, including -MATLAB transfer variables, will be kept. Note that variables with identical names will be overwritten.

You can specify a custom list of variables that will be transferred back to instead of all variables. To specify variables, create the cell array 'MatlabExportList'. Store names of variable to be copied to the Project View as strings in the list. The transfer will be restricted to these variables. will show a warning if more than 5 variables are to be transferred without explicitly specifying them in the transfer list.

Here is an example of working with a custom list: 

a = 1; b = 2; c = 3;
MatlabExportList{1} = 'a';
MatlabExportList{2} = 'b';

or 

MatlabExportList = {'a' 'b'};

The variables names 'a' and 'b' are stored in the cell array and will be copied to . The variable 'c' will be skipped.

MATLAB Script

Enter or change a loaded script in this buffer.

Options

This module starts a MATLAB session in the background. Its interface can be made visible through the first option display Matlab console, thus the user can interact with the running MATLAB process and inspect variables in its workspace. This option is restricted to Windows only. Note: Even if the MATLAB interface is toggled to be visible, it may be minimized and therefore not displayed.
Warning: If you close the MATLAB interface, MATLAB is closed and the Calculus MATLAB module will not work any more.

The second option lattice to struct enables the storage of HxLattice3 objects as structures in MATLAB as described in the previous documentation and examples.