Metadata-Version: 2.4
Name: coordframe
Version: 1.0.0
Summary: 3D coordinate-frame transforms with numpy arrays bound to frames.
Author-email: Praneeth Namburi <praneeth.namburi@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: pytest>=7 ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: scipy ; extra == "dev"
Requires-Dist: black ; extra == "dev"
Requires-Dist: isort ; extra == "dev"
Project-URL: Documentation, https://coordframe.readthedocs.io
Project-URL: Homepage, https://github.com/praneethnamburi/coordframe
Project-URL: Issues, https://github.com/praneethnamburi/coordframe/issues
Provides-Extra: dev

# 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

```bash
pip install coordframe
```

## Quick start

```python
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](https://github.com/praneethnamburi/coordframe/blob/main/LICENSE) for details.

## Acknowledgments

This package was developed as part of the ImmersionToolbox initiative
at the [MIT.nano Immersion Lab](https://immersion.mit.edu). Thanks to
NCSOFT for supporting this initiative.

