vailá - Multimodal Toolbox

Build Type	Linux	macOS	Windows
Build Status

Development of vailá: Versatile Anarcho Integrated Liberation Ánalysis in Multimodal Toolbox

Introduction

The analysis of human movement is fundamental in both health and sports biomechanics, providing valuable insights into various aspects of physical performance, rehabilitation, and injury prevention. However, existing software often restricts user control and customization, acting as a "black box." With vailá, users have the freedom to explore, customize, and create their own tools in a truly open-source and collaborative environment.

vailá (Versatile Anarcho Integrated Liberation Ánalysis) is an open-source multimodal toolbox that leverages data from multiple biomechanical systems to enhance human movement analysis. It integrates data from:

• Retroreflective Motion Capture Systems (e.g., Vicon, OptiTrack)
• Inertial Measurement Unit (IMU) Systems (e.g., Delsys, Noraxon)
• Markerless Video Capture Technology (e.g., OpenPose, MediaPipe)
• Electromyography (EMG) Systems (e.g., Delsys, Noraxon)
• Force Plate Systems (e.g., AMTI, Bertec)
• GPS/GNSS Systems (e.g., Garmin, Trimble)
• MEG/EEG Systems (for brain activity monitoring)
• HR/ECG Systems (for heart rate and electrical activity)

By integrating these diverse data sources, vailá allows for comprehensive and accurate analysis of movement patterns, which is particularly beneficial for research and clinical applications.

Key Features

• Multimodal Data Analysis: Analyze data from various sources such as IMU sensors, motion capture, markerless tracking, EMG, force plates, and GPS/GNSS systems.
• File Management: Tools for file operations, including rename, import, export, copy, move, remove, tree, find, and transfer.
• Data Conversion: Convert between C3D and CSV formats, and perform Direct Linear Transformation (DLT) methods for 2D and 3D reconstructions.
• Video Processing: Tools for converting videos to images, cutting videos, compressing (H.264 and HEVC H.265), synchronizing videos, and extracting pixel coordinates.
• Data Visualization: Display and plot 2D and 3D graphs; visualize CSV and C3D data.

---

Description

This multimodal toolbox integrates data from various motion capture systems to facilitate advanced biomechanical analysis by combining multiple data sources. The primary objective is to improve understanding and evaluation of movement patterns across different contexts.

vailá Manifest

English Version

Join us in the liberation from paid software with the "vailá - Versatile Anarcho Integrated Liberation Ánalysis in Multimodal Toolbox."

In front of you stands a versatile tool designed to challenge the boundaries of commercial systems. This software is a symbol of innovation and freedom, determined to eliminate barriers that protect the monopoly of expensive software, ensuring the dissemination of knowledge and accessibility.

With vailá, you are invited to explore, experiment, and create without constraints. "vailá" means "go there and do it!" — encouraging you to harness its power to perform analysis with data from multiple systems.

Versão em Português

Junte-se a nós na libertação do software pago com o "vailá: Análise Versátil da Libertação Anarquista Integrada na Caixa de Ferramentas Multimodal".

Diante de você está uma ferramenta versátil, projetada para desafiar as fronteiras dos sistemas comerciais. Este software é um símbolo de inovação e liberdade, determinado a eliminar as barreiras que protegem o monopólio do software caro, garantindo a disseminação do conhecimento e a acessibilidade.

Com vailá, você é convidado a explorar, experimentar e criar sem restrições. "vailá" significa "vai lá e faça!" — encorajando você a aproveitar seu poder para realizar análises com dados de múltiplos sistemas.

---

Installation and Setup

Prerequisites

• Conda: Ensure that Anaconda is installed and accessible from the command line.

• FFmpeg: Required for video processing functionalities.

Clone the Repository

git clone https://github.com/vaila-multimodaltoolbox/vaila
cd vaila

Installation Instructions

---

🟠 For Linux:

1. Make the installation script executable:

sudo chmod +x install_vaila_linux.sh

2. Run instalation script:

./install_vaila_linux.sh

• The script will:

  • Set up the Conda environment using ./yaml_for_conda_env/vaila_linux.yaml.
  • Copy program files to your home directory (~/vaila).
  • Install ffmpeg from system repositories.
  • Create a desktop entry for easy access.

3. Notes:

• Run the script as your regular user, not with sudo.
• Ensure that Conda is added to your PATH and accessible from the command line.

---

⚪ For macOS:

1. Make the installation script executable:

sudo chmod +x install_vaila_mac.sh

2. Run the installation script:

./install_vaila_mac.sh

• The script will:
  • Set up the Conda environment using ./yaml_for_conda_env/vaila_mac.yaml.
  • Copy program files to your home directory (~/vaila).
  • Install ffmpeg using Homebrew.
  • Convert the .iconset folder to an .icns file for the app icon.
  • Create an application bundle (vaila.app) in your Applications folder.
  • Create a symbolic link in /Applications to the app in your home directory.

3. Notes:

• You may be prompted for your password when the script uses sudo to create the symbolic link.
• Ensure that Conda is added to your PATH and accessible from the command line.

---

🔵 For Windows:

1. Download and Install Anaconda:

• Make sure to download and install Anaconda.
• Ensure that Conda is installed and accessible from the command line.

2. Download vailá: You can either:

• Clone the repository using git:

  git clone https://github.com/vaila-multimodaltoolbox/vaila
  cd vaila

• Or download the vailá zip file directly from your browser:

  • Go to https://github.com/vaila-multimodaltoolbox/vaila/archive/refs/heads/main.zip
  • Unzip the downloaded file (for example, into your Downloads folder).

3. Run the Installation Script as Administrator:

Now you need to install vailá Anaconda Powershell Prompt as an administrator:

• Press the Windows key and search for "Anaconda PowerShell Prompt".

• Right-click on Anaconda PowerShell Prompt and select "Run as administrator".

• Navigate to the directory where you git clone or downloaded unzipped the vailá files (e.g., C:\Users\YourUserName\Downloads\vaila).

• Run the installation script:

  ./install_vaila_win.ps1
  

4. Allow Script Execution (if necessary):

If the script execution is blocked, you may need to change the execution policy. Run this command in PowerShell as Administrator:

Set-ExecutionPolicy RemoteSigned

5. The Instructions Displayed by the Script:

The script will:

• Set up the Conda environment using vaila_win.yaml inside directory/folder yaml_for_conda_env.
• Install FFmpeg using winget or Chocolatey if necessary.
• Copy program files to C:\ProgramData\vaila.
• Configure the vaila profile in Windows Terminal (recommend you have Windows Terminal installed on your computer).
• Create a Desktop a Start Menu shortcut.

6. If the Windows Terminal profile was not automatically added, follow the instructions below to manually add it. (if necessary)

Manual Addition to Windows Terminal (if necessary)

{
   "name": "vaila",
   "commandline": "pwsh.exe -ExecutionPolicy Bypass -NoExit -Command '& \"%ProgramData%\\Anaconda3\\shell\\condabin\\conda-hook.ps1\" ; conda activate \"vaila\" ; cd \"C:\\ProgramData\\vaila\" ; python \"vaila.py\"'",
   "startingDirectory": "C:\\ProgramData\\vaila",
   "icon": "C:\\ProgramData\\vaila\\docs\\images\\vaila_ico.png",
   "colorScheme": "Vintage",
   "guid": "{17ce5bfe-17ed-5f3a-ab15-5cd5baafed5b}",
   "hidden": false
}

Now the installation instructions are simplified, ensuring users download vailá, run the script with administrator privileges, and see the vailá icon in all the intended places (Desktop, Start Menu, and Windows Terminal).

When vailá is installed on Windows, the files are copied to the following directory:

C:\ProgramData\vaila

This location is used to store data and configuration files that are accessible to all users on the system. However, the ProgramData directory is usually hidden in Windows. To access it, follow these steps:

• Open File Explorer.
• Go to the View tab in the top menu.
• Check the Hidden items box to display the C:\ProgramData directory.
• Navigate to C:\ProgramData\vaila.

For more information about the ProgramData folder on Windows, you can refer to the official Microsoft documentation

---

Running the Application

Running the Application After installation, you can launch vailá from your applications menu or directly from the terminal, depending on your operating system.

• 🟠 Linux and ⚪ macOS: From the Terminal bash or zsh

1. Navigate to the vaila directory:

cd ~/vaila

and run command:

conda activate vaila
python3 vaila.py

• 🔵 Windows

• Click on the vaila icon in the Applications menu or use the shortcut in desktop or Windows Terminal.

• Windows: From the Windows Terminal (Anaconda in path) or use Anaconda PowerShell

1. Open Anaconda Prompt or Anaconda Powershell Prompt (Anaconda Powershell is recommended) and run command:

conda activate vaila
python vaila.py

---

If preferred, you can also run vailá from the launch scripts.

For 🟠 Linux and ⚪ macOS

• From the Applications Menu:

  • Look for vaila in your applications menu and launch it by clicking on the icon.

---

From the Terminal If you prefer to run vailá from the terminal or if you encounter issues with the applications menu, you can use the provided launch scripts.

🟠Linux and ⚪ macOS

• Make the script executable (if you haven't already):

• 🟠 Linux

sudo chmod +x ~/vaila/linux_launch_vaila.sh

• Run the script:

~/vaila/linux_launch_vaila.sh 

• ⚪ macOS

sudo chmod +x ~/vaila/mac_launch_vaila.sh

• Run the script:

~/vaila/mac_launch_vaila.sh 

Notes for 🟠 Linux and ⚪ macOS

• Ensure Conda is in the Correct Location:

  • The launch scripts assume that Conda is installed in ~/anaconda3.
  • If Conda is installed elsewhere, update the source command in the scripts to point to the correct location.

• Verify Paths:

  • Make sure that the path to vaila.py in the launch scripts matches where you have installed the program.
  • By default, the scripts assume that vaila.py is located in ~/vaila.

• Permissions:

  • Ensure you have execute permissions for the launch scripts and read permissions for the program files.

---

Unistallation Instructions

For Uninstallation on Linux

1. Run the uninstall script:

sudo chmod +x uninstall_vaila_linux.sh
./uninstall_vaila_linux.sh

• The script will:
  • Remove the vaila Conda environment.
  • Delete the ~/vaila directory.
  • Remove the desktop entry.

2. Notes:

• Run the script ./uninstall_vaila_linux.sh as your regular user, not with sudo.
• Ensure that Conda is added to your PATH and accessible from the command line.

For Uninstallation on macOs

1. Run the uninstall script:

sudo chmod +x uninstall_vaila_mac.sh
./uninstall_vaila_mac.sh

• The script will:
  • Remove the vaila Conda environment.
  • Delete the ~/vaila directory.
  • Remove vaila.app from /Applications.
  • Refresh the Launchpad to remove cached icons.

2. Notes:

• Run the script as your regular user, not with sudo.
• You will prompted for your password when the script uses sudo to remove the app from /Applications.

For Uninstallation on Windows

1. Run the uninstallation script as Administrator in Anaconda PowerShell Prompt:

• PowerShell Script:
  • Execute .\uninstall_vaila_win.ps1.

1. Follow the Instructions Displayed by the Script:

• The script will:
  • Remove the vaila Conda environment.
  • Delete the C:\ProgramData\vaila directory.
  • Remove the Windows Terminal profile (settings.json file).
  • Delete the desktop shortcut if it exists.

1. Manual Removal of Windows Terminal Profile (if necessary):

• If the Windows Terminal profile is not removed automatically (e.g., when using the uninstall_vaila_win.ps1 script), you may need to remove it manually:

conda remove -n vaila --all

Remove directory vaila inside C:ProgramData\.

---

Project Structure

An overview of the project structure:

tree vaila

vaila
├── __init__.py
├── __pycache__
├── batchcut.py
├── cluster_analysis.py
├── cluster_analysis_cli.py
├── common_utils.py
├── compress_videos_h264.py
├── compress_videos_h265.py
├── compressvideo.py
├── cop_analysis.py
├── cop_calculate.py
├── data_processing.py
├── dialogsuser.py
├── dialogsuser_cluster.py
├── dlt2d.py
├── dlt3d.py
├── drawboxe.py
├── ellipse.py
├── emg_labiocom.py
├── extractpng.py
├── filemanager.py
├── filter_utils.py
├── filtering.py
├── fixnoise.py
├── fonts
├── force_cmj.py
├── force_cube_fig.py
├── forceplate_analysis.py
├── getpixelvideo.py
├── gnss_analysis.py
├── images
├── imu_analysis.py
├── listjointsnames.py
├── maintools.py
├── markerless_2D_analysis.py
├── markerless_3D_analysis.py
├── mergestack.py
├── mocap_analysis.py
├── modifylabref.py
├── modifylabref_cli.py
├── numberframes.py
├── plotting.py
├── readc3d_export.py
├── readcsv.py
├── readcsv_export.py
├── rearrange_data.py
├── rearrange_data_dask.py
├── rec2d.py
├── rec2d_one_dlt2d.py
├── rotation.py
├── run_vector_coding.py
├── run_vector_coding_GUI.py
├── showc3d.py
├── showc3d_nodash.py
├── spectral_features.py
├── stabilogram_analysis.py
├── standardize_header.py
├── sync_flash.py
├── syncvid.py
├── utils.py
├── vaila_manifest.py
├── vaila_upscaler.py
├── vailaplot2d.py
├── vailaplot3d.py
├── vector_coding.py
├── videoprocessor.py
└── videoprocessor2.py

Authors

• Paulo Roberto Pereira Santiago ORCID: 0000-0002-9460-8847
  Biomechanics and Motor Control Lab, School of Physical Education and Sport of Ribeirão Preto, University of São Paulo, Brazil
  Graduate Program in Rehabilitation and Functional Performance, Ribeirão Preto Medical School, University of São Paulo, Brazil

• Abel Gonçalves Chinaglia ORCID: 0000-0002-6955-7187
  Graduate Program in Rehabilitation and Functional Performance, Ribeirão Preto Medical School, University of São Paulo, Brazil

• Kira Flanagan ORCID: 0000-0003-0317-6346
  College of Computing, Engineering and Construction, University of North Florida, USA

• Bruno Luiz de Souza Bedo ORCID: 0000-0003-3821-2327
  Laboratory of Technology and Sports Performance Analysis, School of Physical Education and Sport, University of São Paulo, Brazil

• Ligia Yumi Mochida ORCID: 0009-0005-7266-3799
  Laboratory of Applied Biomechanics and Engineering, Brooks College of Health, University of North Florida, USA
  Department of Physical Therapy, Brooks College of Health, University of North Florida, USA

• Juan Aceros ORCID: 0000-0001-6381-7032
  Laboratory of Applied Biomechanics and Engineering, Brooks College of Health, University of North Florida, USA
  College of Computing, Engineering and Construction, University of North Florida, USA

• Aline Bononi ORCID: 0000-0001-8169-0864 Municipal Pharmacy of Ribeirão Preto - Brazil

• Guilherme Manna Cesar ORCID: 0000-0002-5596-9439
  Laboratory of Applied Biomechanics and Engineering, Brooks College of Health, University of North Florida, USA
  Department of Physical Therapy, Broo~/vaila/linux_launch_vaila.sh ks College of Health, University of North Florida, USA

Contribution

We encourage creativity and innovation to enhance and expand the functionality of this toolbox. You can make a difference by contributing to the project! To get involved, feel free to fork the repository, experiment with new ideas, and create a branch for your changes. When you're ready, submit a pull request so we can review and potentially integrate your contributions.

Don't hesitate to learn, explore, and experiment. Be bold, and don't be afraid to make mistakes—every attempt is a step towards improvement!

License

This project is primarily licensed under the GNU Lesser General Public License v3.0. Please cite our work if you use the code or data. Let's collaborate and push the boundaries together!