Metadata-Version: 2.4
Name: pufbx
Version: 0.1.0
Summary: Fast, Pythonic bindings for the ufbx FBX file loader
Author-email: Andrzej Weremczuk <masterxsido@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Owca-Xsido/pufbx
Project-URL: Repository, https://github.com/Owca-Xsido/pufbx
Project-URL: Issues, https://github.com/Owca-Xsido/pufbx/issues
Keywords: fbx,3d,animation,ufbx,cython,gamedev,scene-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Cython
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: autopep8; extra == "dev"
Dynamic: license-file

# pufbx

[![CI](https://github.com/Owca-Xsido/pufbx/actions/workflows/build.yml/badge.svg)](https://github.com/Owca-Xsido/pufbx/actions/workflows/build.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)

Fast, Pythonic bindings for the [ufbx](https://github.com/ufbx/ufbx) FBX file loader by [Samuli Raivio (@bqqbarbhg)](https://github.com/bqqbarbhg).

**pufbx** wraps the battle-tested C library *ufbx* via Cython, giving you
high-performance access to FBX scene data — nodes, meshes, bones, animations,
materials, and more — without writing a single line of C.

**Project status:** **alpha**. **Planned scope** is **everything ufbx defines** for reading FBX (its public types, fields, lists, and loader-facing API). **Rough completion:** ~**35%** toward that bar (informal): many wrappers exist, but exhaustive parity and polish across the full ufbx surface are still in progress. **Version 0.1.0** focused on **animation** — scene load, **bake**, **dense numpy export** (`anim_to_array`), and **raw curves**.

## Features

- **Fast** — thin Cython layer over native C; loads large FBX files in milliseconds
- **Pythonic API** — scene-graph traversal, properties, iteration, `len()`, and numpy arrays
- **Animation baking** — `bake_anim()` composites full transform chains into quaternion keyframes
- **Dense export** — `anim_to_array()` returns `(nodes × frames × 10)` numpy arrays ready for ML pipelines
- **Raw curves** — access original Euler-angle keyframes with Bezier tangent handles
- **Cross-platform** — Linux, macOS, and Windows wheels for Python 3.9–3.13

## Installation

### From PyPI

```bash
pip install pufbx
```

### From source

```bash
git clone https://github.com/Owca-Xsido/pufbx.git
cd pufbx
uv sync --extra dev
```

> **Note:** Building from source requires a C compiler and Python development
> headers (`python3-dev` / `python3.x-dev` on Debian/Ubuntu).

## Quick start

### Load a scene and traverse nodes

```python
import pufbx

scene = pufbx.load_fbx("character.fbx")

print(f"Nodes: {len(scene.nodes)}")

for node in scene.nodes:
    indent = "  " * node.node_depth
    print(f"{indent}{node.name}  type={node.attrib_type}")
```

### Bake animation to quaternion keyframes

```python
import pufbx

scene = pufbx.load_fbx("character.fbx")
baked = pufbx.bake_anim(scene)

for node in baked.modified_nodes:
    r = node.rotation_keys
    print(f"Node {node.typed_id}: {len(r)} rotation keyframes")
```

### Export dense numpy array (ML-ready)

```python
import pufbx

data, times, names = pufbx.anim_to_array("character.fbx")
# data.shape  → (num_nodes, num_frames, 10)
# channels: [tx, ty, tz, rx, ry, rz, rw, sx, sy, sz]
```

## Examples

See the [`examples/`](examples/) directory for complete, runnable scripts:

| Script | Description |
|--------|-------------|
| [`01_load_scene.py`](examples/01_load_scene.py) | Load a scene and print the node hierarchy |
| [`02_bake_rotation.py`](examples/02_bake_rotation.py) | Bake animation and read rotation quaternions |
| [`03_anim_to_array.py`](examples/03_anim_to_array.py) | Export animation to a dense numpy array |
| [`04_raw_curves.py`](examples/04_raw_curves.py) | Access raw Euler-angle curves with Bezier tangents |

## Development

Install [uv](https://docs.astral.sh/uv/), then:

```bash
git clone https://github.com/Owca-Xsido/pufbx.git
cd pufbx
uv sync --extra dev
uv run python -m pytest tests/
```

### Formatting & linting

```bash
uv run black pufbx/ tests/
uv run isort pufbx/ tests/
```

## How it works

pufbx vendors the [ufbx](https://github.com/ufbx/ufbx) C source (by
[Samuli Raivio](https://github.com/bqqbarbhg)) and compiles it into a shared
Cython extension. On Linux/macOS, `ufbx_wrapper` is loaded with `RTLD_GLOBAL`
so all extension modules share a single copy of the ufbx C symbols (required
for ufbx string interning via pointer identity).

## License

[MIT](LICENSE) — see the license file for details.

The vendored [ufbx](https://github.com/ufbx/ufbx) library is Copyright (c) 2020
[Samuli Raivio (@bqqbarbhg)](https://github.com/bqqbarbhg), available under the
MIT License or the Unlicense (public domain) at your option.
