-
Notifications
You must be signed in to change notification settings - Fork 1
API functions in Matlab
Zoltan Derzsi edited this page Nov 6, 2017
·
21 revisions
If you type help <function_name>, you'll get these helper hints in Matlab. While this is no substitute to the API manual, I found these useful as quick reminders on what these functions do. I also added everything here as a single page, so you can search on it easier. If you can't find a function, it's worth checking the convenience scripts and wrapper functions page too.
A bit of help with the terminology: 'Centroid' is raw data, which includes the centroids only. Conversely 'raw' data is 'full raw' data, which includes the centroids and their statuses in a single structure. The ODAU raw data means sample values. For more information on data types, pleasre read this page.
function [fail, pdtXfrm1, pdtXfrm2, pdtNewXfrm] = CombineXfrms(pdtXfrm1, pdtXfrm2, pdtNewXfrm)
%COMBINEXFRMS Combine two Euler angle transformations into one.
% —> pdtXfrm1 First Euler angle Transform
% -> pdtXfrm2 Second Euler angle transform
% —> pdtNewXfrm is where the result goes.
% Note that this function has no return value so there is no way to find out if it crashes, apart from checking the transformed values themselves.
function [ fail, pdtQuatRot, pdtRotMatrix ] = CvtQuatToRotationMatrix( pdtQuatRot, pdtRotMatrix )
%CVTQUATTOROTATIONMATRIX This function converts a quaternion matrix to a rotation matrix
% Do not use structure arrays in this, execute for each marker!
% -> pdtQuatRot is the quaternion matrix to be converted
% -> pdtRotMatrix is the output of this function, 3-by-3 elements
% fail is the return value of the function. Since the function is initialised as void type, I gave it a constant 0.
% You have to manually check whether the function failed, by inspecting the output values.
function [ fail, pdtQuatRot, pdtRotMatrix ] = CvtRotationMatrixToQuat( pdtQuatRot, pdtRotMatrix )
%CVTROTATIONMATRIXTOQUAT This function converts a rotation matrix to quaternion format
% Do not use structure arrays in this, execute for each marker!
% -> pdtQuatRot is where the results will go in quaternion format
% -> pdtRotMatrix is the input rotation matrix data, 3-by-3 elements.
% fail is the return value of the function. Since the function is initialised as void type, I gave it a constant 0.
% You have to manually inspect whether the function failed, by checking the output values for example.
function [ fail ] = DataBufferAbortSpooling()
%DATABUFFERABORTSPOOLING This function allows you to stop tranfserring data (i.e. 'spooling') the associated destination from the Optotrak system
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [uDataId, pszFileName] = DataBufferInitializeFile(uDataId, pszFileName)
%DataBufferInitializeFile is the function that opens the file where the
%data will be saved. Contrary to what is written in the API manual, make sure that the file doesn't exist before calling this function. Otherwise, the system will hang at optotrak_stop_buffering_and_write_out().
% -> uDataId is the device identifier, as follows:
% 0: OPTOTRAK
% 1: DATA_PROPRIETOR, but this wasn't in the manual
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% pszFileName is the file name with path.
function [ fail, uDataId, pMemory ] = DataBufferInitializeMem( uDataId, pMemory )
%DATABUFFERINITIALIZEMEM This function reserves memory for the data buffer to be downloaded.
% -> uDataId is the device identifier, as follows:
% 0: OPTOTRAK
% 1: DATA_PROPRIETOR, but this wasn't in the manual
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> pMemory is a piece of memory where the data will be stored to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puSpoolStatus ] = DataBufferSpoolData( puSpoolStatus )
%DATABUFFERSPOOLDATA This function downloads (or 'spools') data to the locations you have initialised previously.
% This operation downloads the contents of the buffer completely until the time the funciton was called at without you having to do anything.
% Afterwards, it destroys the links to the destinations you specified, so you will have to re-initialise them
% -> puSpoolStatus is an error indicator telling you if something went wrong during the download. 0 for everything OK, non-zero values for an error.
% There is no definition on what the error codes are, so try using OptotrakGetErrorString()
% Detailed explanation goes here
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = DataBufferStart( )
%DATABUFFERSTART This function starts the downloading ('spooling') the data from the Optotrak device to all the allocated locations on the host computer.
% Use this function together with DataBufferWriteData() and DataBufferStop().
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = DataBufferStop( )
%DATABUFFERSTOP Stops the transfer of data from the Optotrak device to the computer.
% This function is useful when you want to stop transferring the data prematurely for some reason.
% You still have to wait until DataBufferWriteData() says so.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puRealTimeData, puSpoolComplete, puSpoolStatus, pulFramesBuffered ] = DataBufferWriteData( puRealTimeData, puSpoolComplete, puSpoolStatus, pulFramesBuffered )
%DATABUFFERWRITEDATA This is the function that 'catches' data from the Optotrak,
% and it puts it to the correct destinations, which you have previously initialised using DataBufferInitializeFile() or DataBufferInitializeMem()
% WARNING: This function will toss data away if you don't initialise destinations!
% -> puRealTimeData tells you if there is some real-time data to be received
% 0: There is no data available
% nonzero: There is data available
% -> puSpoolComplete tells you whether the operation is completed
% 0: The operation is still in progress
% nonzero: The operation is complete
% -> puSpoolStatus is an error indicator. It's 16 bits long, and the least significant byte contains the error type, and the upper byte contains the device ID.
% Device IDs are:
% 0: OPTOTRAK
% 1: DATA_PROPRIETOR
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% Error codes:
% Not sure which ones these are in the header file. Maybe a better option is OptotrakGetErrorString()?
% -> pulFramesBuffered is the number of frames completed in the operation. This is ideal for making progress bars.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetNextTransforms( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETNEXTTRANSFORMS This function gets you the next frame of acquired rigid body data
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of ridid body transforms found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the 6D data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetLatest3D( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETLATEST3D This function fetches the latest 3D position of the markers.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the X-Y-Z data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetLatestCentroid( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETLATESTCENTROID This function gets the latest centroid data
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puflags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the centroid data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
unction [ fail, nOdauId, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetLatestOdauRaw( nOdauId, puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETLATESTODAURAW Get the latest collected data from a specified ODAU.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the amount of data collected
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the Odau data will be written to, not sure what format to use, so it's initialised as void.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetLatestRaw( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETLATESTRAW This function gets you the latest acquired raw data
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the pixel data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetLatestTransforms( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETLATESTTRANSFORMS This function gets you the latest acquired rigid body data
% This function uses nested structures, so use DataGetLatestTransforms2, where the 3D and the 3D stuff is separated.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of ridid body transforms found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the 6D data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest6d, pDataDest3d ] = DataGetLatestTransforms2( puFrameNumber, puElements, puFlags, pDataDest6d, pDataDest3d )
%DATAGETLATESTTRANSFORMS2 This function obtains both the 3D and 6D rigid body transforms that has been captured.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of ridid body transforms found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest6d is where the calculated ridid bodies will be stored to
% -> pDataDest3D is where the calculated X-Y-Z coordinates will be saved to
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetNext3D( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETNEXT3D This function fetches the next frame of 3D positions of the markers.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the X-Y-Z data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetNextCentroid( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETNEXTCENTROID This function gets the next frame of centroid data
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puflags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the centroid data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetNextOdauRaw( nOdauId, puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETNEXTODAURAW Get the next frame of collected data from a specified ODAU.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the amount of data collected
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the X-Y-Z data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataGetNextRaw( puFrameNumber, puElements, puFlags, pDataDest )
%DATAGETNEXTERAW This function gets you the next frame of acquired raw data
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its 8 MB buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the pixel data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest6d, pDataDest3d ] = DataGetNextTransforms2( puFrameNumber, puElements, puFlags, pDataDest6d, pDataDest3d )
%DATAGETNEXTTRANSFORMS2 This function obtains both the 3D and 6D rigid body transforms that will be captured in the next frame.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of ridid body transforms found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough, or it didn't fit to its buffer.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest6d is where the calculated ridid bodies will be stored to
% -> pDataDest3D is where the calculated X-Y-Z coordinates will be saved to
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = DataIsReady( )
%DATAISREADY Is the data ready? Yes: anything else, No: 0
% fail: if it's non-zero, you can receive data. if it's zero, then you'll have to wait until there will be data available.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataReceiveLatest3D( puFrameNumber, puElements, puFlags, pDataDest )
%DATARECEIVELATEST3D This function fetches the previously requested (using RequestLatest3D()) 3D position of the markers.
% Make sure you poll this with DataIsReady(), otherwise you will corrupt data.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the X-Y-Z data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataReceiveLatestCentroid( puFrameNumber, puElements, puFlags, pDataDest )
%DATARECEIVELATESTCENTROID This function receives the previously requested (using RequestLatestCentroid()) latest centroid data
% Make sure you poll this with DataIsReady(), otherwise you will corrupt data.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puflags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the centroid data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, puFrameNumber, puElements, puFlags, pDataDest ] = DataReceiveLatestOdauRaw( nOdauId, puFrameNumber, puElements, puFlags, pDataDest )
%DATARECEIVELATESTODAURAW Gets the previously requested (using RequestLatestOdauRaw()) latest collected data from a specified ODAU.
% Make sure you poll this with DataIsReady(), otherwise you will corrupt data.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the amount of data collected
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the X-Y-Z data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataReceiveLatestRaw( puFrameNumber, puElements, puFlags, pDataDest )
%DATARECEIVELATESTRAW This function gets you the previously requested (using RequestLatestRaw()) latest raw data
% Make sure you poll this with DataIsReady(), otherwise you will corrupt data.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of markers found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the pixel data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest ] = DataReceiveLatestTransforms( puFrameNumber, puElements, puFlags, pDataDest )
%DATARECEIVELATESTTRANSFORMS This function gets you the previously requested (using RequestLatestTransforms) latest acquired rigid body data
% This function probably doesn't work with Matlab, because it is uses nested structures. Try calling DataReceiveLatestTransforms2().
% Make sure you poll this with DataIsReady(), otherwise you will corrupt data.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of ridid body transforms found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest is where the 6D data will be written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puFrameNumber, puElements, puFlags, pDataDest6d, pDataDest3d ] = DataReceiveLatestTransforms2( puFrameNumber, puElements, puFlags, pDataDest6d, pDataDest3d )
%DATARECEIVELATESTTRANSFORMS2 This function obtains both the 3D and 6D rigid body transforms that has been requested with RequestLatestTransforms()
%(hint: no '2' at the end, becaus this function really just receives the same stuff in two separate buffers).
% Make sure you poll this with DataIsReady(), otherwise you will corrupt data.
% -> puFrameNumber is a counter of frames since data acquisition began
% -> puElements is the number of ridid body transforms found in the frame
% -> puFlags is a status indiator of the Optotrak system. It's a binary mask, so if multiple flags are set, you have to de-compose the number:
% 1 (0x0001): OPTO_BUFFER_OVERRUN is undocumented, but it means that you lost data because you didn't read the buffer often enough.
% 2 (0x0002): OPTO_FRAME_OVERRUN is undocumented
% 4 (0x0004): OPTO_NO_PRE_FRAMES_FLAG is undocumented
% 8 (0x0008): OPTO_SWITCH_DATA_CHANGED_FLAG means you'll have to read out the switch data with RetrieveSwitchData()
% 16 (0x0010): OPTO_TOOL_CONFIG_CHANGED_FLAG means that the device configuration changed.
% 32 (0x0020): OPTO_FRAME_DATA_MISSED_FLAG is undocumented, but one can guess what it means :)
% If you don't use switches in your CERTUS system, don't set the OPTOTRAK_SWITCH_AND_CONFIG_FLAG during OptotrakSetupCollection(). This way, if
% puFlags is non-zero, it can be used as a handy error indicator.
% -> pDataDest6d is where the calculated ridid bodies will be stored to
% -> pDataDest3D is where the calculated X-Y-Z coordinates will be saved to
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pdtRotMatrix, pdtEulerRot ] = DetermineEuler( pdtRotMatrix, pdtEulerRot )
%DETERMINEEULER This function calculates the Euler angles from the provided rotation matrix.
% -> pdtRotMatrix is the input, a 3-by-3 element matrix
% -> pftEulerRot is the output
% fail is the return value of the function. Since Since the function is initialised as void type, I gave it a constant 0.
% You have to manually inspect whether the function failed, by checking the output values for example.
function [ fail, pdtEulerRot, pdtRotMatrix ] = DetermineR( pdtEulerRot, pdtRotMatrix )
%DETERMINER This function calulates the rotations from Euler angles.
% -> pdtEulerRot is the input Euler angles
% -> pdtRotMatrix is the output 3-by-3 rotation matrix
% fail is the return value of the function. Since the function is initialised as void type, I gave it a constant 0.
% You have to manually inspect whether the function failed, by checking the output values for example.
function [ fail, uFileId ] = FileClose( uFileId )
%FILECLOSE This function closes the data file that has been previously opened by the API.
% -> uFileId is the id FileOpen() gave the file you opened programmatically.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, uFileId ] = FileCloseAll( uFileId )
%FILECLOSEALL This function closes the data files that has been previously opened by the API.
% Note that this function is only for things you opened with FileOpenAll().
% -> uFileId is the id FileOpenAll() gave the file you opened programmatically.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszInputFileName, pszOutputFileName, uFileType ] = FileConvert( pszInputFileName, pszOutputFileName, uFileType )
%FILECONVERT This function converts raw data to the NDI file format, as follows:
% Optotrak raw data will be converted to 3D positions.
% ODAU raw data will be converted to voltages.
% Make sure that the file is not being opened by anything else at the same time.
% -> pszInputFileName is the file's name to be converted.
% -> pszOutputFileName is where the converted file will be saved at.
% -> uFileType is a binary mask:
% 1: OPTOTRAK_RAW tells the function that the input file is a raw camera file.
% 2: ANALOG_RAW tells the function that the input file is ODAU waveform data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszFileName, uFileId, uFileMode, pnItems, pnSubItems, plnFrames, pfFrequency, pszComments, pFileHeader ] = FileOpen( pszFileName, uFileId, uFileMode, pnItems, pnSubItems, plnFrames, pfFrequency, pszComments, pFileHeader )
%FILEOPEN This function opens an NDI floating point file, and reads its header.
% -> pszFileName is the file's name to be opened
% -> uFileId is a number you assign to the open file.
% -> uFileMode can be the following:
% 1: OPEN_READ: Open the file as read-only
% 2: OPEN_WRITE: This setting allows you to tinker with the file.
% -> pnItems tells you how many items are in the tile. Refer to the file format docs for this.
% -> pnSubItems tells you how many sub-items are in the file. Refer to the file format docs for this.
% -> pnFrames tells you how many data frames are in the file
% -> pfFrequency tells you the sampling rate
% -> pfzComments will contain the comment field in the file you are reading
% -> pFileHeader is a C file pointer, pointing to the header of the NDI floating point file.
% Important:
% -This function can only open 16 files at the same time.
% -When you open the file in read-write mode, you can meddle with its header only, and not its data.
% -While NDI gave you the file pointer to provide low-level access to the file header, they recommend not using it.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszFileName, uFileId, uFileMode, pnItems, pnSubItems, pnCharSubItems, pnIntSubItems, pnDoubleSubItems, plnFrames, pfFrequency, pszComments, pFileHeader ] = FileOpenAll( pszFileName, uFileId, uFileMode, pnItems, pnSubItems, pnCharSubItems, pnIntSubItems, pnDoubleSubItems, plnFrames, pfFrequency, pszComments, pFileHeader )
%FILEOPENALL This function opens an NDI floating point file, and gives access to the data.
% -> pszFileName is the file's name to be opened
% -> uFileId is a number you assign to the open file.
% -> uFileMode can be the following:
% 1: OPEN_READ: Open the file as read-only
% 2: OPEN_WRITE: This setting allows you to tinker with the file.
% -> pnItems tells you how many items are in the tile. Refer to the file format docs for this.
% -> pnSubItems will be the number of floating-point items in the file
% -> pnCharSubItems will be the number of byte-type sub-items in the file
% -> pnIntSubItems will be the number of integer type sub-items in the file
% -> pnDoubleSubItems will be the number of double type sub-items in the file
% -> pnFrames tells you how many data frames are in the file
% -> pfFrequency tells you the sampling rate
% -> pfzComments will contain the comment field in the file you are reading
% -> pFileHeader is a C file pointer, pointing to the header of the NDI floating point file.
% Important:
% -This function can only open 16 files at the same time.
% -When you open the file in read-write mode, you can meddle with both the header and the data.
% -While NDI gave you the file pointer to provide low-level access to the file header, they recommend not using it.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, uFileId, lnStartFrame, uNumberofFrames, pDataDest ] = FileRead( uFileId, lnStartFrame, uNumberofFrames, pDataDest )
%FILEREAD Reads the floating point data data from the specified file
% -> uFileId is the file indentifier you assigned when you opened the file with either FileOpen() or FileOpenAll()
% -> lnStartFrame is a frame offset. If you want to read from the beginning of the file, set this to 0.
% -> uNumberofFrames tells the function how many frames are to be read. You should know how long your file is, by calling FileOpen() or FileOpenAll()
% -> pDataDest is where the read-out contents go in the memory.
% Important: This function only accesses the floating point data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, uFileId, lnStartFrame, uNumberofFrames, pDataDestFloat, pDataDestChar, pDataDestInt, pDataDestDouble ] = FileReadAll( uFileId, lnStartFrame, uNumberofFrames, pDataDestFloat, pDataDestChar, pDataDestInt, pDataDestDouble )
%FILEREADALL This function reads every type of data from the specified file
% -> uFileId is the file indentifier you assigned when you opened the file with either FileOpen() or FileOpenAll()
% -> lnStartFrame is a frame offset. If you want to read from the beginning of the file, set this to 0.
% -> uNumberofFrames tells the function how many frames are to be read. You should know how long your file is, by calling FileOpen() or FileOpenAll()
% -> pDataDestFloat is where the floating point data gets saved to.
% -> pDataDestChar is where the character data gets saved to.
% -> pDataDestInt is where the integer data gets saved to.
% -> pDataDestDouble is where the double data gets saved to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, uFileId, lnStartFrame, uNumberofFrames, pDataSrc ] = FileWrite( uFileId, lnStartFrame, uNumberofFrames, pDataSrc )
%FILEWRITE writes the floating point data data to the specified file
% -> uFileId is the file indentifier you assigned when you opened the file with either FileOpen() or FileOpenAll()
% -> lnStartFrame is a frame offset. If you want to write your buffer out from the beginning of the file, set this to 0.
% -> uNumberofFrames tells the function how many frames are to be written out. You should know how long your file is.
% -> pDataSrc is the data you want to write out to the opened file.
% Important: This function only saves the floating point data, and make sure that the number of frames written out correspond to what is in the file header. Nothing does this sanity check later-on in the processing chain.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, uFileId, lnStartFrame, uNumberofFrames, pDataSrcFloat, pDataSrcChar, pDataSrcInt, pDataSrcDouble ] = FileWriteAll( uFileId, lnStartFrame, uNumberofFrames, pDataSrcFloat, pDataSrcChar, pDataSrcInt, pDataSrcDouble )
%FILEWRITEALL This function writes out every type of data to the specified file
% -> uFileId is the file indentifier you assigned when you opened the file with either FileOpen() or FileOpenAll()
% -> lnStartFrame is a frame offset. If you want to write out from the beginning your data, set this to 0.
% -> uNumberofFrames tells the function how many frames are to be written out. You should already know how many frames are there in your data.
% -> pDataSrcFloat is where the floating point data gets read out from.
% -> pDataSrcChar is where the character data gets read out from.
% -> pDataSrcInt is where the integer data gets read out from.
% -> pDataSrcDouble is where the double data gets read out from.
% Important: Make sure that the number of data items written out correspond to what is in the file header. Nothing does this sanity check later-on in the processing chain.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pdtXfrm, pdtInverseXfrm ] = InverseXfrm( pdtXfrm, pdtInverseXfrm )
%INVERSEXFRM This function calculates the inverse Euler angles.
% -> pdtXfrm is the input
% -> pdtInverseXfrm is the output
% fail is the return value of the function. Since the function is initialised as void type, I gave it a constant 0.
% You have to manually inspect whether the function failed, by checking the output values for example.
function [ fail, dtAlignParams, pfRMSError ] = nOptotrakAlignSystem( dtAlignParams, pfRMSError )
%NOPTOTRAKALIGNSYSTEM This function changes the Optotrak's coordinate system, and saves this to a specified camera parameter file.
% Basically, you use a previous recording of a known rigid body to align the camera's coordinate system to the rigid body's corrodinate system.
% -> dtAlignParams is a parameter structure. It is initialised as follows:
% char szDataFile is a data file name with a recording of unaligned parameters
% char szRigidBodyFile is the rigid body file name used for the calibration
% char szInputCamFile is the file name for the camera settings, prior to alignment
% char szOutputCamFile is the name of the calibrated camera file which this function will generate
% char szLogFileName is the calibration log file
% boolean bVerbose is a binary (0 - anything else) field, which toggles calibration information to the console.
% -> pfRMSError is a structure where the RMS error of the calibration will be stored.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, dtCalibRigParms, pfRMSError ] = nOptotrakCalibRigSystem( dtCalibRigParms, pfRMSError )
%NOPTOTRAKCALIBRIGSYSTEM If you use more than one sensor, this is the function you need to use to align them together.
% -> dtCalibRigParms is a structure, defined as follows:
% char pszRawDataFile is the file name of a pre-collected raw data with the unaligned sensors
% char pszRigidBodyFile is the rigid body definition with which the data above was collected
% char pszInputCamFile is the file name for the unaligned camera settings
% char pszOutputCamFile is the file name this function will write the new calibration data to.
% char szLogFileName is the name of the log file to be written out during calibration
% boolean bVerbose is a switch (0 vs everything else) that dumps messages to the console.
% -> pfRMSError is where the calibration RMS error is being saved to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, dtRegisterParms, pfRMSError ] = nOptotrakRegisterSystem( dtRegisterParms, pfRMSError )
%NOPTOTRAKREGISTERSYSTEM If you use more than one sensor, you'll need to generate camera parameter files.
% The pre-requisite is that you need to record a moving pre-defined rigid body with the un-aligned cameras.
% -> dtRegisterParms is a stucture, initialised as follows:
% char szRawDataFile is the file name of the raw data file you previously recorded with the unaligned camera settings
% char szRigidBodyFile is the file name of the rigid body you used to make the recording you are giving this function to work with
% char szInputCamFile is the unaligned camera file to be read by this function
% char szOutputCamFile is the camera file which will hold the correct calibration data generated by this function
% char szLogFile is the name of the log file to be generated during the calibration process
% float fXrfmMaxError is the maximum allowable error introduced by the rigid body transformation. Typical value is 0.2...0.5 [mm]. If the error is largen than what you specify here, the function will fail.
% float fXfrm3dRmsError is a maximum allowable RMS error. Typical value is 0.5...0.75 [mm]. If the error is larger than what you set here, the function will fail.
% float fSpread1; float fSpread2, float fSpread3: you can specify the minimum volume to be covered during calibration. Set these to 0 if you don't want to use this feature
% float fMinNumberOfXfrms you can specity how many successful conversions are at least required to the calibration. If the system detects less than this, the function will fail.
% int nLogFileLevel is a number, as follows:
% 0: REG_NO_LOG_FILE means that nothing will be written to the log
% 1: REG_SUMMARY_LOG_FILE instructs the system to keep things as brief as possible in the log
% 2: REG_DETAILED_LOG_FILE for nerds
% boolean bCheckCalibration is a binary parameter, if set to a nonzero value, the function will not write the new camera file. This is useful to see if your system needs calibrating.
% boolean bVerbose is a binary parameter, if set to a nonzero value, it will generate output text to the console
% -> pfRMSError is the RMS error in the calibration process. This allows you to check whether the calibration was up to standard.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, pnChannels, pnGain, pnDigitalMode, pfFrameFrequency, pfScanFrequency, pnStreamData, pfCollectionTime, pfPreTriggerTime, puCollFlags, pnFlags ] = OdauGetStatus( nOdauId, pnChannels, pnGain, pnDigitalMode, pfFrameFrequency, pfScanFrequency, pnStreamData, pfCollectionTime, pfPreTriggerTime, puCollFlags, pnFlags )
%ODAUGETSTATUS This function gets all the information available for a selected ODAU device.
% You can adjust these settings with OdauSetupCollection(...) and/or OdauSetupCollectionFromFile(...)
% -> nOdauId select which ODAU is being queried. It's a binary mask, and the decimal values correspond to:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% (these listed variables are pointers, and the function writes into them)
% -> pnChannels is the number of channels
% -> pnGain is the gain for the analogue channels
% -> pnDigitalMode is the digital ports' operation, as follows:
% 0 (0x00): ODAU_DIGITAL_PORT_OFF is pretty self-explanatory
% 17 (0x11): ODAU_DIGITAL_INPB_INPA means that both ports are inputs
% 33 (0x21): ODAU_DIGITAL_OUTPB_INPA means that PORTB is output, and PORTA is inptut
% 34 (0x22): ODAU_DIGITAL_OUTPB_OUTPA means that both ports are outputs
% 51 (0x33): Both ports are in mixed mode. No info about this in the header file.
% 4 (0x04): ODAU_DIGITAL_OFFB_MUXA means that PORTB is off, and PORTA is connected internally to the muliplexer
% 20 (0x14): ODAU_DIGITAL_INPB_MUXA means that PORTB is input, and PORTA is connected to the multiplexer
% 36 (0x24): ODAU_DIGITAL_OUTPB_MUXA means that PORTB is output, and PORTA is connected to the multiplexer
% -> pfFrameFrequency is the frame rate
% -> pfScanFrequency is the frequency the inputs are being sampled at within a frame
% -> pnStreamData tells whether the ODAU is continuously streaming data, or holds it in its buffer until you read it out
% 0: the ODAU is holding the data until you read out the buffer
% 1: the ODAU is streaming data automatically
% -> pfCollectionTime is the time it took to collect the data in the buffer
% -> pfPreTriggerTime is unimplemented, and is always 0.
% -> puCollFlags tells you how the analogue inputs are configured:
% 0: All voltages are recorded with respect to the ground (aka unbalanced)
% 1: ODAU_DIFFERENTIAL_FLAG means that the voltages were recorded differentially (aka balanced)
% -> pnFlags are the values the ODAU was initialised with. It's a binary mask, so the numbers are added if multiple flags are set.
% (Neither the manual, nor the header file goes into details on how these are organised.)
%
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszCollectFile ] = OdauSaveCollectionToFile( pszCollectFile )
%ODAUSAVECOLLECTIONTOFILE This function creates a config file for the ODAU's set-up. This allows you to load/change it manually.
% -> pszCollectFile is the name of the .ini file you want to save to. Do not add the extension.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, pfVoltage1, pfVoltage2, uChangeMask ] = OdauSetAnalogOutputs( nOdauId, pfVoltage1, pfVoltage2, uChangeMask )
%ODAUSETANALOGOUTPUTS this functions sets the voltages of the two analogue outputs of the ODAU.
% The voltage range is between +5 and -5 Volts.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> pfVoltage1 is the voltage value for analogue output channel 1
% -> pfVoltage2 is the voltage value for analogue output channel 2
% uChangeMask allows you to select what happens with the channels
% 0: If you set this to 0, then you can read out the current voltage values on both channels.
% 1: Channel 1 is being updated, channel 2 is unchanged.
% 2: Channel 2 is being updated, channel 1 is unchanged.
% 3: Update both channels
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, puDigitalOut, uUpdateMask ] = OdauSetDigitalOutputs( nOdauId, puDigitalOut, uUpdateMask )
%ODAUSETDIGITALOUTPUTS This function allows you to se the digital outputs on the ODAU box.
% The two ports are controlled in a single 8-bit word. The four most significant bits are PORTB, and the four least significant bits are PORTA
% However, note that when you actually get data from the ODAU, this byte will be in the most significant half of a 16-bit word.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> puDigitalOut is the byte word with the two ports' bits in.
% -> uUpdateMask allows you to specify which bits are configured as output (0) or input (1)
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, uTimer, uMode, ulVal ] = OdauSetTimer( nOdauId, uTimer, uMode, ulVal )
%ODAUSETTIMER This function allows you to set the internal user timer on the ODAU.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> uTimer is the user timer. Currently the only legal value is 2. (ODAU_TIMER2)
% -> uMode sets the operating mode of the timer, as follows, although it's not very well documented:
% 1: ODAU_TIMER_ONE_SHOT is for monostable operation
% 2: ODAU_TIMER_RATE_GEN is presumably for setting frequency instead of period time
% 3: ODAU_TIMER_SQUARE_WAVE is to be used as a functio generator
% 4: ODAU_TIMER_RETRIGGER is undocumented.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nOdauId, nChannels, nGain, nDigitalMode, fFrameFrequency, fScanFrequency, nStreamData, fCollectionTime, fPreTriggerTime, uFlags ] = OdauSetupCollection( nOdauId, nChannels, nGain, nDigitalMode, fFrameFrequency, fScanFrequency, nStreamData, fCollectionTime, fPreTriggerTime, uFlags )
%ODAUSETUPCOLLECTION This function configures the ODAU for data acquisition.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% -> nChannels is the number of channels to record from. Can select between 1 and 256.
% -> nGain controls the settings of the built-in amplifier. With the different settings, the voltage range is:
% 1: +/- 10V (gain = 1)
% 5: +/- 2V (gain = 5)
% 10: +/- 1V (gain = 10)
% 100: +/- 100mV (gain = 100)
% Note that the gain is only adjustable to these discrete values.
% -> pnDigitalMode is the digital ports' operation, as follows:
% 0 (0x00): ODAU_DIGITAL_PORT_OFF is pretty self-explanatory
% 17 (0x11): ODAU_DIGITAL_INPB_INPA means that both ports are inputs
% 33 (0x21): ODAU_DIGITAL_OUTPB_INPA means that PORTB is output, and PORTA is inptut
% 34 (0x22): ODAU_DIGITAL_OUTPB_OUTPA means that both ports are outputs
% 51 (0x33): Both ports are in mixed mode. No info about this in the header file.
% 4 (0x04): ODAU_DIGITAL_OFFB_MUXA means that PORTB is off, and PORTA is connected internally to the muliplexer
% 20 (0x14): ODAU_DIGITAL_INPB_MUXA means that PORTB is input, and PORTA is connected to the multiplexer
% 36 (0x24): ODAU_DIGITAL_OUTPB_MUXA means that PORTB is output, and PORTA is connected to the multiplexer
% A useful feature is that the output ports can be read as inputs, and you can recover the previously sent out bit combination.
% -> fFrameFrequency is the frequency the ODAU samples all the channels, to collect a frame of data. Ranges between 1 and 100000
% -> fScanFrequency is the rate which the channels are being scanned within a frame. Ranges between 1 and 100000
% Note that the higher gain you use, the lower your scan frequency can be.
% -> nStreamData tells the ODAU to:
% 0: Keep the data in the buffer until you read it out
% 1: Stream the collected data continuously
% -> fCollectionTime tells the ODAU how many seconds of data to collect when using the buffer. Values can be between 1 and 99999.
% -> fPreTriggerTime is not implemented and it 'must' be 0.
% -> uFlags specifies how the analogue channes should be handled:
% 0: All voltages are recorded with respect to the ground (aka unbalanced)
% 1: ODAU_DIFFERENTIAL_FLAG means that the voltages were recorded differentially (aka balanced)
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszCollectFile ] = OdauSetupCollectionFromFile( pszCollectFile )
%ODAUSETUPCOLLECTIONFROMFILE This function allows you to configure your ODAU from a specified config file.
% —> pszCollectFile is the file's name. Please don't use the extension. Standard Windows .ini systax applies:
% [ODAU 01]
% Parameter = value
% ...
% Consult OdauSetupCollection.m for exact parameter description. Remove the 'n', 'f', 'p' to get the sections in the .ini file.
% Also, you can generate your own .ini file with OdauSaveCollectionToFile.m.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszAutoScaleFile ] = OptotrakLoadAutoScale( pszAutoScaleFile )
%OPTOTRAKLOADAUTOSCALE This function loads the auto scale data from the specified file into the system.
% -> pszAutoScaleFile is a file name. Do not use it with extensions, so the 'blablabla.nas' file should be called as OptotrakLoadAutoScale( 'blablabla' )
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = OptotrakActivateMarkers()
%OPTOTRAKACTIVATEMARKERS Turns on the IR leds so tracking them could be
%started. There is some delay between calling the function and the markers
%being switched on. This can create some missing data at the beginning of
%acquisition.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszInputCamFile, nNumMarkers, pdtMeasuredPositions, pdtAlignedPositions, pszAlignedCamFile, pdt3dErrors, pfRmsError] = OptotrakChangeCameraFOR( pszInputCamFile, nNumMarkers, pdtMeasuredPositions, pdtAlignedPositions, pszAlignedCamFile, pdt3dErrors, pfRmsError )
%OPTOTRAKCHANGECAMERAFOR Alters the camera's coordinate system. Input
%arguments are:
% -> pszInputCamFile is the name of the camera file. If this is a zero
% length string, it will load 'standard.cam'.
% -> nNumMarkers is the number of markers used.
% -> pdtAlignedPositions Coordinates in the desired coordinate system
% -> pdtMeasuredPositions Coordinates stored in the current coordinate system
% -> pszAlignedCamFile The name of the new camera file
% -> pdt3dErrors Transforming the alignment introduces errors, this is where they go.
% -> pfRmsError RMS distance errors from the transformation go here.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pElems3d, pSourceCent, pSourceStatus, pdtDataDest3D ] = OptotrakConvertCentroidAndStatusTo3D( pElems3d, pSourceCent, pSourceStatus, pdtDataDest3D )
%OPTOTRAKCONVERTCENTROIDANDSTATUSTO3D This function converts centroid data to 3D data.
% Operation is pretty much the same as OptotrakConvertFullRawTo3d( ... ), but with centroids instead of raw data.
% -> pElems3d is the number of markers that were converted
% -> pSourceCent is where the centroids are located
% -> pSourceStatus is where the status is
% -> pdtDataDest3D is where the 3D data is being written to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pElems3d, pElems6d, pSourceCent, pSourceStatus, pdtDataDest3d, pdtDataDest6d ] = OptotrakConvertCentroidAndStatusTo6D( pElems3d, pElems6d, pSourceCent, pSourceStatus, pdtDataDest3d, pdtDataDest6d )
%OPTOTRAKCONVERTCENTROIDANDSTATUSTO6D This function converts a previously captured centroid data frame into 3D and 6D positions, using the ridid body definitions
% -> pElems3d is the number of markers used in the caputre.
% -> pElems6d is the number of rigid bodies used in the conversion
% -> pSourceCent is the source centroids in the previously caputred frame.
% -> pSourceStatus is the status (the manual is not very talkative on what this actually is on page 100)
% -> pdtDataDest3d is where the 3D coordinates go
% -> pdtDataDest6d is where rigid body stuff goes
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pElems3d, pDataSourceFullRaw, pdtDataDest3d ] = OptotrakConvertFullRawTo3D( pElems3d, pDataSourceFullRaw, pdtDataDest3d )
%OPTOTRAKCONVERTFULLRAWTO3D This functions converts a previously captured single frame's full raw data to 3D positions.
% -> pElems3d is the number of markers that were converted.
% -> pDataSourceFullRaw is the source of the single frame full raw data
% -> pdtDataDest3d is the destination Position3D structure the positions are being written into
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pElems3d, pElems6d, pSrcFullRaw, pDst3d, pdtDataDest6d ] = OptotrakConvertFullRawTo6D( pElems3d, pElems6d, pSrcFullRaw, pDst3d, pdtDataDest6d )
%OPTOTRAKCONVERTFULLRAWTO6D This function converts a previously captured full raw data frame into 3D and 6D positions, using the ridid body definitions
% -> pElems3d is the number of markers that were converted
% -> pElems6d is the number of rigid bodies that were converted
% -> pSrcFullRaw is the source of a single frame's worth of full raw data
% -> pDst3d is a structure where the 3D data is being saved to
% -> pdtDataDest6d is a structure where the 6D ridid body data is being saved to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puElements, pSensorReadings, pdt3DPositions ] = OptotrakConvertRawTo3D( puElements, pSensorReadings, pdt3DPositions )
%OPTOTRAKCONVERTRAWTO3D Converts the camera's raw data to actual 3D
%coordinates.
% -> puElements is the number of converted markers
% -> pSensorReadings is the frame of the raw data
% -> pdt3Dpositions is the coordinate array this function will fill up
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, puElements, pDataDest6D, pDataDest3D ] = OptotrakConvertTransforms( puElements, pDataDest6D, pDataDest3D )
%OPTOTRAKCONVERTTRANSFORMS Converts a frame of 3D data to a 6D data, using the currently loaded rigid body file.
% -> puElements is the number of rigid bodies used in the transformation
% -> pDataDest6D is where your freshly generated data will go
% -> pDataDest3D is the 3D coordinate array you want to do the transform on.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = OptotrakDeActivateMarkers( )
%OPTOTRAKDEACTIVATEMARKERS Turns off the IR LEDs in the Optotrak system.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId ] = OptotrakDeviceHandleEnable( nDeviceHandleId )
%OPTOTRAKDEVICEHANDLEENABLE This function enables a device which has the handle specified in the argument
% If you want to capture data from a device, you'll need to enable it. A device can activate markers, LEDs, and TTL devices.
% -> nDeviceHandleId is the device handle you need to specify
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId ] = OptotrakDeviceHandleFree( nDeviceHandleId )
%OPTOTRAKDEVICEHANDLEFREE This function frees up a device handle, and some memory with it.
% If you decide to re-allocate a device handle for this device, it will get a differen handle.
% -> nDeviceHandleId is the device handle you no longer use and you want the system to free up the allocated memory.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId, pnProperties ] = OptotrakDeviceHandleGetNumberProperties( nDeviceHandleId, pnProperties )
%OPTOTRAKDEVICEHANDLEGETNUMBERPROPERTIES This function tells you how many properties have been assigned to this device.
% This is useful if you need to pre-allocate memory to store the device properties into.
% -> nDeviceHandleId is the device handle number
% -> pnProperties is where the number of properties go, and you can use optotrak_device_handle_property_decoder() to see what this is.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId, grdtProperties, nProperties ] = OptotrakDeviceHandleGetProperties( nDeviceHandleId, grdtProperties, nProperties )
%OPTOTRAKDEVICEHANDLEGETPROPERTIES This function returns the property structure for a device that is specified with the handle.
% This can include the number of switches, location, etc.
% -> nDeviceHandleId is the device handle that selects which device is being read.
% -> grdtProperties is the data structure the function will write things to
% -> nProperties is the number of properties expected to obtain.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandlerId, pdtProperty, uPropertyId ] = OptotrakDeviceHandleGetProperty( nDeviceHandlerId, pdtProperty, uPropertyId )
%OPTOTRAKDEVICEHANDLEGETPROPERTY This function fetches a selected property for a selected device.
% This is a bit cryptic this way, so let me elaborate here:
% -> nDeviceHandlerId is the device handle
% -> pdtProperty is where the property obtained by this function is being written into
% -> uPropertyId is a number, which is initialised in the API as a binary mask. In Matlab, this can be a decimal number, as follows:
% 0: DH_PROPERTY_UNKNOWN doesn't seem to do much
% 1: DH_PROPERTY_NAME gets the selected device's name
% 2: DH_PROPERTY_MARKERS_TO_FIRE tells you how many markers will be used.
% 3: DH_PROPERTY_MAX_MARKERS is the maximum mumbers of markers the device can have
% 4: DH_PROPERTY_STARTMARKERPERIOD tells you which marker will be activated first within a period
% 5: DH_PROPERTY_SWITCHES tells you how many switches are on the device
% 6: DH_PROPERTY_VLEDS tells you how many visible LEDs are there on the device
% 7: DH_PROPERTY_PORT tells you which SCU port is the device being plugged in
% 8: DH_PROPERTY_ORDER '...index within the port'
% 9: DH_PROPERTY_SUBPORT tells you which subport the device is connected to
% 10: DH_PROPERTY_FIRINGSEQUENCE tells you which order the markers are being 'fired' at
% 11: DH_PROPERTY_HAS_ROM tells you whether the selected device has a ROM
% 12: DH_PROPERTY_TOOLPORTS tells you how many ports the selected strober has
% 13: DH_PROPERTY_3020_CAPABILITY tells you if your device can use the Optotrak 3020 strober
% 14: DH_PROPERTY_3020_MARKERSTOFIRE tells you how many markers are ont he 3020 strober
% 15: DH_PROPERTY_3020_STARTMARKERPERIOD tells you which marker is going to fire first within a period
% 16: DH_PROPERTY_STATUS tells you what's happening with the device (ENABLED, FREE, INITIALIZED, UNOCCUPIED, OCCUPIED)
% 17: Undocumented, and it's not even in the header file!
% 18: DH_PROPERTY_SROM_RIGIDMARKERS is undocumented, presumably Serial-number ROM?
% 19: DH_PROPERTY_SROM_RIGIDPOSITIONS is undocumented, presumably Serial-number ROM?
% 20: DH_PROPERTY_SROM_FIRINGSEQUENCE is undocumented, presumably Serial-number ROM?
% 21: DH_PROPERTY_SROM_NORMALMARKERS is undocumented, presumably Serial-number ROM?
% 22: DH_PROPERTY_SROM_NORMALS is undocumented, presumably Serial-number ROM?
% 23: DH_PROPERTY_SROM_SERIALNUMBER is undocumented, presumably Serial-number ROM?
% 24: DH_PROPERTY_SROM_PARTNUMBER is undocumented, presumably Serial-number ROM?
% 25: DH_PROPERTY_SROM_MANUFACTURER is undocumented, presumably Serial-number ROM?
% 26: Undocumented, and it's not even in the header file!
% 27: Undocumented, and it's not even in the header file!
% 28: DH_PROPERTY_STATE_FLAGS is undocumented
% 29: DH_PROPERTY_TIP_ID is undocumented
% 30: DH_PROPERTY_SCAN_MODE_SUPPORT is undocumented
% 31: DH_PROPERTY_HAS_BUMP_SENSOR is undocumented
% 32: DH_PROPERTY_WIRELESS_ENABLED tells you whether the device is operating wirelessly
% 33: DH_PROPERTY_HAS_BEEPER is undocumented, but one can guess :)
% 34: DH_PROPERTY_DEVICE_TYPE is undocumented
% 35: DH_PROPERTY_SERIAL_NUMBER is undocumented, but one can guess :)
% 36: DH_PROPERTY_FEATURE_KEY is undocumented
% 37: DH_PROPERTY_MKR_PORT_ENCODING returns the encoded marker activation
% 38: Undocumented, and it's not even in the header file!
% 39: Undocumented, and it's not even in the header file!
% 40: Undocumented, and it's not even in the header file!
% 41: Undocumented, and it's not even in the header file!
% 42: Undocumented, and it's not even in the header file!
% 43: Undocumented, and it's not even in the header file!
% 44: Undocumented, and it's not even in the header file!
% 45: Undocumented, and it's not even in the header file!
% 46: Undocumented, and it's not even in the header file!
% 47: Undocumented, and it's not even in the header file!
% 48: DH_PROPERTY_SELECT_PROBE_CLUSTER
% 49: Undocumented, and it's not even in the header file!
% 50: DH_PROPERTY_BEEP_PATTERN is undocumented, and probably isn't supported.
% 51: DH_PROPERTY_SWITCH_INDEX is undocumented
% 52: DH_PROPERTY_TIME_SINCE_LAST_RESPONSE is a time value in seconds
% 53: DH_PROPERTY_MAX_MARKER_VOLTAGE is the maximum marker voltage supported by the strober
% 54: DH_PROPERTY_SMART_MARKERS tells you if the strober supports/uses 'smart markers'
% 55: DH_PROPERTY_SROM_IS_CACHED tells you if the device's SROM is cached in the SCU
% 56: DH_PROPERTY_SROM_ID returns the serial numbers of all the devices attached to the SCU
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId, uTime_ms ] = OptotrakDeviceHandleSetBeeper( nDeviceHandleId, uTime_ms )
%OPTOTRAKDEVICEHANDLESETBEEPER This function makes the selected device go beep for a specified time.
% Please exercise caution when using this function. The beeper can be very annoying.
% -> nDeviceHandleId is the device identifier
% -> uTime_ms is the time in milliseconds the beep is on
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId, grdtProperties, nProperties ] = OptotrakDeviceHandleSetProperties( nDeviceHandleId, grdtProperties, nProperties )
%OPTOTRAKDEVICEHANDLESETPROPERTIES This function allows you to save properties into the device. This is done via the property structure.
% It is advisable to read the properties out with OptotrakDeviceHandleGetProperties(...), and then update it accordingly before writing its contents with this function.
% -> nDeviceHandleId is the handle of the selected device
% -> grdtProperties is the property structure to be written
% -> nProperties is the size of the property structute. This is useful if you want to preallocate memory
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandleId, nLED, uState ] = OptotrakDeviceHandleSetVisibleLED( nDeviceHandleId, nLED, uState )
%OPTOTRAKDEVICEHANDLESETVISIBLELED This function allows you to touch the LED in the selected device.
% -> nDeviceHandleId is the device handle which tells which device we are adjusting
% -> nLED is the led's number to be used. The first LED (nLED=1) is 'reserved', and this will throw an error when you adjust it.
% -> uState is a binary mask, defined as follows:
% 0: VLEDST_OFF which turns the LED off
% 1: VLEDST_ON which turns the LED on
% 2: VLEDST_BLINK starts blinking at an unspecified frequency and duty cycle.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDevice, bEnable ] = OptotrakEnableWireless( nDevice, bEnable )
%OPTOTRAKENABLEWIRELESS This function enables the wireless communications facilities. You need this to detect wireless devices.
% -> nDevices is not implemented. They ask you to set it to -1 all the time.
% -> bEnable is a boolean which enables (1) and disables (0) wireless
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pnCurrentMarkerType, pnCurrentMarkerWaveLength, pnCurrentModelType, szStatus, nStatusLength ] = OptotrakGetCameraParameterStatus( pnCurrentMarkerType, pnCurrentMarkerWaveLength, pnCurrentModelType, szStatus, nStatusLength )
%OPTOTRAKGETCAMERAPARAMETERSTATUS This function tells you how your cameras
%are set up, including marker info. The API manual is not very helpful with
%this.
% -> pnCurrentMarkerType is the marker type according to the manual.
% -> pnCurrentMarkerWaveLength is the 'wavelength type'.
% -> pnCurrentModelType can be 'model 1', 'model 2', for example.
% -> szStatus is the status string
% -> nStatusLength is the length of the previous status string.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, grdtDeviceHandles, nDeviceHandles, puFlags ] = OptotrakGetDeviceHandles( grdtDeviceHandles, nDeviceHandles, puFlags )
%OPTOTRAKGETDEVICEHANDLES This function finds out what devices have been connected to the Optotrak SCU.
% You need to know the EXACT number of devices connected before calling this function. You can find this out by calling OptotrakGetNumberDeviceHandles(...)
% -> grdtDeviceHandles is a structure array with all the different things discovered by the Optotrak SCU
% The statuses are as follows:
% 0: DH_STATUS_UNOCCUPIED
% 1: DH_STATUS_OCCUPIED
% 2: DH_STATUS_INITALIZED
% -> nDeviceHandles tells the function how much memory is available for the structure array
% -> puFlags is where the flags are being put by the function. It's a binary mask, so if you only see numbers here, they correspond to:
% 16: OPTO_TOOL_CONFIG_CHANGED_FLAG is set when nDeviceHandles do not match the number of devices connected to the system
%
% If multiple flags are set, then these numbers add together.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, szErrorString, nBufferSize ] = OptotrakGetErrorString( szErrorString, nBufferSize )
%OPTOTRAKGETERRORSTRING If something failed, you have a chance of reading
%the error message here.
% -> szErrorString is the variable the string will be written to
% -> nBufferSize is the length of the string, just in case.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nNodeId, pdtNodeInfo ] = OptotrakGetNodeInfo( nNodeId, pdtNodeInfo )
%OPTOTRAKGETNODEINFO Returns information of any node determined by the
%nNodeId in the system
% -> nNodeId can be six values, listed below
% -> pdtNodeInfo is the structure the data is being written into
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
% Node Ids:
% 0 for Optotrak
% 1 for 'Data proprietor'
% 2 for ODAU1
% 3 for ODAU2
% 4 for ODAU3
% 5 for ODAU4
% 6 for SENSOR_PROP1
function [ fail, pnDeviceHandles ] = OptotrakGetNumberDeviceHandles( pnDeviceHandles )
%OPTOTRAKGETNUMBERDEVICEHANDLES This function tells you how many devices the Optotrak SCU has detected.
%You'll need this to call OptotrakGetDeviceHandles(...).
% -> pnDeviceHandles is the variable the number of devices will be stored into.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pFlags ] = OptotrakGetProcessingFlags( pFlags )
%OPTOTRAKGETPROCESSINGFLAGS Fetches current processing flags from the system.
% The flags are binary, and you'll have to decompose them to binary in order to interpret this. Here's how:
% -> pFlags
% 0 (0x00000000): Clear all flags
% 1 (0x00000001): OPTO_LIB_POLL_REAL_DATA: blocking mode in real-time data transfers
% 2 (0x00000002): OPTO_CONVERT_ON_HOST: Makes the raw data to be converted in the host computer, as opposed to the system. Handy if you need more performance
% 4 (0x00000004): OPTO_RIGID_ON_HOST: Makes the rigid body calculations to be done on the host computer. This also can take off computational load from the system.
% 8 (0x00000008): OPTO_USE_INTERNAL_NIF: Use the network information in the device, as opposed to reading it from a file
% 16 (0x00000010): OPTO_USE_PRIMITIVE_RIGID_BODY_ALGORITHM: Undocumented, but can guess what it does :)
% 32 (0x00000020): OPTO_RIGID_NO_UPDATE3DDATA_MISSINGIFOFFANGLE: Undocumented
% 64 (0x00000040): OPTO_RIGID_NO_UPDATE3DDATA_MISSINGIFMAXERROR: Undocumented
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pnNumSensors, pnNumOdaus, pnNumRigidBodies, pnMarkers, pfFrameFrequency, pfMarkerFrequency, pnThreshold, pnMinimumGain, pnStreamData, pfDutyCycle, pfVoltage, pfCollectionTime, pfPreTriggerTime, pnFlags ] = OptotrakGetStatus( pnNumSensors, pnNumOdaus, pnNumRigidBodies, pnMarkers, pfFrameFrequency, pfMarkerFrequency, pnThreshold, pnMinimumGain, pnStreamData, pfDutyCycle, pfVoltage, pfCollectionTime, pfPreTriggerTime, pnFlags )
%OPTOTRAKGETSTATUS Queries the system for status.
% -> pnNumSensors is the number of sensors in use.
% -> pnNumOdaus is the number of ODAUs in the system
% -> pnNumRigidBodies is the number of rigid bodies in the system
% -> pnMarkers is the number of markers currently used in the system
% -> pfFrameFrequency is the current data acquisition rate
% -> pfMarkerFrequency is the frequency the IR LEDs are being strobed at
% -> pnThreshold is the threshold value in pixels used for processing
% -> pnMinimumGain is the minimum sensor gain used.
% -> pnStreamData: 0 for buffered data when requested, or 1, for automatically blasting data
% -> pfDutyCycle is the duty cycle used on the IR LEDs
% -> pfVoltage is the voltage the IR LEDs are driven at
% -> pfCollectionTime is the length in seconds for buffered data
% -> pfPreTriggerTime: not implemented, and is always 0.
% -> pnFlags is a binary mask. In Matlab, this is a single number, so if you want to read this, you'll need to de-compose it as follows:
% 0 (0x00000000): Clear all flags (also, OPTOTRAK_BACKGROUND_SUBTRACT_OFF), but it's undocumented
% 1 (0x00000001): OPTOTRAK_NO_INTERPOLATION_FLAG: When set, the position is not being interpolated within a frame.
% 2 (0x00000002): OPTOTRAK_FULL_DATA_FLAG: When set along with OPTOTRAK_BUFFER_RAW_FLAG, the device captures everything
% 4 (0x00000004): OPTOTRAK_PIXEL_DATA_FLAG: Undocumented
% 8 (0x00000008): OPTOTRAK_MARKER_BY_MARKER_FLAG: Undocumented
% 16 (0x00000010): OPTOTRAK_ECHO_CALIBRATE_FLAG: Undocumented
% 32 (0x00000020): OPTOTRAK_BUFFER_RAW_FLAG: Acquire the raw data instead of the 3D data.
% 64 (0x00000040): OPTOTRAK_NO_FIRE_MARKERS_FLAG: If this is set, the markers don't become active when this function is called. Call OptotrakActivateMarkers() to switch them on.
% 128 (0x00000080): OPTOTRAK_STATIC_THRESHOLD_FLAG: Use the static thresholds, set in nThreshold.
% 256 (0x00000100): OPTOTRAK_WAVEFORM_DATA_FLAG: Undocumented
% 512 (0x00000200): OPTOTRAK_AUTO_DUTY_CYCLE_FLAG: Undocumented. Presumably NDI wanted to control the brightness of the IR LEDs from within the system.
% 1024 (0x00000400): OPTOTRAK_EXTERNAL_CLOCK_FLAG: The capture frame rate can be from Pin 3 on the DB9 connector, using a TTL signal. Handy.
% 2048 (0x00000800): OPTOTRAK_EXTERNAL_TRIGGER_FLAG: Once this function executed, data acquisition only starts when pin 7 on the DB9 connector is pulled to ground.
% 4096 (0x00001000): OPTOTRAK_REALTIME_PRESENT_FLAG: Don't use it. Always 1.
% 8192 (0x00002000): OPTOTRAK_GET_NEXT_FRAME_FLAG: If this is set, the device will send the next frame instead of the current one. Prevents duplicates.
% 16384 (0x00004000): OPTOTRAK_SWITCH_AND_CONFIG_FLAG: If set, switch data is being set back to the computer. Only works with the Certus system.
% 32768 (0x00008000): OPTOTRAK_COLPARMS_ONLY_FLAG: Undocumented
% 65536 (0x00010000): Undocumented (reserved)
% 131072 (0x00020000): Undocumented (reserved)
% 262144 (0x00040000): Undocumented (reserved)
% 524288 (0x00080000): Undocumented (reserved)
% 1048576 (0x00100000): Undocumented (reserved)
% 2097152 (0x00200000): OPTOTRAK_BACKGROUND_SUBTRACT_ON: Undocumented
% 4194301 (0x00800000): Undocumented (reserved)
% 8388608 (0x01000000): Undocumented (reserved)
% 16777216 (0x02000000): ??? (it's not even in the header file)
% 33554432 (0x04000000): OPTOTRAK_CERTUS_FLAG (set by the Optotrak system itself)
% 67108864 (0x08000000): OPTOTRAK_RIGID_CAPABLE_FLAG (set by the Optotrak system itself)
% 134217728 (0x10000000): Undocumented (reserved)
% 268435456 (0x20000000): Undocumented (reserved)
% 536870912 (0x40000000): OPTOTRAK_CERTUS_FLAG and OPTOTRAK_REVISION_X22_FLAG (set by the Optotrak system itself)
% 1076741824 (0x80000000): OPTOTRAK_3020_FLAG (set by the Optotrak system itself)% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nNodeId, nSubNodeId, pdtNodeInfo ] = OptotrakGetSubNodeInfo( nNodeId, nSubNodeId, pdtNodeInfo )
%OPTOTRAKGETSUBNODEINFO This function gets information from sub-nodes into the system.
% Since NDI is obsessed with this weird transputer architecture, here is some explanation on what happens:
% Back in the day, the idea was that the 'control box' was a node, and the connected sensors and strobers to it was a 'sub-node'.
% However, just like any other company, they just bolted-on extra features to the old stuff to sell it as more expensive new stuff,
% so now the the SCU also has some sub-nodes that were integrated.
% -> nNodeId is the main node ID.
% 0: OPTOTRAK node
% 1: Undocumented (ODAU1?)
% 2: Undocumented (ODAU2?)
% 3: Undocumented (ODAU3?)
% 4: Undocumented (ODAU4?)
% 5: Undocumented (ODAU5?)
% 6: SENSOR_PROP1 node
% -> nSubNodeId is the sub-node ID for a given node:
% For the OPTOTRAK node:
% 299: CPLD (Complex Programmable Logic Device)
% 399: FPGA (Field-Programmable Gate Array)
% 499: 'Default FPGA'
% 599: Cypress (which is I presume is the wireless controller)
% For the SENSOR_PROP1 node (i.e. camera):
% 0: Sensor 0
% 1: Sensor 1
% 2: Sensor 2
% 3: Sensor 3
% Note that the Certus system has only 3 sensors. The PRO CMM has 4.
% -> pdtNodeInfo is the structure being written into
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszCamFile ] = OptotrakLoadCameraParameters( pszCamFile )
%OPTOTRAKLOADCAMERAPARAMETERS Loads camera settings from the given file
%This is the function that handles .cam files generated by TransputerDetermineCfg()
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = OptotrakSaveAutoScale( )
%OPTOTRAKSAVEAUTOSCALE This function saves the autoscale data into the device's non-volatile memory.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszCollectFile ] = OptotrakSaveCollectionToFile( pszCollectFile )
%OPTOTRAKSAVECOLLECTIONTOFILE Saves your settings to a config file specified
% This allows you to edit the file manually, and read it with OptotrakReadCollectionFromFile().
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nMarkerType, nWaveLength, nModelType ] = OptotrakSetCameraParameters( nMarkerType, nWaveLength, nModelType )
%OPTOTRAKSETCAMERAPARAMETERS This function allows you to change the marker type, its wavelength, and the camera lens model.
% -> nMarkerType:
% 1: Metal markers (default)
% 2: Ceramic markers
% 3: Unknown :)
% -> nWaveLength:
% 0: 950 nm (default)
% 1: 880 nm
% -> nModelType:
% 0: Original lens (default)
% 1: 'new' lens
% 2: 'new new' lens (wider angles)
% 3: PRO CMM
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, uFlags ] = OptotrakSetProcessingFlags( uFlags )
%OPTOTRAKSETPROCESSINGFLAGS Set or clear some processing flags from the API.
% You also can change these at optotrak.ini. But, should you need this, here it is:
% These are initalised in binary, so you'll need to add these numbers if you want to set muliple flags.
% You'll need to call TransputerInitializeSystem('') after this, carefully avoiding using a config file.
% -> uFlags
% 0 (0x00000000): Clear all flags
% 1 (0x00000001): OPTO_LIB_POLL_REAL_DATA: blocking mode in real-time data transfers
% 2 (0x00000002): OPTO_CONVERT_ON_HOST: Makes the raw data to be converted in the host computer, as opposed to the system. Handy if you need more performance
% 4 (0x00000004): OPTO_RIGID_ON_HOST: Makes the rigid body calculations to be done on the host computer. This also can take off computational load from the system.
% 8 (0x00000008): OPTO_USE_INTERNAL_NIF: Use the network information in the device, as opposed to reading it from a file
% 16 (0x00000010): OPTO_USE_PRIMITIVE_RIGID_BODY_ALGORITHM: Undocumented, but can guess what it does :)
% 32 (0x00000020): OPTO_RIGID_NO_UPDATE3DDATA_MISSINGIFOFFANGLE: Undocumented
% 64 (0x00000040): OPTO_RIGID_NO_UPDATE3DDATA_MISSINGIFMAXERROR: Undocumented
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nPort1, nPort2, nPort3, nPort4 ] = OptotrakSetStroberPortTable( nPort1, nPort2, nPort3, nPort4 )
%OPTOTRAKSETSTROBERTABLE This function configures how many markers have you got on each port.
% -> nPort1: The number of markers on Port 1.
% -> nPort2: The number of markers on Port 2.
% -> nPort3: The number of markers on Port 3.
% -> nPort4: The number of markers on port 4.
% If you are using the Certus system, you're out of luck, because it doesn't have a fourth port. However, the API doesn't know that,
% and nPort4 must be set to 0.
% Particulars of strobing are set in the optotrak.ini file.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nMarkers, fFrameFrequency, fMarkerFrequency, nThreshold, nMinimumGain, nStreamData, fDutyCycle, fVoltage, fCollectionTime, fPreTriggerTime, nFlags ] = OptotrakSetupCollection( nMarkers, fFrameFrequency, fMarkerFrequency, nThreshold, nMinimumGain, nStreamData, fDutyCycle, fVoltage, fCollectionTime, fPreTriggerTime, nFlags )
%OPTOTRAKSETUPCOLLECTION This function configures the Optotrak system using the parameters you specify here.
% Sets up the Optotrak system for data collection.
% -> nMarkers is the number of markers to be used
% -> fFrameFrequency is the data acquisition frame rate (lowest is 1, max is 4600 / [<number of markers> + 2] )
% -> fMarkerFrequency is the frequency the markers are driven at
% -> nThreshold is the noise threshold for the marker positions in sensor pixels. Can be adjusted statically (0...3000) or dynamically (0...3000)
% -> nMinimumGain is the gain to be applied on the sensor. (0...255)
% -> nStreamData decides whether the buffer is to be read out periodically or manually
% 0: You are reading out the buffer manually
% 1: The device sends the contents of the buffer automatically.
% -> fDutyCycle is the duty cycle the IR LEDs are turned on (0.1...0.85)
% -> fVoltage is the voltage the IR LEDs are being driven at (6.0....12.0)
%
% WARNING: DO NOT OVERDRIVE THE IR LEDS! YOU WILL DAMAGE THEM!!!!
% (rule of thumb: the duty cycle and the driving voltages are inversely proportional)
%
% -> fCollectionTime is the time the Optotrak records movement, in seconds (0, 99999), up to about 1600 hours.
% -> fPreTriggerTime is not implemented and has to be 0.
% -> nFlags is a binary mask. In Matlab, they are represented as binary numbers, so if you want to trigger multiple flags, just add their numbers:
% 0 (0x00000000): Clear all flags (also, OPTOTRAK_BACKGROUND_SUBTRACT_OFF), but it's undocumented
% 1 (0x00000001): OPTOTRAK_NO_INTERPOLATION_FLAG: When set, the position is not being interpolated within a frame.
% 2 (0x00000002): OPTOTRAK_FULL_DATA_FLAG: When set along with OPTOTRAK_BUFFER_RAW_FLAG, the device returns raw data
% 4 (0x00000004): OPTOTRAK_PIXEL_DATA_FLAG: Undocumented
% 8 (0x00000008): OPTOTRAK_MARKER_BY_MARKER_FLAG: Undocumented
% 16 (0x00000010): OPTOTRAK_ECHO_CALIBRATE_FLAG: Undocumented
% 32 (0x00000020): OPTOTRAK_BUFFER_RAW_FLAG: Acquire the raw data instead of the 3D data.
% 64 (0x00000040): OPTOTRAK_NO_FIRE_MARKERS_FLAG: If this is set, the markers don't become active when this function is called. Call OptotrakActivateMarkers() to switch them on.
% 128 (0x00000080): OPTOTRAK_STATIC_THRESHOLD_FLAG: Use the static thresholds, set in nThreshold.
% 256 (0x00000100): OPTOTRAK_WAVEFORM_DATA_FLAG: Undocumented
% 512 (0x00000200): OPTOTRAK_AUTO_DUTY_CYCLE_FLAG: Undocumented. Presumably NDI wanted to control the brightness of the IR LEDs from within the system.
% 1024 (0x00000400): OPTOTRAK_EXTERNAL_CLOCK_FLAG: The capture frame rate can be from Pin 3 on the DB9 connector, using a TTL signal. Handy.
% 2048 (0x00000800): OPTOTRAK_EXTERNAL_TRIGGER_FLAG: Once this function executed, data acquisition only starts when pin 7 on the DB9 connector is pulled to ground.
% 4096 (0x00001000): OPTOTRAK_REALTIME_PRESENT_FLAG: Don't use it. Always 1.
% 8192 (0x00002000): OPTOTRAK_GET_NEXT_FRAME_FLAG: If this is set, the device will send the next frame instead of the current one. Prevents duplicates.
% 16384 (0x00004000): OPTOTRAK_SWITCH_AND_CONFIG_FLAG: If set, switch data is being set back to the computer. Only works with the Certus system.
% 32768 (0x00008000): OPTOTRAK_COLPARMS_ONLY_FLAG: Undocumented
% 65536 (0x00010000): Undocumented (reserved)
% 131072 (0x00020000): Undocumented (reserved)
% 262144 (0x00040000): Undocumented (reserved)
% 524288 (0x00080000): Undocumented (reserved)
% 1048576 (0x00100000): Undocumented (reserved)
% 2097152 (0x00200000): OPTOTRAK_BACKGROUND_SUBTRACT_ON: Undocumented
% 4194301 (0x00800000): Undocumented (reserved)
% 8388608 (0x01000000): Undocumented (reserved)
% 16777216 (0x02000000): ??? (it's not even in the header file)
% 33554432 (0x04000000): OPTOTRAK_CERTUS_FLAG (set by the Optotrak system itself)
% 67108864 (0x08000000): OPTOTRAK_RIGID_CAPABLE_FLAG (set by the Optotrak system itself)
% 134217728 (0x10000000): Undocumented (reserved)
% 268435456 (0x20000000): Undocumented (reserved)
% 536870912 (0x40000000): OPTOTRAK_CERTUS_FLAG and OPTOTRAK_REVISION_X22_FLAG (set by the Optotrak system itself)
% 1076741824 (0x80000000): OPTOTRAK_3020_FLAG (set by the Optotrak system itself)
%
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszCollectFile ] = OptotrakSetupCollectionFromFile( pszCollectFile )
%OPTOTRAKSETUPCOLLECTIONFROMFILE Configures and initialises the Optotrak system from a specified config file. I added a sample config file in the examples directory
% -> pszCollectFile is a file name.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nMarkers, nSensors, pDataSourceFullRaw, pCentroids, pSensorsStatus ] = OptotrakSplitFullRaw( nMarkers, nSensors, pDataSourceFullRaw, pCentroids, pSensorsStatus )
%OPTOTRAKSPLITFULLRAW This function splits the full raw data to centroids and statuses.
% -> nMarkers is the number of markers found in the raw data
% -> nSensors is the number of sensors used to capture the raw data
% -> pDataSourceFullRaw is one frame of full raw data to be processed
% -> pCentroids is where the centroid data will be saved to
% -> pSensorsStatus is where the sensor status information will go
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = OptotrakStopCollection( )
%OPTOTRAKSTOPCOLLECTION This function makes the system stop collecting data
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestLatest3D( )
%REQUESTLATEST3D This function tells the Optotrak system to prepare to send the freshest 3D data avilable.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveLatest3D().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestLatestCentroid( )
%REQUESTLATESTCENTROID This function tells the Optotrak system to prepare to send the freshest centroid data avilable.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveLatestCentroid().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestLatestOdauRaw( nOdauId )
%REQUESTLATESTODAURAW This function tells the Optotrak system to prepare to send the freshest data available from a selected ODAU.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveLatestOdauRaw().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestLatestRaw( )
%REQUESTLATESTRAW This function tells the Optotrak system to prepare to send the freshest full raw data available.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveLatestRaw().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestLatestTransforms( )
%REQUESTLATESTTRANSFORMS This function tells the Optotrak system to prepare to send the freshest 6D rigid body data avilable.
% You must define the rigid bodies using RigidBodyAdd() or RigidBodyAddFromFile(), so the system could actually do the conversion.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveLatestRaw().
% Also make sure that you have only one request running at the time, otherwise you will corrput data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestNext3D( )
%REQUESTNEXT3D This function tells the Optotrak system wait until a new frame is captured and send the 3D data available.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveNext3D().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestNextCentroid( )
%REQUESTNEXTCCENTROID This function tells the Optotrak system wait until a new frame is captured and send the centroid data available.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveNextCentroid().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
unction [ fail ] = RequestNextOdauRaw( nOdauId )
%REQUESTNEXTODAURAW This function tells the Optotrak system to wait until a new frame is captured and send the data from a selected ODAU.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveNextOdauRaw().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% -> nOdauId is the ODAU selected, as follows:
% 2: ODAU1
% 3: ODAU2
% 4: ODAU3
% 5: ODAU4
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestNextRaw( )
%REQUESTNEXTRAW This function tells the Optotrak system to wait until a new frame is captured and send the full raw data available.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveNextRaw().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = RequestNextTransforms( )
%REQUESTNEXTTRANSFORMS This function tells the Optotrak system to wait until a new frame is captured and send the freshest 6D rigid body data available.
% You must define the rigid bodies using RigidBodyAdd() or RigidBodyAddFromFile(), so the system could actually do the conversion.
% Make sure you wait until DataIsReady() says so, and then you can call DataReceiveNextRaw().
% Also make sure that you have only one request running at the time, otherwise you will corrupt data.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nNumSwitches, pbSwtichData ] = RetrieveSwitchData( nNumSwitches, pbSwtichData )
%RETRIEVESWITCHDATA This is the function that allows you to get the states of the switches.
% Note that the switches are being monitored even after the data acquisition stopped. If you want to reset the switches,
% you will have to re-initialise the system.
% -> nNumSwitches is the number of switches
% -> pbSwtichData is where the switch states will be loaded to.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nRigidBodyId, nStartMarkers, nNumMarkers, pRigidCoordinates, pNormalCoordinates, nFlags ] = RigidBodyAdd( nRigidBodyId, nStartMarkers, nNumMarkers, pRigidCoordinates, pNormalCoordinates, nFlags )
%RIGIDBODYADD This function adds a rigid body definition for the Optotrak system to track.
% -> nRigidBodyId is specified by you, depending on what number you want to give it
% -> nStartMarkers tells the Optotrak system which marker is the rigid body's first marker
% -> nNumMarkers specifies the number of markers in the rigid body
% -> pRigidCoordinates is an x-y-z array where the marker positions go in 'home'.
% -> pNormalCoordinates will contain vectors that are normal (as in, perpendicular) to the markers' surface
% -> nFlags is a binary mask, for the rigid body settings. If you want to set multiple flags, you'll need to add these numbers:
% 1 (0x0001): OPTOTRAK_UNDETERMINED_FLAG is undocumented.
% 2 (0x0002): OPTOTRAK_STATIC_XFRM_FLAG is undocumented.
% 4 (0x0004): OPTOTRAK_STATIC_RIGID_FLAG tells the system to use the rigid body's current position and orientation as the origin of its local cooridnate system
% 8 (0x0008): OPTOTRAK_CONSTANT_RIGID_FLAG tells the Optotrak system to measure a rigid body's movement with respect to an other rigid body's movement
% 16 (0x0010): OPTOTRAK_NO_RIGID_CALCS_FLAG makes the Optotrak system not to calculate positions for this rigid body
% 32 (0x0020): OPTOTRAK_DO_RIGID_CALCS_FLAG restarts the rigid body calculations for this specified rigid body
% 64 (0x0040): OPTOTRAK_QUATERN_RIGID_FLAG uses Berthold Horn's algorithm to track the rigid body. More info here: Horn, Berthold KP. "Relative orientation." International Journal of Computer Vision 4.1 (1990): 59-78.
% 128 (0x0080): OPTOTRAK_ITERATIVE_RIGID_FLAG uses the Iterative Euler Algorithm to track your rigid body. In general, it's slower, but can be more accurate.
% 256 (0x0100): OPTOTRAK_SET_QUATERN_ERROR_FLAG is undocumented
% 512 (0x0200): OPTOTRAK_SET_MIN_MARKERS_FLAG is undocumented
% 1024 (0x0400): OPTOTRAK_RIGID_ERR_MKR_SPREAD is undocumented
% 2048 (0x0800): OPTOTRAK_USE_SCALED_MAX3DERROR is undocumented
% 4096 (0x1000): OPTOTRAK_RETURN_QUATERN_FLAG makes the function return the rigid body transform in quaternion format
% 8192 (0x2000): OPTOTRAK_RETURN_MATRIX_FLAG gets your data back in the rotation matrix format
% 16384 (0x4000): OPTOTRAK_RETURN_EULER_FLAG gives you the rigid body transform in the Euler Angle format, IN RADIANS!!!
% This a computationally intensive function. Add a few seconds' worth of sleep after calling this. Also, be aware that some flags can't be set at the same time.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nDeviceHandle, nFlags ] = RigidBodyAddFromDeviceHandle( nDeviceHandle, nFlags )
%RIGIDBODYADDFROMDEVICEHANDLE This function adds a rigid body from a device to be tracked by the Optotrak system.
% -> nDeviceHandle is the device you want to get the rigid body from
% -> nFlags is a binary mask, for the rigid body settings. If you want to set multiple flags, you'll need to add these numbers:
% 1 (0x0001): OPTOTRAK_UNDETERMINED_FLAG is undocumented.
% 2 (0x0002): OPTOTRAK_STATIC_XFRM_FLAG is undocumented.
% 4 (0x0004): OPTOTRAK_STATIC_RIGID_FLAG tells the system to use the rigid body's current position and orientation as the origin of its local cooridnate system
% 8 (0x0008): OPTOTRAK_CONSTANT_RIGID_FLAG tells the Optotrak system to measure a rigid body's movement with respect to an other rigid body's movement
% 16 (0x0010): OPTOTRAK_NO_RIGID_CALCS_FLAG makes the Optotrak system not to calculate positions for this rigid body
% 32 (0x0020): OPTOTRAK_DO_RIGID_CALCS_FLAG restarts the rigid body calculations for this specified rigid body
% 64 (0x0040): OPTOTRAK_QUATERN_RIGID_FLAG uses Berthold Horn's algorithm to track the rigid body. More info here: Horn, Berthold KP. "Relative orientation." International Journal of Computer Vision 4.1 (1990): 59-78.
% 128 (0x0080): OPTOTRAK_ITERATIVE_RIGID_FLAG uses the Iterative Euler Algorithm to track your rigid body. In general, it's slower, but can be more accurate.
% 256 (0x0100): OPTOTRAK_SET_QUATERN_ERROR_FLAG is undocumented
% 512 (0x0200): OPTOTRAK_SET_MIN_MARKERS_FLAG is undocumented
% 1024 (0x0400): OPTOTRAK_RIGID_ERR_MKR_SPREAD is undocumented
% 2048 (0x0800): OPTOTRAK_USE_SCALED_MAX3DERROR is undocumented
% 4096 (0x1000): OPTOTRAK_RETURN_QUATERN_FLAG makes the function return the rigid body transform in quaternion format
% 8192 (0x2000): OPTOTRAK_RETURN_MATRIX_FLAG gets your data back in the rotation matrix format
% 16384 (0x4000): OPTOTRAK_RETURN_EULER_FLAG gives you the rigid body transform in the Euler Angle format, IN RADIANS!!!
% This a computationally intensive function. Add a few seconds' worth of sleep after calling this. Also, be aware that some flags can't be set at the same time.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nRigidBodyId, nStartMarker, pszRigFile, nFlags ] = RigidBodyAddFromFile( nRigidBodyId, nStartMarker, pszRigFile, nFlags )
%RIGIDBODYADDFROMFILE This function adds a rigid body to be tracked by the Optotrak system from a specified file.
% -> nRigidBodyId is a number you can choose to identify the rigid body you are loading
% -> nStartMarker tells the Optotrak system which is the first infrared marker that belongs to the rigid body
% -> pszRigFile is the name of .rig file you want to load. Don't use the extension in this argument (i.e. call 'blabla', instead of 'blabla.rig')
% -> nFlags is a binary mask, for the rigid body settings. If you want to set multiple flags, you'll need to add these numbers:
% 1 (0x0001): OPTOTRAK_UNDETERMINED_FLAG is undocumented.
% 2 (0x0002): OPTOTRAK_STATIC_XFRM_FLAG is undocumented.
% 4 (0x0004): OPTOTRAK_STATIC_RIGID_FLAG tells the system to use the rigid body's current position and orientation as the origin of its local cooridnate system
% 8 (0x0008): OPTOTRAK_CONSTANT_RIGID_FLAG tells the Optotrak system to measure a rigid body's movement with respect to an other rigid body's movement
% 16 (0x0010): OPTOTRAK_NO_RIGID_CALCS_FLAG makes the Optotrak system not to calculate positions for this rigid body
% 32 (0x0020): OPTOTRAK_DO_RIGID_CALCS_FLAG restarts the rigid body calculations for this specified rigid body
% 64 (0x0040): OPTOTRAK_QUATERN_RIGID_FLAG uses Berthold Horn's algorithm to track the rigid body. More info here: Horn, Berthold KP. "Relative orientation." International Journal of Computer Vision 4.1 (1990): 59-78.
% 128 (0x0080): OPTOTRAK_ITERATIVE_RIGID_FLAG uses the Iterative Euler Algorithm to track your rigid body. In general, it's slower, but can be more accurate.
% 256 (0x0100): OPTOTRAK_SET_QUATERN_ERROR_FLAG is undocumented
% 512 (0x0200): OPTOTRAK_SET_MIN_MARKERS_FLAG is undocumented
% 1024 (0x0400): OPTOTRAK_RIGID_ERR_MKR_SPREAD is undocumented
% 2048 (0x0800): OPTOTRAK_USE_SCALED_MAX3DERROR is undocumented
% 4096 (0x1000): OPTOTRAK_RETURN_QUATERN_FLAG makes the function return the rigid body transform in quaternion format
% 8192 (0x2000): OPTOTRAK_RETURN_MATRIX_FLAG gets your data back in the rotation matrix format
% 16384 (0x4000): OPTOTRAK_RETURN_EULER_FLAG gives you the rigid body transform in the Euler Angle format, IN RADIANS!!!
% This a computationally intensive function. Add a few seconds' worth of sleep after calling this. Also, be aware that some flags can't be set at the same time.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nRigidBodyId, nRotationMethod ] = RigidBodyChangeFOR( nRigidBodyId, nRotationMethod )
%RIGIDBODYCHANGEFOR This function changes the coordinate system in which the rigid body positions are calculated.
% -> nRigidBodyId is the identifier of the rigid body you specified when added/loaded it
% -> nRotationMethod can be two values:
% 4 (0x0004): OPTOTRAK_STATIC_RIGID_FLAG tells the system to use the rigid body's current position and orientation as the origin of its local cooridnate system
% 8 (0x0008): OPTOTRAK_CONSTANT_RIGID_FLAG tells the Optotrak system to measure a rigid body's movement with respect to an other rigid body's movement
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nRigidBodyId, nMinMarkers, nMaxMarkerAngle, fMax3dError, fMaxSensorError, fMax3dRmsError, fMaxSensorRmsError, nFlags ] = RigidBodyChangeSettings( nRigidBodyId, nMinMarkers, nMaxMarkerAngle, fMax3dError, fMaxSensorError, fMax3dRmsError, fMaxSensorRmsError, nFlags )
%rigidbodychangesettings This function enables you to change the rigid body definition in the Optotrak system.
% -> nRigidBodyId is the identifier of the previously added rigid body which you want to change
% -> nMinMarkers is the minimum number of visible markers to be able to do a rigid body transformation
% -> nMaxMarkerAngle is the maximum angle which a marker can rotate with. This also requires the normal vectors of the markers to be loaded as well.
% -> fMax3dError is the maximum calculated 3D position error, in millimetres.
% -> fMaxSensorError is the maximum raw data error (in pixels) above which the system will ignore the bad marker's data
% -> fMax3dRmsError is tha maximum 3D Root Mean Square (RMS) error in millimetres. If the transformation error is larger than this value, it will fail.
% -> fMaxSensorRmsError is the maximum raw pixel data RMS error. If the error is larger than this vale, the transform will fail.
% -> nFlags is a binary mask, for the rigid body settings. If you want to set multiple flags, you'll need to add these numbers:
% 1 (0x0001): OPTOTRAK_UNDETERMINED_FLAG is undocumented.
% 2 (0x0002): OPTOTRAK_STATIC_XFRM_FLAG is undocumented.
% 4 (0x0004): OPTOTRAK_STATIC_RIGID_FLAG tells the system to use the rigid body's current position and orientation as the origin of its local cooridnate system
% 8 (0x0008): OPTOTRAK_CONSTANT_RIGID_FLAG tells the Optotrak system to measure a rigid body's movement with respect to an other rigid body's movement
% 16 (0x0010): OPTOTRAK_NO_RIGID_CALCS_FLAG makes the Optotrak system not to calculate positions for this rigid body
% 32 (0x0020): OPTOTRAK_DO_RIGID_CALCS_FLAG restarts the rigid body calculations for this specified rigid body
% 64 (0x0040): OPTOTRAK_QUATERN_RIGID_FLAG uses Berthold Horn's algorithm to track the rigid body. More info here: Horn, Berthold KP. "Relative orientation." International Journal of Computer Vision 4.1 (1990): 59-78.
% 128 (0x0080): OPTOTRAK_ITERATIVE_RIGID_FLAG uses the Iterative Euler Algorithm to track your rigid body. In general, it's slower, but can be more accurate.
% 256 (0x0100): OPTOTRAK_SET_QUATERN_ERROR_FLAG is undocumented
% 512 (0x0200): OPTOTRAK_SET_MIN_MARKERS_FLAG is undocumented
% 1024 (0x0400): OPTOTRAK_RIGID_ERR_MKR_SPREAD is undocumented
% 2048 (0x0800): OPTOTRAK_USE_SCALED_MAX3DERROR is undocumented
% 4096 (0x1000): OPTOTRAK_RETURN_QUATERN_FLAG makes the function return the rigid body transform in quaternion format
% 8192 (0x2000): OPTOTRAK_RETURN_MATRIX_FLAG gets your data back in the rotation matrix format
% 16384 (0x4000): OPTOTRAK_RETURN_EULER_FLAG gives you the rigid body transform in the Euler Angle format, IN RADIANS!!!
% This a computationally intensive function. Add a few seconds' worth of sleep after calling this. Also, be aware that some flags can't be set at the same time.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, nRigidBodyId ] = RigidBodyDelete( nRigidBodyId )
%RIGIDBODYDELETE This function deletes the definition of a specified rigid body in the Optotrak system.
% -> nRigidBodyId is the identifier of the rigid body you want to get rid of
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pdtRotationMatrix, pdtTranslation, pdtOriginalPositionPtr, pdtTransformedPositionPtr ] = TransformPoint( pdtRotationMatrix, pdtTranslation, pdtOriginalPositionPtr, pdtTransformedPositionPtr )
%TRANSFORMPOINT This function calculates the 3D x-y-z point of a point, after it has been manipulated by translation and rotation.
% -> pdtRotationMatrix is the 3-by-3 matrix that contains the rotation data
% -> pdtTranslation has the translation structure
% -> pdtOriginalPositionPtr is your point's X-Y-Z data
% -> pdtTransformedPositionPtr is where the new coordinates go
% fail is the return value of the function. Since the function is initialised as void type, I gave it a constant 0.
% You have to manually inspect whether the function failed, by checking the output values for example.
function [fail, pszInputLogFile] = TransputerDetermineSystemCfg(pszInputLogFile)
%TRANSPUTERDETERMINESYSTEMCFG Whatever you did to the device, this needs to
%be called first.
% pszInputLogFile is the path for the log
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = TransputerInitializeSystem( uFlags )
%TRANSPUTERINITIALIZESYSTEM Checks if the hardware is compatible with this
%API, and then initialises the system.
% uFlags is a binary mask, you would normally have defines for this in the C API, but here:
% -> 0 for no logging
% -> 1 for error logs to 'opto.err'
% -> 2 errors and messages to 'opto.err'
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail, pszNifFile ] = TransputerLoadSystem( pszNifFile )
%TRANSPUTERLOADSYSTEM Loads system configuration. When loading the .nif
%files, make sure that the extension is missed off. i.e.
%TransputerLoadSystem('blabla') is loading blabla.nif.
%Make sure you add about 2 seconds delay after the function so the
%Optotrak system can work properly.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.
function [ fail ] = TransputerShutdownSystem()
%TRANSPUTERSHUTDOWNSYSTEM If you couldn't guess what this function does
%from its name, let me explain.
% If this was a nuclear reactor, this would be the equivalent of the SCRAM
% (Safety Rope-Cutting Axe-man) process, which gradually slows down and
% kills off the sustained chain reaction in the reactor core, which in turn
% minimises its heat output.
% fail is the return value of the function. The API docs don't go into details on what this does.
% So, 0 for all good, and pretty much anything else for fail.