1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
/**
\page tutorial-visp-matlab Tutorial: Using ViSP and MATLAB
\tableofcontents
\section intro_visp_matlab Introduction
This tutorial shows how to invoke MATLAB functions from ViSP using MATLAB Engine. The MATLAB C/C++ engine library
contains routines that allow you to call MATLAB from your own programs, using MATLAB as a computation engine. This can
be used to extend ViSP functionality using MATLAB.
Standalone programs written using MATLAB engine communicates with MATLAB process using pipes on UNIX system and
Component Object Model (COM) interface on a Microsoft Windows system. MATLAB provides an API to start and end MATLAB
process, send and receive data, and send commands to be processed in MATLAB.
Using the MATLAB engine requires an installed version of MATLAB; you cannot run the MATLAB engine on a machine that
only has the MATLAB Runtime. Also, path to MATLAB runtime must be set in the PATH environment variable. For a 64bit
machine running Windows, the path is `path\to\MATLAB\R20XXy\bin\win64`.
For this tutorial, we create a vpMatrix object containing a 3x3 matrix and pass it to MATLAB sum function to compute a
column wise sum of the vpMatrix.
Note that all the material (source code and image) described in this tutorial is part of ViSP source code
(in `tutorial/matlab` folder) and could be found in https://github.com/lagadic/visp/tree/master/tutorial/matlab.
\section visp_matlab_cmake CMakeLists.txt file
In order to build a source code that mix ViSP and MATLAB you should first create a `CMakeLists.txt` file that tries to
find ViSP and MATLAB. In the following example we consider the case of the tutorial-matlab.cpp source file.
\code
cmake_minimum_required(VERSION 3.10)
project(visp-matlab)
find_package(VISP REQUIRED visp_core)
include_directories(${VISP_INCLUDE_DIRS})
# Matlab
find_package(Matlab COMPONENTS MX_LIBRARY ENG_LIBRARY REQUIRED)
include_directories(${Matlab_INCLUDE_DIRS})
add_executable(tutorial-matlab tutorial-matlab.cpp)
target_link_libraries(tutorial-matlab ${VISP_LIBRARIES} ${Matlab_LIBRARIES})
\endcode
To build this example when MATLAB is in your PATH, use:
$ cd tutorial/matlab
$ mkdir build && cd build
$ cmake .. -DVISP_DIR=<path to ViSP build dir>
\section visp_matlab_column_sum Call MATLAB function from ViSP program
This example shows the use of MATLAB engine in a ViSP program.
\include tutorial-matlab.cpp
The output of the program is the column-wise sum of the matrix stored in vpMatrix object computed using MATLAB.
\image html img-visp-matlab-result.jpg
Now we explain the main lines of the source.
First, we include matrix.h and engine.h libraries from MATLAB for matrix implementation and connection to MATLAB respectively. We also include the ViSP vpMatrix.h library for ViSP based matrix implementation and operation.
\snippet tutorial-matlab.cpp Include
The initial input is available in a ViSP matrix, which in our case is a 3x3 matrix. It contains numbers from 1 to 9 sequentially in a row-major order.
\snippet tutorial-matlab.cpp InputData
We then declare MATLAB variables i.e. Engine object reference and MATLAB matrix references for storing input and output MATLAB data. We also initialize the MATLAB matrix (of the same size as input vpMatrix) for storing input data using \e mxCreateDoubleMatrix().
\snippet tutorial-matlab.cpp MATLABVariables
Then we start a MATLAB engine process using \e engOpen() and assign the engine handle to the pre-declared Engine pointer \e ep. If the process initiation is unsuccessful, then \e engOpen() will return NULL and this program terminates with a failure.
\snippet tutorial-matlab.cpp EngineOpen
The contents of the vpMatrix is available in \e data attribute of vpMatrix class which points to a double array. This content is copied to the MATLAB matrix variable \e T of type double defined earlier. The \e mxGetPr() function returns a pointer to the first mxDouble element of the data.
\snippet tutorial-matlab.cpp CopyToVariable
The MATLAB variable is then put onto the MATLAB workspace.
\snippet tutorial-matlab.cpp AddToWorkspace
Once the matrix is available in the MATLAB workspace, we can use the \e engEvalString() function to evaluate an expression in MATLAB environment. So, we pass the MATLAB Engine the expression to determine the sum of each column of input matrix \e T and obtain an output matrix \e D which will be again stored in the MATLAB workspace. Since, ViSP matrix is row-major and MATLAB matrix is column-major, so we transpose the matrix \e T before evaluation.
\snippet tutorial-matlab.cpp EvalFunction
The MATLAB variable \e Dm is retrieved from the MATLAB workspace and stored in a local MATLAB array \e D.
\snippet tutorial-matlab.cpp GetFromWorkspace
We then copy the contents of MATLAB variable \e Dm to local double array \e res and print the result on the screen.
\snippet tutorial-matlab.cpp CopyFromVariable
Finally, we free the MATLAB variables, close MATLAB Engine and Exit
\snippet tutorial-matlab.cpp Exit
*/
|
