pufbx 0.1.0

Fast, Pythonic bindings for the ufbx FBX file loader

pufbx

Fast, Pythonic bindings for the ufbx FBX file loader by Samuli Raivio (@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

pip install pufbx

From source

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

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

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)

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/ directory for complete, runnable scripts:

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

Development

Install uv, then:

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

Formatting & linting

uv run black pufbx/ tests/
uv run isort pufbx/ tests/

How it works

pufbx vendors the ufbx C source (by Samuli Raivio) 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 — see the license file for details.

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