Damage Control FAQ

Something failed. Now what?

If you are reading this, you probably got an error message and you are seconds away from giving up. This is OK, I have given up on projects too. But before you decide to close this page and go about your business, perhaps you could give it an other chance. I wrote this page based on feedback I got, and it may well help you too!

---

I HATE compiling. Why don't you just give away the compiled binaries and let me go about my business?

While this would be the ideal solution, unfortunately there is a legal barrier that prevents me from doing it. The compiled binary files contain some of the Optotrak API code, which is the intellectual property of Northern Digital. Until I receive explicit permission to share the binary files, I can't just give them away as part of the toolbox. This is why you have to buy the API, and compile C-code on your computer. I know it's a hassle, but it's the best I can do. This is what you get when you use proprietary software.

---

RUNME.m fails because it says that a .h file is missing. Why?

If you made sure you have copied the header files to the source directory, you could check whether they were correctly edited:

• Add these lines as they appear here to the top of ndopto.h:

#include "ndtypes.h"
#include "ndpack.h"
#include "ndhost.h"

• Make sure that these files are references as:

#include "xxx.h" ...and NOT as: #include <xxx.h> This way, the compiler will know to use the local files, and will not fail searching for them in a default search path where.

---

RUNME.m fails when trying to compile, because it says I don't have a compiler. What should I do?

You should have some error message during the compilation process. If you got something like:

No supported C++ compiler found.

it means that the toolbox couldn't compile the C-code because it doesn't know how to handle your C-compiler. During development, six different compilers were used, five of which proved usable. These are:

• Microsoft Visual C++ 2015 Professional
• Microsoft Visual C++ 2015
• MinGW64 Compiler with Windows 10 SDK or later (C++)
• Microsoft Visual C++ 2017
• g++

You could try installing one of the Microsoft ones, or you may have something else installed. If you have a really old set-up, you could try Borland's Turbo C++, and Matlab R2008a.

First of all, type in this command, and see if your Matlab can see a compiler:

>> mex -setup C++

On a Mac, for example (on which the MOTOM toolbox does NOT work!) I am getting something similar to this:

>> mex -setup C++
MEX configured to use 'Xcode Clang++' for C++ language compilation.
Warning: The MATLAB C and Fortran API has changed to support MATLAB
	 variables with more than 2^32-1 elements. You will be required
	 to update your code to utilize the new API.
	 You can find more information about this at:
	 http://www.mathworks.com/help/matlab/matlab_external/upgrading-mex-files-to-use-64-bit-api.html.
>> 

If nothing like this gets returned, you should install a supported C compiler. The Optotrak API prefers a Microsoft Visual C++ compiler. The 'stock' minGW compiler does not seem to work! The supported compilers in the MOTOM toolbox are listed in compilers.m. If the C-compiler you have does not appear in compilers.m, please add it yourself, and submit a bug report.

---

I am using something exotic/old. How to add my own C-compiler?

If Matlab sees your C-compiler, you can add it to compilers.m. Here is how. 1., Fetch your compiler information:

compiler_info_structure = mex.getCompilerConfigurations('C++', 'selected');

This creates a structure, with a few fields in. compiler_info_structure.Name is the name of the compiler, and this is how the compiler gets identified. compiler_info_structure.Version is a string which contains the version number. It may not be present. This may be important, if you know that the code compiles with one version, but does not with the other one.

Just to show, on a Mac, the name is:

>> compiler_info_structure.Name

ans =

    'Xcode Clang++'

2., Edit compilers.m accordingly There is a section in this file that you can overwrite. It looks like this:

%% ADD YOUR COMPILER NAME HERE, CHANGE THIS LINE!
% Change this comment too, so we will know how did you get it to work.
if(strcmp(compiler_info.Name, 'ADD YOUR COMPILER NAME HERE') && ~compiler_found)
    %Maybe only certain versions of your compiler is usable. Perhaps you will need to do a version check
    %Note that the version number is also stored as a string.
    if(strcmp(compiler_info.Version, 'ADD YOUR COMPILER VERSION HERE'))
        %Note that we always APPEND to the compiler flags. The default flags are set in the $COMPFLAGS environment
        %variable and is used by Matlab's mex command.
        compiler_flags = ''; %You may not need to add any extra compiler flags, but if you do, add them here.
        
        compiler_found = 1;
    end
end

Now we know that our compiler is Xcode Clang++. For the sake of simplicity, we can ignore the version. The code becomes:

%% Xcode Clang++
% This is a compiler for a Mac. It will never work with the Optotrak API, but it's just for demonstration only.
if(strcmp(compiler_info.Name, 'Xcode Clang++') && ~compiler_found)

        compiler_flags = ''; %You may not need to add any extra compiler flags, but if you do, add them here.
        
        compiler_found = 1;
    end
end

If you know you need special compiler flags, add them to compiler_flags. In the vast majority of cases, it is pretty safe to leave it how it is, blank.

Now if you run RUNME.m, it should compile the code, assuming the Optotrak API is happy with the compiler you use.

---

Matlab crashes when calling a function in the toolbox! I am not getting any error messages, Matlab simply vanishes and an 'app crashed' dialogue box shows up!

These are difficult to trace. The prime suspect is some sort of an access violation in the C-code. This can happen when the software wants to write outside of the memory space allocated for it. A lot of safeguards and sanity checks are in place to prevent this, but users are usually very talented in crashing software in ways that were not thought about developers. In this case, the safest way is to submit a bug report here on GitHub.

---

I am getting a system initialisation error. What does it mean?

If you are getting the following error message:

System initialisation error: Buffered data will be overwritten before the end of collection time!

This means that you are trying to save more data in the buffer than what the buffer can accommodate. Unfortunately there is no easy way around it. You may try to:

• Reduce the number of cameras in your system, if possible.
• Use a shorter collection time.
• Use a lower frame rate.
• Reduce the number of markers.

If you find this error message in the code and bypass it, everything will work, but you will lose data.

---

I am connecting to the Optotrak system. via Ethernet. Sometimes optotrak_startup fails. What can I do?

Usually this happens because the timeout settings in c:\ndigital\settings\optotrak.ini are incorrect. The timeout values are in milliseconds. Usually, the value of 10000 seems to work. Also, check your opto.err file for error messages, see if something else is going on.

---