Skip to content

Releases: freemocap/freemocap

FreeMoCap v1.8.* release

22 Apr 22:23
@jonmatthis jonmatthis
v1.8.2
a1cd374

Choose a tag to compare

View all tags
FreeMoCap v1.8.* release Latest
Latest

How to Update

Via Pip:

pip install freemocap==1.8.*

Verify the update by checking the version in the FreeMoCap GUI Welcome Screen's bottom right corner.

Via Installer:
Download from the assets section below and review platform-specific instructions.

✨ Headline Feature — Reprojection Outlier Rejection

10cam_Fight_Demo_Color_hb.mp4

v1.8.0 adds an optional outlier-rejection step to the 3D triangulation pipeline that should substantially improve reconstruction quality on 4+ camera systems. Previously, adding more cameras ran into a "poison pill" problem: the more cameras in your rig, the higher the chance that one would pick up a bad track (spooky ghost skeletons 💀👻) and contaminate the reconstruction. The new method identifies and rejects those bad views on a per-point basis, making higher-camera-count rigs much more robust.

The option is OFF by default in this release. We are confident it will improve results in most cases, but because it touches the core reconstruction pipeline we want to roll it out cautiously. Enable it under Process Data > 3D Triangulation > Use Outlier Rejection Method? before processing.

If you have a 4+ camera setup — or better yet, an old recording that didn't quite reconstruct right — please try it and let us know how it goes on the tracking issue freemocap#782 or in the FreeMoCap Discord.

👉 For the full write-up (how it works, the math, recommended settings), see the in-app release notes popup (Help menu → Release Notes) or the Reprojection Filtering docs page.

🆕 Also New — Minimum Cameras for Triangulation

A new top-level "Minimum Cameras for Triangulation" option was added to the 3D Triangulation Methods panel (default: 3). It applies to both the simple triangulation path and the new outlier-rejection path. Points with fewer valid 2D detections than this threshold are dropped from the 3D output. If the value exceeds the number of cameras in the recording, FreeMoCap will warn and auto-adjust it down so processing still runs.

🎉 Contributor Shout-out

The outlier-rejection feature was contributed by ajc27, a long-time community member whose previous work includes the Blender output pipeline. This is their first contribution to the core reconstruction pipeline — thank you! 🙌

What's Changed

New Contributors

Full Changelog: v1.7.4...v1.8.0

Contributors

jonmatthis, philipqueen, and 2 other contributors
Assets 6
Loading

FreeMoCap v1.7.2 release

17 Sep 18:26
@aaroncherian aaroncherian
v1.7.2
1f40469

Choose a tag to compare

View all tags
FreeMoCap v1.7.2 release

How to Update

Updating with Pip

In the virtual or conda environment where you launch freemocap, enter the following command:

pip install freemocap==1.7.*

You can confirm the update by checking the version number in the bottom right corner of the FreeMoCap GUI Welcome Screen

Installing with Dedicated Installer

Releases for this version are in the assets files at the bottom of this page. Please read the general notes and specific instructions for your platform before installing. If you already have FreeMoCap downloaded through the installer, there are notes on how to update the version in the v1.2.0 Release Notes.

Release Notes

Some big updates to our overall calibration pipeline!

Calibration Pipeline Updates

In FreeMoCap 1.7.0, we've updated our calibration process to use same multiprocessing parameters that apply to 2D pose estimation - which means calibration should now overall be a much faster process. The calibration process now saves out the annotated video tracks of the charuco board in a new charuco_annotated_videos folder, as well as the 2D and 3D Charuco board data.

Ground Plane Calibration

We've added the option for users to define the ground plane and origin of a particular recording by leaving the Charuco board flat on the ground for a few seconds at the start of calibration. This means that the reconstructed data will automatically come in with the subject oriented 'upwards' with their feet on the ground. Check out the documentation here for how to use this feature: https://freemocap.github.io/documentation/groundplane-calibration.html

More Charuco boards!

For awhile now, our default Charuco board has been a 7x5 grid. We've now added the option for users to print and use a 5x3 grid on their board instead.

Calibration toml updates

We've updated our output calibration toml with:

  1. A parameter in the metadata that lets you know whether a given calibration used the ground plane option. It will say groundplane_calibration = true if you did, and groundplane_calibration = false otherwise.
  2. Each camera output now has sections called the world_orientation and world_position - these are the real world orientations and positions of each camera in the 3D space.

What's Changed

New Contributors

Full Changelog: v1.6.3...v1.7.0

Contributors

paulmatthis, aaroncherian, and 2 other contributors
Loading
1 Join discussion

v1.6.1

05 Jun 14:46
@aaroncherian aaroncherian
v1.6.1
42a1812

Choose a tag to compare

View all tags
v1.6.1

FreeMoCap v1.6.1 release

How to Update

Updating with Pip

In the virtual or conda environment where you launch freemocap, enter the following command:

pip install freemocap==1.6.*

You can confirm the update by checking the version number in the bottom right corner of the FreeMoCap GUI Welcome Screen

Installing with Dedicated Installer

Releases for this version are in the assets files at the bottom of this page. Please read the general notes and specific instructions for your platform before installing. If you already have FreeMoCap downloaded through the installer, there are notes on how to update the version in the v1.2.0 Release Notes.

Release Notes

FreeMoCap 1.6.0 fixes a bug in our calibration pipeline that was causing a ~10-15% difference scaling offset to our data (i.e. so measured limb segment lengths would be ~85-115% of their real world lengths). Additionally, this same bug was also leading to the scaling of the same set of data being different across different OS's. See #681 for more details on the bug and our troubleshooting.

If your application of FreeMoCap requires empirical accuracy, we recommend updating and reprocessing critical data with the new version of FreeMoCap to ensure the highest quality results.

We discovered this bug due to our ongoing efforts to incorporate comprehensive quality assurance diagnostics into our pipeline.

Additionally, the YOLO tracking in FreeMoCap has been not working due to using an outdated version of ultralytics - so we've updated to YOLO v11 to get that working again.

General Changes

  • FreeMoCap (v1.6.0): Output 3D data should now be much more accurately scaled to real-world units
  • FreeMoCap (v1.6.0): Output 3D data should be scaled the same across different OS's
  • FreeMoCap (v1.6.0): Small update on MacOS to detect variations in names of Blender.app. Thanks @gonewest818 for the contribution!
  • SkellyTracker (v2025.5.1022): Fixed the CharucoTracker in SkellyTracker
  • SkellyTracker (v2025.5.1022): Upgraded our YOLO version to v11, which should also get the YOLOMediaPipe combo tracker working again

What's Changed

New Contributors

Full Changelog: v1.5.4...v1.6.0

Contributors

gonewest818, aaroncherian, and trentwirth
Loading
0 Join discussion

v1.5

26 Dec 21:34
@philipqueen philipqueen
v1.5.2
639e5f9

Choose a tag to compare

View all tags
v1.5

FreeMoCap v1.5 release

How to Update

Updating with Pip

In the virtual environment where you launch freemocap, enter the following command:

pip install freemocap==1.5.*

Confirm update by checking the version number in the bottom right corner of the FreeMoCap GUI Welcome Screen

Installing with Dedicated Installer

Releases for this version are in the assets files at the bottom of this page. Please read the general notes and specific instructions for your platform before installing. If you already have FreeMoCap downloaded through the installer, there are notes on how to update the version in the v1.2.0 Release Notes.

Release Notes

FreeMoCap 1.5.0 focuses on improving our data output. Thanks to @ajc27-git, our final 3d data output now includes both .fbx and .bvh files, improving the portability of our output data for animation purposes.

We also added a tidy data output in a "tall" instead of "wide" format. This new file is called {recording_name}_by_frame.csv, and the old .csv format is still available as {rcording_name}_by_trajectory.csv. This update is thanks to a suggestion from @roaldarbol, and is discussed here: #653.

General Changes

  • FreeMoCap (v1.5.0): Fix blender addon 'images as planes' behavior for Blender v4.2+
  • FreeMoCap (v1.5.0): Added a "tall" format, tidy data .csv output *_by_frame.csv. Also fixed links to the docs and privacy policy and a path in the .ipynb output.
  • FreeMoCap Blender addon (v2024.12.1033): Add fbx and bvh files to the output. Also improved the logging messages.
  • SkellyViewer (v2024.12.1026): Patch the --help command.
  • SkellyForge (v2024.12.1009): Patch the --help command.

What's Changed

Full Changelog: v1.4.7...v1.5.0

Attached Files:

  • freemocap_test_data_processed_with_freemocap_v1.5.0.zip - A zipped copy of the freemocap_test_data recording processed with freemocap_v1.5.0

Installers

NOTE - For detailed instructions on the use of these installers, see the v1.2.0 Release Notes

  • freemocap_linux_app.zip - Dedicated installer for Linux systems.

  • freemocap_windows_exe.zip - Dedicated installer/executable for Windows systems. Does not work on Windows 11.

  • freemocap_mac_app.zip - Dedicated installer/application for Mac systems. Works on both Intel and Arm systems.

Contributors

aaroncherian, philipqueen, and 3 other contributors
Loading

FreeMoCap v1.4 release

04 Sep 17:58
@aaroncherian aaroncherian
v1.4.7
2f8097c

Choose a tag to compare

View all tags
FreeMoCap v1.4 release

FreeMoCap v1.4.0 release

How to Update

Updating with Pip

In the conda environment where you launch freemocap, enter the following command:

pip install freemocap==1.4.*

Confirm update by checking the version number in the bottom right corner of the FreeMoCap GUI Welcome Screen

Installing with Dedicated Installer

Releases for this version are in the assets files at the bottom of this page. Please read the general notes and specific instructions for your platform before installing. If you already have FreeMoCap downloaded through the installer, there are notes on how to update the version in the v1.2.0 Release Notes.

Release Notes

This minor release adds the ability to get 3d data from a single camera. Because this data is less reliable, 2d data is still the default. To turn on 3d data for single camera recordings, uncheck the Flatten Single Camera Data (Recommended) button in the motion capture parameters. It also fixes a bug in the processing pipeline check that was interfering with some single camera recordings.

FreeMoCap 1.4.0 marks a significant backend overhaul across almost all of our sub-repositories. As we're working towards our long-term goal of providing users the flexibility to integrate and use different pose estimation trackers, this update focuses on making the backend more tracker-agnostic and simplifying the process for writing new pose estimation trackers within our SkellyTracker repository.

General Changes

  • FreeMoCap (v1.4.0): 3D data can now be collected from a single camera. The backend has been fully generalized to remove the hard dependency on MediaPipe for data and file management. Now, tracker-specific information is provided by SkellyTracker, making it easier to integrate different trackers.
    • Note: As a part of this, we did update some of our file naming conventions - see notes below for more
  • SkellyTracker (v2024.08.1018): Some big updates to simplify writing new trackers for FreeMoCap. Check out the mediapipe_model_info.py in SkellyTracker if you're interesting in seeing how its written.
  • SkellyForge (v2024.8.1008): Small update to remove MediaPipe dependency
  • FreeMoCap Blender addon (v2024.09.1024): Updated paths to align with the new file naming conventions. The addon now also checks for compatibility with old file names.

IMPORTANT: New file naming convention

We've standardized our file naming convention with this update - which means if you have any scripts that depend on specific file names, they may not work with recordings made with v1.4.

We now follow a standard convention of tagging any file names with the prefix `[tracker_name]_' - which affects these following file names moving forward:

Raw Data: All raw data file names previously lacked underscores and have been changed to do so.
Output Data: The file name for the numpy array with all the processed name has been changed.
Center of Mass: All center of mass file names are now prefixed with mediapipe_.

See the table below for the full name changes.

Update Script

We have also added an update script to standardize an entire freemocap_data folder to the new naming convention. You can run the script by running python -m freemocap.utilities.update_1_4_path_names in your terminal. To specify a non-default freemocap_data folder, you can run python -m freemocap.utilities.update_1_4_path_names {PATH_TO_OTHER_FOLDER}. Depending on your Python installation you may need to run python3 -m ....

Old File Name New File Name
mediapipe2dData_numCams_numFrames_numTrackedPoints_pixelXY.npy mediapipe_2dData_numCams_numFrames_numTrackedPoints_pixelXY.npy
mediapipe3dData_numCams_numFrames_numTrackedPoints_reprojectionError.npy mediapipe_3dData_numCams_numFrames_numTrackedPoints_reprojectionError.npy
mediapipe3dData_numFrames_numTrackedPoints_reprojectionError.npy mediapipe_3dData_numFrames_numTrackedPoints_reprojectionError.npy
mediapipe3dData_numFrames_numTrackedPoints_spatialXYZ.npy mediapipe_3dData_numFrames_numTrackedPoints_spatialXYZ.npy
mediaPipeSkel_3d_body_hands_face.npy mediapipe_skeleton_3d.npy
total_body_center_of_mass_xyz.npy mediapipe_total_body_center_of_mass_xyz.npy
segmentCOM_frame_joint_xyz.npy mediapipe_segmentCOM_frame_joint_xyz.npy

What's Changed

Full Changelog: v1.3.1...v1.4.0

Attached Files:

  • freemocap_test_data_processed_with_freemocap_v1.4.0.zip - A zipped copy of the freemocap_test_data recording processed with freemocap_v1.4.0

Installers

NOTE - For detailed instructions on the use of these installers, see the v1.2.0 Release Notes

  • freemocap_linux_app.zip - Dedicated installer for Linux systems.

  • freemocap_windows_exe.zip - Dedicated installer/executable for Windows systems. Does not work on Windows 11.

  • freemocap_mac_app.zip - Dedicated installer/application for Mac systems. Works on both Intel and Arm systems.

Contributors

philipqueen
Loading

v1.3.0

01 Aug 12:48
@jonmatthis jonmatthis
v1.3.0
61f2bc6

Choose a tag to compare

View all tags
v1.3.0

FreeMoCap v1.3.0 release

How to Update

Updating with Pip

In the conda environment where you launch freemocap, enter the following command:

pip install freemocap==1.3.0

Confirm update by checking the version number in the bottom right corner of the FreeMoCap GUI Welcome Screen

Installing with Dedicated Installer

Releases for this version are in the assets files at the bottom of this page. Please read the general notes and specific instructions for your platform before installing. If you already have FreeMoCap downloaded through the installer, there are notes on how to update the version below.

New minor version bump (i.e. the middle number increased, SemVar for fmc-core), the most exciting part of which is the fixes and improvements to the standard Blender output - continuing the process of integrating @ajc27's great work into the core FreeMoCap software

Here is a link to relevant release on the freemocap_blender_addon repo (v2024.07.1022 - CalVer for the sub-skellies)

This release includes a .zip you can use to install as Blender addon, and a sample output based on the standard freemocap_test_data
https://github.com/freemocap/freemocap_blender_addon/releases/tag/v2024.07.1022

Going forward, we will try to keep the freemocap_blender_addon latest release up to date with an installable Blender addon (Hopefully autmated via GitHub Action, see: freemocap/freemocap_blender_addon#16)

Whee!

❤️💀✨

Auto-generated Release notes (i.e. merged Pull Requests in this release)

Full Changelog: v1.2.2...v1.3.0

Attached Files:

  • freemocap_test_data_processed_with_freemocap_v1.3.0.zip - A zipped copy of the freemocap_test_data recording processed with freemocap_v1.3.0

Installers

NOTE - For detailed instructions on the use of these installers, see the v1.2.0 Release Notes

  • freemocap_linux_app.zip - Dedicated installer for Linux systems.

  • freemocap_windows_exe.zip - Dedicated installer/executable for Windows systems. Does not work on Windows 11.

  • freemocap_mac_app.zip - Dedicated installer/application for Mac systems. Works on both Intel and Arm systems.

Contributors

ajc27 and philipqueen
Loading
0 Join discussion

1.2.0

30 Apr 02:12
@philipqueen philipqueen
v1.2.0
76195af

Choose a tag to compare

View all tags
1.2.0

FreeMoCap 1.2.0

FreeMoCap 1.2.0 is a minor release with major impacts, including new features, workflow upgrades, and bug fixes. Below is a list of our new features:

Highlights

  • freemocap_data folder is now configurable: You can set any folder location to use as your freemocap_data folder, and it will be remembered across sessions
  • Blender executable path is remembered across sessions: Once you set a Blender executable path, it will now be remembered across sessions. If the automatic finder doesn't work, you will only need to manually find the path once, instead of having to reset it every session.
  • Deprecated legacy Blender export methods: We have deprecated the "alpha megascript" blender methods, so the "ajc27_freemocap_blender_addon" is now the only option.
  • Enable Rigify automatically: Now rigify is enabled automatically during the Blender export, removing a confusing barrier for first time users.
  • Improved sample data calibration: We have updated the calibration file for both the sample and test data, so the output is higher quality.
  • Expose YOLO crop parameters: Users can now set parameters for the YOLO crop preprocessing step, allowing for finer grained control of preprocessing.

Full Changelog

Detailed Changelog: https://github.com/freemocap/freemocap/compare/v1.1.1...v1.2.0

Updating with Pip

To update the installation with pip, run pip install freemocap --upgrade.

Installing with Dedicated Installer

  • We are trying out PyApp as a method to create a non-CLI based installer
  • Please note that this is our first time bundling installers, so there will likely be issues when trying to install and run them. You can always download FreeMoCap from PyPI following our installation instructions. Some general and platform-specific notes about the installers are listed below:

‼️General Notes Before Using the Installer Executable:

  • This is not an endgame solution, but it should be functional enough for the time being
  • The first time you open the [PyApp](executable, it will install the necessary environment to run FreeMoCap.
  • This means that an internet connection is required the first time you open FreeMoCap with the executable, but from then on, you can run it without internet connection.
  • Please note that the installation process will require roughly 3GB of available space
  • NOTE: This will take roughly 5-10 mins to install with no indication of installation. Please wait patiently :)
  • As the installers are still experimental they will likely be flagged by your OS security settings

Platform-Specific Notes:

  • Windows:
    The FreeMoCap installers do not work on Windows 11 yet. We're currently working towards getting the software approved by Windows as virus free.

  • Mac:
    The single installer should work on both Intel and Apple Silicon Macs.
    To run the app, you will need to open the zip file and you will see the app, which you can drag to the Applications folder. The first time you open the app, it will tell you it is from an unidentified developer and ask if you would like to move it to the trash. Close out of that window, right click the app, click Open, and choose to open the file. Once you have done this once, you can open the app as normal in the future. For more information, see the official Apple documentation.

Deleting, Updating, and Restoring the Installer

The installer has a handful of management command that can be run in a terminal by using the path to the executable as the start of the command (referred to below as {EXECUTABLE_PATH}). On Mac, you need to add /Contents/MacOS/freemocap_app to the freemocap.app path to get the below commands to work.

To delete the installed version of FreeMoCap, you can run {EXECUTABLE_PATH} self remove. This will delete all of the data associated with the executable (but not your freemocap_data folder), and then you can manually delete the executable or app.

To update the installed version of FreeMoCap, you can run {EXECUTABLE_PATH} self update. This will update to the latest release of FreeMoCap.

If you have installed FreeMoCap through the installer but it will not successfully run, something may have happened during the installation process. You can try running {EXECUTABLE_PATH} self restore, which will delete the associated installation files and reinstall them. Ensure you give enough time for the installer to fully download when restoring.

Contributors

aaroncherian and philipqueen
Loading

1.1.0

19 Jan 18:10
@jonmatthis jonmatthis
1.1.0
7616f65
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
1.1.0

FreeMoCap 1.1.0

FreeMoCap 1.1.0 is a minor release with major impacts, including new features, workflow upgrades, and bug fixes. Below is a list of our new features:

Processing Pipeline Updates

  • YOLO Cropping: We've integrated a new pre-processing feature that utilizes YOLO cropping to significantly reduce false positives during tracking, especially enhancing the performance when using wide-angle cameras. See YOLO Cropping in our docs for more info.

  • Reprojection Error Filtering: We've added new post-processing step to filter and reprocess points with significant reprojection error. See Reprojection Error Filtering in our docs for more info.

  • More Multiprocessing Control: Previously, the multiprocessing feature (i.e. how many videos you're processing simultaneously) automatically started a process for each video in a recording, which was essentially an all-or-nothing approach. This default setting limited users with less powerful hardware from leveraging multiprocessing. We've introduced a customizable option that enables users to specify the exact number of processes they want to use when processing a recording - which should allow more users to take advantage of it. See Multiprocessing in our docs for more info.

  • GUI Updates: We've improved progress updates in the GUI, so it should be more apparent when processes are running. We've also updated our error handling and reporting throughout the program.

New Installation Methods

  • We are trying out PyApp as a method to create a non-CLI based installer
  • Please note that this is our first time bundling installers, so there will likely be issues when trying to install and run them. You can always download FreeMoCap from PyPI following our installation instructions. Some general and platform-specific notes about the installers are listed below:

‼️General Notes Before Using the Installer Executable:

  • This is and endgame solution, but it should be functional enough for the time being
  • The first time you open the [PyApp](executable, it will install the necessary environment to run FreeMoCap.
  • This means that an internet connection is required the first time you open FreeMoCap with the executable, but from then on, you can run it without internet connection.
  • Please note that the installation process will require roughly 3GB of available space
  • NOTE: This will take roughly 5-10 mins to install with no indication of installation. Please wait patiently :)
  • As the installers are still experimental they will likely be flagged by your OS security settings

Platform-Specific Notes:

  • Windows:
    The FreeMoCap installers do not work on Windows 11 yet. We're currently working towards getting the software approved by Windows as virus free, but it will take some time.

  • Mac:
    The single installer should work on both Intel and Apple Silicon Macs.
    To run the app, you will need to open the zip file and you will see the app, which you can drag to the Applications folder. The first time you open the app, it will tell you it is from an unidentified developer and ask if you would like to move it to the trash. Close out of that window, right click the app, click Open, and choose to open the file. Once you have done this once, you can open the app as normal in the future. For more information, see the official Apple documentation.

Deleting your FreeMoCap download, if necessary

To delete a version of FreeMoCap downloaded through an installer, you must delete both the executable/app file, and the PyApp file found in the path below. You can either delete the entire freemocap folder, or specific versions inside the folder.

Platform Path
macOS ~/Library/Application Support/pyapp
Windows %USERPROFILE%\AppData\Local\pyapp
Unix $XDG_DATA_HOME/pyapp (the XDG_DATA_HOME environment variable default is ~/.local/share)
Loading

FreeMoCap 1.0

09 Nov 16:18
@jonmatthis jonmatthis
v1.0.25
005fed5

Choose a tag to compare

View all tags
FreeMoCap 1.0

There's all sorts of number bigger than 1 💫

What's Changed

New Contributors

  • @newturok made their first contribution in #432
  • @CypressJack made their first contribution in #439

Full Changelog: v0.1.0...v1.0.25

Contributors

yuturiy, jonmatthis, and 4 other contributors
Loading

FreeMoCap 1.0 - pre-release

15 Mar 15:57
@jonmatthis jonmatthis
v1.0.0-rc
179cd1b

Choose a tag to compare

View all tags
FreeMoCap 1.0 - pre-release Pre-release
Pre-release

There's all sorts of number after '1' ✨

Loading
0 Join discussion