CIBC:Documentation:SCIRun:Reference:MatlabInterface:ImportDatatypesFromMatlab

From SCIRun Documentation Wiki
Jump to: navigation, search

ImportDatatypesFromMatlab

Information

Package: MatlabInterface
Catagory: DataIO
Author(s): Jeroen Stinstra
Status: Supported in latest version
Version: 3.0

Description

Summary

The ImportDatatypesFromMatlab module reads SCIRun fields, SCIRun Matrices, and SCIRun Nrrds from a MATLAB file.

Detailed Description

This module takes a specially prepared MATLAB file and converts it into a SCIRun Field, Matrix, or Nrrd object. Currently only files from matlab version 5 and higher are supported by this module. The GUI of the module lets the user choose one MATLAB file and subsequently displays all the matrices inside the file. Currently the implementation only shows those MATLAB matrices for which a suitable converter exists, the other ones are not shown. Hence, if your MATLAB matrix does not show up in the selection window the module does not know how to translate the that data set into a SCIRun Field object. Since, a MATLAB file can contain multiple MATLAB matrices, the module is equipped with nine output ports. Three for SCIRun Fields, three for SCIRun matrices, and three for SCIRun Nrrds. By selecting the port the module will show which conversion options are available. This module is a combination of the MatlabFieldsReader, the MatlabNrrdsReader and the MatlabMatricesReader and is intended as a way of using one matlab file to specify fields and the accompaning data. Especially since time data cannot yet be stored in a field this module allows the time data to exist as a separate datastream from the same file. This will limit the amount of files that need to be reloaded when all the data is contained in one matlab file. Depending on how the user configures the module, each output port can represent one of the MATLAB matrices in the file. Hence, multiple geometries/fields/matrices/nrrds can be stored in the same MATLAB file.

Follow the next two steps in order to setup the GUI properly: Choose the MATLAB file that contains the geometry/field/matrices/nrrds data. You can either use the BROWSE button to select a file or enter the filename in the filename entry on top of the GUI and press the OPEN button to list the contents of the file in the listbox in the center of the GUI.

Next the MATLAB matrices in the file need to be connected to an output port. In order to do this click on one of the FIELD/MATRIX/NRRD buttons and then select the MATLAB matrix you want to load on that outport. A FIELD port exports the data as a field, a MATRIX port as a scirun matrix and a NRRD port as a scirun nrrd object. Note that for convenience the first suitable matrix in the file is automatically for the FIELD 1 port. Matrices and nrrds need to be selected before they appear on an output port.


Preparing MATLAB files for SCIRun Fields

One crucial step for the conversion from MATLAB to SCIRun is a proper preparation of the data files. Since a SCIRun field object is a complex entity, a simple numeric dense matrix is difficult to translate. Hence, it is required that you build a STRUCTURED MATRIX in matlab with some of the fields listed below. Based on the fields that are supplied the data is converted in one of the many types of geometries available in SCIRun. The module will try to match the data you supplied with the closest Field object it finds.

The following sections describe the fields of the structure matrix can be defined and are recognized by the module.


Unstructured Meshes

FIELDNAME .node This field is required for unstructured meshes and defines the position of the nodes within the mesh. This matrix should be a dense 3 by M matrix, where M is the number of nodes.

FIELDNAME .edge This field is required for curve meshes and defines the line elements in the mesh. This matrix should be a dense 2 by N matrix, where N is the number of line segments. The numbers in this mesh refer to the node positions in the NODE matrix. By default it is assumed that the numbering of nodes starts at one. However if one of the indices in this EDGE matrix is zero, a zero base is assumed.

FIELDNAME .face This field is required for surfaces meshes and defines the surface elements in the mesh. This matrix should be a dense 3 by N matrix for triangulated meshes and a 4 by N matrix for quadsurf meshes. Here N is the number of surface elements. The numbers in this mesh refer to the node positions in the NODE matrix. By default it is assumed that the numbering of nodes starts at one. However if one of the indices in this FACE matrix is zero, a zero base is assumed.

FIELDNAME .cell This field is required for volume meshes and defines the volume elements in the mesh. This matrix should be a dense 4 by N matrix for tetrahedral meshes, or a 6 by N matrix for prism shaped volume elements, or a 8 by N matrix for hexahedral elements. Here N is the number of volume elements. The numbers in this mesh refer to the node positions in the NODE matrix. By default it is assumed that the numbering of nodes starts at one. However if one of the indices in this CELL matrix is zero, a zero base is assumed.


Structured Meshes

FIELDNAMES x , y , AND z The fields X, Y, and Z form the description of a structured mesh. These fields are 1D, 2D, or 3D matrices defining the structured line, surface, or volume data. The connectivity of these meshes is defined by the position of the matrix, neighboring elements are connected. In this definition matrix X defines the x cartesian co-ordinate of each node, matrix Y the y cartesian co-ordinate and matrix Z the z cartesian co-ordinate. This kind of definition is compatible with MATLAB functions such as ndmesh() and sphere().


Structured regular Meshes

As structured matlab arrays:

FIELDNAME .dims This field describes the dimensions of the regular grid and is required for making a regular structured mesh. This field is a vector with 1, 2, or 3 elements describing the dimensions in each direction. Hence depending on this field the module creates a line, a surface, or a volume. This field is required for structured regular meshes.

FIELDNAME .transform This field describes a 4x4 matrix which defines an affine transformation, which is applied to the mesh. This matrix describes rotation, translation and scaling of each node in the regular mesh. This field is optional and does not need to be supplied. In case on transform matrix is defined a regular grid with spacing of 1 in each direction will be generated. [NEED TO ADD MORE DETAILS]

As regular dense matrices:

ImageFields and LatVolFields can be entered as well as dense matrices. A 2D matrix will be translated into an ImageField, and a 3D matrix will be translated into a LatVolField. When entering data as regular matrices, the data is assumed to be on the nodes and to be a scalar double field.

Note: The displaying dimensions between matlab and SCIRun are flipped, in matlab the first dimension is along the vertical axis, whereas in SCIRun it is along the horizontal axis. Depending on the application the data may need to be transposed, in order to make to obtain the proper vertical alignment.


Field Data

FIELDNAME .field A matrix specifying scalar/vector/tensor data for each node/element in the mesh. Each subsequent element in this vector is added to the next node/element in the field. Use the field FIELDLOCATION to specify where the data should be located. The module detects the type of data. The tensor and respectively the vector dimension is assumed to be the first one.

FIELDNAME .fieldtype A string specifying the type of data stored in field. Currently three value are accepted: 'scalar', 'vector', and 'tensor'. If this type information is omitted it defaults to 'scalar'

FIELDNAME .fieldat The location of the data. This field is a string describing where the data should be located. The default field location is assumed to be the nodes, meaning each node has a scalar, vector, or tensor value. In case the data is at the nodes, this field does not to be specified. This field is a string with the following options: "node", "edge", "face", or "cell".

The way of specifying a field was different in version 1.22 of SCIRun. The modules still support input through the fields 'vectorfield', 'tensorfield', and 'scalarfield'. However to be compatible with future additions this has been changed to a combination of 'field' and 'fieldtype'. The new fieldwriters will use this convention instead of the old one.

The module will try to reconstruct data, for instance if a matrix is transposed, it will detect this and read the data properly. Most of the fields mentioned are optional and are not necessary. Only choose those fields from the list that are needed to describe your data. Currently not every field type supported by SCIRun is implemented in this module. Hopefully future versions will support more data types and have even less restrictive converters.


Example 1: preparing MATLAB file

The following lines of MATLAB code demonstrate how to structure a matrix for the use in SCIRun:

Assuming that the nodes are specified in nodematrix and the connectivity of these nodes is specified in facematrix

>> geom.node = nodematrix 
>> geom.face = facematrix 
>> save mymesh.mat geom 

Opening the file with the MatlabFieldsReader module will show that there is one data matrix called "geom" whose contents is a TRISURFMESH with no data on any of the node points

In case MATLAB is not available to structure the data, use the MODULE REFERENCE module to read a MATLAB matrix data directly and use the MODULE REFERENCE module to construct a Field out of the Nrrd object.


Example 2: Creating a structured mesh

The following lines of MATLAB code demonstrate the creation of a matlab file with the matlab logo on a structured mesh:

>> [X,Y,DATA] = peaks(100); 
>> field.x = X; 
>> field.y = Y; 
>> field.z = DATA; 
>> field.scalarfield = DATA; 
>> save myfield field 

This will create a surface mesh in the shape of the peaks logo and uses the z value as its data values. Be sure to specify all the three cartensian coordinates, omitting one will result in the module not to recognise the mesh and it will not display the object in its selection box.


Exampe 3: Creating an unstructured mesh

The following lines of MATLAB code demonstrate the creation of a matlab fiel with an unstructured tesselated surface:

>> [X,Y,Z] = ndmesh(1:10,1:10,0); 
>> field.node = [X(:)'; Y(:)'; Z(:)']; 
>> field.face = delauney(X,Y); 
>> field.scalarfield = X(:).^2; 
>> save myfield2 field 

Frequently Asked Questions


Known Bugs


Recent Changes


Go back to Documentation:SCIRun:Reference:MatlabInterface