coordframe

3D coordinate-frame transforms with numpy arrays bound to frames.

Overview

Two headline abstractions for scripted 3D visualization and motion-capture analysis:

  • CoordFrame — a coordinate frame defined by an origin and three unit vectors (or a 4×4 transformation matrix). Frames are first-class objects with named axes; transforms can be applied to a frame or within a frame.

  • PointCloud — a numpy array of 3D points bound to a CoordFrame. Lets you reason about “joint positions in the femur frame” or “marker positions in the camera frame” directly, without manually tracking which transform applies to which point set.

The package also exports a Quat quaternion class and a small collection of helpers (transform, m4, v4, apply_matrix, normal2tfmat, twisttf, scaletf, norm_vec).

Why coordframe?

Existing 3D-transform libraries (transforms3d, pytransform3d, scipy.spatial.transform, pyquaternion) operate primarily on rotations and translations as standalone objects. coordframe’s distinguishing move is to make the frame a first-class object with named axes, and to bind numpy point arrays to frames so you can express transform operations in the language of the application (“transform these markers in the camera frame”) rather than the language of the math (“multiply this rotation matrix by these vectors”).

This is the abstraction that powers bpn (the parent project, which uses it for Blender-scripted scientific visualization) and the motion-capture analysis pipelines built on top.

Install

pip install coordframe

Quick start

import numpy as np
import coordframe as cf

# World frame
world = cf.CoordFrame()

# A custom frame
femur = cf.CoordFrame(
    i=[1, 0, 0], j=[0, 1, 0], k=[0, 0, 1], origin=[0.1, 0.2, 0.3]
)

# Bind 3 marker positions to the femur frame
markers = cf.PointCloud(
    [[0, 0, 0], [0.05, 0, 0], [0, 0.05, 0]], frame=femur
)

# Express the markers in world coordinates
world_markers = markers.in_world()

# Rotate the femur frame 30 degrees around its k axis using a quaternion
q = cf.Quat([0, 0, 1], np.pi / 6, frame=femur)
femur_rotated = q * femur

History

Originally developed inside bpn (https://github.com/praneethnamburi/blender-ScriptViz) as bpn.trf. Graduated to a standalone package so consumers (motion- capture analysis pipelines, robotics tooling, generic scientific- Python users) can use it without installing Blender.

License

Distributed under the MIT License. See LICENSE for details.

Acknowledgments

This package was developed as part of the ImmersionToolbox initiative at the MIT.nano Immersion Lab. Thanks to NCSOFT for supporting this initiative.