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 referenced as:

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

Also, make sure that you do the following changes:
The simplest way to do this is to use 'Find and Replace' in a text editor, to change:

Replace every #include <ndtypes.h> with -> #include "ndtypes.h"

Replace every #include <ndpack.h> with -> #include "ndpack.h"

Replace every #include <ndhost.h> with -> #include "ndhost.h"

---

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. Many compilers were tried, but not all of them proved to be usable. Here is a list of compilers at least one person reported successful compilation with:

• Microsoft Visual C++ 2013 Professional
• 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 release no more recent than 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 by default. 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.

---

The toolbox code randomly crashes, and there is absolutely NOTHING in the onto.err file! What can I do?

Make sure whoever is running Matlab, can write to the ndigital and ndioapi directories. The Optotrak API functions will fail if some files can't be written to.

I am using USB on a 64-bit Windows. First Principles can communicate with the Optotrak system without problems, but the toolbox can't: TransputerDetermineSystemCfg() fails! How do I solve this?

Check your optotrak.ini file to see if you have included the Driver64 = usblink64.dll line in [OPTOTRAK System]. Also, make sure that usblink64.dll is available in the directory C:\ndigital\drivers (or wherver you installed your Optotrak files to).

I am trying to use virtual markers with a rigid body. My centroid location is correct, but it seems that the roll rotation is inverted and pitch and yaw are swapped with each other. What's going on?

This happens because the rigid body definition is incorrect. In NDI 6D architect, load the rigid body definition, and apply a 180° rotation along the Z axis (which inverts roll), and a 90° rotation along the X or Y axis (swaps pitch and yaw). Once this is done, save the rigid body definition, and test your virtual marker set-up!

How do I make sure that the rigid body transform's translation data returns the centroid coordinates of my rigid body?

You can calculate the centroid coordinate from the rigid body's markers by taking the mean values of the corresponding axes:

centroid_X = mean(X1, X2, ..., Xn);
centroid_Y = mean(Y1, Y2, ..., Yn);
centroid_Z = mean(Z1, Z2, ..., Zn);

...and then translate the coordinate system's origin to this point.