/freemocap

Free Motion Capture for Everyone 💀✨

Primary LanguagePythonGNU Affero General Public License v3.0AGPL-3.0

Project Logo

freemocap

📝 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

DOI-via-Zenodo.org https://img.shields.io/badge/code%20style-black-000000.svg Latest Release AGPLv3 Contributions Welcome https://img.shields.io/badge/code%20style-black-000000.svg Discord Community Server

2022-03-09_FreeMoCap_Clips_SHORT_compressed.mp4

How to use the pre-alpha code

We're in the process of switching over to the alpha phase of this project (v0.1.0 and on) , which use full refactor code written with help from a professional experienced software architect.

Until the new code stabilizes, you may have more luck using the pre-alpha code (e.g. v0.0.54)

INSTALLATION

Note: This will install the latest/last version from the pre-alpha phase of this project, frozen at release tag v0.0.54 here

Open an Anaconda-enabled command prompt or powershell window and enter the following commands:

  1. Create a Python3.7 Anaconda environment
conda create -n freemocap-env python=3.7
  1. Activate that newly created environment
conda activate freemocap-env
  1. Install freemocap (version 0.0.54) from PyPi using pip
pip install freemocap==0.0.54

BUG FIX - Update mediapipe with: pip install mediapipe --upgrade

That should be it!

How to create a NEW freemocap recording session

tl;dr- Activate the freemocap Python environment and run the following lines of code (either in a script or in a console)

import freemocap
freemocap.RunMe()

But COOL KIDS will install Blender (blender.org and generate an awesome .blend file animation by setting useBlender=True:

import freemocap
freemocap.RunMe(useBlender=True)

👉 For additional, more detailed instructions (including methods to re-process recorded sessions), refer to the OLD_README.md document) 👈

HOW TO RUN THE alpha GUI

NOTES

  • no promises here, friends. Work in progress lol 😂
  • Personally, I run the gui through PyCharm, but its easier to write instructions on how to run from an anaconda prompt

Pre-requisites:

  1. Install Anaconda
  2. Install git
  3. (OPTIONAL) Install Blender - https://blender.org

Installation instructions

  1. Open anaconda enabled terminal

  2. Create a python=3.9 environment

conda create -n freemocap-gui python=3.9
  1. Activate that environment:
conda activate freemocap-gui
  1. Clone the repository (i.e. download the code from github. It'll show up in the current working directory of your terminal session)
git clone https://github.com/freemocap/freemocap
  1. Navigate into that newly cloned/downloaded freemocap folder with:
cd freemocap
  1. Install the dependencies listed in the requirements.txt file:
pip install -r requirements.txt
  1. Run the GUI by running the src/gui/main/main.py file by entering this command into the terminal:
python src/gui/main/main.py
  1. Hopefully a GUI popped up! There are no docs on usage yet, so just click and see what you can figure out 😂

Current limitations

At the moment, the alpha GUI's method for connecting to the cameras is very innefficient and will experience framerate drops with more than ~3 cameras (even with a powerful PC). We're working on a fix, and should have it handled soon! In the mean time, you can still use the GUI to process videos recorded with other methods (workflow described in the next section!) __

Create 3D skeleton animations from externally recorded (and synchronized) videos ✨

You can use alpha GUI to process videos that were recorded and synchronized from any source!

Simply synchronize your videos in whatever way you wish, convert them to .mp4 format, and place them all in a single folder.

Then, import that folder via the Import Videos button in the GUI and follow the standard processing steps

For details, see this guide - https://freemocap.readthedocs.io/en/latest/how_to_guides/how_to_process_previously_recorded_videos/

Documentation and Knowledge Base

Documentation for this software is currently pretty thin... but we're woking on it!

Here's a YouTube video that covers a lot of relevant material (check the chapters for specific topics) - https://youtu.be/GxKmyKdnTy0

Our documentation lives here (for now) - https://freemocap.readthedocs.io

For Developers

Dev Setup

After you've done the easy install instructions, you'll be able to run our repo commands

  1. Run the "setup" command to set up your environment
task setup
  1. Run the tests to ensure that everything works appropriate
task test

Contribution Guidelines

Please read our contribution doc: CONTRIBUTING.md

Creating a new binary (may or may not work lol)

Create a new binary on your local system by running the below comand

task installer

Navigate to the /dist/ directory and you'll see the new FreeMoCap Binary there.

Related

Maintainers

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