Overview

“Upperlimb” is a stand alone application focused on upper extremity motion analysis, based on measurement data collected from 3D optical marker tracking systems.

It has been created for quick and easy processing and analysis of upper limb movement data and is offered as a graphical user interface to ensure maximum applicability in medical practice and research.

Upperlimb is tested extensively with data collected by the Vicon system, especially the deprecated software Vicon Workstation, its current pendant Nexus and also the software Tracker, which is often used in the context of robotics sciences.

The application includes advanced algorithms for joint center- and axes estimation, based on functional methods. The results of the data processing can be visualized as 3D stick figure motion and time series plots. It also integrates a motion analysis data mining tool to collect frame based parameters from the time series and it allows to export this data for external processing, e.g. by spreadsheet programs (Excel or Open/Libre-Office).

Upperlimb is a highly configurable software tool that allows to:

• anatomical landmark reconstruction and process joint kinematics
• split the captured motion data into motion cycles based on a free configurable event scheme
• determine spatiotemporal parameters for every motion cycle
• export data in different formats (d3d, MAT, PDF, CSV, XML, gla, glx)
• create reference data files from processed data

Distinctive features:

• Stand-alone and multiplatform application (no matlab licence is needed, available for windows and linux baased operating systems).
• Using of trial-metadata files (e.g. .enf-files from Vicon measurement systems) to control the processing steps (Details).
• Several functional methods available for joint center/axes estimation with event-based control of the phases the estimations are based on (Details).
• Working with additional static scapula “tip-trials”, to deal with scapula measurement for humerus elevation angles bigger than 90 degrees.
• Adjunct SHR ratio algorithm, without gimbal locks and independent from offset angles (Details).

The original application Version 0.1 has been developed from the company ORAT Software-Entwicklung in the year 2009 to simplify and standardize research projects from medical PD students in the Gait- and Motionlab at Heidelberg University clinics. It fullfills the specific needs of this gaitlab only.

“Upperlimb 0.2” was the first application based on the Nimue platform - a high configurable set of modules to build up motion analysis applications. It includes a big set of commercial modules, which prohibits, that the application can be made available open source as a whole.

With the growing number of student projects (at University of Heidelberg till 2017, at DHBW Karlsruhe after 2017), working with this software, and with the growing number of publications based on its calculations, the idea comes up to implement a “Version 2 Upperlimb software” and to make it commonly available.

The work on this project is still in progress and concentrates 2021 in the integration of the Vicon software Tracker, which is used in the Robot and Human Motion lab at the DHBW-Karlsruhe.

Changed

• Upgraded to Nimue Platform 0.100 2021-05. Have a look at the platform documentation about changes.

Changed

• Upgraded to Nimue Platform 0.99 2020-12. Have a look at the platform documentation about changes.

Fixed

• If the model configuration is broken NULLPointer exceptions are fired from the UI which shows the processed data of a selected session folder. Now, in the case of a broken configuration no processed files are shown.

Added

• Folders which include files with the suffix “.r3d” are recognized as session folders (The Module “Motion Data SessionSet” is included in the default upperlimb distribution. This allows to use motiondata collected from a stream e.g. Vicon DataStream API or even from non Vicon equipment.

Changed

• Upgraded to Nimue Platform 0.93 2019-01. Have a look at the platform documentation about changes.

Added

• JSON-Format added to save processed data, used for deep leaarning based applications.

Planed/known bugs

• If not data is availble to be plot in a plot sheet, the selection/navigation shows strange behavoir (select/deselct does not work …)
• In rare cases an additional wrong RElePhase, whichs ends at the end of the trial, is added, e.g. RSA3D-201 (Trial 12, position 2, right side), RSA3D-313 (Trial 12, position 2, left side), RSA-224 (Trial 12, position 2, right side), RSA3A-223 (Trial 12, right side, position 2)
• The action “Process…” tries to access directly FilterNodes instead usage of the indirection of the Lookup. This can fail.
• Automatically deleting output files, if process is canceled
• Planed to fix in this version: Static shoulder angles measurements over 90 degree sometimes show offset about 180 degree.
• The resizing behavior of the window showing processed data is unhandy. If the status switched from processed data not available to available the size should be grown vertically automatically to show the new processed data node.
• Extention of the model with R/LSHRCardanISB based on Thorax- and Humerus coordinate systems following the ISB recommendations exactly.

Added

• PlotSheet declaration files for none, first, second or both static positions (as a WORKAROUND for the Plotsheet Bug which results in broken selection/navigation for uncomplete data in certain cases);

Changed

• Upperlimb models upgraded to Version 1.7 (Determination of scapular rotation for static positions in projection angles). The new angles are shown per default in the plot sheets. The old cardan bases ones are still available.
• Update to Nimue Platform 0.92 - 2018-11. Have a look at the platform documentation about changes.

Added

Changed

• Upperlimb models upgraded to Version 1.6
• The Adjunct SHR curves shown in the plot sheet hat discontinous curves typiscally includning short separate parts for small humeral elevation angles. This is not wrong but not wanted. The model ist changed to determine a better startpoint. The SHR (adjunct) curves now starts at the point where scapularhumeral and scapulathoracal angles comes over a threshold of 2 degrees and monoton grows. This changed model works only together with the fixed issues in the implementation of the <Phase>-Element.
• R/LSHRAdjunct has based on Thorax_ISB. Now it is based on Thorax_HDCal which is more consistently.

Removed

• Logging info, if no group enf-file is available shown only in debug output (removed from INFO mode)

Fixed

• Canceling of running processes is working again in common cases (more tests are needed)

Added

• Default Upperlimb Model changed to Version 1.5, which includes new measure variants for describing Scapula Humeral Rhythm (SHR) and functionality to show configurable glenohumeral ROM phases in the sheets. This is useful to analyse data of patients with less the 90 degree humeral elevation.
• New attribute “threshold” added to the <AdjunctRotation>-element.
• Installer for 64bit Windows machines
• Support for JDK1.8/64bit with more memory support
• Support for Windows 10
• Fast Fourier transformation available in a Plotsheet or as Input/Output-Filter of the Processing Step.
• Documentation of filter implementations, mp-file format and other parts added.
• The export as csv file format functionality now considers a given labelset and label group name. If a labelset is given, than only the defined labels are exported. If a label group name is given, than the name is interpreted as as phase an only frames of phases with phase type name = label group name are exported. Addionionally the number of fraction digits as defined in the options for the csv file format are respected.
• If functional joint center determination for center of rotation based on Gamage 2002 is used, a new attribute “biasCompensationMaximumChange” is added, which defines a value for the maximum allowed difference between the last two interations. If the difference is bigger than this value, for one or more of the three components, than an explicit warning is given in the process log. The Upperlimb default models has switched on this functionality.

Changed

• Grouping for big numbers is switched off in the csv-export.
• Determination of R/LElePhase depends now on a new parameteter defined as a constant to define the minimum elemvation ROM to detect a phase. Details are described here.

Removed

• The context menu of the nodes in the “Data”-view have included actions, which are not needed. The child-nodes representing d3d-files now do not allow cut, copy, paste, delete and rename. Instead these actions are useful for the raw-data files, e.g. c3d-files. All nodes now include only useful actions.

Fixed

• Sometimes the tree view update of the processed d3d-file corrupts. During processing a session, the the UI reaction can be slow and it can happen, that undesired mouse actions invokes a rename process. Internal node names of d3d-files depend on the file name. That´s why renaming during processing a session can corrupt the file. If this happens, the user can see that nodes names change to a name with an inserted “.c3d” string. This bug is fixed by elimination of the rename action in the context menu of the d3d-nodes.
• If the plot sheet is switched from singles trials to meanStd (action in the toolbar) and not for all plots all timeseries are available you get an error message that mean-std is not possible and the toolbar action switch “meanstd” is automatically unchecked if you close the modal warning message. But the single trials are not shown again. Now this is fixed and the single trials are automatically shown again after closing the warning dialog.
• Some export routines has wrongly written only one time frame, if only matrix 3×3 timeseries should be exported. Fixed by a better timeserie length estimation for generic data objects which does not know anything about timeseries.
• Usage of adjunct rotation failes, if the attribute phase is used during setting the values to NaN before the given phase starts.
• If a session folder contains “_” characters output d3d-files are not shown in the ouput view of the Data Explorer.

At the preset, I have started to make the usage of the current (already extended) version of the software possible outside the Heidelberg Motionlab. To do this, the documentation must be extended and components which are very specific for the Heidelberg Motionlab must be removed. Based on the experiences made with the application of the software in Schulthess clinics in Zürich - Swizerland and at Hertie institute Tübingen - Germany I move the development of the software into a direction to create a generic tool, which can be used by the customers with minimal support. This is also driven by the usage of the software in the Robot and Human Motion Lab at Baden-Württemberg Cooperative State Universtity Karlsruhe.

If you are interested in starting with upperbody motion analysis you can ask Oliver Rettig for an introduction in measuring and modelling details, in the usage of the Upperlimb software and for adaptions to your specific research interests. Professional support and consulting is available.

It is planed to find a funding, to build a basis version of Upperlimb, open sourced as a whole. An extended version, inclusive professional support, cauld be made commerically available and supported in the future.