introlab/openimu

Open Source Analytics & Visualisation Software for Inertial Measurement Units

OpenIMU - Data Analyser for Inertial Measurement Units and Actimetry Data

Authors

• Dominic Létourneau (@doumdi)
• Simon Brière (@sbriere)

Description

OpenIMU aims to provide an open source and free generic data importer, viewer, manager, processor and exporter for Inertial Measurement Units (IMU) and actimetry data. By using a common sensor data format and structure, data from different sources can be imported and managed in the software. This software was developped with support from INTER.

Features

Current features

• Common file format (SQLite) managed by OpenIMU, but that can also be opened from other software

• Import recorded data from sensors:

  • Actigraph GTX3 series
  • OpenIMU-MiniLogger
  • AppleWatch SensorLogger (Custom research app for data collection)

• Transfer data directly from sensors:

  • AppleWatch SensorLogger (Custom research app for data collection)

• Data organization

  • By participants groups
  • By participants
  • By recordsets
  • By results

• Data viewing

  • Temporal display of recordsets to quickly see when data was recorded
  • Sensor graph view plotting with zoom functions
  • GPS viewer for GPS data

• Data processing

  • Processing module, currently supporting:
    • Freedson Activity Algorithm (Freedson PS1, Melanson E, Sirard J., Calibration of the Computer Science and Applications, Inc. accelerometer., Med Sci Sports Exerc. 1998 May;30(5):777-81)
  • Evenson Activity Alogirhtm (Kelly R. Evenson, Diane J. Catellier, Karminder Gill, Kristin S. Ondrak & Robert G. McMurray (2008) Calibration of two objective measures of physical activity for children, Journal of Sports Sciences, 26:14, 1557-1565, DOI: 10.1080/02640410802334196 )
  • Processed results viewer

• Data exporter

  • CSV format
  • Matlab format
  • Data export selector

• Available in French and English, and as Windows and Mac OS apps.

Planned features

• Data splitting into sub-recordsets (by time, by day, manually)

• More data processing modules

Screenshots

Getting Started for Developers

Please follow those steps to setup your development environment.

Requirements

1. Make sure you have a valid compiler installed:

   1. Linux : gcc/g++
   2. Mac : LLVM through XCode
   3. Windows: Visual Studio C++ 2017

2. Install CMake

3. Install Qt + QtCreator

   1. Install the latest Desktop distribution fitting your compiling environment (will not be needed in the future)

4. Install MiniConda3

5. Install PyCharm Community Edition

Step 1 : Open the root CMakeLists.txt in QtCreator

1. Opening the root CMakeLists.txt will allow to create and build the project
   1. Build the project using the "python-all" target, it will automatically generate the Python environment in env/python-3.10, PySide6 UI and RCC files.
   2. All python dependencies will be automatically downloaded
   3. Once the project is built, you will not need QtCreator until you change or add a resource file or a QtDesigner ui file.
   4. If you change or add ui or resources files, you need to rebuild the project from QtCreator.

Step 2 : Create a PyCharm project

1. Using PyCharm, opening the directory "{PROJECT_ROOT}/python"
   1. Select the existing Python 3.10 environment in "{PROJECT_ROOT}/python/env/python-3.10" in the app menu: PyCharm->Preferences->Project:python->Project Interpreter

Step 3 : Run the application

1. Run the OpenIMUApp.py application from PyCharm

2. Edit the code as you would normally do in a python program.

3. Run tests in the tests directory

Notes

1. In a near future, we hope to have everything in the QtCreator IDE. Stay tuned!

Enjoy!

openimu's Issues

Add support for "activity" files (Apple Watch)

Apple Watch file for activities isn't supported yet, but should be added to allow display and data export.

Batch import with special meta-importation file

Add support for batching an import with minimal user interaction, either from a predefined meta-session batcher, or by intelligent directory crawling, or a combination of both (directory crawling to find batchers).

Draft for formatting of an OpenIMU Meta-Import (.oimi 😃) with JSON formatting:

{
  "version" : "1"
  "logger_type" : "AppleWatch",
  "deviceID" : "W01P1",
  "appVersion" : "0.11.2",
  "participant" : "abcd1234",
  "description" : "any additional info on session? optional",
  "files" : [
    "watch_Battery.data",
    "watch_Coordinates.data",
    ...
  ]
}

Freedson algorithm gives more than 1440 minutes a day on whole day recordings.

Verify algorithm to make sure the cumulation of seconds fits a day.

Upgrade to Python 3.11

Create MacOS dmg installer

File format backward compatibility / upgrade

Currently, using only SQLAlchemy to access and manage the file structure (database), when the file format changes, there is no backward compatibility provided, since SQLAlchemy doesn't create by itself the missing fields / tables.

Usual solution is to use an external migration tool running when the software is installed, but that works only in a scenario with only one database, which is not the case here since each file is its own database.

The solution would be to integrate checking the file version before opening it in OpenIMU and upgrade its structure, if required, using direct database access (not SQLAlchemy).

Review User Interface

Build new logo and icon for the app.
Revise user interactions and paths and fix usability issues.

Migrate to PySide6

Since PySide is officially supported by Qt, should migrate the project to PySide and update everything.

Data Transfer crash when changing the "Delete data" flag

On Windows (at least), settings are saved as "string", not boolean, and thus crash when opening the "Transfer" dialog.

HR not visible

Rare case of HR not appearing in OpenImu.
The watch was not worn but data are present (HR is activated in the options).
HR data is still exportable via OpenImu.
Faulty dataset attached.
2023-02-23_11-55-29-0.zip

AppleWatch Data transfer hangs when watch shuts down

An issue was reported with the transfer of Applewatch data, when the watch shuts down (because of an empty battery level, for example), that makes the transfer hangs the application.

AppleWatch SensorLogger - Add support for Magneto Data in Motion file

In file version 3 for Motion, magneto values were added. Import them.

Display beacon data

As of now, beacon data isn't plotted. A suggestion to plot beacon data would be the following:

• Plot absence / presence of beacon, separated by channels (beacons)
• Ability to filter only specific beacons on graph.

Recent dataset history

When loading a new dataset, remember the last 5 used datasets (recent) and allow the user to quickly select and load those recently used files.

Groups / Participants sorting and searching

Currently, participants and groups are listed in the order they were created in the file.

However, it would be useful to display them by alphabetical order and to allow text search to quickly find a specific participant in a larger dataset.

Specifically:

• Add buttons to sort data
• Add a search button or area to filter items from the list

ModuleNotFoundError: No module named 'resources.ui.python

Hello,

My name is Filipe Salles and I'm working at Porto University, Portugal (indeed everyone is working at home during these quarantine times). I'm trying to install it, but I had a problem. When PyCharm is running, it shows up the following:

/usr/bin/python3.6 /home/salles/Documentos/OpenIMU-master/python/OpenIMUApp.py
Traceback (most recent call last):
File "/home/salles/Documentos/OpenIMU-master/python/OpenIMUApp.py", line 409, in
from libopenimu.qt.MainWindow import MainWindow
File "/home/salles/Documentos/OpenIMU-master/python/libopenimu/qt/MainWindow.py", line 12, in
from resources.ui.python.MainWindow_ui import Ui_MainWindow
ModuleNotFoundError: No module named 'resources.ui.python'
Process finished with exit code 1.

Anyone can help me with this? Thanks.

PS - It's my first time using Qt Creator and PyCharm (in ubuntu), so I think that maybe I did simething wrong in these parts.

Add Cancel button to progress dialogs

Add a cancel button to cancel ongoing processing / loading.

Adaptative zoom data loading

Improve zoom feature on graph to load further data when the zoom level change, in order to gain a better prevision when zooming in.

no error with build, but have fail to run

Got the following error when run from pyCharm. Any pointer?

Traceback (most recent call last):
  File "/home/tan/proj/imu/OpenIMU/python/OpenIMUApp.py", line 409, in <module>
    from libopenimu.qt.MainWindow import MainWindow
  File "/home/tan/proj/imu/OpenIMU/python/libopenimu/qt/MainWindow.py", line 12, in <module>
    from resources.ui.python.MainWindow_ui import Ui_MainWindow
ModuleNotFoundError: No module named 'resources.ui.python.MainWindow_ui'Traceback (most recent call last):
  File "/home/tan/proj/imu/OpenIMU/python/OpenIMUApp.py", line 409, in <module>
    from libopenimu.qt.MainWindow import MainWindow
  File "/home/tan/proj/imu/OpenIMU/python/libopenimu/qt/MainWindow.py", line 12, in <module>
    from resources.ui.python.MainWindow_ui import Ui_MainWindow
ModuleNotFoundError: No module named 'resources.ui.python.MainWindow_ui'

Matlab export not properly working with sensor names with spaces

When exporting data with sensor name with space in it (ex. "Raw Accelerometer"), the .mat file is properly generated, but the file can't be loaded in Matlab because of a space in the variable name.

AppleWatch version

Hi, may I know when will the apple watch version be available?

Data grouping by recordsets (sessions)

Importing into the database doesn't keep the data into sessions, instead it agglomerates it into day long recordSet.

A recordSet should be analogous to a single logging session. Many sessions in a single day could then be discernible in the UI, and erroneous sessions easily removable.

Agglomeration into other groups should instead be done at the demand of the user and not affect the DB, maybe with a drop menu of choices for different options for visualizations (session, hour, day, week, ...)

English Translation

Add precise timestamp data of every sample to database

The import process currently strips all sample from its temporal data, assuming that it will be able to reconstruct it later. This proves to not be exact in the cases where the sampling rate is missing or imprecise, or when samples are missing.

The solution discussed involves creating a specialized table for timestamps as so:

tabTimestamps
=============
[PK] id_timestamps : Integer [Not Null]
first_timestamp_us : UInt64 // unix timestamp with microsecond precision
nb_samples : Int32 // Number of samples in blob
data : blob  // Compact list of UInt32, offseted from first_timestamp_us, with microsecond precision

Adding a foreign-key to this table into tabSensorData, to be potentially shared by many.

One big trade-off from this method is that we will be maximizing performance at the cost of granularity, hence a SELECT on the database might be more complicated and take up more memory than needed. Also, potential UPDATE on the data would be very inefficient. However, it is my understanding that those should not be needed pretty much ever, so it might be negligible.

For future proofing and without a bigger space cost, timestamps can have microsecond precision with a max offset of 2^32 microseconds = 4294 seconds = 1:12:35. I also suggests that this be the size of all windows instead of an arbitrary one hour, for maximal packing.

It is my opinion that all sensors, not only high frequency data, should also abide by this format, for coherence's sake. Low frequency would mean a low amount of data, mitigating the bigger memory consumption on single sample SELECT.

No python files getting generated after build in Qt

The python/env/python-3.7 folder gets created but no files are generated within the folder. Although the build goes successful.

System: Macbook Pro
OS: Catalina

MacOS WebEngine not working in deployed package

Code signing of the webengine (used to display GPS data on a map) doesn't seem to be properly working for now on Mac OS.
Feature has been disabled on Mac OS.

Investigate and fix the issue - maybe related to wrong entitlement or missing signing on some dependencies?

GPS data exportation not working properly with new timestamp format

Since the changes to the new timestamps format in the database, timestamp of each GPS sample isn't properly exported. This issue might also affects other sensors date exportation.

Incorrect timestamps for Apple watch processed motion

There is an exactly one minute gap every hour in the timeline of imported 'ProcessedMotion' data. I've checked in the log files for error, but these gaps are not present in the data.

I highly suspect that there is a problem with the code at 'AppleWatchImporter.py:738', namely the comparison timestamp_sec > last_timestamp + 3600 is for an hour, however I don't quite understand the import process to make a fix.

I can send you sample data if you wish, but any watch_ProcessedMotion.data file greater than 20Mb will show this behavior.

Actigraph data import

Improve Actigraph data importer.

Add license to the project.

• Split GUI / processing to license the GUI LGPLv3 (caused by Qt GPL/LGPL) and the core library Apache v2.

Data visualization QoL modifications

Here are the feature requests for improving the data visualization UI

• Don't freeze UI on sensor selection
  • As of now, the UI freezes for a good 5 seconds before showing a graph with a lot of points
  • Should directly show the panel with a 'loading' icon, and do fetch in the background
• Zoom and move on the main timeline
• Access value(s) of sensor(s) for a precise timestamp
  • Upon selecting a precise timestamp on timeline and/or graph
  • Maybe even simply a label on mouse location (showing sensor name and data at point)
• Easier correlation between timeline and sensor
  • Current color scheme is very hard to differentiate with 5+ sensor
  • A simple label when the mouse is over a precise timeline would help a lot
• Add option to pop (and re-embed) data graphs into a new window to permit a full screen visualization.
  • The current bottom right panel uses maximum 50% of the screen real estate
  • Normally easy to implement, as the user is tasked with window management
• Give possibility to overlap 2+ sensors on the same graph

Add version check

A version check could be implemented using GitHub API with this URL: https://api.github.com/repos/introlab/OpenIMU/releases

This would allow to retrieve the latest release version and compare to the current version to allow user to update, if necessary.

Cleanup main UI thread

Currently, any long running operation freezes up the UI. Moving all of those (DB operation, data graphing, data imports) on a background thread would relieve the main thread and make the application snappier. One other benefit is that if a background thread crashes, it doesn't crash the whole application with it.

This will require a refactoring of the data and operation flow in the application, but will ultimately make it more modular and maintainable.

Apple Watch: Add support for dyskinetic symptom result