moven software development kit documentation...moven software development kit documentation document...

Moven Software Development Kit

Documentation Document MV0302P Revision C, 21 December, 2007

Xsens Technologies B.V. Pantheon 6a phone +31-(0) 88-9736700 P.O. Box 559 fax +31-(0) 88-9736701 7500 AN Enschede e-mail [email protected]

The Netherlands internet www.moven.com

Moven Software Development Kit, © 2007-2008, Xsens Technologies B.V.

Revisions Revision Date By Changes A Jan 18 2007 JMU First version. A1 Mar 16 2007 JMU Finalized for first release. B June 12, 2007 JMU Prefixes for all functions and structures B1 Aug 13, 2007 JMU New functions added C Dec 21, 2007 JMU Release 2.0

© 2007, Xsens Technologies B.V. All rights reserved. Information in this document is subject to change without notice. Xsens is a registered trademark of Xsens Technologies B.V. Moven is a trademark of Xsens Technologies B.V.

MV0302P.C 1


Table of Contents 1 INTRODUCTION 4

1.1 BUILDING AND RUNNING XME APPLICATIONS 4 2 RECOMMENDED WORKFLOW 5 3 XME CONTROL DEFINITION 8

3.1 XSENS RESULT VALUES 8 3.2 INTERFACE FUNCTIONS 10

3.2.1 General interfaces 10 xmeCreateInstance 10 xmeDestroyInstance 10 xmeDisconnectHardware 10 xmeGetDllVersion 11 xmeGetInstance 11 xmeGetLastResult 11 xmeGetStatus 11 xmeResultAsText 12 xmeSetCallback 12 xmeSetScanMode 12

3.2.2 MVN File interfaces 13 xmeNewMvnFile 13 xmeOpenMvnFile 13 xmeSaveMvnFile 13 xmeCloseMvnFile 13 xmeGetUserComment 13 xmeSetUserComment 14 xmeGetMarkerList 14 xmeGetMarkerText 14 xmeSetMarker 14

3.2.3 Linked segment model interface 15 xmeGetActorDimensionDescription 15 xmeGetActorDimensionLabelList 15 xmeGetActorDimensionValue 15 xmeGetPointInfoList 15 xmeGetPointOffset 16 xmeGetSegmentId 16 xmeGetSegmentLabel 16 xmeSetActorDimension 16

3.2.4 Segment calibration interface 17 xmeGetCalibrationLabelList 17 xmeInitializeCalibration 17 xmeAbortCalibration 17 xmeClearCalibration 17 xmeFinalizeCalibration 18 xmeGetCalibrationPose 18 xmeGetCalibrationResult 19 xmeIsCalibrationPerformed 19 xmeStartCalibration 19 xmeStopCalibration 20

3.2.5 Motion Capture interface 20 xmeGetConfiguration 20 xmeGetConfigurationLabelList 20 xmeGetPose 21 xmeGetSampleRate 21 xmeGetUserScenario 21 xmeGetUserScenarioLabelList 21 xmeReprocessData 22 xmeSetConfiguration 22 xmeSetSampleRate 22 xmeSetUserScenario 23

MV0302P.C 2


xmeStartRecording 23 xmeStopRecording 23 xmeSetSleepMode 23

3.2.6 Aiding interfaces 24 xmeAddAiding 24 xmeClearAiding 24 xmeGetExternalContacts 25 xmeSetExternalContacts 25

APPENDIX I TYPES AND STRUCTURES 26 XmeAiding 26 XmeAidingType 26 XmeCalibrationQuality 27 XmeConnectionQuality 27 XmeContactFlag 27 XmeEventCallBackFunction 28 XmeEventType 29 XmeExternalContact 30 XmeExternalContactWithHeight 30 XmeFileStatus 30 XmeHwScanMode 31 XmeLabel 31 XmeMatrix3x3 31 XmePointInfo 32 XmePose 32 XmePoseType 33 XmeSegmentIds 33 XmeSegmentIndices 34 XmeSegmentState 35 XmeSegPoint 35 XmeStatus 35 XmeSuitStatus 37 XmeVector3 38 XmeVersion 38 XsensResultValue 38

APPENDIX II EXAMPLES 39 APPENDIX III XME 1.1 2.0 MIGRATION GUIDE 40

MV0302P.C 3


1 Introduction This document describes the workings of the XME SDK. It starts with a recommended workflow and continues with a reference of the various functions available in the XME SDK. But first, a short description of the system is given. XME stands for Xsens Moven Engine. The XME was created to allow for easy motion capture (mocap) of human subjects. The XME provides an abstraction from having to deal with hardware directly. It performs all data analysis automatically so that the output is clean orientation and position data of the subject. This functionality is available in real-time, but post-processing with different filter settings or with changes to the data is also possible. The XME is autonomous once started. It runs in its own thread(s) and can be controlled by the supplied library functions. All functions return in a short time of less than 5 ms. If a task could take longer than this, the actual processing is done in one of the XME-threads and an event is generated when the task is completed. The application that is calling the XME can specify a callback function for handling these events. For a smooth operation it is important that this callback handler also returns in a few milliseconds. Data can be recorded to and read from MVN (MoVeN) files by the XME. These files have a proprietary format. With Moven Studio it is easy to export captured data to BVH or MVNX files, which use standard or non-proprietary formats1. The next chapter describes the suggested workflow, which is close to what is used in the Moven Studio application. For information on a particular function or data structure, you can use this document or you can refer to the Doxygen-generated documentation. It is also recommended to read the supplied examples as described in Appendix II.

1.1 Building and running XME applications The XME SDK was written in and for Microsoft Visual Studio 2005 (MSVS). The dll can be used with other compilers, but this has not been tested. To build an application with MSVS, make sure the application links with the XME.lib file and that the XME.h file can be found by the compiler. To run an XME application, the supplied dll, xsb and mvnc files need to be in a path where the application can find them. This path can be set with the xmeCreateInstance function for all files except the dll.

1 Exporting data to these formats must currently be done in Moven Studio, but this will also be supported in the XME SDK in the future.

MV0302P.C 4


2 Recommended workflow This is the recommended workflow for using the XME. It is close to the workflow that is used in the Moven Studio application. 1. Start of user application, this loads the dll into memory 2. Create an XME instance with xmeCreateInstance. Each XME instance can control a

single Moven suit or a single MVN file. 3. Initialise the callback function with xmeSetCallback. This function registers the

callback function that will handle events 4. Start a hardware scan with xmeSetScanMode. 5. The XME will now start searching for a Moven Suit. If a suit is found an

XME_ET_HARDWARE_READY event will be generated. If no hardware is found or there was a problem during detection, an XME_ET_HARDWARE_ERROR event will be generated. The nature and details of the error can be retrieved with xmeGetStatus. If the scan-mode is set to XME_HWSM_CONT, a hardware scan will be performed continuously until properly configured hardware has been found and initialized. XME_ET_HARDWARE_ERROR events will be generated after each unsuccessful attempt.

6. Viewing real-time data 6.1. Notify the XME that the application wants to receive real-time pose data by

using xmeSetRealTimePoseMode. This will make the XME start generating XME_ET_POSE_READY events every time a frame has been computed.

6.2. When an XME_ET_POSE_READY event is received, retrieve the last pose with xmeGetPose.

7. Calibrating It is very important to always perform calibration before recording data for obtaining the most accurate data. Although the default (uncalibrated) settings are sometimes acceptable, you should always perform at least a Tpose calibration.

7.1. Setting actor dimensions 7.1.1. The first calibration to perform should be to set the basic sizes of the

person in the suit (the actor). Use a call to xmeGetActorDimensionLabelList to get the list of available actor dimensions.

7.1.2. Set the known dimensions with the xmeSetActorDimension function. 7.2. Performing suit calibrations

7.2.1. Use a call to xmeGetCalibrationLabelList to retrieve the list of available calibration methods.

7.2.2. Call xmeIsCalibrationPerformed to check which calibrations have been performed and xmeGetCalibrationResult for the (global) consistency and quality indicators of the calibrations that have been performed. Xsens has sorted the different calibration methods so that the most important methods are at the top of the list.

7.2.3. Perform a calibration

MV0302P.C 5


7.2.3.1. Call xmeInitializeCalibration with the desired calibration name. This loads the details about the given calibration from a calibration file (.mvnc). Note that from version 2.0, a Tpose is required before other calibrations can be started.

7.2.3.2. Request the phase-markers with xmeGetCalibrationPhaseList and the phase text of each marker with xmeGetCalibrationPhaseText. This text describes which action the person in the suit should perform during the phase. This is somewhat deprecated in 2.0, because all calibrations have only one phase.

7.2.3.3. Playback the example poses with calls to xmeGetCalibrationPose, which is syntactically identical to xmeGetPose.

7.2.3.4. Begin the calibration by calling xmeStartCalibration; this starts the recording of calibration data to a temporary file.

7.2.3.5. Playback of the example poses with calls to xmeGetCalibrationPose during recording. It is required to fetch at least one pose from each phase, since a side-effect of the xmeGetCalibrationPose function is the administration of which phases the calibration procedure is in. It is not possible to return to a previous phase during recording by requesting a previous phase pose. Use xmeStopCalibration and xmeStartCalibration functions to repeat the calibration from start.

7.2.3.6. End the calibration by calling xmeStopCalibration. At this point, XME will start to process the calibration sequence and will give an XME_ET_CALIBRATION_PROCESSED event on completion.

7.2.3.7. With xmeGetCalibrationResults the quality of the calibration can be requested.

7.2.3.8. If the calibration is acceptable, use xmeFinalizeCalibration to commit the calibration sequence to the fusion engine. The (global) consistency value is updated in the segment calibration list. When the commit is complete, an XME_ET_CALIBRATION_COMPLETE event will be given.

7.2.3.9. At all times it is possible to abort the calibration by calling xmeAbortCalibration, which will generate an XME_ET_CALIBRATION_ABORTED event on completion. To restart from an aborted calibration, you must start again with an xmeInitializeCalibration. To retry a failed calibration, use xmeStopCalibration and xmeStartCalibration.

7.2.4. A performed calibration can be cleared from the list by calling xmeClearCalibration. This also updates the global consistency and will generate an XME_ET_CALIBRATION_COMPLETE event upon completion.

8. Recording & Playback 8.1. The application can create a new MVN file by calling xmeNewMvnFile. 8.2. The application can now start recording to the file by calling the

xmeStartRecording function. 8.3. Markers can be added at any time by calling the xmeSetMarker function.

Existing markers can also be removed individually by calling xmeSetMarker with a NULL text. The old limit of 50 markers per file has been removed.

8.4. The application can stop recording by calling the xmeStopRecording function or by calling the xmeCloseMvnFile function.

MV0302P.C 6


8.4.1. Once a file has been recorded to, it is impossible to record new motion capture data to that same file again unless the file is closed first and then overwritten by a call to xmeNewMvnFile.

8.4.2. Any unsaved data is automatically saved to the file when it is closed, but an explicit call to xmeSaveMvnFile can also do this. The XME handles recorded poses in files directly on-disk. So any change to pose data is immediately saved in the file, without an undo option. Make sure to make backups when experimenting with MVN files.

8.5. A file can be opened with the xmeOpenMvnFile function. Note that this is only possible in an XME instance that is not handling hardware at the moment. This is mainly to prevent ambiguities when calling certain functions.

8.6. Pose data can be retrieved from an open file with the xmeGetPose function and a supplied frame number.

8.7. External contacts can be checked, added and removed with xmeGetExternalContacts, xmeSetExternalContacts and xmeSetExternalContactsRt.

8.8. It is possible to reprocess all data by calling the xmeReprocessData function. Note that this function also is only available when no hardware is connected to the XME instance. Hardware can be disconnected with the xmeDisconnectHardware function, but it is advised to close the file and open it again with another XME instance, since reconnecting to the hardware can take a few seconds.

8.8.1. After every Nth frame that has been re-processed an XME_ET_PROCESSING_INTERMEDIATE event is generated. By default N is set to 100. It can be changed by calling xmeSetProcessingEventInterval.

9. Destroy the XME instance(s) with xmeDestroyXmeInstance. This cleans up the memory used by the instance and closes any files and hardware connections associated with the instance. It is also possible to simply close the application, in which case the XME dll will clean itself up.

MV0302P.C 7


3 XME control definition This section describes some of the various functions that are available in the Moven/XME SDK, grouped roughly by functionality. For a complete alphabetical list, please check the doxygen-generated html-documentation supplied with the SDK. XME is implemented as a DLL with standard C interfaces. It uses an instance identifier to handle multiple simultaneous files or suits. These instance identifiers are similar to regular handles, but they are allocated and deallocated by the XME dll. Each instance can deal with either a single suit or a single file. Moven 2.0 has a maximum of 20 instances that can be in use at one time, just like Moven 1.1. All XME calls are designed to be non-blocking. The fast functions perform their operation and return when it is complete. The slow functions return immediately and generate an event (XME_ET_...) on completion.

3.1 Xsens Result Values Most functions have an XsensResultValue (XRV) as the direct return code. These codes describe what went wrong or if everything went OK. The most common XRV codes with their descriptions are included below. The description of all codes can be retrieved with the xmeResultAsText function. XRV_OK Operation was performed successfully. The

value of XRV_OK is 0. XRV_INVALIDPARAM An invalid parameter is supplied. This indicates

that a parameter exceeds some boundaries. XRV_ERROR A generic error occurred. This is only returned

when XME can’t supply more useful information about the nature of the error.

XRV_NOTIMPLEMENTED Operation not implemented in this version (yet). Some functions may not be fully implemented, while their interfaces are already made available. When the not-implemented functionality is requested, this value is returned.

XRV_TIMEOUT A timeout occurred while waiting for an operation to complete.

XRV_TIMEOUTNODATA A timeout occurred while waiting for data and no data was received at all.

XRV_NOTFOUND The requested item was not found. XRV_INVALIDID Invalid id supplied. XRV_INVALIDOPERATION The requested operation can not be performed at

this particular time. This is due to the state of the system and whether hardware is connected, a file is open, etc.

XRV_INPUTCANNOTBEOPENED The specified i/o device (file or COM port) can not be opened.

MV0302P.C 8


XRV_OUTPUTCANNOTBEOPENED The specified i/o device can not be opened. XRV_ALREADYOPEN An I/O device is already opened with this

object. XME can’t handle multiple files or multiple suits in a single instance at the same time.

XRV_COULDNOTREADSETTINGS A required settings file could not be opened or is missing some data. This could indicate a corrupt MVN file or an old xmedef.xsb file.

XRV_READONLY Tried to change a read-only value. XRV_NULLPTR Tried to supply a NULL value where it is not

allowed. XRV_INVALIDINSTANCE Invalid instance called. Make sure the instance

number was created with xmeCreateInstance. XRV_READINITFAILED Failure during read of settings. This could

indicate a corrupt MVN file or an old xmedef.xsb file.

XRV_NOXMFOUND Could not find any Moven-compatible hardware. No Xbus Masters found at all.

XRV_ONLYONEXMFOUND Found only one responding Xbus Master. Two are required.

XRV_MTLOCATIONINVALID One or more sensors are not where they were expected. This is a common problem, usually the left and right hands or feet are switched. The problematic devices can be requested with xmeGetStatus.

XRV_INSUFFICIENTMTS Not enough sensors were found for the currently selected configuration. The missing devices can be requested with xmeGetStatus.

XRV_INITFUSIONFAILED Failure during initialization of Fusion Engine. This could indicate a corrupt MVN file or an old xmedef.xsb file.

XRV_NOFILEOPEN No file opened for reading/writing, while the operation requires a file to be open.

XRV_NOPORTOPEN No serial port opened for reading/writing, while the operation requires a COM port to be open.

XRV_NOFILEORPORTOPEN No file or serial port opened for reading/writing, while the operation requires a COM port or file to be open.

XRV_PORTNOTFOUND A specified COM port could not be found. Try to let the system scan for ports automatically or check if the port number is correct.

XRV_CONFIGCHECKFAIL The in-config check of the device failed. Upon connection, some diagnostics are run on the hardware and one of the tests has failed.

XRV_SYNC_DATA_MISSING A device is not sending enough data. This usually indicates that the sync-cable is not connected properly.

MV0302P.C 9


3.2 Interface functions This is a sampling of the currently defined functions and their parameters. Please read the doxygen-generated documentation for a full list and more details about each function.

3.2.1 General interfaces

xmeCreateInstanceParameters in: A string with the path where the settings files can be found. Output integer containing an instance number Prototype long xmeCreateInstance(const char* settingsPath, const char*

serialKey)

Description When using the XME dll, an instance number is required for every function call. This instance identifies the distinct XME object that should perform the function. The xmeCreateInstance function supplies that number after creating a new XME object. The output is the first parameter in all other functions (long instance). From version 2.0 onwards, XME requires you to supply the serial code of your product when requesting an instance. This is the full code, including dashes. The settingsPath is the place where the settings (xmedef.xsb) and calibration files (*.mvnc) can be found. When set to NULL, the path of the dll is used as the base path for reading these files.

xmeDestroyInstanceParameters in: The instance number of the XME object that should be destroyed. Output none Prototype void xmeDestroyInstance(long instance)

Description Destroys the given XME object, freeing up its instance number for use by another process. This also saves and closes any open MVN files and disconnects hardware.

Events XME_ET_RECORDING_STOPPED when called while recording

xmeDisconnectHardwareParameters none Output XsensResultValue indicating success or failure. Prototype XsensResultValue xmeDisconnectHardware(const long instance)

Description Stops all interaction with hardware (closing all connected ports, possibly ending recording, etc.)

Events XME_ET_RECORDING_STOPPED when called while recording XME_ET_HARDWARE_DISCONNECTED once the hardware is disconnected

Notes If hardware scanning is set to XME_HWSM_CONT, a new hardware scan will be initiated automatically after the connection has been closed.

MV0302P.C 10


xmeGetDllVersionParameters none Output XmeVersion structure containing 4 unsigned shorts that contain the full

version of the dll. Prototype XmeVersion xmeGetDllVersion(void)

Description Returns the version of the dll in use. The XmeVersion structure contains m_major, m_minor, m_revision and m_build.

Notes Usually only the major and minor fields are relevant for determining the version of the XME dll. The official releases of Moven 2.0 and higher will always return a 0 in the revision and build fields.

xmeGetInstanceParameters in: const void* containing a pointer to an XME object Output integer containing an instance number or -1 Prototype long getInstance(const void* object)

Description Returns the instance number associated with the given XME object. If the pointer is not an XME object or there is no instance number associated with it, the function will return -1. This function is only useful in an XmeEventCallBackFunction, where only a pointer is supplied. A pointer is supplied to the callback function instead of an instance number due to technical limitations.

xmeGetLastResultParameters none Output XsensResultValue of the last user call Prototype XsensResultValue xmeGetLastResult(const long instance)

Description Returns the result code of the last user call.

xmeGetStatusParameters in/out: status, a pointer to an XmeStatus object that will be filled Output XsensResultValue indicating success or error Prototype XsensResultValue getStatus(const long instance, XmeStatus*

status)

Description Returns the full status of the XME system in a status structure. See Appendix I and doxygen docs for more information about the XmeStatus data structure.

MV0302P.C 11


xmeResultAsTextParameters in: XsensResultValue that needs to be translated Output XsensResultValue indicating success or error Prototype const char* xmeResultAsText(const XsensResultValue result)

Description Returns a pointer to a descriptive text associated with the given result code. The pointer points to a static descriptive text, which should not be modified, freed or deleted.

xmeSetCallbackParameters in: XmeEventCallBackFunction* or NULL. The type is defined as:

typedef void (*XmeEventCallBackFunction)(const XmeEventType, void*, void*)

in: void* a parameter passed to the call-back function on every call, may be NULL.

Output XsensResultValue indicating success or error Prototype XsensResultValue setCallback(const long instance,

XmeEventCallBackFunction callback, void* callbackParam)

Description The callback parameter, when not NULL is used by XME for event notification. When set to NULL, the event triggering mechanism is disabled for this instance. The callbackParam value is passed to the callback function on every call. When not used, the value may be set to NULL or any other value.

xmeSetScanModeParameters in: XmeHwScanMode, one of XME_HWSM_OFF, XME_HWSM_ONCE, XME_HWSM_CONT Output XsensResultValue indicating success or error Prototype XsensResultValue setScanMode(const long instance, const

XmeHwScanMode scanMode)

Description Tell the XME instance to start or stop scanning for hardware. If scanMode is XME_HWSM_ONCE or XME_HWSM_CONT, XME will scan for hardware. If the scanMode is XME_HWSM_CONT, the system will keep scanning until compatible hardware is found and will generate an event after every scan-loop. When scanMode is XME_HWSM_ONCE, only one scan will be performed. Use xmeGetStatus to get the latest status information about XME, including hardware status and possible problems.

Events An XME_ET_HARDWARE_ERROR or XME_ET_HARDWARE_READY event is sent at the end of every scan loop.

MV0302P.C 12


3.2.2 MVN File interfaces

xmeNewMvnFileParameters in: path + filename of .mvn file Output XsensResultValue indicating success or error Prototype XsensResultValue xmeNewMvnFile(const long instance, const char*

filename)

Description Creates and opens a new .mvn-file. The filename is automatically suffixed with a .mvn extension if necessary. Any currently open mvn file will be saved and closed first. If the required mvn-file already exists, it will be overwritten.

xmeOpenMvnFileParameters in: path + filename of .mvn file Output XsensResultValue indicating success or error Prototype XsensResultValue xmeOpenMvnFile(const long instance, const char*

filename)

Description Opens an existing .mvn-file. The filename is automatically suffixed with a .mvn extension if necessary. Any currently open mvn file will be saved and closed first.

xmeSaveMvnFileParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSaveMvnFile(const long instance)

Description Stores all unsaved data into the current .mvn file. This includes meta-data, frame-count information, etc.

xmeCloseMvnFileParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeCloseMvnFile(const long instance)

Description Stores all unsaved data into the current .mvn file and closes the file.

xmeGetUserCommentParameters in: The index of the user comment to retrieve.

out: buffer will be filled with the comment. Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetUserComment(const long instance, const

uint32 index, char* buffer)

Description This function will get the indicated comment from the open mvn file. index can be any positive integer value from 1, while buffer must be able to contain at least XSENS_LONG_STRING_SIZE (16384) characters.

MV0302P.C 13


xmeSetUserCommentParameters in: The index of the user comment to set.

in: A buffer containing a user comment. Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetUserComment(const long instance, const

uint32 index, const char* buffer)

Description This function will set the indicated comment in the open mvn file. index can be any positive integer value from 1, while the text in buffer should not be larger than XSENS_LONG_STRING_SIZE (16384) characters.

xmeGetMarkerListParameters out: list of frame numbers where markers are defined Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetMarkerList(const long instance, uint32*

markers, uint32* markerCount, uint32 maxMarkers)

Description Returns a list with the frames at which markers are defined.

xmeGetMarkerTextParameters in: number of the frame for which the marker text should be retrieved

out: the text of the marker Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetMarkerText(const long instance, const

uint32 frameNumber, char* text)

Description Fills the text-buffer with the text of the marker at the given frame number. The text buffer should be able to contain 256 characters worth of text. If no marker is defined, XRV_NOTFOUND is returned and text will be set to an empty string.

xmeSetMarkerParameters in: number of the frame for which the marker text should be set

in: the text of the marker Output XsensResultValue indicating success or error Prototype XsensResultValue setMarker (const long instance, const uint32

frameNumber, const char* text)

Description Sets a marker at the given frame number. The text should be less than 256 characters long. Passing a NULL text or an empty string will clear the given marker.

MV0302P.C 14


3.2.3 Linked segment model interface

xmeGetActorDimensionDescriptionParameters in: label, string containing actor dimension label

out: description, buffer that will contain the description (must be at least 256 chars)

Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetActorDimensionDescription(const long

instance, const char* label, char* description)

Description Retrieves the specified actor dimension description. The stored description is copied to the description parameter, which must be at least 256 characters long.

xmeGetActorDimensionLabelListParameters none Output const XmeLabel* pointing to the NULL-terminated list of actor dimensions.Prototype const XmeLabel* xmeGetActorDimensionLabelList(const long

instance)

Description Returns the labels of the implemented actor dimensions. A label is defined as char[64].

xmeGetActorDimensionValueParameters in: label, string containing actor dimension label

out: value, the value of the actor dimension Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetActorDimensionValue(const long

instance, const char* label, double* value)

Description Retrieves the specified actor dimension value into the value parameter.

xmeGetPointInfoListParameters in: the segment ID for which to retrieve point information Output const XmePointInfo* list containing the point information Prototype const XmePointInfo* xmeGetPointInfoList(const long instance,

unsigned short segmentId)

Description Returns the info of all relevant points for the given segment, terminated by a point with an empty label. See XmePointInfo description for more details. Although the list is ‘const’, it is advised to make a copy, because the list may be reused (and changed) when this function is called for another segment.

MV0302P.C 15


xmeGetPointOffsetParameters in: ids of the segment-point combination

in: quaternion (in w,x,y,z format) containing the rotation of the segment out: vector (x,y,z) containing the offset of the point

Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetPointOffset(const long instance, const

unsigned short segmentId, const unsigned short pointId, const double* quat, double* offset)

Description This function retrieves the offset in global coordinates of the given point relative to the segment origin. The segment uses the supplied quaternion as its orientation before computing the offset.

xmeGetSegmentIdParameters in: Segment name

out: Segment id Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetSegmentId(const long instance, const

char* label, uint32* segmentId)

Description Retrieves the segment id (1-based) of the segment with the given name. If the name is not found, the result value will be XRV_NOTFOUND.

xmeGetSegmentLabelParameters in: Segment id

out: Segment label Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetSegmentLabel(const long instance,

unsigned short segmentId, char* label)

Description Retrieves the label of the segment with the given id. If the id is out of range, the result value will be XRV_NOTFOUND. Segment IDs are in the range 1-30, but usually only 1-23 are used. When props are used, they are typically ids 24 and 25.

xmeSetActorDimensionParameters in: string containing actor dimension label

in: double value Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetActorDimension(const long instance, const

char* label, double value)

Description Updates the specified actor dimension value and re-computes the appropriate internal dimensions. If a value of 0 or less is supplied, the specified dimension is cleared.

MV0302P.C 16


3.2.4 Segment calibration interface

xmeGetCalibrationLabelListParameters none Output const XmeLabel* pointing to a list with all currently defined segment

calibration labels Prototype const XmeLabel* xmeGetCalibrationLabelList(const long instance)

Description Returns a pointer to an array with the labels of all possible segment calibrations. The array is terminated by an empty label “\0”.

xmeInitializeCalibrationParameters in: label, string containing the label of the segment calibration to load

in: tempFile, the name of the temporary file to use for calibration. Output XsensResultValue indicating success or error Prototype XsensResultValue xmeInitializeCalibration(const long instance,

const char* label, const char* tempFile)

Description Loads a specific segment calibration and prepares the necessary data structures. If the tempFile value is NULL, a temporary file will be created in the current working folder and the file will be removed when the calibration is complete. If the filename is not NULL, the specified file will be used. In this case the file will not be discarded on completion, unless the first character of tempFile is an asterisk (*). The * will be skipped when creating the file.

xmeAbortCalibrationParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeAbortCalibration(const long instance)

Description This function cancels a running calibration if logging data or if calculating new LSM parameters. The segment calibration is completely ended and needs to be re-initialized before it can be attempted again.

Events XME_ET_CALIBRATION_COMPLETE when the calibration has been successfully aborted. Do not start a new calibration or recording before this event has been received!

xmeClearCalibrationParameters in: label, string containing the label of the segment calibration to clear Output XsensResultValue indicating success or error Prototype XsensResultValue xmeClearCalibration(const long instance, const

char* label)

Description Clears the specified segment calibration. The global consistency is recomputed. Call xmeGetCalibrationResult to retrieve the updated value.

MV0302P.C 17


xmeFinalizeCalibrationParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeFinalizeCalibration(const long instance)

Description This function ends a Segment Calibration procedure and merges the results with any previous calibrations.

xmeGetCalibrationPoseParameters in: frameNumber to retrieve the pose for, or XME_LAST_AVAILABLE_FRAME

for the next frame in the sequence out: XmePose structure to store the pose in.

Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetCalibrationPose(const long instance,

uint32 frameNumber, XmePose* pose)

Description If the frameNumber is not -1, the pose is returned from the preview. During the preview (before xmeStartCalibration or after xmeStopCalibration), any frame number can be retrieved and the sequence will cycle automatically. During calibration (before xmeStartCalibration or after xmeStopCalibration), you can only retrieve the same frame or a later frame than the one that was previously requested (xmeStartCalibration resets the counter to frame 0). For a successful calibration, at least one pose needs to be retrieved from every calibration phase, since the markers between phases are created by xmeGetSegmentCalibrationPose.

MV0302P.C 18


xmeGetCalibrationResultParameters in: label of the segment calibration

out: consistency, a consistency measurement of the segment calibration with respect to the other performed calibrations out: quality, a measurement of the specific calibration. The value is one of XME_CAL_GOOD, XME_CAL_SUSPECT or XME_CAL_FAIL. out: warning, a warning if some calibration-specific error has been detected.

Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetCalibrationResult(const long instance,

const char* label, double* consistency, XmeCalibrationQuality* quality, char* warning)

Description Retrieves the calibration results of the segment calibration with the specified label. When a NULL label is supplied, the global consistency is supplied. If this function is called during segment calibration with the label of the current segment calibration or a NULL label, the results of the active segment calibration are returned. When the function is called outside a segment calibration procedure or with a non-matching label, the stored results are returned. The result values are updated whenever a calibration is performed or cleared. A NULL pointer for the consistency, quality or warning parameters is allowed.

xmeIsCalibrationPerformedParameters in: label, the label of the calibration routine to check Output integer specifying whether the given calibration has been performed (1)

or not (0) Prototype int xmeIsCalibrationPerformed(const long instance, const char*

label)

Description Returns whether the calibration routine with the given label has been performed or not.

Events none

xmeStartCalibrationParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeStartCalibration(const long instance)

Description Starts recording for the segment calibration. The calling application should get at least 1 pose from each calibration phase before calling xmeStopSegmentCalibration. Otherwise the calibration will fail.

MV0302P.C 19


xmeStopCalibrationParameters in: Boolean value indicating whether processing should start or not Output XsensResultValue indicating success or error Prototype XsensResultValue xmeStopCalibration(const long instance, const

long process)

Description This function is called to stop logging of data for the calibration procedure. The logged data is processed by the segment calibration module.

Events XME_ET_CALIBRATION_COMPLETE

3.2.5 Motion Capture interface

xmeGetConfigurationParameters out: char* buffer to store the label in Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetConfiguration(const long instance, char*

label)

Description Places the current configuration label in the supplied label parameter. The supplied label can be either the label of the current configuration as the suit has been initialized or read from a file or it can be the configuration that is desired by the user when the suit is initialized.

xmeGetConfigurationLabelListParameters none Output array of XmeLabel containing the available labels Prototype const XmeLabel* xmeGetConfigurationLabelList(const long instance)

Description Returns a list with the labels of the available configurations. Each configuration label describes the basic setup of the suit (LowerBody, UpperBody, FullBody, etc). The list is terminated by an empty string.

MV0302P.C 20


xmeGetPoseParameters in: frameNumber to retrieve the pose for, or XME_LAST_AVAILABLE_FRAME

for the last available real-time frame in: pt the type of pose to retrieve XME_POSETYPE_PREPROC, XME_POSETYPE_POSTPROC or XME_POSETYPE_ANY out: XmePose structure to store the pose in.

Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetPose(const long instance, uint32

frameNumber, XmePose* pose, const XmePoseType pt)

Description Returns the best pose matching the input criteria. If a frame number other than XME_LAST_AVAILABLE_FRAME and higher than the number of frames recorded is supplied, an XRV_ENDOFFILE value is returned. If no sensor data has been processed yet and no file is open (in other words, no pose data is available yet), an XRV_NODATA value is returned. If calibration has been stopped with a 0 as the process parameter (see xmeStopCalibration), this function will return the respective pose from the recorded calibration file.

xmeGetSampleRateParameters none Output double value containing the current sample rate in Hz Prototype double xmeGetSampleRate(const long instance)

Description This function returns the sample rate of the XME instance in Hz. It returns the value used by the connected suit first. If no suit is connected it will return the value used by the open mvn file. If no file is open, it will return the value that would be used if a suit would be initialized.

xmeGetUserScenarioParameters out: char* string containing the current scenario label Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetUserScenario(const long instance, char*

label)

Description This function retrieves the current user scenario. See xmeSetUserScenario for more information about scenarios.

xmeGetUserScenarioLabelListParameters none Output const XmeLabel* list containing the labels of the defined scenarios Prototype const XmeLabel* xmeGetUserScenarioLabelList(const long instance)

Description This function retrieves the list of all defined user scenarios, including the ‘default’ scenario. See xmeSetUserScenario for more information about scenarios.

MV0302P.C 21


xmeReprocessDataParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeReprocessData(const long instance)

Description Starts reprocessing thread using the latest XME settings. The status returned by xmeGetStatus will show the current progress in the m_framesPreProcessed and m_framesPostProcessed fields. Reprocessing data is cached internally to save time while editing a file. If a file is changed during reprocessing, the reprocessing will restart from the first stored cache point before the change. The same will occur if a new reprocess is initiated after the file has been changed. To reprocess an entire file from the beginning, either close and reopen the file and then reprocess it, or reprocess when there are no changes in the file and there is no reprocess operation active. Reprocessing is done in multiple phases, currently only the preprocessing phase is actually used, but in the future the postprocessing phase may also be used, as well as any additional computational steps.

Events ET_PROCESSING_INTERMEDIATE at each reprocessed frame that is a multiple of the value set by xmeSetReprocessingEventInterval (100 by default) and when a full phase is complete. ET_PROCESSING_COMPLETE when reprocessing is complete.

xmeSetConfigurationParameters in: const char* buffer with the desired label Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetConfiguration(const long instance, const

char* label)

Description Changes the desired configuration label to the given value if it is a valid configuration label. Changing the configuration will cause a reinitialise of the hardware.

Events XME_ET_HARDWARE_DISCONNECTED XME_ET_HARDWARE_READY XME_ET_HARDWARE_ERROR

xmeSetSampleRateParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetSampleRate(const long instance, const

double hz)

Description This function changes the sample rate of the connected suit to the given value in Hz. The function will fail if an mvn file is open. It can be called if no suit has been initialized so the suit will be initialized at the proper sample rate. Note that calling this function before the first hardware scan has been performed may cause the desired value to be overwritten by the default value.

MV0302P.C 22


xmeSetUserScenarioParameters in: label of the desired scenario Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetUserScenario(const long instance, const

char* label)

Description This function sets the user scenario. A user scenario is a set of processing options designed for a specific purpose, such as stair walking or horse riding. Selecting the right scenario can greatly improve your mocap data. If the desired label can’t be found, the default scenario is always used.

xmeStartRecordingParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeStartRecording(const long instance)

Description Starts real-time processing of MT data and data logging to .mvn file. Existing data will be overwritten (one take in an .mvn file).

Events XME_ET_RECORDING_STARTED

xmeStopRecordingParameters none Output XsensResultValue indicating success or error Prototype XsensResultValue xmeStopRecording(const long instance)

Description Stops real-time processing of MT data and data logging. Events XME_ET_RECORDING_STOPPED

xmeSetSleepModeParameters in: long indicating whether the real-time pose mode should be on (1) or

off (0) Output XsensResultValue indicating success or error Prototype XsensResultValue xmeSetSleepMode(const long instance, const long

sleepEnabled)

Description This function sets whether the system should be in sleep / low-power mode or not. When in sleep-mode, the suit uses very little power as all sensor activity is disabled. To resume normal operation when in sleep mode, sleep mode must be disabled with another call to this function. Note that a wake-up may take a few seconds as some components need to be re-initialized.

MV0302P.C 23


3.2.6 Aiding interfaces

xmeAddAidingParameters in: number of the frame for which you wish to add aiding data

in: list of XmeAiding structures and a count indicating the size of the list Output XsensResultValue indicating success or error Prototype XsensResultValue xmeAddAiding(const long instance, const uint32

frameNumber, const uint32 aidingCount, const XmeAiding* aidList)

Description This function adds aiding for a specific frame. The new list supersedes but does not replace any previously defined aiding. There is a limited amount of aiding items available per frame (5 by default) and the items supplied by this function will be placed at the start of the list, possibly pushing other items beyond the end (and discarding them). See the XmeAiding structure description for more details on what kinds of aiding can be specified. Some examples of possible aiding are GPS position data, contacts at a specific height instead of the floor, setting a new floor level and disabling automatic contact detection.

xmeClearAidingParameters in: number of the frame for which you wish to add aiding data Output XsensResultValue indicating success or error Prototype XsensResultValue xmeClearAiding(const long instance, const uint32

frameNumber)

Description Removes all user-defined aiding from the selected frame.

MV0302P.C 24


xmeGetExternalContactsParameters out: List of XmeExternalContact structures Output XsensResultValue indicating success or error Prototype XsensResultValue xmeGetExternalContacts(const long instance,

const uint32 maxContactCount, XmeExternalContact* contactList, uint32* contactCount)

Description Returns the ground contact information for the frames where an external contact is defined. See also xmeSetExternalContacts. The contactCount parameter is filled with the actual number of items that should be in the list. If this number is greater than the given maxCount, the function will return XRV_INSUFFICIENT_SPACE. A segment number that is equal to XME_CONTACT_NONE will be included when the user has specified that there should be no contacts for the given frame.

xmeSetExternalContactsParameters in: List of XmeExternalContact structures Output XsensResultValue indicating success or error Prototype XsensResultValue setExternalContacts(const long instance,

const uint32 contactCount, const XmeExternalContact* contactList)

Description Specifies the external contact locations. This will not automatically initiate reprocessing of the file, but it can restart active reprocessing to make use of the new contact definitions. So in order for the changes to take effect, a call to xmeReprocessData is required. The special contact with segment XME_CONTACT_NONE can be used to make sure that there are no contacts for a frame. Note that this disables automatic contact detection for the frame. The special contact with segment XME_CONTACT_DELETE can be used to delete all user defined contacts for the specified frame and revert to automatic contact detection.

MV0302P.C 25


Appendix I Types and Structures This appendix describes the types and structures used to pass parameters between a program and the XME dll. These structures are also available in the Doxygen-generated documentation. The doxygen documentation may contain more items in enumerators than listed here. The items listed here are the most common options.

XmeAiding This structure is for storing aiding information which is used to improve the motion-capture data. Members: Type Name Description uint32 m_aidingType The type of aiding, one of the XmeAidingType values,

masked by XME_AID_MASK. uint16 m_segment The 1-based id of the segment involved with the aiding. uint16 m_point The 1-based id of the point in the segment. double[3] m_param1 First parameter (vector) of the aiding, see the selected type

for the use of this parameter. double[3] m_param2 Second parameter (vector) of the aiding, see the selected

type for the use of this parameter.

XmeAidingType This enumeration describes what kind of aiding an XmeAiding structure contains. Enumerator: XME_AID_EXTERNAL_CONTACT An external contact aiding, these can also be set with

xmeSetExternalContacts XME_AID_GROUND_LEVEL A ground level aiding. param1[2] sets the new ground

level for use in the current and all future frames. When used with XME_AID_NO, automatic contact detection is disabled. Using xmeSetExternalContacts with XME_CONTACT_NONE is automatically translated into this combination internally.

XME_AID_CONTACT_WITH_HEIGHT An external contact aiding at a height given in param1[2]

XME_AID_NO This value can be logically OR-ed with one of the other types to indicate a negation of that aiding. This can be used to disable a specific contact for example. See the other aiding types for more details.

XME_AID_MASK This mask can be applied to a received aiding type to get the basic type.

MV0302P.C 26


XmeCalibrationQuality This is an indicator for the stand-alone quality of a performed calibration sequence. This can be influenced by detected motion while the subject should have been standing still, magnetic disturbances in the area, etc. Enumerator: XME_CALIB_QUAL_GOOD Good calibration quality. Nothing out of the ordinary was

detected. XME_CALIB_QUAL_SUSPECT Suspicious calibration quality. Everything was just within

range of the accepted calibration boundaries. It is recommended to do the calibration again.

XME_CALIB_QUAL_FAIL Failed calibration. Something was out of range of the accepted boundaries. It is recommended to do this calibration again, as the current result will not be stored.

XME_CALIB_QUAL_UNKNOWN Unknown calibration quality. Returned for cases where the quality can't be determined from the supplied data.

XmeConnectionQuality This is an indicator for the quality of the communication connection to the hardware. Enumerator: XME_CONQUAL_BAD Bad quality. Indicates that a lot of data is lost in transmission. XME_CONQUAL_MODERATE Moderate quality. Indicates thatsome data is lost in

transmission. XME_CONQUAL_GOOD Good quality. Indicates that no data is lost in transmission. XME_CONQUAL_UNKNOWN Unknown quality. Indicates that either there is no connection

or the quality could not be determined.

XmeContactFlag These flags describe some specifics about an external contact, such as whether it was set manually or automatically detected. Enumerator: XME_CONTACT_FLAG_USER_DEF The contact is defined by the user, when not set, it was

automatically detected XME_CONTACT_FLAG_PROCESSED The contact is included in the processing

MV0302P.C 27


XmeEventCallBackFunction This is the type of the call-back routine that can be registered in the XME dll with the xmeSetCallback function. The call-back function will receive 3 parameters. The first is an XmeEventType with the type of event that triggered the call-back. The second is a void* that points to the XME instance. The appropriate instance number can be retrieved from this pointer with the xmeGetInstance function. The reason that a pointer is used here instead of an instance number is that at the level where the call-backs are generated, the instance management is not available. The last parameter is the void* that was supplied to the xmeSetCallback function. This can be used for a user parameter, i.e. a structure containing information about the instance or a graphical interface handle. Parameters in: const XmeEventType, the type of event

in: void*, the XME instance that caused the event. This pointer can be translated into an instance number using the xmeGetInstance function. in: void*, a user parameter that was passed to the initialize function.

Output none Prototype typedef void (__cdecl* XmeEventCallBackFunction)(const

XmeEventType, void*, void*)

Description This is not an internal function, but a prototype for the function that will be called in case of an event. For a list of all defined events, see XmeEventType below. Note that in the future, more event-types will be added as new functionality demands them, so make sure that the call-back function doesn’t crash when a new event is added.

Events none Notes The call-back function is run in the main thread of the XME dll, so it is

important that the amount of processing done by the function is kept to a minimum. If a lot of processing is required, use the call-back function to copy the data and schedule the processing in another thread. During the call-back, some internal locks may be set that can prevent other threads from completing XME calls. So again, make sure that the function exits as quickly as possible.

MV0302P.C 28


XmeEventType These are the possible events that can be generated by the XME dll. These event codes are sent to the registered EventCallBackFunction (if any). More events will be added as new XME functionality requires it, so it is important that any function that handles these event-codes can deal with currently unspecified events (possibly just ignoring them). Enumerator: XME_ET_POSE_RT_READY Indicates that a new pose has been computed. XME_ET_HARDWARE_ERROR Indicates that there is something wrong with the

hardware or that the hardware could not be located or initialized during a hardware scan.

XME_ET_HARDWARE_READY Indicates that the hardware is ready after a hardware scan or wakeup call.

XME_ET_HARDWARE_DISCONNECTED Indicates that the hardware has been successfully disconnected.

XME_ET_RECORDING_STARTED Indicates that recording of data to the open MVN file has begun.

XME_ET_RECORDING_STOPPED Indicates that recording of data to the open MVN file has ended.

XME_ET_COPY_MVN_ERROR Indicates that an error occurred while trying to make a copy of the current MVN file.

XME_ET_COPY_MVN_READY Indicates that the requested copy of the current MVN file has been successfully made.

XME_ET_CALIBRATION_STOPPED Indicates that the recording of calibration data has stopped and that the data has been processed, but not merged with the other calibrations yet.

XME_ET_CALIBRATION_COMPLETE Indicates that calibration data has been processed after a xmeFinalizeCalibration call or that the calibration process has been successfully aborted after an xmeAbortCalibration call.

XME_ET_LOW_BATTERY_LEVEL Indicates that the power level of at least one of the Xbus Masters is low and that the batteries should be replaced. This event takes place at 10% power, which usually means that about 15 minutes of power is left.

XME_ET_POST_PROCESSING_COMPLETE Indicates that post processing of all the data in the current file has completed.

XME_ET_PROCESSING_INTERMEDIATE Indicates that x frames of data have been pre- or post-processed or that all frames have been pre-processed. The event is sent for every x processed frames. Use xmeSetProcessingEventInterval to change x from the default value of 100.

XME_ET_LAG_WARNING Indicates that the sample data buffer is half full. This means that there will be serious lag in real-time applications. No data has been lost yet and the user should be advised to reserve more CPU time for the XME process.

MV0302P.C 29


XME_ET_BUFFER_OVERFLOW Indicates that the sample data buffer is completely full. This is worse than the XME_ET_LAG_WARNING event, since it is almost guaranteed that data has been lost or will be lost. The user should close some applications to reserve more CPU time for the XME process and redo the recording.

XME_ET_CONTACTS_UPDATED Indicates that the external contacts have been updated successfully.

XmeExternalContact This structure defines a single external contact. Members: Type Name Description uint32 m_frameNumber The frame at which the contact takes place when used with

xmeSetExternalContacts or xmeGetExternalContacts. The number of frames for which to set the contact when used with xmeSetExternalContactsRt.

uint16 m_segment The id of the segment involved with the contact. uint16 m_point The id of the point in the segment that actually makes the

contact. uint32 m_flags Flags for extra information about the contact. This is a logical

OR of XmeContactFlag values.

XmeExternalContactWithHeight This structure defines a single external contact with an additional height parameter to define at which height the contact took place. Members: Type Name Description uint32 m_frameNumber The frame at which the contact takes place when used with

xmeSetExternalContacts or xmeGetExternalContacts. The number of frames for which to set the contact when used with xmeSetExternalContactsRt.

double m_height The height at which this contact takes place. uint16 m_segment The id of the segment involved with the contact. uint16 m_point The id of the point in the segment that actually makes the

contact. uint32 m_flags Flags for extra information about the contact. This is a logical

OR of XmeContactFlag values.

XmeFileStatus This enumerator describes what is currently being done with / by a file. Enumerator: XME_FILE_NO_FILE There is no file.

MV0302P.C 30


XME_FILE_IDLE The file is idle. No operations are currently being performed with the file.

XME_FILE_COPYING The file is being copied. XME_FILE_SAVING The file is being saved. XME_FILE_ERROR The file is in an error state.

XmeHwScanMode The hardware scan mode to use. Enumerator: XME_HWSM_OFF Do not scan for hardware. XME_HWSM_ONCE Scan for hardware once. On success, the hardware is properly

initialized. In any case the scanning stops after the first attempt. XME_HWSM_CONT Scan for hardware continuously. On success, the hardware is properly

initialized and scanning stops, on failure, the scanning will restart.

XmeLabel This is a generic XME label. It is defined as a char[64].

XmeMatrix3x3 A 3 by 3 matrix. The data is read row by row, so m_data[0][0..2] is the first row. Members: Type Name Description double[3][3] m_data The data in the matrix

MV0302P.C 31


XmePointInfo This structure contains information about a point of interest defined by XME. Members: Type Name Description XmeLabel m_label The name of the point. Names are always

unique in a segment and usually unique globally, but they are not always globally unique.

double[3] m_offset A vector containing the offset of the point relative to the segment origin.

unsigned short m_segmentId The ID of the segment this point belongs to. unsigned short m_pointId The ID of the point, unique in a segment, but

not globally. unsigned char m_possibleContact A Boolean value (1 or 0) indicating if the

point is used for automatic contact detection or not. This value is also used in Moven Studio to determine which points to show in the contact point bar.

unsigned char[3] reserved reserved for future use.

XmePose This structure contains a single full pose of the Moven suit. Members: Type Name Description uint32 m_frameTime The timestamp of the pose in ms since

the start of the recording. When not recording, it simply counts on from the moment the first data was received or from the start of the last recording.

uint16 m_segmentStateCount The number of valid segments in the pose. The pose contains a fixed number of segments, but only the first m_segmentStateCount should be used.

uint16 m_contactCount The number of external contacts in the pose.

XmePoseType m_poseType The type of the pose. XmeSegmentState[30] m_segmentStateList An array containing the state of each

segment in the pose. XmeSegPoint[5] m_contactList An array containing the contacts that are

present in the pose.

MV0302P.C 32


XmePoseType This enumerator describes the type of a pose. It indicates the level of processing that has been performed to achieve this pose. Enumerator: XME_POSETYPE_PREPROC Pre-processed pose type. This type has been processed once

to compute the pose from sensor data. XME_POSETYPE_POSTPROC Post-processed pose type. This type has been processed

twice. It is computed from the pre-processed poses. XME_POSETYPE_ANY Any of the above pose-types. Used as a parameter it

indicates that the returned pose may be either.

XmeSegmentIds This is an enumerator that contains the IDs of segments, which are to be used when addressing a specific segment. This is the segment id that needs to be supplied to xmeGetMeshScaleFactors for example. Enumerator: XME_PELVIS_SEGMENT_ID Segment id of the pelvis segment. XME_L5_SEGMENT_ID Segment id of the L5 segment. XME_L3_SEGMENT_ID Segment id of the L3 segment. XME_T12_SEGMENT_ID Segment id of the T12 segment. XME_T8_SEGMENT_ID Segment id of the T8 segment. XME_NECK_SEGMENT_ID Segment id of the neck segment. XME_HEAD_SEGMENT_ID Segment id of the head segment. XME_RIGHT_SHOULDER_SEGMENT_ID Segment id of the right shoulder segment. XME_RIGHT_UPPER_ARM_SEGMENT_ID Segment id of the right upper arm segment. XME_RIGHT_FORE_ARM_SEGMENT_ID Segment id of the right fore arm segment. XME_RIGHT_HAND_SEGMENT_ID Segment id of the right hand segment. XME_LEFT_SHOULDER_SEGMENT_ID Segment id of the left shoulder segment. XME_LEFT_UPPER_ARM_SEGMENT_ID Segment id of the left upper arm segment. XME_LEFT_FORE_ARM_SEGMENT_ID Segment id of the left fore arm segment. XME_LEFT_HAND_SEGMENT_ID Segment id of the left hand segment. XME_RIGHT_UPPER_LEG_SEGMENT_ID Segment id of the right upper leg segment. XME_RIGHT_LOWER_LEG_SEGMENT_ID Segment id of the right lower leg segment. XME_RIGHT_FOOT_SEGMENT_ID Segment id of the right foot segment. XME_RIGHT_TOE_SEGMENT_ID Segment id of the right toe segment. XME_LEFT_UPPER_LEG_SEGMENT_ID Segment id of the left upper leg segment. XME_LEFT_LOWER_LEG_SEGMENT_ID Segment id of the left lower leg segment. XME_LEFT_FOOT_SEGMENT_ID Segment id of the left foot segment. XME_LEFT_TOE_SEGMENT_ID Segment id of the left toe segment.

MV0302P.C 33


XmeSegmentIndices This is an enumerator that contains the indices of segments in supplied data structures. These values should be used when accessing data in an XmePose structure. It is advised that an application always uses these enumerated values and not the immediate integer value, as the values are only semi-fixed and may change in future versions of the XME. Enumerator: XME_PELVIS_SEGMENT_INDEX Segment index of the pelvis segment. XME_L5_SEGMENT_INDEX Segment index of the L5 segment. XME_L3_SEGMENT_INDEX Segment index of the L3 segment. XME_T12_SEGMENT_INDEX Segment index of the T12 segment. XME_T8_SEGMENT_INDEX Segment index of the T8 segment. XME_NECK_SEGMENT_INDEX Segment index of the neck segment. XME_HEAD_SEGMENT_INDEX Segment index of the head segment. XME_RIGHT_SHOULDER_SEGMENT_INDEX Segment index of the right shoulder segment. XME_RIGHT_UPPER_ARM_SEGMENT_INDEX Segment index of the right upper arm segment. XME_RIGHT_FORE_ARM_SEGMENT_INDEX Segment index of the right fore arm segment. XME_RIGHT_HAND_SEGMENT_INDEX Segment index of the right hand segment. XME_LEFT_SHOULDER_SEGMENT_INDEX Segment index of the left shoulder segment. XME_LEFT_UPPER_ARM_SEGMENT_INDEX Segment index of the left upper arm segment. XME_LEFT_FORE_ARM_SEGMENT_INDEX Segment index of the left fore arm segment. XME_LEFT_HAND_SEGMENT_INDEX Segment index of the left hand segment. XME_RIGHT_UPPER_LEG_SEGMENT_INDEX Segment index of the right upper leg segment. XME_RIGHT_LOWER_LEG_SEGMENT_INDEX Segment index of the right lower leg segment. XME_RIGHT_FOOT_SEGMENT_INDEX Segment index of the right foot segment. XME_RIGHT_TOE_SEGMENT_INDEX Segment index of the right toe segment. XME_LEFT_UPPER_LEG_SEGMENT_INDEX Segment index of the left upper leg segment. XME_LEFT_LOWER_LEG_SEGMENT_INDEX Segment index of the left lower leg segment. XME_LEFT_FOOT_SEGMENT_INDEX Segment index of the left foot segment. XME_LEFT_TOE_SEGMENT_INDEX Segment index of the left toe segment.

MV0302P.C 34


XmeSegmentState This structure describes the state of a single segment of the Moven system. Members: Type Name Description double[3] m_acc_g Vector containing the acceleration with respect to the

global coordinate system. double[4] m_q_gb Quaternion containing the orientation with respect to

the global coordinate system. double[3] m_pos_g Vector containing the position with respect to the

global coordinate system. double[3] m_angvel_g Vector containing the angular velocity with respect to

the global coordinate system. double[3] m_vel_g Vector containing the velocity with respect to the

global coordinate system. double[3] m_angacc_g Vector containing the angular acceleration with respect

to the global coordinate system. uint8 m_magDisturbance Single byte containing the magnetic disturbance

relative to the Pelvis in the range 0-255. char[15] reserved Reserved bytes for future expansion. do not use

XmeSegPoint A segment and point index, used to identify a point in a pose. Note that this structure uses 0-based indexing, while most other structures use 1-based indexing. Members: Type Name Description uint16 m_segmentIndex The 0-based index of the segment in the pose uint16 m_pointIndex The 0-based index of the point in the segment.

XmeStatus This structure contains the total system status. This structure contains a lot of frequently changing information about the status of the XME system, as well as information about the last hardware error that occurred (if any). Members: Type Name Description char m_isReady Boolean value. Indicates that the

system is ready for reading poses. Note that this value should be checked before checking the suit's m_hardwareStatus field, as the latter can be OK while the suit is not ready during a hardware scan.

char m_isRecording Boolean value. Indicates that the system is currently recording data to an MVN file.

MV0302P.C 35


char m_isPostProcessing Boolean value. Indicates that the system is currently pre- or post-processing data.

char m_isHandlingFile Boolean value. Indicates that the system is currently processing a file.

char m_isCalibrating Boolean value. Indicates that the system is currently in calibration mode.

char m_isHwScanning Boolean value. Indicates that the system is currently scanning for hardware.

char m_isSleeping Boolean value. Indicates that the system is currently in low-power mode.

char m_isFileChanged Boolean value. Indicates that the currently open MVN file has been changed since opening it.

XmeFileStatus m_fileStatus The status of the currently open file (if any). See XmeFileStatus

uint32 m_framesRecorded The number of frames that has been recorded in the currently open MVN file.

uint32 m_framesPreProcessed The number of frames in the currently open MVN file that has been pre-processed.

uint32 m_framesPostProcessed The number of frames in the currently open MVN file that has been post-processed.

XmeConnectionQuality m_xm1ConnectionQuality The connection quality of the first Xbus Master. See XmeConnectionQuality.

XmeConnectionQuality m_xm2ConnectionQuality The connection quality of the second Xbus Master. See XmeConnectionQuality.

XmeSuitStatus m_currentSuitStatus The current status of the suit (if connected) or the recorded status as read from an MVN file.

XmeSuitStatus m_lastErrorSuitStatus The status of the suit after the last unsuccessful hardware scan.

MV0302P.C 36


XmeSuitStatus This structure contains the status of a Moven Suit. Members: Type Name Description XsensResultValue m_hardwareStatus The error code of the last hardware

scan or the run-time last hardware error. Also see the m_isReady field in the XmeStatus structure.

uint32 m_xm1DeviceId The device ID of the 1st Xbus Master (master) or 0 if it wasn't detected

uint32 m_xm2DeviceId The device ID of the 2nd Xbus Master (slave) or 0 if it wasn't detected

uint16 m_xm1BatteryLevel The battery power level of the 1st Xbus Master (master)

uint16 m_xm2BatteryLevel The battery power level of the 2nd Xbus Master (slave)

uint32 m_ProblematicDeviceId Contains the device ID of the sensor that caused the last hardware error. This is an experimental and estimated value. It should not be treated as 100% reliable, but more as an indication of where a problem could have occurred.

uint32 m_mtCount The number of valid items in m_mtDeviceIdList, m_mtLocationIdList, m_mtValidityList and m_mtConnectionList

uint32 m_missingMtCount The number of valid items in m_missingLocationList

uint32[30] m_mtDeviceIdList Contains the device Id of each detected sensor

uint32[30] m_mtLocationIdList Contains the location Id of each detected sensor

uint32[30] m_mtValidityList Contains whether each sensor is connected to the proper Xbus Master (1), to the wrong Xbus Master (0) or that the sensor is extra and could not be placed (2).

uint8[30] m_mtMasterList Contains the nr of the XM to which each sensor is connected (1 or 2).

uint32[30] m_missingLocationIdList Contains the location IDs of sensors that were expected to be found, but couldn't be detected

MV0302P.C 37


XmeVector3 This structure contains a 3-component vector. Members: Type Name Description double[3] m_data The data in the vector.

XmeVersion This structure contains the version of the XME dll. Members: Type Name Description uint16 m_major The major version number; updated for a release with breaking

or severely changed functionality. A dll with a new major version number will usually require a rebuild of the software that uses it.

uint16 m_minor The minor version number; updated for a release with non-breaking changes, new functions or new events only. A dll with a higher minor version number but the same major version number should not require a rebuild of the software that uses it, except when new functions are to be used of course.

uint16 m_revision The revision number; updated for a release with tweaks and bug-fixes, but no new functionality.

uint16 m_build The build number; updated for every compilation, usually changes with big steps between releases.

XsensResultValue This enumeration describes the result of a function call. Mostly, checking if the result is XRV_OK is enough, but the returned error code can supply more information than just success or failure. These values are enumerated in the HTML documentation.

MV0302P.C 38


Appendix II Examples This appendix contains a description of the supplied examples. The C examples can be opened in Microsoft Visual Studio 2005 through their project file or the solution file. When using another compiler, you need to link with xme.lib and make sure that xme.h is in the compiler’s search path. See the note on building and running XME applications in the introduction.

II.I Simple_C Simple_C is a very simple demonstration of the system, which reads 10 poses from the Moven Suit. Try this program first if you are new to the XME SDK. The program attempts to initialize the hardware in the simplest way, without registering a call-back function. Then it loops 10 times while calling xmeGetPose every 20ms to read poses from the XME. Of each pose that was read the Pelvis and Right Hand orientation are shown. After the 10 poses have been displayed, the program ends after a key press.

II.II Advanced_C Advanced_C is more complex than Simple_C, supplying a simple user interface that allows for more interaction with the XME. It is a nice example to see what happens in the various states that the XME can be in. Before writing your own application using the XME SDK, you are strongly advised to read this example and play with it for a while so the XRV and event mechanisms are clear. The program is written to let the user know what it is doing at all times. Read the various printf statements as if they were code comments. The program has some quirks in exceptional circumstances as it is an example and written for readability (not for fool-proof-ity). Handling a number of exceptional situations would only make the code less clear.

MV0302P.C 39


Appendix III XME 1.1 2.0 migration guide

III.I Function name changes All functions have been renamed so they now have “xme” as prefix and the first letter of their name has been capitalized.

Eg. getPose xmeGetPose Special cases createXmeInstance xmeCreateInstance destroyXmeInstance xmeDestroyInstance initialize xmeSetCallback

III.II Structure name changes All structure names now start with Xme. Eg. ConnectionQuality XmeConnectionQuality special cases Matrix3x3C XmeMatrix3x3 Vector3C XmeVector3

III.III Obsolete structures HardwareStatus in the XmeStatus has been replaced by XsensResultValue. XRV_OK indicates that the hardware is operational.

III.IV Operational changes The parameter interface has been made obsolete. This means that the following functions do not exist anymore. getParameter getParameterLabelList getParameterType setParameter setBoolParameter Instead, specialized functions have been created and some functions have been expanded. New functions xmeGetProcessingEventInterval xmeGetRealTimePoseMode xmeGetRecordStart xmeGetSampleRate xmeGetScanMode xmeGetUserComment xmeSetProcessingEventInterval xmeSetRealTimePoseMode xmeSetSampleRate xmeSetScanMode xmeSetSleepMode xmeSetUserComment

MV0302P.C 40

moven software development kit documentation...moven software development kit documentation document...

Documents