⚙️ Install and Get Started

Follow these steps to set up ErgoMoCap on your computer.

Follow A. Simple Install if you don't know how to code or use dev tools. Follow B. Dev Install if you are familiar with dev tools.

A. Simple Install

Download: Get the latest ZIP file from the GitHub releases page of the public repository.
Extract: Extract all the files and folders from the downloaded ZIP to your desired location.
Launch: Run ErgoMoCap.exe to start the application.

File Structure & Output

Inside the extracted folder, you will find an _internal directory. Here is what you need to know about it:

Data Directories

Output Location: Your generated files will be saved inside _internal/ergomocap_data/. This directory will store your processed calculation data and annotated videos.
FreeMoCap Integration: If you are using and setting up FreeMoCap for the first time, we highly recommend locating your freemocap_data folder and use the 📂 SELECT FREEMOCAP ROOT to point ErgoMoCap to the same folder.

⚠️ Important Note: The _internal folder contains a large number of system packages and core files. We strongly suggest not touching or modifying anything else inside this directory unless you know exactly what you are doing.

B. Dev Install

1. Requirements

Before you start, make sure you have these installed:

Python 3.12 or higher: This is the engine that runs the code.
FreeMoCap: If you want to record new data, you need their software installed and calibrated.

2. Installation

Clone the repo: Clone the Github Repo

git clone [https://github.com/medlav/ergomocap.git](https://github.com/medlav/ergomocap.git)

Open your Terminal/Command Prompt: Navigate to the ergomocap folder.

cd path/to/ergomocap/

Create a Virtual Environment: Create a new virtual environment.

python -m venv venv

Activate the Virtual Environment (Windows): Activate the environment on Windows:

venv\Scripts\activate

Activate the Virtual Environment (Linux/macOS): Activate the environment on Linux or macOS:

source venv/bin/activate

Install the dependencies: Run this command to install all the libraries (like PySide, Pandas, and Matplotlib) at once:

pip install -r requirements.txt

3. Launching the App

You must be in the Ergomocap folder to launch the app

cd path/to/ergomocap/

Then run the main.py file from terminal

python main.py

The dark-themed main window should appear on your screen.

Your First 5 Minutes

If you just want to see how it works without recording anything new:

Set your folder: Click 📂 SELECT FREEMOCAP ROOT and point it to the folder where your FreeMoCap data lives.
Pick a session: Use the dropdown menu to select a recording (e.g., session_001).
Run a test: Select REBA from the method list and click 🏃 RUN ANALYSIS.
Check the stats: Once the status bar says "Finished," click 📊 OPEN REPORT DASHBOARD to see the charts.

🛠️ Common Fixes

"Command not found": Make sure Python is added to your "PATH" during installation.
Video not loading: Ensure you have a folder named annotated_videos inside your session folder.
Missing Skeletal Data: The app needs the .csv or .npy files created by FreeMoCap to work. If they are missing, run the FreeMoCap "Post-Processing" step first.

🏁 Next Steps

Now that the software is running, you need to learn how to navigate the interface and interpret the ergonomic data.

Read the [User Guide](user_guide.md): Learn what each button does and how to read the risk charts.
Follow the [Tutorial](tutorial.md): Walk through your first REBA assessment from start to finish.