CISST to MATLAB Interface

Last updated: 5/16/2012


The cisst libraries offer powerful ways to manipulate surgical robots. We wish to create a MATLAB wrapper for the cisst libraries so the library may be called in a MATLAB environment.

  • Students: Zachary Zhou
  • Mentor(s): Anton Deguet

Background, Specific Aims, and Significance

“The cisst package is a collection of libraries designed to ease the development of computer assisted intervention systems. The Surgical Assistant Workstation (SAW) is a platform that combines robotics, stereo vision, and intraoperative imaging (e.g., ultrasound) to enhance a surgeon's capabilities. The SAW package therefore consists of implemented components (e.g., interfaces to many of the devices used for computer-integrated surgery) as well as reusable applications.” Although the cisst library is a very powerful tool utilized in many of the medical robots in this lab, the entire library is written in C++. As a result, one requires a sufficient understanding of C++ in order to fully utilize the library. However, not necessarily all of the researchers who would like the use the cisst libraries are proficient in the C++ language. In order to make the cisst package more accessible, it would be beneficial to port the library onto a different language. For example, MATLAB happens to be a popular language that is fairly easy to learn and utilize. There are several advantages to utilizing MATLAB over C++. First of all, the MATLAB package includes many numerical methods for matrix manipulation and mathematical interfaces, making it a powerful package for reducing and analyzing data. In addition, MATLAB uses very loose type definitions which, in addition the command console, makes it very user friendly. Finally, researchers often reduce data acquired through the cisst libraries on MATLAB. Utilizing the wrapper will allow for users to manipulate collected data directly in memory and not be required to output to a file.

Overview of Goals: Creation of a general purpose dynamic wrapper that will allow the use of the cisst packages from MATLAB. A breakdown of the goals are listed below:

  • General MATLAB wrapper for the cisst classes
  • Utilize CMake to create the plug-in library
  • Dynamically load cisst components onto MATLAB
  • Handle data manipulation between C++ and MATLAB


Minimum (completed):

  • Be able to load a single component without configuration file onto MATLAB
  • Get dynamic loading to work
  • Write basic data conversion methods for native types

Expected (completed):

  • Utilize CMake to built MATLAB plug-in library
  • Create MATLAB object on the fly with string names
  • Populate MATLAB with component interfaces, names, and commands
    • Partially complete - needs to support dynamic loading of entire library
  • Conversion methods for vectors and matrices

Technical Approach

In order to keep the wrapper as dynamic as possible, we chose to utilize MATLAB’s ability to load dynamic libraries into the MATLAB environment (loadlibary) over MATLAB’s compiled mex files. Utilizing shared libraries offers several advantages over mex files. First of all, MEX requires all C source code to be recompiled every time in order for MATLAB to be able to access the C libraries. Also, there is only one point of entry for MEX files: the mexfunction. This severely limits our MATLAB calls to C functions and requires significant amounts of string manipulation in order to correctly work. Finally, objects created in MEX calls do not always remain after the mexfunction returns. Often, variables are collected by MATLAB’s garbage collector.

For this wrapper, we created a branch from the cisst trunk. After which, we added several C functions and MATLAB script files in order to facilitate the wrapping the library. Once compiled ultilizing CMAKE, there are two files which MATLAB is concerned with: cisstMatlab.h and cisstMatlab.dylib. cisstMatlab.dylib is the compiled dynamic library which contains the cisst source and additional C functions to be loaded onto MATLAB. cisstMatlab.h identifies which C functions MATLAB can directly interact with.

After the dynamic library is created, the cisst wrapper can be loaded onto the MATLAB interface using a call to loadlibrary from the MATLAB environment. We decided to separate calls from MATLAB to C to be handled by two main C files: creatComponent.cpp and callFunction.cpp. A call to create component will result in an object of the desired type being created on the C side, and a dynamic prop wrapping the object to be created on the MATLAB environment. Each object created in the MATLAB environment is a dynamic_prop. A dynamic_prop is a MATLAB type which mimics a class definition. However, there are several advantages in using dynamic_prop’s over classes. First of all, we are able to define props on the fly and add which ever components we chose to it. Secondly, the creation of MATLAB classes requires that a file be created in the MATLAB working directory. Utilizing dynamic_props will allow us to not have to create a MATLAB class file every time new object is created. The resultant dynamic_prop which is returned to the MATLAB environment is mostly an empty class. The prop itself corresponds to the component which was created, subcomponents and interfaces are attached as dynamic props to the main component.

Function calls are also stored as dynamic_props under the main component. However, the value for function calls are not empty. Instead, they are anonymous MATLAB functions which will call the C library and pass arguments to the C side. Each function prop holds the pointer to the mirror function on the C side. A function dynamic prop will general be defined as such:

Function= @()calllib(‘libcisstMatlab’,’mtlCallFunction’, -function pointer-, args )

This allows us to call from the MATLAB side:


Also, when passing arguments from C to MATLAB, we had to wrap matricies/arrays into/from MATLAB. To do this, we would wrap arguments from C to MATLAB as mexArrays. When passing from MATLAB to C, we wrapped as mtsVector types.


Regular contact with Anton

  • Resolve by: 2/20/2012
  • Status: Resolved

Access/set-up to cisst packages and Cmake

  • Resolve by: 2/22/2012
  • Status: Resolved

Solve issue with multiple instances of a class

  • Resolve by: 4/17/2012
  • Status: resolved

Milestones and Status

  • Read/understand cisst library (esp. cisstMultiTask)
    • Expected date: 2/22/12
    • Status: Complete
  • Explore MATLAB/C interfaces
    • Expected date: 3/1/12
    • Status: complete
  • Call a C method from MATLAB
    • Expected date: 2/28/12
    • Status: complete
  • Call a MATLAB method from C
    • Expected Date: 4/1/12
    • Status: complete
  • Pass variables between C/MATLAB
    • Expected Date: 4/2/12
    • Status: complete
  • Utilize CMake to create library
    • Expected Date: complete
  • Dynamically load component
    • Expected Date: 4/20/12
  • Load single component on Matlab
    • Expected Date: 4/20/12
  • Data Conversion of Basic Types
    • Expected Date: complete
  • Data Conversion of Vectors/Matrices
    • Expected Date: complete

Reports and presentations

Project Bibliography

Other Resources and Project Files

Here give list of other project files (e.g., source code) associated with the project. If these are online give a link to an appropriate external repository or to uploaded media files under this name space.

courses/446/2012/446-2012-16/project16.txt · Last modified: 2012/12/10 17:36 (external edit)