Geometric Transformations in FreeMoCap: A Complete Guide to the utilities/geometry Module

The freemocap/utilities/geometry module exposes two pure NumPy geometric transformations—rotate_by_90_degrees_around_x_axis and project_3d_data_to_z_plane—for manipulating 3-D motion capture skeletons with shape (frames, markers, 3).

The FreeMoCap repository is an open-source markerless motion capture pipeline that processes multi-camera skeletal data into 3-D coordinate arrays. The freemocap/utilities/geometry package provides lightweight, functional utilities for performing common geometric transformations on these skeletons, enabling preprocessing steps like reorientation and flattening without mutating source data.

Available Geometric Transformations

The geometry module currently implements two specialized transformations for 3-D skeletal data. Both functions operate on NumPy arrays of shape (N, M, 3), where N represents frames, M represents markers (joints or tracking points), and the final dimension stores XYZ coordinates.

rotate_by_90_degrees_around_x_axis

Located in freemocap/utilities/geometry/rotate_by_90_degrees_around_x_axis.py, this utility performs a 90-degree rotation around the X-axis using a right-hand rule coordinate system.

The transformation applies the following mapping to each coordinate triplet:

• X: Remains unchanged
• Y: Becomes the original Z value
• Z: Becomes the negative of the original Y value

This rotation is useful for reorienting skeletons to align with different coordinate system conventions or correcting camera calibration orientations.

project_3d_data_to_z_plane

Implemented in freemocap/utilities/geometry/project_3d_data_to_z_plane.py, this function projects 3-D data onto the XY plane (Z-plane projection) by zeroing the Z-component while preserving X and Y values.

This transformation effectively flattens the skeleton into a 2-D representation, commonly used for generating floor-plan visualizations or analyzing planar movement patterns without depth information.

Working with 3-D Skeleton Data

Both geometric transformation functions expect input arrays with shape (frames, markers, 3) and return new arrays with identical shape, leaving the original data untouched. This pure functional design ensures safe integration with NumPy-based data pipelines and enables reliable unit testing.

The module's __init__.py file re-exports these functions, providing a clean public API:

from freemocap.utilities.geometry import rotate_by_90_degrees_around_x_axis, \
                                         project_3d_data_to_z_plane

Code Examples

Rotating a Skeleton 90° Around the X-Axis

The following example demonstrates how to rotate motion capture data using the X-axis rotation utility:

import numpy as np
from freemocap.utilities.geometry import rotate_by_90_degrees_around_x_axis

# Generate dummy data: 10 frames, 5 markers, XYZ coordinates

raw_skel = np.random.rand(10, 5, 3)

rotated_skel = rotate_by_90_degrees_around_x_axis(raw_skel)

print("Original first marker (frame 0):", raw_skel[0, 0])
print("Rotated first marker (frame 0):", rotated_skel[0, 0])

Output behavior: The X-coordinate remains constant, while Y becomes the original Z and Z becomes the negative original Y.

Projecting Skeleton Data onto the XY Plane

To flatten 3-D motion capture data onto the Z-plane:

import numpy as np
from freemocap.utilities.geometry import project_3d_data_to_z_plane

# Generate dummy data: 8 frames, 6 markers, XYZ coordinates

skel = np.random.rand(8, 6, 3)

projected_skel = project_3d_data_to_z_plane(skel)

print("Original Z of first marker (frame 0):", skel[0, 0, 2])
print("Projected Z of first marker (frame 0):", projected_skel[0, 0, 2])  # always 0

Output behavior: Every Z-coordinate is set to zero, effectively projecting the skeleton onto the XY plane while preserving X and Y spatial relationships.

Module Architecture and API Design

The freemocap/utilities/geometry package follows a flat architecture optimized for discoverability and testing. The __init__.py file located at freemocap/utilities/geometry/__init__.py explicitly exposes the two transformation functions, preventing deep import chains and maintaining a stable public interface.

By implementing these geometric transformations as pure functions without side effects, the module ensures thread safety and compatibility with functional programming patterns. The implementation relies entirely on vectorized NumPy operations, avoiding Python loops for performance optimization on large motion capture datasets.

Unit tests for these utilities reside in freemocap/tests/test_geometry_utilities.py, validating mathematical correctness across various input shapes and edge cases.

Summary

• Two core transformations are available: rotate_by_90_degrees_around_x_axis and project_3d_data_to_z_plane
• Input format requires NumPy arrays of shape (frames, markers, 3) containing XYZ coordinates
• Pure functional design ensures input arrays remain unmodified, returning new transformed arrays
• Clean imports are available via freemocap.utilities.geometry thanks to __init__.py re-exports
• Vectorized NumPy operations provide efficient processing for high-frame-rate motion capture data

Frequently Asked Questions

What input format does the freemocap geometry module expect?

The geometric transformation functions expect NumPy arrays with shape (N, M, 3), where N is the number of frames, M is the number of markers (joints or tracking points), and the final dimension contains XYZ coordinates. Both functions validate that the input array has exactly three dimensions with a final axis size of 3.

How do I import the geometric transformation functions?

Import the functions directly from the geometry package using from freemocap.utilities.geometry import rotate_by_90_degrees_around_x_axis, project_3d_data_to_z_plane. The __init__.py file handles the internal module references, so you do not need to reference the individual .py files directly.

Are these transformations destructive to the original data?

No, both rotate_by_90_degrees_around_x_axis and project_3d_data_to_z_plane are pure functions that return new NumPy arrays. The input skeleton data remains completely unmodified, allowing you to chain multiple transformations or preserve the original dataset for comparison without creating defensive copies manually.

Where are the unit tests for the geometry utilities?

Unit tests validating the mathematical correctness of these geometric transformations are located in freemocap/tests/test_geometry_utilities.py. These tests verify that rotations and projections produce expected coordinate mappings across various input shapes, ensuring reliability when processing real motion capture data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}