HAS-Motion Software Documentation

User Tools

Site Tools

You are here: Main Page » visual3d » documentation » third-party » Matlab
visual3d:documentation:third-party:matlab:matlab

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
visual3d:documentation:third-party:matlab:matlab [2024/07/16 17:02] – removed sgrangervisual3d:documentation:third-party:matlab:matlab [2024/07/17 15:46] (current) – created sgranger
Line 1: Line 1:
 +====== Matlab ======
 +
 +Matlab is a challenging program to interact with because each version of Matlab seems to be incompatible with previous versions; not completely incompatible, of course, but enough so to be a nuisance.
 +
 +Visual3D communicates with Matlab in 4 different ways.
 +
 +  - By [[#Export_Data_To_Matfile|exporting]] and importing mat files. The Matlab structures are documented on the internet.
 +  - Visual3D will [[#Call_MFile|call an exe function from a command]]. This is a kludgy but effective method because it is Matlab version independent. First, the Matlab m-files must be compiled into an executable. There are Matlab restrictions on the kinds of m-files that can be compiled. These restrictions vary from version to version in Matlab. The Visual3D command allows the export of a mat file, the Matlab executable reads this mat file as its input, processes the data, then exports a mat file. Visual3D then imports this matfile.
 +  - Release 12 and 13 of Matlab can be [[#Integrating_Matlab_dlls|compiled into a dll]] (this is documented on the website). A header file must be written telling Visual3D how to call the dll; the dll then appears as a command in the Visual3D pipeline.\\
 +The Matlab dll's required for release 12 are the default files in Visual3D.\\
 +To use Matlab release 13, the user should delete the release 12 dll's from the Visual3D installation folder, so that Visual3D links to the release 13 dll's on the computer.\\
 +Matlab Release 14 compiler version 1 cannot be integrated, but Matlab Release 14 compiler version 2 can be, albeit with a different architecture in the compiled code.\\
 +Matlab release 15 can also be integrated, but with another architecture in the compiled code.\\
 +
 +
 +=== Matlab dll's installed during Visual3D Installation ===
 +
 +Visual3D's installation program places some Matlab dll's in the same folder as Visual3D.exe These dll's are from Matlab Release 12. If you have a licence to a more recent version of Matlab, you should delete these dll's from the folder containing Visual3D because you will want to use the dll's from your version of Matlab.
 +
 +Remove the following dll's:
 +
 +libeng.dll
 +libmat.dll
 +libmi.dll
 +libmx.dll
 +libut.dll
 +With the removal of these dll's Visual3D will search your **PATH** to find the installed Matlab dll's.
 +
 +=== Exporting signals to a Matlab .mat file ===
 +
 +A useful function of the Visual 3D scripting language is its ability to communicate with Matlab, a programming language specifically designed for technical computing.
 +
 +Data can be exported from Visual 3D to a MAT file by using the **Export_Data_To_Matfile** command. This command allows you to save signal data and parameter data from Visual 3D into MAT format so it can be read by a Matlab function. You must specify the file name of the file from which the data is to be taken, the signal name, the signal type, whether or not the signal is processed or not, and the output name. The output name is simply the name of the variable that is saved in the MAT file; this is not necessarily the same as the signal name (see below). In addition to this, if you want to export parameters (data from the PARAMETERS branch of the data tree), you can include the **PARAMETER_GROUPS, PARAMETER_NAMES, and OUTPUT_PARAMETER_NAME.**
 +
 +As an example, Visual3D will export data to Matlab (.mat) files using the following pipeline command syntax. This example was derived using the ExampleWalk.c3d file available on the website.
 +
 +**Export_Data_To_Matfile**
 +**/FILE_NAME=**c:demo filesMatlabtestmat.mat
 +**/SIGNAL_TYPES=**TARGET+TARGET+TARGET+ANALOG+ANALOG
 +**/SIGNAL_NAMES=**RFT1+RFT2+RFT3+FZ2+EMG9
 +**/SIGNAL_FOLDER=**ORIGINAL+ORIGINAL+ORIGINAL+ORIGINAL+ORIGINAL
 +**/OUTPUT_NAMES=**RFT1+RFT2+RFT3+FZ2+EMG9
 +**! /PARAMETER_NAMES=**
 +**! /PARAMETER_GROUPS=**
 +**! /OUTPUT_PARAMETER_NAMES=**
 +**;**
 +Note that Matlab 7.0 Release 14 is incompatible with Release 12 and 13; Visual3D currently import/exports data for release 12 and 13.
 +
 +== Matlab Cell Array ==
 +
 +Visual3D exports signals to a mat file as [[[https://blogs.mathworks.com/loren/2006/06/21/cell-arrays-and-their-contents/|cell arrays.]]]
 +
 +For example, the following command:
 +
 +**Export_Data_To_Matfile**
 +**/FILE_NAME=**c:demo filesMatlabtestmat.mat
 +**/SIGNAL_TYPES=**LINK_MODEL_BASED
 +**/SIGNAL_NAMES=**RANKLE_ANGLE
 +**/SIGNAL_FOLDER=**ORIGINAL
 +**/OUTPUT_NAMES=**RANK
 +**! /PARAMETER_NAMES=**
 +**! /PARAMETER_GROUPS=**
 +**! /OUTPUT_PARAMETER_NAMES=**
 +**;**
 +places 4 cell arrays into the matfile.
 +
 +RANK contains the contents of the signal RANKLE_ANGLE
 +FILE_NAME contains the names of the associated files in Visual3D
 +FRAME_RATE contains the Point Rate in Visual3D
 +ANALOG_VIDEO_FRAME_RATE contains the ratio analog rate to point rate
 +to extract the contents of the first file in the cell array for RANK, use the following Matlab syntax:
 +
 +vec= RANK{1}
 +\\
 +
 +
 +== Importing signals from a Matlab .mat file ==
 +
 +When exporting from Matlab, you need to use the option to save an old format (uncompressed) .mat file, as follows.
 +
 +<code>
 +save('testmat.mat', '-v6')
 +</code>
 +
 +Data can be imported to Visual3D using a syntax similar to export.
 +
 +**Import_Data_From_Matfile**
 +**/FILE_NAME=**c:\demo files\Matlab\testmat.mat
 +**/SIGNAL_TYPES=**TARGET+TARGET+TARGET+ANALOG+ANALOG
 +**/SIGNAL_NAMES=**RFT1A+RFT2A+RFT3A+FZ2A+EMG9A
 +**/SIGNAL_FOLDER**PROCESSED
 +**/INPUT_NAMES=**RFT1+RFT2+RFT3+FZ2+EMG9
 +**;**
 +== Format of the mat file for Visual3D ==
 +
 +The format of the matfile is specific to Visual3D. The following example demonstrates a simple use of the mat file that reveals the particular syntax expected by Visual3D.
 +
 +! ---------------------------------------------------------------------
 +! The example m-file is listed here.
 +! To compile the m-file
 +! Switch to dos (Command Prompt)
 +! Change to directory containing the m-file
 +! To create the executable
 +! mcc -p average_3targets_return_target
 +!
 +! edit average_3targets_return_target.m
 +! and add the following code
 +! ---------------------------------------------------------------------
 +function testmfile
 +% load the file that was written out by C-Motion Visual3D
 +load c:\temp\3Targets_In.mat;
 +% loop throught the elements
 +for file=1:length(SIGNAL1_IN)
 +[n1,n2]=size(SIGNAL1_IN{file});
 +for frame=1:n1
 +% Lets average the targets.
 +if ((SIGNAL1_IN{file}(frame,1) == -999999)| ...
 +(SIGNAL2_IN{file}(frame,1) == -999999)| ...
 +(SIGNAL3_IN{file}(frame,1) == -999999))
 +SIGNAL_OUT{file}(frame,1)=-999999.0; % retain the integrity of the missing points.
 +SIGNAL_OUT{file}(frame,2)=-999999.0; % retain the integrity of the missing points.
 +SIGNAL_OUT{file}(frame,3)=-999999.0; % retain the integrity of the missing points.
 +SIGNAL_OUT{file}(frame,4)=-999999.0; % retain the integrity of the missing points.
 +SIGNAL_OUT{file}(frame,5)=-999999.0; % retain the integrity of the missing points.
 +else
 +SIGNAL_OUT{file}(frame,1)=(SIGNAL1_IN{file}(frame,1) +SIGNAL2_IN{file}(frame,1)
 ++SIGNAL3_IN{file}(frame,1))/3;
 +SIGNAL_OUT{file}(frame,2)=(SIGNAL1_IN{file}(frame,2) +SIGNAL2_IN{file}(frame,2)
 ++SIGNAL3_IN{file}(frame,2))/3;
 +SIGNAL_OUT{file}(frame,3)=(SIGNAL1_IN{file}(frame,3) +SIGNAL2_IN{file}(frame,3)
 ++SIGNAL3_IN{file}(frame,3))/3;
 +SIGNAL_OUT{file}(frame,4)=(SIGNAL1_IN{file}(frame,4) +SIGNAL2_IN{file}(frame,4)
 ++SIGNAL3_IN{file}(frame,4))/3;
 +SIGNAL_OUT{file}(frame,5)=(SIGNAL1_IN{file}(frame,5) +SIGNAL2_IN{file}(frame,5)
 ++SIGNAL3_IN{file}(frame,5))/3;
 +end
 +end
 +end
 +===== Integrating Matlab Executables =====
 +
 +One of the most useful functions of the Visual 3D scripting language is its ability to communicate with Matlab, a programming language specifically designed for technical computing. Programs designed to perform data processing not handled by Visual 3D can be written in Matlab and called by a Visual 3D script. Data processed by Matlab programs can then be sent back to Visual 3D as new events or signals.
 +
 +It is assumed that you know how to create m-files in the Matlab programming environment. If you do not know how to use Matlab, I recommend you take a look at the manual ’Getting Started with Matlab’; it provides a good overview of the Matlab environment and basic programming syntax. As well, you should have a recent version of Matlab (release 12 or higher) and the Matlab Compiler installed on your computer.
 +
 +Communication between Visual 3D and compiled Matlab functions takes place by way of MAT files. MAT files are data files, readable only by Matlab and Visual 3D, that can contain any number of signal, event, or parameter data.
 +
 +Data can be exported from Visual 3D to a MAT file by using the EXPORT_MATFILE command. This command allows you to save signal data and parameter data from Visual 3D into MAT format so it can be read by a Matlab function. You must specify the file name of the file from which the data is to be taken, the signal name, the signal type, whether or not the signal is processed or not, and the output name. The output name is simply the name of the variable that is saved in the MAT file; this is not necessarily the same as the signal name (see below). In addition to this, if you want to export parameters (data from the PARAMETERS branch of the data tree), you can include the PARAMETER_GROUPS, PARAMETER_NAMES, and OUTPUT_PARAMETER_NAME lines as shown below.
 +
 +[[https://www.has-motion.com/download/Matlab/average_3targets_return_target.m|average_3targets_return_target.m]]
 +
 +! ---------------------------------------------------------------
 +! CALL_MFILE
 +! - save specified signals to a mat file
 +! - run an exe compiled from Matlab that
 +! reads a mat file
 +! creates a new mat file
 +! - load the new mat file into Visual3D
 +!
 +!/MFILE_NAME= name of the Matlab executable
 +! specify the entire directory path
 +!/OUTPUT_FILE= name of the mat file exported
 +! from Visual3D
 +!/OUTPUT_SIGNAL_NAMES= Visual3D Signals to export
 +!/OUTPUT_SIGNAL_TYPES= Visual3D Signal Type
 +!/OUTPUT_SIGNAL_PROCESSED= Visual3D Processed Flag
 +!
 +!/OUTPUT_NAMES= Signal names used in the exported
 +! file. These are the names that
 +! the .m file will see
 +!
 +!/INPUT_FILE= name of the mat file save by the Matlab exe
 +!/INPUT_NAMES= signals stored by the Matlab exe
 +!
 +!/INPUT_SIGNAL_NAMES= names assigned to these signals
 +! when they are imported to Visual3D
 +!/INPUT_SIGNAL_TYPES= types of signals imported to Visual3D
 +!
 +! This example uses the ExampleTrial data that can be downloaded from the website.
 +! --------------------------------------------------------------- ---------------------
 +**CALL_MFILE**
 +**/MFILE_NAME=** [[https://www.has-motion.com/download/Matlab/Average_3Targets_Return_Target.exe|average_3targets_return_target.exe]]
 +**/OUTPUT_FILE=** c:temp3Targets_in.mat
 +**/OUTPUT_SIGNAL_NAMES=** RFT1+RFT2+RFT3
 +**/OUTPUT_SIGNAL_TYPES=** TARGET+TARGET+TARGET
 +**/OUTPUT_SIGNAL_PROCESSED=** FALSE+FALSE+FALSE
 +**/OUTPUT_NAMES=** SIGNAL1_IN+SIGNAL2_IN+SIGNAL3_IN
 +**/INPUT_FILE=** c:tempaveraged_targets_out.mat
 +**/INPUT_SIGNAL_NAMES=**RFT AVE
 +**/INPUT_SIGNAL_TYPES=**TARGET
 +**/INPUT_NAMES=**SIGNAL_OUT;
 +The CALL_MFILE command performs the following tasks:
 +
 +  - Exports data to a MAT file
 +  - Runs a compiled Matlab-based .exe file to load the data, process the data, and create a new MAT file containing the processed data
 +  - Imports the data from the second MAT file back into Visual 3D
 +
 +  * The OUTPUT_FILE parameter specifies the name of the MAT file to create
 +  * OUTPUT_SIGNAL_NAMES, OUTPUT_SIGNAL_TYPES, and OUTPUT_SIGNAL_PROCESSED refer to the cell array variables that the Matlab function is expecting.
 +  * MFILE_NAME specifies the name of the compiled Matlab function to run (this must be an .exe file).
 +  * INPUT_FILE specifies the MAT file from which the processed data is imported
 +  * INPUT_NAMES are the variable names (in the m-file) that are read.
 +  * The processed data is placed in the signals specified by INPUT_SIGNAL_NAMES and INPUT_SIGNAL_TYPES (this data is considered "processed" by default).
 +
 +To clarify, the basic algorithm of the above CALL_MFILE command is illustrated below:
 +
 +{{:integrateMatlab.gif}}\\
 +
 +
 +Note that, in order to pass the time signal to a MAT file, you should use "TIME" for the signal name, ”FRAME_NUMBERS” for the signal type, and "FALS" for processed.
 +
 +===== Integrating Matlab dlls =====
 +
 +In a nutshell, to create a Matlab plugin you need to compile a Matlab script into a dll create a text file that describes to Visual3D what it's interface looks like and put both files in a directory named Matlab-Plugins in the Visual3D plugins directory.
 +
 +**The text file must have a .txt extension and the same name as the .dll it describes. An example would be:**
 +
 +$ ls MathLab-Plugins # (or 'dir' if you are a DOS person)
 +swindowlib.dll
 +swindowlib.txt
 +\\
 +
 +
 +$ cat swindowlib.txt
 +swindow
 +/SIGNAL%%__%%IN%%__%%SIGIN
 +/INT%%__%%IN%%__%%WINSIZE
 +/INT%%__%%IN%%__%%WINSTEP
 +/SIGNAL%%__%%OUT%%__%%SIGOUT
 +;
 +**This tells Visual3D that swindowlib.dll has an entry point named swindo that takes 4 parameters:**
 +
 +  - LSIGIN (an input signal)
 +  - WINSIZE ( an input integer)
 +  - WINSTEP (an input integer)
 +  - SIGOUT (an output signal).
 +
 +**Note: Signals are specified as TYPE:FOLDER:NAME**
 +
 +**To Compile the dll**
 +
 +function makedll(sName,varargin)
 +\\
 +
 +
 +%MAKEDLL Compiles a Matlab function into a DLL.
 +%
 +% Usage:
 +% makedll(MFilename,[options])
 +%
 +% Description:
 +% This function compiles a Matlab DLL from the M-file provided. Only a single file should
 +% be given, since dependencies are determined automatically. That is, any other M-file
 +% called will automatically be compiled and linked into the resulting DLL. Additional
 +% options to the MCC program can be provided, but none should be necessary in most cases.
 +%
 +% The resulting file will be called mfilenamelib.dll, and will appear in the current
 +% directory.
 +%
 +% Parameters:
 +% MFilename The name of the M-file containing the entry-point function.
 +% [options] A variable number of strings which are appended to the standard compiler options.
 +%
 +% Remarks:
 +% There are some serious limitations on the kind of Matlab code which can be compiled
 +% into a stand-alone DLL. See the document "Matlab DLL Limitations.doc" for a list of
 +% rules to follow.
 +%
 +% Copyright (C) 2004 C-Motion
 +% Author: Paul Cisek
 +% Created: 6/28/2004 mfilename
 +**Note: Remember to verify the path.**
 +
 +% Path to Visual3D %%**%%* VERIFY THIS %%**%%*
 +vis3dpath = 'c:\program files\visual3d v3';
 +%cd c:\Matlab\matv3d
 +% Build the command to the compiler
 +options = {};
 +command = ['mcc -t -h -W lib:',sName,'lib -T link:lib ',sName];
 +%command = [command,' Matlaberror.c'];
 +if nargin>1
 +command = [command,sprintf(' %s',varargin{:})];
 +end
 +options = {'-O optimize_integer_for_loops:on'};
 +if length(options)>1
 +command = [command,sprintf(' %s',options{:})];
 +end
 +% Run the compiler
 +disp(['Running command: ',command]);
 +eval(command);
 +% Copy the files
 +dos(['copy ',sName,'lib.dll "',vis3dpath,'\Matlab-plugins"']);
 +dos(['copy ',sName,'lib.txt "',vis3dpath,'\Matlab-plugins"']);
 +**Example files:**
 +
 +test.m (Matlab file to be compiled into test.dll)
 +function out = stupid_test(in)
 +out = in;
 +**V3D pipeline command: test.v3d**
 +
 +test
 +/SIGNAL%%__%%IN%%__%%IN=TARGET::ORIGINAL::RFT1
 +/SIGNAL%%__%%OUT%%__%%OUT=DERIVED::MATLAB::MTL1
 +;
 +**test.txt (lets V3D know the interface to the dll)**
 +
 +stupid_test
 +/SIGNAL%%__%%IN%%__%%IN
 +/SIGNAL%%__%%OUT%%__%%OUT
 +;
 +===== Transferring Information between Visual3D and MATLAB =====
 +
 +**Please note for examples below:** When referring to segments in a pipeline script, it is better to use Visual3D’s internal three letter segment names (e.g., RTH instead of Right Thigh, etc.). For further details, see the segment_names.ini file installed in the Config folder along with Visual3D.exe under Program Files.
 +
 +==== Generating Visual3D Pipeline Scripts Using MATLAB ====
 +
 +Visual3D’s flexible pipeline scripting architecture can be further extended by automatically generating and pipeline scripts using MATLAB. Download this ([[https://www.has-motion.com/download/examples/MatlabLaunchVisual3D.zip|MatlabLaunchVisual3D]]) zip file to follow along with the next example. This remainder of this section assumes that you have stored the files in **c:\Visual3D\data\Matlab**.
 +
 +The MatlabLaunchVisual3D zip file contains three Matlab functions (generatev3DPipeline, runV3DPipeline, loadMATData). Begin by copying the command below into the Matlab command line.
 +
 +<code>
 +generateV3DPipeline('C:\Visual3D\data\Matlab');
 +</code>
 +
 +This function should produce the Visual3D pipeline **C:\Visual3D\data\Matlab\example.v3s** attached in the MatlabLaunchVisual3D zip file download. This pipeline can be loaded into Visual3D and executed. This pipeline will export a model based signal to a .mat file (**c:\Visual3D\data\Matlab\example.mat**)
 +
 +Note: this function will probably need to be modified to reflect the user’s specific set of motion capture and model template files, etc.
 +
 +A little background: generating a pipeline script using MATLAB is done in three steps:
 +
 +  - Open a file
 +  - Write text strings that conform to Visual3D's pipeline syntax.
 +  - Close the file
 +
 +For example:
 +
 +<code>
 +fid = fopen(’C:\Visual3D\data\Matlab\pipeline.v3s’, ’w’);
 +fprintf(fid,’Open_File\r\n’);
 +fprintf(fid, '/FILE_NAME=%s\r\n’,’C:\Visual3D\data\Matlab\walk.c3d’);
 +fprintf(fid, ';\r\n’);
 +fclose(fid);
 +</code>
 +
 +When these commands are executed, a new file (**C:\Visual3D\data\Matlab\pipeline.v3s**) is created that contains pipeline script command that can be later run using Visual3D. **Note for C/C++ programmers:** fprintf() in MATLAB works very much like printf() in the standard C library. See MATLAB’s online help for more information on fprintf(). Also, no error checking is done in the above example to increase readability.
 +
 +==== Running Visual3D Pipeline Scripts From MATLAB ====
 +
 +It is also possible, however, to have **Matlab launch Visual3D and execute this pipeline automatically.**
 +
 +Visual3D can be run from the Windows command line prompt along with the /s switch followed by the name of a pipeline script to execute.
 +
 +MATLAB provides the corresponding dos() function to run Windows applications. For example type the following at the Matlab command prompt:
 +
 +<code>
 +dos(’Visual3D.exe /s C:\Visual3D\data\Matlab\example.v3s’);
 +</code>
 +
 +Important: Visual3D.exe must be in the user’s path in order for the MATLAB dos() command to work properly. Alternatively, the full path to the application can be used instead
 +
 +<code>
 +dos(’"C:\Program Files\Visual3D v3\Visual3D.exe" /s C:\Visual3D\data\Matlab\example.v3s’ '&'];
 +</code>
 +
 +The Visual3D processing results dialog that results should reflect the above pipeline.
 +
 +**Note to edit the path on Windows XP:**
 +
 +  - Click Start menu, then right click My Computer and select Properties.
 +  - Click the Adanced tab and then the Environment Variables button.
 +  - The path variable is in the System variables section.
 +
 +See the **runV3DPipeline()** MATLAB function in the example files linked at the start of this topic for a working example of how to run this procedure from within an m-file.
 +
 +At the Matlab prompt type:
 +
 +<code>
 +runV3DPipeline('C:\Visual3D\data\Matlab\example.v3s'); 
 +</code>
 +
 +Note that Visual3D remains active at the end of this function. If you want Visual3D to exit after running the pipeline, place the following command at the end of the pipeline.
 +
 +<code>
 +Exit_Workspace
 +;
 +</code>
 +
 +==== Loading and Parsing MAT Files Generated With Visual3D ====
 +
 +MAT files are loaded using the load() MATLAB function. For example type the following at the Matlab command prompt:
 +
 +**matData = load(’C:\Visual3D\data\Matlab\example.mat’);**
 +
 +The names of all the fields present in the file are found using the fieldnames() MATLAB function. For example:
 +
 +**names = fieldnames(matData);**
 +
 +Finally, the actually data is obtained using the getfield() MATLAB function. For example:
 +
 +**tmp = getfield(matData,names{4});**\\
 +**if numel(tmp) > 0**\\
 +**data = tmp{1};**\\
 +**disp(data);                % displays the data on the screen**\\
 +**end**
 +
 +See the **loadMATData()** MATLAB function in the example files linked at the start of this topic for an example of how to load and parse the data fields in a MAT file.
 +
 +At the Matlab command prompt enter:
 +
 +**loadMATData('c:\Visual3D\Data\Matlab\example.mat');**
 +
 +The example function provides a good starting point for parsing MAT files, however, problem specific details need to be considered by the end user.
 +
 +===== FIR and IRR Filter Design and Analysis =====
 +
 +Matlab's [[https://www.mathworks.com/help/dsp/filter-design-and-analysis.html?category=filter-design-and-analysis&s_tid=CRUX_topnav|Filter Design and Analysis]] tool allows you to design and validate [[https://www.mathworks.com/help/signal/ug/fir-filter-design.html|FIR]] and [[https://www.mathworks.com/help/signal/ug/iir-filter-design.html|IRR]] filters. Using the Filter Design and Analysis (FDA) tool requires the DSP System Toolbox to be installed as an Add On in Matlab. Once this Add On is installed:
 +
 +<code>
 +filterDesigner
 +</code>
 +
 +Running filterDesigner will open an interface that can be used to design and analyze filters. The design techniques detailed in Matlab's documentation will compute filter coefficients based on the specified filter parameters, which can then be used in Visual3D. More information [[https://www.mathworks.com/help/dsp/ug/using-filter-designer.html|here]].
 +
 +<code>
 +filterBuilder
 +</code>
 +
 +Running filterBuilder will start an interactive tool for building and testing filters. It both creates filter coefficients and can be used to filter test data. More information [[https://www.mathworks.com/help/dsp/ug/the-graphical-interface-to-fdesign.html|here]].
 +
 +===== Visual3D Pipeline Commands =====
 +
 +==== Call_MFile ====
 +
 +Exports signals to an MFile routine, and imports results back to Visual3D. This should probably be simply called [[#Integrating_Matlab_Executables|Call_Matlab_Executable]]. See [[#Integrating_Matlab_Executables|this section]] also.
 +
 +<code>
 +Call_MFile
 +! /MFILE_NAME=
 +! /USE_CALIBRATION_FILE=FALSE
 +! /USE_NAN_FOR_DATANOTFOUND=FALSE
 +! /INPUT_FILE=
 +/INPUT_NAMES=
 +/INPUT_SIGNAL_TYPES=
 +! /INPUT_SIGNAL_FOLDERS=
 +/INPUT_SIGNAL_NAMES=
 +! /OUTPUT_FILE=
 +/OUTPUT_SIGNAL_TYPES=
 +/OUTPUT_SIGNAL_FOLDER=
 +/OUTPUT_SIGNAL_NAMES=
 +/OUTPUT_NAMES=
 +! /PARAMETER_NAMES=
 +! /PARAMETER_GROUPS=
 +! /OUTPUT_PARAMETER_NAMES=
 +;
 +</code>
 +
 +==== Import_Data_From_Matfile ====
 +
 +Imports specified signals from a Matfile.
 +
 +<code>
 +Import_Data_From_Matfile
 +/SIGNAL_TYPES=
 +!/SIGNAL_FOLDER=PROCESSED
 +/SIGNAL_NAMES=
 +/FILE_NAME=
 +/MATLAB_NAMES=
 +;
 +</code>
 +
 +This function expects the .mat file to have a specific input. For example, within MATLAB, we write and run the following script:
 +
 +<code>
 +array = linspace(0,10,100);
 +importThisData = {sin(array)};
 +
 +FRAME_RATE{1,1} = 180;
 +ANALOG_VIDEO_FRAME_RATIO{1,1} = 0;
 +FILE_PATH = {'C:\Users\Public\MATLAB\Sub01_Walk001.c3d'};
 +
 +matDirectory = 'C:\Users\Public\MATLAB\Sub01_Walk001.mat';
 +save(matDirectory,'importThisData','FILE_PATH','FRAME_RATE','ANALOG_VIDEO_FRAME_RATIO','-v6')
 +</code>
 +
 +What is really important is the FILE_PATH. Within your Visual3D workspace, you will presumably have loaded some .c3d files (in this case, Sub01_Walk001.c3d). The address under FILE_PATH must match the location of the original .c3d files, even if that path is different from the path of the Visual3D workspace. If the Import_Data_From_Matfile command executes but doesn't create or populate a folder in the Visual3D workspace, check the FILE_PATH.
 +
 +FILE_PATH is different from FILE_NAME, which should be the path to the .mat file you wish to import data from.
 +
 +==== Export_Data_To_Matfile ====
 +
 +This command is similar to [[#Export_Data_To_Matlab|Export_Data_To_Matlab]] except that the resulting data is placed in an Matlab .mat file rather than being pushed into the Matlab Workspace
 +
 +{{:export_data_to_matfile.png}}
 +
 +It is very important to note that Visual3D expresses an unknown value (e.g. a TARGET with residual of -1) using the value DATA_NOT_FOUND (-99999). Matlab doesn't recognize this Visual3D expression, so you may want to replace DATA_NOT_FOUND with NaN (e.g. /USE_NAN_FOR_DATANOTFOUND=TRUE). If you don't and you list the contents of the variable in Matlab, your data may be scaled to 1.e5, which means that most of your values may end up looking as if they were zero. If you enter DATA_NOT_FOUND, you can have your m-file search for this value, so that you can continue to perform matrix math in Matlab (which won't process NaN in an array). Text version below:
 +
 +<code>
 +Export_Data_To_Matfile
 +! /SIGNAL_TYPES=
 +! /SIGNAL_FOLDER=
 +! /SIGNAL_NAMES=
 +! /FILE_NAME=
 +/MATLAB_NAMES=
 +! /PARAMETER_NAMES=
 +! /PARAMETER_GROUPS=
 +! /OUTPUT_PARAMETER_NAMES=
 +! /USE_NAN_FOR_DATANOTFOUND=FALSE
 +;
 +</code>
 +
 +==== Get_From_Matlab ====
 +
 +Uses DCOM to put data from one active file in the Visual3D Workspace into Matlab (e.g. with Matlab running concurrently).
 +
 +<code>
 +Get_From_Matlab
 +/Matlab_Item_Name= the name of the signal in Matlab
 +/Signal_Types= the Visual3D Type
 +/Signal_Names= the Visual3D Name
 +/Signal_Folder= the Visual3D Folder
 +;
 +</code>
 +
 +In Matlab the signal should appear with the Matlab_Item_Name. This is necessary because Matlab does not allow multiple signals with the same name but with a different type.
 +
 +==== Put_To_Matlab ====
 +
 +Uses DCOM to put data from one active file in the Visual3D Workspace into Matlab (e.g. with Matlab running concurrently).
 +
 +<code>
 +Put_To_Matlab
 +/Matlab_Item_Name= the name of the signal in Matlab
 +/Signal_Types= the Visual3D Type
 +/Signal_Names= the Visual3D Name
 +/Signal_Folder= the Visual3D Folder
 +;
 +</code>
 +
 +In Matlab the signal will appear with the Matlab_Item_Name. This is necessary because Matlab does not allow multiple signals with the same name but with a different type.
 +
 +==== Export_Data_To_Matlab ====
 +
 +**THIS COMMAND DOES NOT WORK IN ANY VERSION OF MATLAB NEWER THAN Matlab R13. Use the Export_Data_to_Matfile command instead**
 +
 +Visual3D will use DCOM to push signal directly in the Matlab Workspace without having to save the m-file. This command is different from Put_To_Matlab because it allows the data to be exported from all ACTIVE_FILES. This is possible because it uses a Matlab struct_array to store the data.
 +
 +\\
 +
 +
 +**Export_Data_To_Matlab**
 +
 +|**/MATLAB_ITEM_NAME=**        |the name of the struct_array in Matlab                 |
 +|**/SIGNAL_TYPES=**            |the Visual3D Types                                     |
 +|**/SIGNAL_NAMES=**            |the Visual3D Names                                     |
 +|**/SIGNAL_FOLDER=**           |the Visual3D Folders                                   |
 +|**/OUTPUT_NAMES=**            |the names of the signal within the struct array        |
 +|**/PARAMETER_GROUPS**         |the C3D Parameter Group                                |
 +|**/PARAMETER_NAMES=**         |the C3D Parameter Name                                 |
 +|**/OUTPUT_PARAMETER_NAMES=**  |the Matlab name for the C3D Parameter                  |
 +|**/USE_NAN_FOR_DATANOTFOUND=**|DATANOTFOUND is the Visual3D name for a missing signal.|
 +
 +\\
 +
 +
 +For example, export 3 TARGETS (LFT1, LFT2, LFT3) from Visual3D to Matlab.
 +
 +Invoke the Pipeline Edit Dialog
 +
 +{{:Export_Data_To_Matlab_Dlg1.gif}}\\
 +
 +
 +\\
 +
 +
 +Add the name of the Matlab struct array and the first TARGET. Select the Add Data button
 +
 +{{:Export_Data_To_Matlab_Dlg2.gif}}\\
 +
 +
 +\\
 +
 +
 +Add the remaining 2 signals
 +
 +{{:Export_Data_To_Matlab_Dlg3.gif}}\\
 +
 +
 +The text version of the pipeline command should look like this:
 +
 +**Export_Data_To_Matlab**
 +
 +|**/MATLAB_ITEM_NAME=**          |TEST                      |
 +|**/SIGNAL_TYPES=**              |TARGET+TARGET+TARGET      |
 +|**/SIGNAL_NAMES=**              |LFT1+LFT2+LFT3            |
 +|**/SIGNAL_FOLDER=**             |ORIGINAL+ORIGINAL+ORIGINAL|
 +|**/OUTPUT_NAMES=**              |O_LFT1+O_LFT2+O_LFT3      |
 +|**/PARAMETER_GROUPS**           |                          |
 +|**/PARAMETER_NAMES=**           |                          |
 +|**/OUTPUT_PARAMETER_NAMES=**    |                          |
 +|**/USE_NAN_FOR_DATA_NOT_FOUND=**|TRUE                      |
 +
 +\\
 +
 +
 +Execute the command with 4 active files in the Visual3D Workspace.
 +
 +\\
 +
 +
 +Matlab should contain the following struct_array
 +
 +» TEST
 +
 +TEST =
 +
 +ANALOG_VIDEO_FRAME_RATIO: {4x1 cell}
 +FRAME_RATE: {4x1 cell}
 +FILE_NAME: {4x1 cell}
 +  O_LFT1: {4x1 cell}
 +  O_LFT2: {4x1 cell}
 +  O_LFT3: {4x1 cell}
 +\\
 +
 +
 +» TEST.O_LFT1
 +
 +ans =
 +
 +[230x5 double]
 +[231x5 double]
 +[220x5 double]
 +[211x5 double]
 +==== Import_Data_From_Matlab ====
 +
 +Visual3D will use DCOM to pull signals directly from the Matlab Workspace without having to save the m-file. This command is different from [[#Get_From_Matlab|Get_From_Matlab]] because it allows the data to be imported to multiple files. This is possible because it uses a Matlab struct_array to store the data.
 +
 +\\
 +
 +
 +**Import_Data_From_Matlab**
 +
 +|**/MATLAB_ITEM_NAME=**|the name of the Matlab struct_array            |
 +|                      |                                               |
 +|**/SIGNAL_TYPES=**    |the Visual3D Types                             |
 +|                      |                                               |
 +|**/SIGNAL_NAMES=**    |the Visual3D Names                             |
 +|                      |                                               |
 +|**/SIGNAL_FOLDER=**   |the Visual3D Folders                           |
 +|                      |                                               |
 +|**/INPUT_NAMES=**     |the names of the signal within the struct array|
 +|                      |                                               |
 +
 +\\
 +
 +
 +{{:Import_Data_From_Matlab_Dlg.gif}}
 +
 +==== Eval_In_Matlab ====
 +
 +Causes a concurrent version of Matlab to execute the specified Matlab function.
 +
 +**Eval_In_Matlab**\\
 +/Matlab_Command= The neame of the Matlab procedure that is to be executed\\
 +**;**
 +
 +===== Examples =====
 +
 +=== mFile for Tagging Files Based on Vicon Workstation Description ===
 +
 +This mFile was kindly provided by one of our customers.
 +
 +Vicon Workstation provides a DESCRIPTION parameter for a file name. It may be convenient to use that DESCRIPTION to TAG the c3d file in Visual3D.
 +
 +This [[https://www.has-motion.com/download/Matlab/Autotagger.m|Matlab mfile]] should be compiled, then called by Visual3D using the [[#Call_MFile|Call_MFile]] pipeline command.
 +
 +The mFile exports a Visual3D pipeline command that can loaded and run in Visual3D.
 +
 +=== Read a text file exported from Visual3D into Matlab ===
 +
 +This sample code [[Visual3D:Documentation:Third-Party:MATLAB:Matlab_Read_V3D_Text|Matlab_Read_V3D_Txt]] can be used to read a text file exported from Visual3D into Matlab.
 +
 +
  
visual3d/documentation/third-party/matlab/matlab.1721149355.txt.gz · Last modified: 2024/07/16 17:02 by sgranger