ERGOMOCAP

MOTION CAPTURE x COMPUTER VISION × ERGONOMICS ASSESSMENT

ErgoMoCap is a free, open-source app that runs completely on your own computer. It connects standard video motion tracking with official workplace ergonomics checks. It gives students and researchers a free, and reliable way to measure physical workplace safety risks without needing to buy expensive, corporate hardware and software. At the time of v0.0.1 the tool is not reliable and prone to errors.

THE MISSION & PHILOSOPHY

We built this tool to solve a common problem in school and research settings: making it easy and completely free to get reliable ergonomics safety scores (like REBA, RULA, NIOSH, and SNOOK) directly from simple video files.

We didn't want to reinvent the wheel. ErgoMoCap is built directly on top of the amazing work done by the FreeMoCap project. We share their values, use their open-source setup, and designed our app to expand on their excellent video tracking tools. Huge thanks and credit go to the FreeMoCap community for making this possible!

📢 CITATION FROM THE FREEMOCAP PHILOSOPHY:
"Knowledge is free. Labor is expensive. Anything that can be infinitely and losslessly duplicated, code, documentation, videos, should be available to everyone, for free."

Believing fully in this idea, ErgoMoCap has absolutely no paid extras, no paywalls, and no premium versions. Under our AGPL-3.0 License, you are completely free to use, change, or build upon this software, as long as you share your updates under the exact same open terms.

HOW IT WORKS

The app works like a simple assembly line: it takes the physical movement data captured from your videos and calculates standard ergonomic safety scores.

1. Loading Data

The app imports the 3D body tracking data created by FreeMoCap. It uses a translation file (the freemocap_adapter) to read the positions of 22 key body joints. Right now, in this early version (v0.0.1), the app uses the calculated joint angles to run its checks.

2. Calculating Scores

The math engine instantly reads these joint positions frame-by-frame and checks them against standard ergonomic safety limits to find any risky movements. Note: Speed optimizations are planned for version v0.1.0, but the current engine is already fast enough for standard use.

Raw Video Data

Data Reader

22-Joint Body Map

Ergonomic Calculators (REBA/RULA)

Finished Reports

THE LONG-TERM PLAN

Right now, ErgoMoCap acts as an easy-to-use visual screen that controls FreeMoCap behind the scenes to gather your data. However, this is just the first step in a larger project.

Our ultimate goal is to combine the best parts of both systems. We plan to build the video tracking features right into ErgoMoCap itself. This will eventually give ergonomics researchers a single, standalone desktop app that handles everything from video recording to final safety reports with no extra setup required.

⚠️ SYSTEM STATUS

CURRENT PHASE: PRE-ALPHA (V0.0.1)
The main visual controls and FreeMoCap data links are working. However, the RULA tracking scores are still unstable. Right now, the app should only be used for testing and academic experiments, not official certifications.

Development Progress

[REBA/RULA Setup] ──> [Testing Calculators] ──> [Final Safety Checks]

DEVELOPER NOTE: Our code updates strictly require successful documentation builds and at least 90% test coverage across our math tools (including SNOOK and EWAS) before changes can be saved. If any automated pre-commit check fails, the commit is blocked.

⚙️ 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

Follow these quick steps to get the application up and running without configuration:

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:

Output Location: Your generated files will be saved inside _internal/ergomocap_data/. This directory will contain your annotated videos, pure MoCap/MediaPipe data, and post-processed files.
FreeMoCap Integration: If you are using and setting up FreeMoCap for the first time, we highly recommend placing your freemocap_data folder right here inside the _internal directory.

⚠️ 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 & LAUNCH

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

Download the code: Clone the folder or download the source ZIP from the repository.
```
https://github.com/medlav/ergomocap.git
```
Open your Terminal/Command Prompt: Navigate to the ergomocap folder.
```
cd path/to/ergomocap/
```
Create a Virtual Environment: Initialize a clean isolated environment inside the directory.
```
python -m venv venv
```
Activate the Virtual Environment (Windows): Run the activation script via Command Prompt or PowerShell.
```
venv\Scripts\activate
```
Activate the Virtual Environment (Linux/macOS): Source the activation script into your current shell.
```
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 execution thread.

cd path/to/ergomocap/

Then run the main.py file from terminal window:

python main.py

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

YOUR FIRST 5 MINUTES

If you just want to see how it works without recording anything completely 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

Review these quick pipeline patches if execution engine flags errors:

"Command not found": Make sure Python is added to your environment variables "PATH" array structure during its core installation step.
Video not loading: Ensure you have a folder named annotated_videos exactly configured inside your session data folder freemocap_data/recording_sessions/. Select the correct freemocap_data/ folder using 📂 SELECT FREEMOCAP ROOT.
Missing Skeletal Data: The app needs the .csv or .npy dataset matrices created by FreeMoCap to work. If they are missing, execute the FreeMoCap "Post-Processing" step first. For more info read the FreeMoCap Official Documentation.

PREREQUISITE CHECK

You must have already completed a FreeMoCap recording session with valid 3D trajectory data. If you need to record new data, click the 💀 RUN FREEMOCAP button in the main interface. New to FreeMoCap? Read the Official Documentation.

GET YOUR DATA IN

Load your FreeMoCap recording session into ErgoMoCap. The application expects data organized in the standard freemocap_data/record_sessions directory structure.

Open the ErgoMoCap application
Click 📂 SELECT FREEMOCAP ROOT and navigate to your freemocap_data folder.
⚠️ NOTE: Use the same freemocap_data folder used by FreeMoCap! Read the FreeMoCap docs for the instruction on how to select the freemocap_data folder inside FreeMoCap.
Use the Select Recording Session dropdown to choose your specific session folder
Select a video file from the Select Video list, the skeleton overlay should appear immediately in the preview pane

Files involved: gui/core/session_manager.py, calculators/adapters/freemocap_adapter.py

CHOOSE YOUR METHOD

Select which ergonomic assessment protocol to apply. REBA (Rapid Entire Body Assessment) evaluates full-body posture; RULA (Rapid Upper Limb Assessment) focuses on neck, trunk, and upper limbs.

Navigate to the Select Ergonomic Method dropdown menu
Choose REBA for full-body lifting tasks, or RULA for upper-body repetitive work
Click 🏃 RUN ANALYSIS to begin computation
Monitor the status bar at the bottom, wait for "Analysis Complete" before proceeding

⚠️ NOTE: Analysis is CPU-intensive. Thread safety prevents UI freezing, but video playback may lag during computation. Wait for completion for optimal performance.

Files involved: calculators/reba_calculator/REBA_calculator.py, gui/workers/analysis_worker.py, gui/core/analysis_engine.py

CHECK THE VIDEO

Validate that the computed skeleton accurately tracks the subject throughout the recording. Visual verification ensures your ergonomic scores reflect real movement.

Click ▶ PLAY / PAUSE to start video playback
Observe the skeleton overlay, joints should remain anchored to the subject's body
If the skeleton appears "shaky" or jumps erratically, review your recording conditions:

Ensure adequate, even lighting (avoid harsh shadows)
Keep camera view unobstructed (no boxes, chairs, or people blocking joints)
Use FreeMoCap's ChArUco calibration for improved 3D accuracy

Files involved: gui/widgets/video_canvas.py, calculators/adapters/freemocap_adapter.py

SEE RESULTS & EXPORT

Review your ergonomic risk assessment and generate shareable documentation for compliance records or team review.

Click 📊 OPEN REPORT DASHBOARD to launch the results viewer
Examine the Risk Pie Charts, red zones indicate "High Risk" postures requiring intervention
Review time-series graphs showing risk score evolution across the task duration
Export your findings using the available formats:

📜 EXPORT TO PDF, Immutable, print-ready compliance report
📄 EXPORT TO DOCX, Editable Word document for annotations or integration

Files involved: gui/views/report_view.py, gui/templates/REBA_report.j2, exports/pdf_generator.py

💡 PRO TIPS FOR BETTER RESULTS

Use FreeMoCap Calibration: Run the built-in ChArUco board calibration before recording, this dramatically improves 3D joint position accuracy.
Maintain Clear Camera Views: Ensure no objects obstruct the subject's joints (knees, elbows, shoulders). Occluded joints produce unreliable scores.
Optimize Lighting: Avoid low-light conditions or harsh directional shadows. Even, diffuse lighting reduces tracking "noise" and skeleton jitter.
Double-Check Critical Scores: Automated systems can misclassify edge cases. Always visually verify any "High Risk" flags against the actual video footage before making safety decisions.

For advanced recording techniques, calibration workflows, and MoCap best practices, consult the FreeMoCap Official Documentation.

🏁 NEXT STEPS

Now that the software engine is running, you need to learn how to navigate the interface system layout and interpret the compiled econometric data arrays.

Read the User Guide: Learn what each dashboard module button does and how to parse out raw risk charts.
Follow the Tutorial: Walk through your first end-to-end REBA assessment pipeline from start to finish.

WHAT IS ERGOMOCAP?