SPECIAL INSTRUCTIONS FOR THE /development BRANCH

Installation

Python server

1. Install uv
   • https://github.com/astral-sh/uv?tab=readme-ov-file#installation
2. clone the repo
   • git clone https://github.com/freemocap/freemocap
3. Change directory to the repo:
   • cd freemocap
4. Change to the development branch:
   • git switch development
5. Create virtual environment:
   • uv venv
6. Activate virtual environment
   • Windows: .venv/bin/activate
   • Mac/Linux: source .venv/bin/activate
7. Install dependencies

• uv sync — installs skellytracker with NVIDIA GPU acceleration on Windows/Linux, or CPU-only on macOS, automatically
• No supported GPU on Windows/Linux? Force the CPU-only build instead: uv sync --no-default-groups --group cpu

React GUI

1. Install Node.js
   • https://nodejs.org/en/download/
2. Change directory to the freemocap-ui folder
   • cd freemocap-ui
3. Install dependencies
   • npm install

Run the FreeMoCap application in development mode

1. Start the Python Server:
   • python freemocap/__main__.py
   • The server should start on http://localhost:8005
2. Start the React GUI:
   • npm run dev
   • An Electron window should pop up with the FreeMoCap GUI

Build the FreeMoCap application

(NOTE - This is not necessary for development, and does not handle the Python server yet)

1. Change directory to the freemocap/freemocap-ui folder
   • npm run build
   • The build will be in the freemocap/freemocap-ui/releases folder

---

---

STANDARD README CONTINUES BELOW

---

---

---

The FreeMoCap Project

A free-and-open-source, hardware-and-software-agnostic, minimal-cost, research-grade, motion capture system and platform for decentralized scientific research, education, and training

https://user-images.githubusercontent.com/15314521/192062522-2a8d9305-f181-4869-a4b9-1aa068e094c9.mp4

--

QUICKSTART

0. Create a a Python 3.9 through 3.11 environment (python3.11 recommended)¶

1. Install software via pip:

freemocap requires the cuda or cpu extra to be specified — plain pip install freemocap will install without its tracker. Pick one:

pip install freemocap[cuda]   # Windows/Linux with an NVIDIA GPU

pip install freemocap[cpu]    # macOS, or Windows/Linux without a supported GPU

2. Launch the GUI by entering the command:

freemocap

3. A GUI should pop up that looks like this:

4. Have fun! It might break! Work in Progress lol

5. Join the Discord and let us know how it went!

---

Install/run from source code (i.e. the code in this repo)

This repo's dependencies (skellytracker, skellycam, etc.) are pulled from private git repos via uv, so conda + pip install -e . will not work here — use uv instead:

1. Install uv

   • https://github.com/astral-sh/uv?tab=readme-ov-file#installation

2. Clone the repository

git clone https://github.com/freemocap/freemocap

1. Navigate into the newly cloned/downloaded freemocap folder

cd freemocap

1. Create a virtual environment

uv venv

1. Install dependencies

uv sync

This installs skellytracker with NVIDIA GPU acceleration on Windows/Linux, or CPU-only on macOS, automatically. If you're on Windows/Linux without a supported GPU, force the CPU-only build instead:

uv sync --no-default-groups --group cpu

1. Launch the Python server

uv run python freemocap/__main__.py

The server starts on http://localhost:8005.

1. In a separate terminal, launch the React/Electron GUI (requires Node.js):

cd freemocap-ui
npm install
npm run dev

An Electron window should pop up with the FreeMoCap GUI!

---

Documentation

Our documenation is hosted at: https://freemocap.github.io/documentation/index_md.html

That site is built using writerside from this repository: https://github.com/freemocap/documentation

---

Contribution Guidelines

Please read our contribution doc: CONTRIBUTING.md

Related

Maintainers

• Jon Matthis
• Endurance Idehen

License

This project is licensed under the APGL License - see the LICENSE file for details.

If the AGPL does not work for your needs, we are happy to discuss terms to license this software to you with a different agreement at a price point that increases exponentially as you move spiritually away from the AGPL