vailá - Multimodal Toolbox

App version (GUI/CLI banner): see vaila.py. Package version: see [project].version in pyproject.toml. Python: 3.12.x (pinned in-repo for uv).

Last updated: 2026-06-10

Operating System	Installation Method	Status
🪟 Windows	uv (Recommended)	✅ Ready
🐧 Linux	uv (Recommended)	✅ Ready
🍎 macOS	uv (Recommended)	✅ Ready

⚡ Install Now (One-Line)

Install vaila with a single command!

🐧 Linux:

wget -qO- https://raw.githubusercontent.com/vaila-multimodaltoolbox/vaila/main/install_vaila_linux.sh | bash

🍎 macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/vaila-multimodaltoolbox/vaila/main/install_vaila_mac.sh)"

🪟 Windows:

irm https://raw.githubusercontent.com/vaila-multimodaltoolbox/vaila/main/install_vaila_win.ps1 | iex

or

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; irm https://raw.githubusercontent.com/vaila-multimodaltoolbox/vaila/main/install_vaila_win.ps1 | iex

If you use a one-liner that points to https://vaila.io/install.ps1, use the same TLS fix first:

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; iwr -useb https://vaila.io/install.ps1 | iex

Windows SSL/TLS error? If you see "could not establish trust relationship for the SSL/TLS secure channel", the line above enables TLS 1.2 before the download.

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.

Table of Contents

• Introduction
• Description
• vailá Structure and Interface
• Installation and Setup
  • Optional: Crop Face model
  • Optional: SAM 3 (video segmentation)
• Running the Application
• Uninstallation Instructions
• Documentation
• Citing vailá
• Contribution
• Releases and versioning
• License

---

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

The toolbox is designed to integrate and analyze data from diverse measurement systems commonly used in biomechanics research, including motion capture systems (such as Vicon and OptiTrack), inertial measurement units (IMU), markerless tracking solutions (OpenPose and MediaPipe), force plates (AMTI and Bertec), electromyography (EMG), GNSS/GPS systems, physiological sensors (heart rate, ECG, MEG, EEG), video analysis tools, and ultrasound systems. This comprehensive integration enables researchers to perform advanced multimodal analysis by combining data from different sources, providing a more complete understanding of human movement patterns and biomechanical parameters.

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.

---

vailá Structure and Interface

vailá provides a comprehensive multimodal analysis framework organized into three main sections (Frames A, B, and C) that handle different aspects of biomechanical data processing:

vailá - 09.Jun.2026 v0.3.51 (Python 3.12.13)
                                             o
                                _,  o |\  _,/
                          |  |_/ |  | |/ / |
                           \/  \/|_/|/|_/\/|_/
##########################################################################
Mocap fullbody_c3d           Markerless_3D      Markerless_2D_MP and YOLO
                  \                |                /
                   v               v               v
   CUBE2D  --> +---------------------------------------+ <-- Vector Coding
   IMU_csv --> |                                       | <-- Cluster_csv
Open Field --> |       vailá - multimodal toolbox      | <-- Force Plate
 StartBlock -->|                                       | <-- GRF Analysis
 etc, etc. --> +---------------------------------------+ <-- etc, etc, etc.
                                 |
                                 V
        +---------------------------------------------------+
        | Processed Data, Figures and Reports etc, etc, etc.|
        +---------------------------------------------------+

============================ File Manager (Frame A) ========================
A_r1_c1 - Rename          A_r1_c2 - Import           A_r1_c3 - Export
A_r1_c4 - Copy            A_r1_c5 - Move             A_r1_c6 - Remove
A_r1_c7 - Tree            A_r1_c8 - Find             A_r1_c9 - Transfer

========================== Multimodal Analysis (Frame B) ===================
B1_r1_c1 - IMU                    B1_r1_c2 - Motion Capture Cluster
B1_r1_c3 - Motion Capture Full Body B1_r1_c4 - Markerless 2D
B1_r1_c5 - Markerless 3D

B2_r2_c1 - Vector Coding  B2_r2_c2 - EMG             B2_r2_c3 - Force Plate
B2_r2_c4 - GNSS/GPS       B2_r2_c5 - MEG/EEG

B3_r3_c1 - HR/ECG         B3_r3_c2 - Yolo + Markerless_MP
B3_r3_c3 - Vertical Jump
B3_r3_c4 - Cube2D         B3_r3_c5 - Animal Open Field

B4_r4_c1 - YOLO and SAM   B4_r4_c2 - ML Walkway      B4_r4_c3 - Markerless Hands
B4_r4_c4 - MP Angles      B4_r4_c5 - Markerless Live

B4_r5_c1 - Ultrasound     B4_r5_c2 - Brainstorm      B4_r5_c3 - Scout
B4_r5_c4 - StartBlock     B4_r5_c5 - Pynalty

B5_r6_c1 - Sprint         B5_r6_c2 - Face Mesh       B5_r6_c3 - tugturn
B5_r6_c4 - Soccer Tools   B5_r6_c5 - Deadlift

B6_r7_c1 - vailá          B6_r7_c2 - vailá           B6_r7_c3 - vailá
B6_r7_c4 - vailá          B6_r7_c5 - vailá

============================== Tools Available (Frame C) ===================
-> C_A: Data Files
C_A_r1_c1 - Edit CSV      C_A_r1_c2 - C3D <--> CSV   C_A_r1_c3 - Smooth & Filter
C_A_r2_c1 - Make DLT2D    C_A_r2_c2 - Rec2D 1DLT     C_A_r2_c3 - Rec2D MultiDLT
C_A_r3_c1 - Make DLT3D    C_A_r3_c2 - Rec3D 1DLT     C_A_r3_c3 - Rec3D MultiDLT
C_A_r4_c1 - ReID Marker   C_A_r4_c2 - vailá          C_A_r4_c3 - vailá

-> C_B: Video and Image
C_B_r1_c1 - Video<-->PNG  C_B_r1_c2 - Crop Face      C_B_r1_c3 - Draw Box
C_B_r2_c1 - Compress Video C_B_r2_c2 - vailá         C_B_r2_c3 - Make Sync file
C_B_r3_c1 - GetPixelCoord C_B_r3_c2 - Metadata info  C_B_r3_c3 - Merge|Split Video
C_B_r4_c1 - Distort Video/data C_B_r4_c2 - Cut Video  C_B_r4_c3 - Resize Video
C_B_r5_c1 - YT Downloader C_B_r5_c2 - Insert Audio   C_B_r5_c3 - rm Dup PNG

-> C_C: Visualization
C_C_r1_c1 - Show C3D      C_C_r1_c2 - Show CSV 3D    C_C_r2_c1 - Plot 2D
C_C_r2_c2 - Plot 3D       C_C_r3_c1 - Draw Sports    C_C_r3_c2 - Stroboscopic
C_C_r4_c1 - vailá         C_C_r4_c2 - vailá          C_C_r4_c3 - vailá
C_C_r5_c1 - vailá         C_C_r5_c2 - vailá          C_C_r5_c3 - vailá

Type 'h' for help or 'exit' to quit.

Use the button 'imagination!' to access command-line (xonsh) tools for advanced multimodal analysis!

An overview of the project file structure:

vaila
├── AGENTS.md                     # Hybrid CPU vs CUDA workstation, SAM/FIFA notes
├── CLAUDE.md                     # AI assistant tooling (Ruff, ty, uv)
├── CONTRIBUTING.md               # PR workflow, versioning, models policy
├── vaila.py                      # Main Tkinter GUI entry point
├── pyproject.toml                # Active manifest (default: universal CPU; Hatchling + uv)
├── pyproject_*.toml              # Platform templates (Linux/Windows CUDA, macOS, CPU)
├── uv.lock                       # Locked deps (re-run uv lock after template switch)
├── bin/                          # setup_pyproject.sh/.ps1 (unified) + legacy use_pyproject_*.sh/.ps1 shims
├── install_vaila_linux.sh        # Linux installer (uv-only)
├── install_vaila_mac.sh          # macOS installer (uv-only)
├── install_vaila_win.ps1         # Windows installer (uv-only)
├── uninstall_vaila_linux.sh
├── uninstall_vaila_mac.sh
├── uninstall_vaila_win.ps1
├── create_dmg_installer.sh       # macOS .dmg builder (optional)
├── vaila_installer.iss           # Windows Inno Setup spec
├── vaila/                        # Python package (~100+ analysis modules)
│   ├── help/                     # Per-module HTML/Markdown help (e.g. vaila_sam.html)
│   ├── models/                   # Reference CSV/JSON; large weights are gitignored
│   ├── vaila_sam.py              # SAM 3 video CLI/GUI + FIFA subcommands
│   ├── fifa_skeletal_pipeline.py # FIFA Skeletal Tracking Light orchestration
│   └── ...                       # See vaila/help/index.md for the full map
├── sam_3d_body/                  # Vendored SAM 3D Body (optional fifa extra)
├── tests/                        # pytest suite
└── docs/                         # MkDocs site, button docs, images

Developer quick reference: AGENTS.md (build commands, uv run, optional extras sam / gpu / fifa, SAM 3 CUDA limits).

---

Installation and Setup

⚡ Engine: Powered by uv

vailá uses uv, an extremely fast Python package installer and resolver, written in Rust. uv is the single, official installation method for all platforms (Windows, Linux, macOS). Conda is no longer supported.

Why uv:

• Speed: Installation is 10-100x faster than legacy Conda setups.
• Simplicity: You no longer need to pre-install Anaconda or Miniconda.
• Reliability: Uses a strictly locked dependency file (uv.lock) ensuring that what runs on our machine runs on yours.
• Modern: Built with Rust, following Python packaging standards (pyproject.toml).
• Dynamic Hardware Optimization: Automatically detects hardware (NVIDIA GPU, Apple Silicon) and selects the optimized configuration template for your system.
• Cross-Platform: Windows (CUDA 12.1 + TensorRT where applicable), Linux (CUDA 12.8 + TensorRT), and macOS (Metal/MPS for the general PyTorch stack). Exception: SAM 3 video (vaila_sam.py) requires NVIDIA CUDA at runtime — it does not use MPS and has no CPU-only path.

🎯 Smart Configuration System

vailá uses a template-based configuration system that automatically selects the optimal dependencies for your hardware:

• pyproject.toml (in repository): Universal CPU-only configuration (default in repository, compatible with all systems)
• pyproject_win_cuda12.toml: Windows with NVIDIA CUDA 12.1 support (TensorRT, GPU acceleration)
• pyproject_linux_cuda12.toml: Linux with NVIDIA CUDA 12.8 support (TensorRT, GPU acceleration)
• pyproject_macos.toml: macOS with Metal/MPS acceleration (Apple Silicon optimized)
• pyproject_universal_cpu.toml: Universal CPU-only fallback (backup template)

Manual template switch (developers / second machine): prefer the unified interactive bootstrap which auto-detects OS + NVIDIA + arch and runs uv lock + uv sync:

bash bin/setup_pyproject.sh                                       # Linux / macOS / WSL / Git Bash
pwsh bin/setup_pyproject.ps1                                      # Windows PowerShell
bash bin/setup_pyproject.sh --target=linux-cuda --extras=gpu,sam --yes   # non-interactive

Flags: --target=auto|cpu|linux-cuda|win-cuda|macos, --extras=a,b,c, --non-interactive, --yes, --no-lock, --no-sync, --help.

Legacy per-platform shims (thin wrappers around the bootstrap, kept for backward compatibility): bin/use_pyproject_linux_cuda.sh, bin/use_pyproject_universal_cpu.sh, bin/use_pyproject_macos_metal.sh, plus the Windows PowerShell equivalents. See AGENTS.md for the full hybrid workflow.

How it works (step-by-step):

1. Hardware Detection: The installation script detects your hardware:
   • Windows/Linux: Checks for NVIDIA GPU via nvidia-smi command
   • macOS: Detects architecture via uname -m (Apple Silicon arm64 vs Intel x86_64)
2. User Prompt: If GPU/accelerator is detected, it asks if you want GPU support:
   • Windows: "NVIDIA GPU detected. Install with GPU support (CUDA 12.1)? [Y/n]"
   • Linux: "NVIDIA GPU detected. Install with GPU support (CUDA 12.8)? [Y/n]"
   • macOS: "Apple Silicon detected. Use Metal/MPS acceleration? [Y/n]"
3. Template Selection: Based on your choice, it selects the appropriate template:
   • Windows + GPU → pyproject_win_cuda12.toml (CUDA 12.1 + TensorRT)
   • Linux + GPU → pyproject_linux_cuda12.toml (CUDA 12.8 + TensorRT)
   • macOS (Apple Silicon) + Metal → pyproject_macos.toml (Metal/MPS optimized)
   • Otherwise → pyproject_universal_cpu.toml (CPU-only)
4. Backup: Backs up current pyproject.toml to pyproject_universal_cpu.toml
5. Template Application: Copies the selected template to pyproject.toml BEFORE creating the virtual environment
   • ⚠️ Critical: This happens before uv python pin and uv venv are executed
   • This ensures the virtual environment is created with the correct dependencies from the start
6. Environment Creation: uv creates the .venv with the correct dependencies from the beginning
7. Dependency Installation: Runs uv sync (or uv sync --extra gpu if GPU support was selected)
8. Automatic Fallback: If installation fails, it automatically restores the universal CPU configuration and retries

Important: The template selection happens before uv python pin and uv venv are executed. This ensures the virtual environment is created with the correct dependencies from the beginning, avoiding dependency resolution conflicts.

This ensures that:

• ✅ The virtual environment is created with the correct dependencies from the beginning
• ✅ No dependency resolution conflicts occur during installation
• ✅ Each OS/GPU combination gets its optimized dependency set
• ✅ Automatic fallback to CPU-only if GPU installation fails

For more information about uv, visit: https://github.com/astral-sh/uv

Optional: Crop Face model

The Crop Face button uses dependencies already included in the standard vailá install. On first use, it downloads the official MediaPipe BlazeFace short-range detector into the local Git-ignored model cache:

vaila/models/crop_face/face_detector.task

To provision the model before opening the GUI, run:

uv run python vaila/crop_faces_atletas.py --download-model

The downloaded bytes come from Google's versioned MediaPipe BlazeFace short-range model. If automatic download fails, the GUI still allows manual selection of a compatible .task or .tflite file.

Optional: SAM 3 (video segmentation)

The Segment Anything Model 3 stack is not installed by default. If the GUI shows “SAM 3 not installed” (or the CLI exits when you run batch mode without the package), install the optional dependencies and restart vailá.

Standard installation (universal CPU pyproject template):

uv sync --extra sam

Workstation with NVIDIA CUDA — recommended one-liner (auto-detects + switches template + syncs):

bash bin/setup_pyproject.sh --target=linux-cuda --extras=gpu,sam --yes   # Linux
pwsh bin/setup_pyproject.ps1 -Target win-cuda -Extras gpu,sam -Yes        # Windows

Or do it manually after switching the pyproject template (legacy bin/use_pyproject_*.sh / .ps1 shims):

uv sync --extra gpu --extra sam

Runtime (important): SAM 3 video uses torch.cuda in this integration. It requires an NVIDIA GPU with CUDA (torch.cuda.is_available()), even when the sam extra is installed on a CPU-only or macOS machine.

Situation	SAM 3 video
Linux / Windows + NVIDIA + CUDA PyTorch	Supported
Windows without NVIDIA CUDA	Not supported — CLI/GUI stop with a clear message; use Markerless 2D / YOLO or a CUDA host
macOS (Metal / Apple Silicon)	Not supported for SAM 3 video (not an MPS code path); use other vailá modules or run SAM 3 on a CUDA workstation / cloud GPU

--frame-by-frame only reduces VRAM on CUDA; it is not CPU inference.

For laptop vs workstation installs, see AGENTS.md (“Hybrid CPU vs NVIDIA workstation”).

Weights (Hugging Face, gated): accept the model on Hugging Face, then e.g. uv run hf auth login and uv run vaila/vaila_sam.py --download-weights, or hf download into vaila/models/sam3/ or repo-root models/sam3/ (both are auto-detected).

In-browser setup page (same instructions): open the local help file after install, or run:

uv run vaila/vaila_sam.py --open-help

That opens vaila/help/vaila_sam.html in your default browser.

FIFA Skeletal Tracking Light (separate optional stack): uv sync --extra fifa (often together with --extra gpu on CUDA templates). See AGENTS.md and vaila_sam.py fifa --help.

---

🪟 For Windows

Installation is now streamlined using uv with automatic GPU detection.

Important Notice Before Installation

vailá values freedom and the goodwill to learn. If you are not the owner of your computer and do not have permission to perform the installation, we recommend doing it on your own computer. If you are prevented from installing software, it means you are not prepared to liberate yourself, make your modifications, and create, which is the philosophy of vailá!

1. Download vailá

• Option A (Git):

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

• Option B (Zip):

  • Download the .zip file from the vailá GitHub Repository
  • Extract it
  • Important: Rename the folder from vaila-main to vaila

2. Run the Installation Script

Open PowerShell inside the vaila folder and run:

.\install_vaila_win.ps1

The script will:

1. Detect if you have an NVIDIA GPU.
2. Ask if you want to install with GPU support (optimizes for CUDA 12.1).
3. Automatically select and apply the correct configuration template:
   • GPU detected + user chooses GPU: Uses pyproject_win_cuda12.toml (CUDA 12.1, TensorRT)
   • No GPU or user chooses CPU: Uses pyproject_universal_cpu.toml (CPU-only)
4. Install uv and all dependencies with the selected configuration.

Note: If you run as Administrator, vailá installs to C:\Program Files\vaila. If you run as a Standard User, it installs to your user profile (~\vaila).

3. What the Script Does

The installation script automatically:

• Checks for uv; if missing, installs it automatically
• Detects your hardware (NVIDIA GPU) and prompts for GPU support preference
• Selects the optimal configuration template (pyproject_win_cuda12.toml or pyproject_universal_cpu.toml)
• Applies the template to pyproject.toml before creating the virtual environment
• Installs Python 3.12.13 (via uv) securely isolated for vailá
• Creates a virtual environment (.venv) with the correct dependencies from the start
• Syncs all dependencies using uv sync (with --extra gpu if GPU support was selected)
• Installs FFmpeg and Windows Terminal (if running as Administrator)
• Configures shortcuts:
  • Desktop shortcut with proper icon
  • Start Menu shortcut
  • Windows Terminal profile for quick access
• Sets appropriate permissions for the installation directories
• Automatically falls back to CPU-only configuration if GPU installation fails

⚠️ Important Notes

• The installation script requires administrative privileges to install system components (FFmpeg, Windows Terminal)
• If you run without admin privileges, some features may be skipped, but vailá will still be installed
• The script dynamically configures paths, so no manual adjustments are necessary
• No Conda required: Conda is no longer supported; the installer uses uv only.

Erro de SSL/TLS ao baixar o script? Se aparecer "could not establish trust relationship for the SSL/TLS secure channel", use o one-liner da seção Install Now (com a linha que ativa TLS 1.2).

4. Launching vailá

After installation, you can launch vailá:

• Using the Desktop shortcut (with proper icon)

• From the Windows Start Menu under vailá

• From Windows Terminal via the pre-configured vailá profile

• Manually, by running:

  cd path\to\vaila
  uv run vaila.py

---

🐧 For Linux

Installation uses uv (Conda is no longer supported).

Using uv

We provide an automated installation script that handles everything for you (dependencies, uv installation, virtual environment, etc.).

1. Make the script executable:

   chmod +x install_vaila_linux.sh

2. Run the installation script:

   ./install_vaila_linux.sh

   The script will:

   1. Detect if you have an NVIDIA GPU.
   2. Ask if you want to install with GPU support (optimizes for CUDA 12.8).
   3. Automatically select and apply the correct configuration template:
      • GPU detected + user chooses GPU: Uses pyproject_linux_cuda12.toml (CUDA 12.8, TensorRT)
      • No GPU or user chooses CPU: Uses pyproject_universal_cpu.toml (CPU-only)
   4. Install uv and all dependencies with the selected configuration.

3. Manual Installation (Alternative)

If you prefer to install manually using uv:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install vailá
git clone https://github.com/vaila-multimodaltoolbox/vaila
cd vaila

# ⚠️ IMPORTANT: Select GPU configuration BEFORE creating virtual environment
# The template must be copied to pyproject.toml BEFORE running uv python pin and uv venv
# For NVIDIA GPU with CUDA 12.8:
# cp pyproject_linux_cuda12.toml pyproject.toml
# For CPU-only (default):
# The default pyproject.toml is already CPU-only, so no copy needed for CPU
# (or explicitly: cp pyproject_universal_cpu.toml pyproject.toml)

# Initialize Python version (uses the pyproject.toml you just configured)
uv python pin 3.12.13

# Create virtual environment (uses the pyproject.toml you just configured)
uv venv --python 3.12.13

# Generate lock file
uv lock --upgrade

# Install dependencies
uv sync
# Or with GPU support (if you selected GPU template):
# uv sync --extra gpu

# Run vailá
uv run vaila.py

⚠️ Critical Note: When installing manually, you MUST copy the appropriate template to pyproject.toml BEFORE running uv python pin and uv venv. The installation scripts do this automatically, but for manual installation you need to do it yourself. The order matters because uv reads pyproject.toml when creating the virtual environment.

---

🍎 For macOS

Installation uses uv (Conda is no longer supported).

Installation Script

1. Make the script executable:

   chmod +x install_vaila_mac.sh

2. Run the installation script:

   ./install_vaila_mac.sh

   The script will:

   1. Detect your architecture (Apple Silicon vs Intel).
   2. If Apple Silicon, ask if you want to use Metal/MPS acceleration (recommended).
   3. Automatically select and apply the correct configuration template:
      • Apple Silicon + user chooses Metal: Uses pyproject_macos.toml (Metal/MPS optimized)
      • Intel or user chooses CPU-only: Uses pyproject_universal_cpu.toml (CPU-only)
   4. Install uv and all dependencies with the selected configuration.

The uv installer will automatically:

• Install/update uv if needed
• Install Python 3.12.13 via uv
• Create a virtual environment
• Install all dependencies
• Set up the macOS application bundle with icon
• Create a launcher in Applications folder
• Install system dependencies via Homebrew (if needed)

Notes:

• You may be prompted for your password when the script uses sudo to create the symbolic link.

---

Running the Application

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

🚀 Using uv (Recommended)

uv provides faster execution times and is the recommended method for all platforms.

• Using the Desktop shortcut (with proper icon)

• From the Windows Start Menu under vailá

• From Windows Terminal via the pre-configured vailá profile

• Manually, by running:

  cd path\to\vaila
  uv run vaila.py

---

🧪 Automated Testing

vailá includes an automated test suite to ensure the reliability of biomechanical calculations and data processing pipelines.

Running Tests

To run the full test suite, use uv:

uv run pytest

You can also run specific test files for more detailed output:

# Unit tests for biomechanical formulas
uv run pytest tests/test_vaila_and_jump.py -v

# Integration tests for full data pipelines
uv run pytest tests/test_vaila_and_jump_integration.py -v

The test suite covers:

• Unit Tests: Physics formulas (Force, Power, Energy), TOML configuration loading, and baseline calculations.
• Integration Tests: End-to-end processing of Time-of-flight, Jump-height, and MediaPipe data using real sample files.

---

---

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

For 🐧 Linux and 🍎 macOS

• From the Applications Menu:
  • Look for vailá 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 launch script created during installation.

🐧 Linux and 🍎 macOS

The installation scripts automatically create a run_vaila.sh script in the installation directory (~/vaila).

• Run the script:

~/vaila/run_vaila.sh

The script uses the uv virtual environment created during installation.

🪟 Windows

The installation script automatically creates run_vaila.ps1 and run_vaila.bat scripts in the installation directory.

• Run using PowerShell:

.\run_vaila.ps1

• Or double-click:

run_vaila.bat

Notes

• The launch scripts (run_vaila.sh, run_vaila.ps1, run_vaila.bat) are automatically created during installation.
• These scripts run vaila through the uv-managed virtual environment.
• The scripts are located in the installation directory (~/vaila on Linux/macOS, or the Program Files/user directory on Windows).

---

⚡ GPU Support & Optimization

vailá provides comprehensive GPU support across all platforms with automatic hardware detection and optimized dependency installation.

Installation-Time GPU Support

During installation, the scripts automatically:

• Detect NVIDIA GPUs (Windows/Linux) or Apple Silicon (macOS)
• Prompt you to choose GPU or CPU-only installation
• Select the optimal configuration template:
  • Windows: pyproject_win_cuda12.toml (CUDA 12.1 + TensorRT)
  • Linux: pyproject_linux_cuda12.toml (CUDA 12.8 + TensorRT)
  • macOS: pyproject_macos.toml (Metal/MPS acceleration)
  • Fallback: pyproject_universal_cpu.toml (CPU-only, always available)

Runtime GPU Optimization

vailá includes a HardwareManager that automatically optimizes performance for your specific computer:

• Auto-Export: The first time you run a model, vailá builds a custom .engine file for your GPU.
  • Note: This process takes 2-5 minutes on the first run.
• Cross-Platform:
  • On Windows, it uses trtexec.exe to build Windows-compatible engines.
  • On Linux, it builds Linux-compatible engines.
  • Both can coexist in the same folder if you dual-boot.
• Profiles:
  • The toolbox automatically selects valid settings (Workspace size, Precision) based on your VRAM.

---

Uninstallation Instructions

For Uninstallation on Linux 🐧

1. Run the uninstall script:

chmod +x uninstall_vaila_linux.sh
./uninstall_vaila_linux.sh

• The script will:
  • Remove the uv virtual environment (.venv).
  • Delete the ~/vaila directory.
  • Remove the desktop entry.
  • Best-effort: remove any leftover legacy vaila Conda environment from old installs.

Notes:

• Run the script as your regular user, not with sudo.

For Uninstallation on macOS 🍎

1. Run the uninstall script:

chmod +x uninstall_vaila_mac.sh
./uninstall_vaila_mac.sh

• The script will:
  • Remove the uv virtual environment (.venv).
  • Delete the ~/vaila directory.
  • Remove vaila.app from /Applications and ~/Applications.
  • Refresh the Launchpad to remove cached icons.
  • Best-effort: remove any leftover legacy vaila Conda environment from old installs.

Notes:

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

For Uninstallation on Windows 🪟

1. Run the uninstallation script (PowerShell, Administrator recommended):

.\uninstall_vaila_win.ps1

If you encounter execution policy restrictions, run:

powershell -ExecutionPolicy Bypass -File .\uninstall_vaila_win.ps1

The script will:

• Remove the uv virtual environment (.venv).
• Delete the installation directory (C:\Program Files\vaila or C:\Users\<YourUser>\vaila).
• Remove the Windows Terminal vaila profile (settings.json).
• Delete the Desktop and Start Menu shortcuts if they exist.
• Best-effort: remove any leftover legacy vaila Conda environment from old installs.

---

Documentation

📚 Script Help Documentation

Comprehensive documentation for all Python scripts and modules in vailá:

• Script Help Index (HTML) - Complete documentation for all Python modules and scripts (HTML version)
• Script Help Index (Markdown) - Complete documentation for all Python modules and scripts (Markdown version)

The help documentation includes detailed information about:

• Module descriptions and functionality
• Configuration parameters
• Usage instructions
• Input/output formats
• Requirements and dependencies

📖 Additional Documentation

• AGENTS.md - uv run recipes, hybrid CPU vs CUDA pyproject templates, SAM 3 / FIFA pointers
• Project Documentation - Overview and module documentation
• PDF Transcription - Brainstorm PDF exam transcription workflow
• Help Guide - User guide and installation instructions
• GUI Button Documentation - Complete documentation for all GUI buttons

---

Citing vailá

If you use vailá in your research or project, please consider citing our work:

@misc{vaila2024,
  title={vailá - Versatile Anarcho Integrated Liberation Ánalysis in Multimodal Toolbox},
  author={Paulo Roberto Pereira Santiago and Guilherme Manna Cesar and Ligia Yumi Mochida and Juan Aceros and others},
  year={2024},
  eprint={2410.07238},
  archivePrefix={arXiv},
  primaryClass={cs.HC},
  url={https://arxiv.org/abs/2410.07238}
}

@article{tahara2025predicting,
  title={Predicting walkway spatiotemporal parameters using a markerless, pixel-based machine learning approach},
  author={Tahara, Ariany K and Chinaglia, Abel G and Monteiro, Rafael LM and Bedo, Bruno LS and Cesar, Guilherme M and Santiago, Paulo RP},
  journal={Brazilian Journal of Motor Behavior},
  volume={19},
  number={1},
  pages={e462--e462},
  year={2025}
}

@article{Mochida2025,
  author = {Mochida, Ligia Yumi and Santiago, Paulo R. P. and Lamb, Miranda and Cesar, Guilherme M.},
  title = {Multimodal Motion Capture Toolbox for Enhanced Analysis of Intersegmental Coordination in Children with Cerebral Palsy and Typically Developing},
  journal = {Journal of Visualized Experiments},
  year = {2025},
  number = {206},
  pages = {e69604},
  doi = {10.3791/69604},
  url = {https://www.jove.com/t/69604/multimodal-motion-capture-toolbox-for-enhanced-analysis}
}

@article{chinaglia2026automating,
  title={Automating Timed Up and Go Phase Segmentation and Gait Analysis via the tugturn Markerless 3D Pipeline},
  author={Chinaglia, Abel Gon{\c{c}}alves and Cesar, Guilherme Manna and Santiago, Paulo Roberto Pereira},
  journal={arXiv preprint arXiv:2602.21425},
  year={2026},
  doi = {10.48550/arXiv.2602.21425},
  url = {https://arxiv.org/abs/2602.21425}
}

You can also refer to the tool's GitHub repository for more details and updates

• vailá on arXiv
• vailá GitHub Repository

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.

See CONTRIBUTING.md for workflow, style, and tests. For security (secrets, reporting vulnerabilities), see SECURITY.md.

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!

Releases and versioning

The installable package version is defined in pyproject.toml ([project].version). That is what uv and pip report (e.g. when you uv sync or install from PyPI). Current line in the checked-in tree: 0.3.51 (see also the vaila.py window title string).

GitHub releases may use an additional milestone codename: rp refers to Ribeirão Preto, plus a date suffix (day + abbreviated month + two-digit year), e.g. rp23mar26 for 23 Mar 2026. This codename does not replace the package version.

Maintainership policy (semver tag vs rp tag, and what to write in release notes) is documented in CONTRIBUTING.md — Versioning and GitHub releases.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). This license ensures that any use of vailá, including network/server usage, maintains the freedom of the software and requires source code availability.

For more details, see the LICENSE file or visit: https://www.gnu.org/licenses/agpl-3.0.html