Extending MATLAB
AE6382
Using MATLAB
• MATLAB can be used as a mathematical scripting language (.m
files)
• Stand-alone MATLAB applications
– MATLAB code can be converted to a stand-alone form
• requires a MATLAB Compiler toolbox license to compile
• no license required for the stand-alone file
• Extending MATLAB
– MATLAB can access shared libraries written in C/C++ and Fortran in
both Windows (DLL) and Unix/Linux
– MATLAB can access functions written in C/C++ and Fortran as MATLAB
functions, the so-called MEX files
– MATLAB and Java have a very close relationship
• MATLAB can use Java classes
• MATLAB and Java can exchange data using Java classes
AE6382
Using MATLAB
• Accessing MATLAB from other programs
– C/C++ and Fortran programs can access MATLAB
• Using the MATLAB Engine API (Windows and Unix/Linux)
• Using COM functions in Windows
– As an extension of the Standalone Application, a C/C++/Fortran callable
library that encapsulates a set of m-files can be built
– MATLAB and Excel can inter-operate (Excel can use MATLAB objects)
• Data Exchange applications
– C/C++ and Fortran can read and write MAT-files - files that contain
native MATLAB data
– MATLAB is able to read and write data in a variety of other formats
AE6382
Why
•
•
•
•
You can create a standalone application based on MATLAB that can
be freely distributed – no license required to run it
You have a complex application written in C/C++/Fortran that you
would like to access from within MATLAB. Compile and link as a
MATLAB function.
You need to load a large data set into MATLAB. Use either the
native text input functions of MATLAB or use MAT-Files. This will
require C/C++ or Fortran programming. The COM interface can also
be used when using Windows.
You have an m-function that you would like to use in Excel. The
MATLAB Excel Builder will create a COM object that can be used
from Excel. This capability is similar to the MATLAB Compiler
functionality.
AE6382
Why
•
•
•
You would like to make use of some feature that MATLAB provides
in a program that you currently have or are developing. The
MATLAB Engine API can be used for this purpose. It allows the
control of MATLAB from another process. This API is intended for
C/C++ and Fortran programmers, however, the COM Automation
interface can be used on Windows from a script. There are also
add-on modules for Python and Perl that provide Engine access
from those languages.
You would like to combine MATLAB with a Java program
You would like to create a Java GUI with MATLAB
AE6382
External MATLAB
The MATLAB manual that
describes the Compiler toolbox
that enables the creation of
standalone executables for use
on other systems that do have
have MATLAB installed.
AE6382
External MATLAB
•
•
•
•
The MATLAB manual that describes
the available external interfaces that
are available in MATLAB.
MAT-Files
Calling external libraries
Calling C/Fortran from MATLAB
–
•
Calling MATLAB from C/Fortran
–
•
•
•
MEX files (C/C++/Fortran)
Matlab Engine
Calling Java from MATLAB
COM interfaces in MATLAB (Windows)
Web Services
AE6382
External MATLAB
The MATLAB manual that
describes the interface
designed for Excel. It turns M
functions into COM objects that
can be accessed from with
Excel using VBA.
AE6382
External MATLAB
The MATLAB manual that
describes the interface to Java.
It converts MATLAB mfunctions into Java classes that
can be used from within a Java
program.
AE6382
External MATLAB
The MATLAB manual that
describes the API functions
that can be used by C/C++ and
Fortran programs to interact
with MATLAB.
• MAT-File
• MX Array Manipulation
• MEX-Files
• MATLAB Engine
AE6382
Standalone MATLAB Application
• Use MATLAB Compiler to generate a standalone application, library,
or component
• Requires the Compiler toolbox be licensed and installed on your
system
• Requires that an MCR (MATLAB Component Runtime) file be
installed on the target system
• Applications created using the MATLAB compiler are versions
specific and require the correct MCR file, it must match the MATLAB
version used to create the application
AE6382
Using MATLAB Compiler
• Use the MATLAB compiler to include the user supplied m-files in the
CTF file
• Create a wrapper C file and compile into an executable program
• Terms
– CTF is the Component Technology File
• this is an encrypted copy of your m-files and all dependencies (toolbox, …)
• once created it cannot be modified
• contains a copy of your preferences files
– MCR is the MATLAB Component Runtime
• this is a complete set of MATLAB runtime libraries that enables the
application to run
• supplied by MATLAB, usually ~200MB in size
– application executable
• this is the compiled wrapper code generated by MATLAB
• it contains the encryption keys that allow the CTF file to execute
AE6382
Setting Up MATLAB Compiler
• Before you can create your application the MATLAB compiler must
be configured – only required once per installation
• Determine what C/C++ compilers exist on your system
• Windows – supported compilers
– Lcc C is the built-in C compiler
– Microsoft Visual C/C++ (MSVC) Versions 6.0, 7.1, and 8.0
• Linux – supported compilers
– gcc and g++
• Setup environment
– mbuild –setup
– for Windows execute from a cmd.exe window
– creates the options file that is used by the mcc command
AE6382
Setting Up MATLAB Compiler
• mbuild on Linux R2007B
[matlab2007b]$ bin/mbuild -setup
Options files control which compiler to use, the compiler and link command
options, and the runtime libraries to link against.
Using the 'mbuild -setup' command selects an options file that is
placed in ~/.matlab/R2007b and used by default for 'mbuild'. An options
file in the current working directory or specified on the command line
overrides the default options file in ~/.matlab/R2007b.
To override the default options file, use the 'mbuild -f' command
(see 'mbuild -help' for more information).
The options files available for mbuild are:
1: /usr/local/matlab2007b/bin/mbuildopts.sh :
Build and link with MATLAB C-API or MATLAB Compiler-generated library via the system ANSI C/C++ compiler
0: Exit with no changes
/usr/local/matlab2007b/bin/mbuildopts.sh is being copied to
/home/latham/.matlab/R2007b/mbuildopts.sh
[matlab2007b]$
AE6382
Setting Up MATLAB Compiler
• mbuild on Windows R2007A
AE6382
Creating the MCR
• Windows R2007A
AE6382
Creating the MCR
• For MATLAB R2007A and before the buildmcr process is required
• Beginning with MATLAB R2007B the toolbox/deploy/<arch> directory
will contain the appropriate MCRInstaller file for that system
architecture
– Windows – MCRInstaller.exe
– Linux – MCRInstaller.bin
AE6382
Deploying the Application
• Deploying your standalone MATLAB application consists of copying
the CTF file, the MCR file, and the application executable to the
target system
– The target must be the same architecture of the system that built the
application
•
•
•
•
•
win32 – 32-bit Windows
glnx86 – 32-bit Linux
glnxa64 – 64-bit Linux
sol2 – Solaris
mac – OS/X
– Installation of the MCR is not required if that version of MATLAB is
already installed on the target system
– Having MATLAB and/or multiple MCR files requires care to ensure the
right libraries are loaded (see Compiler manual for all details)
AE6382
MATLAB Application Example
• There are two examples following
– They are compiled m-files that perform a matrix multiplication
– They are both compiled for Linux
– One is R2007B the other is R2006A
• Starting with R2007B the compile process has been altered slightly
– Rather than creating an MCRInstaller.zip file the installation includes
• MCRInstaller.exe for Windows
• MCRInstaller.bin for Linux
– The buildmcr is deprecated
• R2007A still includes buildmcr but it appears that the installer files
are present in the installation
• Performing this process in Windows is similar
• Graphics are allowed
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
[app1]$ ls
app1.m
[app1]$ cat app1.m
a=rand(1000,1000);
b=rand(1000,1000);
tic
for i=1:1000
for j=1:1000
c(i,j)=0.;
for k=1:1000
c(i,j)=c(i,j)+a(i,k)*b(k,j);
end
end
end
toc
tic
a*b;
toc
[app1]$
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• Use the MATLAB Compiler (mcc) to create an application for the
app1.m script
[app1]$ mcc -m app1.m
sh: ifconfig: command not found
[app1]$ ls
app1
app1_main.c
mccExcludedFiles.log
app1.ctf
app1_mcc_component_data.c
readme.txt
app1.m
app1.prj
run_app1.sh
[app1]$
• The ls shows that mcc created several files
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• Copy the created files to the target system
– use tar to create an archive
– send tar file to remote system
– un-tar archive at target system
ON BUILD SYSTEM:
ON TARGET SYSTEM:
[app1]$ tar cf app1.tar .
[app1]$ tar xf app1.tar .
tar: ./app1.tar: file is the archive; not dumped
[app1]$
[app1]$ tar tf app1.tar
./
./readme.txt
./app1.prj
./run_app1.sh
./app1.ctf
…
./mccExcludedFiles.log
./app1_main.c
./app1
[app1]$
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• If the local system already has the version of MATLAB installed
–
–
–
–
this is the case for the build system
to test the program
no need to install the MCR files
use files at /usr/local/matlab2007b
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• Installing the MCR
– not required on build system
– not required on target if same version already installed
• Within a shell window, find the MCRInstaller.bin in the MATLAB
installation directory
– /usr/local/matlab2007b/toolbox/compiler/deploy/glnxa64/MCRInstaller.bin
– The underlined portion is determined by where the MATLAB distribution has been
installed
– The glnxa64 is the architecture, 64-bit Linux
– Copy to the target system
•
Execute the installer program
[app1]$ ./MCRInstaller.bin
AE6382
MATLAB Application Example
• Example performed on Linux
R2007B
• Installing the MCR
• This requires write access to
the /opt directory in this case
• The location can be moved but
the run scripts will need to be
altered
AE6382
MATLAB Application Example
• Example performed on Linux
R2007B
• Installing the MCR
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• Installing the MCR
• The MCR files were installed into
/opt/matlab/MATLAB_Component_Runtime/v77 (the default)
• This requires 469MB of disk in this case
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• Test on build system or target where appropriate MATLAB is already
installed
• Using run_app1.sh to execute the application
– This script takes care of all library path settings
[app1]$ ./run_app1.sh /usr/local/matlab2007b
-----------------------------------------Setting up environment variables
--Found MCR Java JRE version: 1.6.0
LD_LIBRARY_PATH is
.:/usr/local/matlab2007b/runtime/glnxa64:/usr/local/matlab2007b/bi
n/glnxa64:/usr/local/matlab2007b/sys/os/glnxa64:/usr/local/matlab2
007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/native_threads:/usr/l
ocal/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/server:/u
sr/local/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/clien
t:/usr/local/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64
Elapsed time is 27.425378 seconds.
Elapsed time is 0.287423 seconds.
[app1]$
AE6382
MATLAB Application Example
• Example performed on Linux R2007B
• On target system with MCR runtime files
• Using run_app1.sh to execute the application
– This script takes care of all library path settings
[app1]$ ./run_app1.sh /opt/MATLAB/MATLAB_Component_Runtime/v77
-----------------------------------------Setting up environment variables
--Found MCR Java JRE version: 1.6.0
LD_LIBRARY_PATH is
.:/opt/MATLAB/MATLAB_Component_Runtime/v77/runtime/glnxa64:/opt/M
ATLAB/MATLAB_Component_Runtime/v77/bin/glnxa64:/opt/MATLAB/MATLAB
_Component_Runtime/v77/sys/os/glnxa64:/opt/MATLAB/MATLAB_Componen
t_Runtime/v77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/native_thre
ads:/opt/MATLAB/MATLAB_Component_Runtime/v77/sys/java/jre/glnxa64
/jre1.6.0/lib/amd64/server:/opt/MATLAB/MATLAB_Component_Runtime/v
77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/client:/opt/MATLAB/MAT
LAB_Component_Runtime/v77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64
Extracting CTF archive. This may take a few seconds, depending on
the
size of your application. Please wait...
...CTF archive extraction complete.
Elapsed time is 27.418982 seconds.
Elapsed time is 0.281665 seconds.
[app1]$
AE6382
MATLAB Application Example
• The following slides demonstrate the same procedure under earlier
versions of MATLAB
• This example was also performed on Linux using MATLAB R2006A
AE6382
MATLAB Application Example
• MATLAB R2006A Linux
• Compile into a standalone version
1. cd /home/latham/matlab/app1
2. mcc –m m2.m
This results in the following files being created in this directory
• m2 (this is the executable program)
• m2_main.c
• m2_mcc_component_data.c
• m2.ctf (the component technology file)
• mccExcludedFiles.log
The two files displayed in bold text are the important files
AE6382
MATLAB Application Example
•
•
MATLAB R2006A Linux
Test the executable just created
– Find where MATLAB is installed on the system. In this case MATLAB is
installed in /usr/local/matlab_2006a
– Now setup the library path
export LD_LIBRARY_PATH=/usr/local/matlab_2006a/sys/os/glnx86:/usr/local/matlab_2006a/bin/glnx86
• The m2 executable can now be run
./m2
AE6382
MATLAB Application Example
•
•
MATLAB R2006A Linux
Once the program is working it can be exported to another
computer.
– The target system must have the same architecture
– The same OS (compatible version in case of Linux)
– The correct version of the MCR
•
Copy the generated files to the remote system
– scp m2 user@target:matlab/
– scp m2.ctf user@target:matlab/
– Note that the matlab directory already exists on the target system
AE6382
MATLAB Application Example
•
•
MATLAB R2006A Linux
Setting up the target system requires that the MATLAB runtime
library be available
– the correct version of MATLAB is already installed on the target
– the MCRInstaller files are installed
•
Older versions of MATLAB require that the MCRInstaller.zip file
be created on the system where the application is compiled
– use buildmcr command to create file
•
Copy this file to the target
AE6382
MATLAB Application Example
•
•
MATLAB R2006A Linux
On the target system and unpack the file.
– cd /home/latham/matlab
– unzip MCRInstaller.zip
•
•
This will create a directory tree for the version of MATLAB used. In
this case the directory is named v74.
To execute the m2 program on this remote system setup the library
paths with
–
export LD_LIBRARY_PATH=/home/latham/matlab/v74/sys/os/glnx86:/home/latham/matlab/v74/runtime/glnx86
• Now execute
• ./m2
AE6382
MATLAB Application Example
•
•
MATLAB R2006A Linux
On the target system and unpack the file.
– cd /home/latham/matlab
– unzip MCRInstaller.zip
•
•
This will create a directory tree for the version of MATLAB used. In
this case the directory is named v74.
To execute the m2 program on this remote system setup the library
paths with
–
export LD_LIBRARY_PATH=/home/latham/matlab/v74/sys/os/glnx86:/home/latham/matlab/v74/runtime/glnx86
• Now execute
• ./m2
AE6382
MATLAB Excel Component
AE6382
MATLAB Excel Component
•
•
MATLAB compiler can be used to create components for use in
Excel
As for the Standalone application
– the MCR runtime files are required on the target system
– the m-files are encased in the CTF file
– a VBA (Visual Basic for Applications) wrapper is created that provides
access
– a DLL (Windows shared library) is created that contains the compiled
component code
•
•
•
The component is made available to Excel using the Microsoft
Component Object Model (COM)
The component is accessible through Excel macros
No example currently available
AE6382
MATLAB Excel Interaction
•
•
The Windows version of MATLAB also has access to other COM
components installed on a Windows system
Using the Automation capability of COM
– an instance of Excel can be created by a MATLAB m-file
– cells, worksheets, etc can be manipulated by the MATLAB script
•
Requires knowledge of the Excel object model
– This information can be found in the Office CD and at
http://msdn.microsoft.com
– also some documents also at
http://www.ae.gatech.edu/classes/ae6382/documents/MS_scripting/
•
For code and output see
– http://www.ae.gatech.edu/classes/ae6382/samples/matlab/excel-1/
AE6382
MATLAB Excel Interaction
%
Create a COM server running Microsoft Excel
% Create an interface "eWorkBooks"
e = actxserver ('Excel.Application')
eWorkbooks = e.Workbooks
% e =
% eWorkbooks =
%
COM.excel.application
%
Interface.Microsoft_Excel_9.0_Object_Library.Workbooks
% Make the Excel frame window visible
% List all methods for that interface
e.Visible = 1;
eWorkbooks.invoke
% Use the get method on the Excel object "e"
% ans =
% to list all properties of the application:
%
e.get
%
% ans =
%
Application: [1x1Interface.Microsoft_Excel_9.0_
Add: 'handle Add(handle, [Optional]Variant)'
Close: 'void Close(handle)'
%
Item: 'handle Item(handle, Variant)'
%
Open: 'handle Open(handle, string, [Optional]Variant)'
%
OpenText: 'void OpenText(handle, string, [Optional]Variant)'
%Object_Library._Application]
%
%
Creator: 'xlCreatorCode'
Workbooks: [1x1 Interface.Microsoft_Excel_9.0_
%Object_Library.Workbooks]
%
%
%
%
% Add a new workbook "w",
% also creating a new interface
w = eWorkbooks.Add
Caption: 'Microsoft Excel - Book1'
CellDragAndDrop: 0
ClipboardFormats: {3x1 cell}
% w =
%
Interface.Microsoft_Excel_9.0_Object_Library._Workbook
Cursor: 'xlNorthwestArrow'
%
.
% Close Excel and delete the object
%
.
e.Quit;
e.delete;
AE6382
MATLAB Excel Interaction
•
•
The Windows version of MATLAB also has access to other COM
components installed on a Windows system
Using the Automation capability of COM
– an instance of Excel can be created by a MATLAB m-file
– cells, worksheets, etc can be manipulated by the MATLAB script
•
Requires knowledge of the Excel object model
– This information can be found in the Office CD and at
http://msdn.microsoft.com
– also some documents also at
http://www.ae.gatech.edu/classes/ae6382/documents/MS_scripting/
•
For code and output see
– http://www.ae.gatech.edu/classes/ae6382/samples/matlab/excel-1/
AE6382
MATLAB Builder for Java
AE6382
MATLAB Builder for Java
•
•
•
The MATLAB Builder for Java is an extension of the MATLAB
Compiler that will wrap m-files as Java classes
The wrapped classes can then be used (without a MATLAB license)
by any Java program
Requires the MCR files on the system where the classes will be
used
AE6382
MATLAB Java Interaction
•
•
Java and MATLAB are tightly bound together – rich environment
There is a Java Runtime Environment (JRE) included as part of the
MATLAB installation
– need to be aware of what version of Java MATLAB is using
•
•
•
•
version -java
MATLAB can use Java classes
MATLAB can call Java methods internally
A simple example of what can be done
– accessing the Java Swing classes to create a GUI with MATLAB
– works in all architectures
import javax.swing.*
J=JFrame(‘Hi there’)
L=JLabel(‘A Label’);
P=J.getContentPane
P.add(L)
J.setSize(200,200);
J.setVisible(1)
AE6382
Add External Function to MATLAB
AE6382
Add External Function to MATLAB
The MEX-Files capability is used to create a custom C/C++ or Fortran
coded function that can be used in MATLAB.
The process can be tedious. It requires creating a gateway function,
void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
that is called by MATLAB. This function is passed two variables that
indicate the number of input and output arrays. In addition, two other
C arrays are passed that contain pointers to the mxArray’s in the
case input. These pointers are used to access the data provided to
the function by the MATLAB call. The output array contains mxArray
pointers for the results. The result arrays are allocated by the C
program using the MATLAB API and their addresses passed back to
MATLAB. The mxArray type defines an array in MATLAB, it include
size, type (numeric, cell, …) and location.
AE6382