omi_physics

A renderer-agnostic, real-time rigid-body physics engine for Python, built natively on the OMI glTF physics data model. State lives in flat NumPy arrays, the whole step pipeline is vectorized, and optional compiled Cython accelerators drop in transparently for the hot paths (the contact solver and box/sphere collision).

NumPy is the only hard dependency. No graphics library is required to simulate.
PyOpenGL is optional — used solely by the experimental GPU compute backend (omi_physics.glcompute).
Deterministic on the CPU backend: the same inputs produce the same trajectory, run to run.
Fast: sweep-and-prune broadphase, SAT/GJK narrowphase, an island-parallel sequential-impulse solver, sleeping, and a background-threaded simulation loop that overlaps with a consumer's render/IO thread.

⚠️ This code is largely LLM-written. It has a test suite and the CPU backend is deterministic, but it comes with no guarantees of correctness, accuracy, or fitness for any purpose (see LICENSE, MIT). Review it before relying on it for anything that matters.

Install

pip install omi_physics            # core engine (NumPy only)
pip install "omi_physics[gl]"      # + PyOpenGL for the GPU compute backend

Prebuilt wheels ship the compiled accelerators, so no C compiler is needed. A source install without a compiler still works — the engine falls back to the identical pure-NumPy code paths.

Quick start

import numpy as np
from omi_physics import PhysicsWorld, model

world = PhysicsWorld(gravity=model.Gravity(gravity=9.81, direction=(0, -1, 0)))

# A static ground box and a dynamic box that falls onto it.
ground = world.add_shape(model.Shape.box((20, 1, 20)))
box    = world.add_shape(model.Shape.box((1, 1, 1)))
wood   = world.add_material(model.Material())

world.add_body(model.Motion(type=model.STATIC),
               collider=model.Collider(shape=ground, physicsMaterial=wood),
               position=(0, 0, 0))
falling = world.add_body(model.Motion(type=model.DYNAMIC, mass=1.0),
                         collider=model.Collider(shape=box, physicsMaterial=wood),
                         position=(0, 5, 0))

for _ in range(120):                       # 2 seconds at 60 Hz
    world.step(1 / 60)

print(world.position[falling])             # resting on the ground

The exact add_body/add_shape signatures are the source of truth in world.py; see the tests for worked examples.

Off-thread simulation

ThreadedSimulation steps the world on a daemon thread and publishes an immutable pose snapshot each tick. A renderer reads the latest snapshot every frame without ever blocking on the solver:

from omi_physics.threaded import ThreadedSimulation

sim = ThreadedSimulation(world, sim_hz=120)
sim.start()
# ... each render frame:
snapshot, version = sim.latest()           # (position, axis_angle, awake, dynamic)
# ... on shutdown:
sim.stop()

How it works

One world.step(dt) runs this fixed-timestep pipeline over the world's structure-of-arrays state:

flowchart LR
    A[integrate forces<br/>gravity · damping · drag] --> B[refit AABBs]
    B --> C[broadphase<br/>sweep & prune]
    C --> D[narrowphase<br/>SAT · GJK/EPA]
    D --> E[solver<br/>sequential impulse]
    E --> F[joints]
    F --> G[integrate positions]
    G --> H[sleeping]

The data model is OMI glTF physics (model.Shape, Motion, Collider, Material, Joint, ...), so scenes round-trip to and from glTF documents (omi_physics.omi_gltf). See docs/ for a deep dive:

docs/ARCHITECTURE.md — components, layering, and how they fit together.
docs/PIPELINE.md — the step pipeline stage by stage, with the data that flows between stages.
docs/DATA-MODEL.md — the OMI data model and the structure-of-arrays world state.
docs/ACCELERATORS.md — the Cython accelerators and the pure-Python fallback contract.

Working on omi_physics

git clone https://github.com/mcfletch/omi_physics
cd omi_physics
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"          # editable install, builds the accelerators
pytest                            # run the test suite

Handy commands:

# Rebuild the accelerators in place after editing a .pyx
python setup.py build_ext --inplace

# Force the pure-Python fallback (delete the compiled modules)
rm -f src/omi_physics/*.so

# Type-check and lint
mypy src/omi_physics
ruff check src tests

The accelerators are a pure speedup: every .pyx has an identical NumPy/ Python implementation the engine uses when the compiled module is absent. Tests must pass in both configurations (with and without the .so files present).

Layout

src/omi_physics/        the engine (importable as omi_physics)
  model.py              OMI glTF physics data model
  world.py              PhysicsWorld — structure-of-arrays state + step()
  backend.py            NumpyBackend / GPU backend selection
  glcompute.py          optional GL 4.3 compute integration backend (needs PyOpenGL)
  broadphase.py         sweep-and-prune + dynamic AABB tree
  collide.py            SAT box-box, sphere tests (vectorized)
  gjk.py                GJK/EPA for convex shapes
  narrowphase.py        contact generation, routes to accelerators
  solver.py             island-parallel sequential-impulse contact solver
  joints.py             point / distance / hinge constraints and motors
  character.py          kinematic character controller
  cookery.py / hull.py  shape cooking (convex hulls, trimeshes)
  omi_gltf.py           read/write OMI physics from glTF documents
  threaded.py           ThreadedSimulation — background-thread stepping
  _solver_native.pyx    Cython contact solver accelerator
  _collide_native.pyx   Cython collision accelerator
tests/                  pytest suite (pure NumPy; GPU-parity tests skip w/o GL)
docs/                   deep-dive documentation (Markdown + Mermaid)

License

MIT — see LICENSE. In some jurisdictions LLM generated code cannot have any copyright assignment. The intent of the license is that anyone anywhere can use the code for whatever purpose they deem fit, provided that they assume any liability for that usage.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

omi_physics-0.3.0.tar.gz (497.2 kB view details)

Uploaded Aug 7, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

omi_physics-0.3.0-cp314-cp314-win_amd64.whl (634.6 kB view details)

Uploaded Aug 7, 2026 CPython 3.14Windows x86-64

omi_physics-0.3.0-cp314-cp314-win32.whl (603.6 kB view details)

Uploaded Aug 7, 2026 CPython 3.14Windows x86

omi_physics-0.3.0-cp314-cp314-musllinux_1_2_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.14musllinux: musl 1.2+ x86-64

omi_physics-0.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

omi_physics-0.3.0-cp314-cp314-macosx_11_0_arm64.whl (649.2 kB view details)

Uploaded Aug 7, 2026 CPython 3.14macOS 11.0+ ARM64

omi_physics-0.3.0-cp313-cp313-win_amd64.whl (624.1 kB view details)

Uploaded Aug 7, 2026 CPython 3.13Windows x86-64

omi_physics-0.3.0-cp313-cp313-win32.whl (593.6 kB view details)

Uploaded Aug 7, 2026 CPython 3.13Windows x86

omi_physics-0.3.0-cp313-cp313-musllinux_1_2_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.13musllinux: musl 1.2+ x86-64

omi_physics-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

omi_physics-0.3.0-cp313-cp313-macosx_11_0_arm64.whl (639.9 kB view details)

Uploaded Aug 7, 2026 CPython 3.13macOS 11.0+ ARM64

omi_physics-0.3.0-cp312-cp312-win_amd64.whl (624.5 kB view details)

Uploaded Aug 7, 2026 CPython 3.12Windows x86-64

omi_physics-0.3.0-cp312-cp312-win32.whl (593.8 kB view details)

Uploaded Aug 7, 2026 CPython 3.12Windows x86

omi_physics-0.3.0-cp312-cp312-musllinux_1_2_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.12musllinux: musl 1.2+ x86-64

omi_physics-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

omi_physics-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (641.3 kB view details)

Uploaded Aug 7, 2026 CPython 3.12macOS 11.0+ ARM64

omi_physics-0.3.0-cp311-cp311-win_amd64.whl (621.7 kB view details)

Uploaded Aug 7, 2026 CPython 3.11Windows x86-64

omi_physics-0.3.0-cp311-cp311-win32.whl (592.1 kB view details)

Uploaded Aug 7, 2026 CPython 3.11Windows x86

omi_physics-0.3.0-cp311-cp311-musllinux_1_2_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.11musllinux: musl 1.2+ x86-64

omi_physics-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.6 MB view details)

Uploaded Aug 7, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

omi_physics-0.3.0-cp311-cp311-macosx_11_0_arm64.whl (639.3 kB view details)

Uploaded Aug 7, 2026 CPython 3.11macOS 11.0+ ARM64

omi_physics-0.3.0-cp310-cp310-win_amd64.whl (621.2 kB view details)

Uploaded Aug 7, 2026 CPython 3.10Windows x86-64

omi_physics-0.3.0-cp310-cp310-win32.whl (593.0 kB view details)

Uploaded Aug 7, 2026 CPython 3.10Windows x86

omi_physics-0.3.0-cp310-cp310-musllinux_1_2_x86_64.whl (1.5 MB view details)

Uploaded Aug 7, 2026 CPython 3.10musllinux: musl 1.2+ x86-64

omi_physics-0.3.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

Uploaded Aug 7, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

omi_physics-0.3.0-cp310-cp310-macosx_11_0_arm64.whl (639.8 kB view details)

Uploaded Aug 7, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file omi_physics-0.3.0.tar.gz.

File metadata

Download URL: omi_physics-0.3.0.tar.gz
Upload date: Aug 7, 2026
Size: 497.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for omi_physics-0.3.0.tar.gz
Algorithm	Hash digest
SHA256	`5f82f6563c26281f5183a1f7d4fdaafe98f15d9bd6fc8893af22133a480d5441`
MD5	`d7905cc392305d97689b602736eae4b8`
BLAKE2b-256	`2ece76e6b26dddbe5c7560273f16793cb8bdc51cee7de5dd69287484479382c8`

Algorithm	Hash digest
SHA256	`561ba15f6d710c0194ad40fb8203a08339c057a935f8b69d84b49ce359752d51`
MD5	`9a530f57ba8bd58ed4be5b5f9793604e`
BLAKE2b-256	`f9f06adcd9b0907d1e2c999e50d6a661a9d18431aa52339c5c4aa98351972fe5`

Algorithm	Hash digest
SHA256	`f7b8774658f3cdf9166c1a8de05fa7644d059152db734328cd2f4df40edeef6c`
MD5	`a7c446300eb15f02ba911d12d658aa40`
BLAKE2b-256	`1538320ad7912d54cd5c9024d63f20e1ed9c4ec5bbff016078abb169fbdf35ce`

Algorithm	Hash digest
SHA256	`b1ba94072317cf0206ac9bf10e9622aa70ff8054ad106d7c80c79a53cd56dd55`
MD5	`fc2474e86d3f4653e54a9e297af6680a`
BLAKE2b-256	`5f02505ce9505d41d934f4759f9aa79421a0371684531f95885ba96aa4e30fc7`

Algorithm	Hash digest
SHA256	`2298b7be57c2962881ca5e58b318254e6907dc5e32783e9d8a33d6577bbd8747`
MD5	`ee57a192fbd26bdd3b6fb9e093abfacc`
BLAKE2b-256	`9ba8d300f4fb85a500c57344d123c436a78a73eb7d3c84463611274536c86152`

Algorithm	Hash digest
SHA256	`5b1d124b4fb6dcdb62058c5dc6f4daccec013a5c9493c71c0ab6efbff0b3be43`
MD5	`849a49e20ab2631defb6d5135a44d687`
BLAKE2b-256	`e299dba2d9161688f18cc20121321dd02ab720549adb677c44ef0b7a102559b7`

Algorithm	Hash digest
SHA256	`9e2fa13edd1ffffbfacd992df5e08369d6461b9ef3b0c2c51c908ed31fbffee6`
MD5	`aa85195bb84ac288f55ba212d52831f8`
BLAKE2b-256	`5917201d31653dbfc20710c410ff7db6b3a7f7f78170b38b6efcb58acea40ee2`

Algorithm	Hash digest
SHA256	`27979e7ec8209e57359e5cce98d98d032e8f533a61a401173e33f01f51683b32`
MD5	`22c6a6c9440fd4a96434bfc8b5917a3c`
BLAKE2b-256	`a1267394738ec4bc1cb987ef11b346c254518c1a397c7400c06fbd1210588335`

Algorithm	Hash digest
SHA256	`738d4b51994b7f1863f721b5e5cebd26c01b0048a93dea455defbe4c01c966f1`
MD5	`2611544cb85d1db9356adb9c7b1c9ba4`
BLAKE2b-256	`4b4b9c71c724c1d503a2156790b0c3420a6b465af31360b8475a5e9db3b633bd`

Algorithm	Hash digest
SHA256	`df5e485168184233a77a6d402caf4e5d64f16017dc5fd42b214e8a9fb080bbda`
MD5	`94ea6c1faa83f6a6945960318fd16a20`
BLAKE2b-256	`ace3d904fcc940ec1c6fee624ffe2c445b636f674fd16c8114c5fc023db44572`

Algorithm	Hash digest
SHA256	`05a0b741bc41a1abec092dea85b6a44f370cc2d44bcde0ec8450316c4758e8a5`
MD5	`d2dbd5b5335fb4a993dc800b4e63d579`
BLAKE2b-256	`26e88053555f190eccf3f340853650a4c64767709bfae75629e0cd33acc12c91`

Algorithm	Hash digest
SHA256	`662e1c95802194e9d208c9f43c753ee99153641cee10706701fdddc3e75e7c2e`
MD5	`9f070487ffce8624ffbe6f1a8a44f589`
BLAKE2b-256	`2bda24b193d4fbb18e1be7aba9ccd25ef6dff7eaa732522665cae1faab706b32`

Algorithm	Hash digest
SHA256	`b3c795c4778c8fb920ec132fbd61ba77cefcc133d906c0e7bda1899028d54900`
MD5	`74a9439b97b217db6538af08299fd636`
BLAKE2b-256	`5d4ea64f2dbe4be069db7ec771634d4da8ca0eef1189bb6b37c82ee8917e0adf`

Algorithm	Hash digest
SHA256	`eb930c9ee4e48c7a201487a4a2e8c30cf3ccc4f7c8a3c7f7ecfb560b1ed25a10`
MD5	`7316b428d14730fac4b0580bbb479281`
BLAKE2b-256	`7cc21b693a19afdba6d95890b5c247ca96a484a552e7f849d8cff7276aa94831`

Algorithm	Hash digest
SHA256	`e80a046993c2cc70685567e5d56eac3487b72ac0783c1f4e0802bca4d55fd9f9`
MD5	`628fc27bae71c78288ad195e3a4bea64`
BLAKE2b-256	`69e4171d3b9d2e17b2bc62697ca902ba0834cd6dfb4d199b3932fb4baa477565`

Algorithm	Hash digest
SHA256	`f1d0556f43e474b14c2de6df48fac60f84ef680da88e01841aec2b50a15efe92`
MD5	`c18753fb0d0f9bfa430f2f4cf1dfde02`
BLAKE2b-256	`c1373fad8e9a8c9e58fd9ee232e5dc55d7ee8e6599096917482f2bedd843f430`

Algorithm	Hash digest
SHA256	`d153311fb87d929dcfb12fabda7a644fcd5eea2b518e8fe13ce6b7c315266a93`
MD5	`87427bfa7b19e02ff35d0aa5a8f853f4`
BLAKE2b-256	`51ab41c0936b15dbbc8b004f5bbb202b6f3f2cc43f2d7de9242d040047ccaea3`

Algorithm	Hash digest
SHA256	`1d442254938cd8394dc38063dc70e88fc3346944c43c9f4143121198bd352741`
MD5	`10c438f3fecdcbd5203ffb034d761fc6`
BLAKE2b-256	`998e87fe954e950837b094e2cb2a62787dc0f381c26f23c6717eac354922fcda`

Algorithm	Hash digest
SHA256	`743434fb2e56919a5e0cbd789f740578e7bbf182db4b21682482cdaa48d57d63`
MD5	`3df4f978ccc7851533b58e930975f0f0`
BLAKE2b-256	`8db2a866f0eea1f90bc013193af0072d11dd2df19b86304a4a552ece4d75d0d3`

Algorithm	Hash digest
SHA256	`d02d04cf7aa3062a2961e54109d9713b5329cb740988a035f3c0e84d426cc42d`
MD5	`276823638ccc15df910f807238110787`
BLAKE2b-256	`efde3277436f59872206210bb0af0aee006d40f674f4d4e9def054e247a711ca`

Algorithm	Hash digest
SHA256	`dd5a455f67d37f4c0077214e25f8879398f2722a54472403c474e32e33ca47ac`
MD5	`6f68ff21a6eb429785796c2813ec8299`
BLAKE2b-256	`44739b5ded442d1b83b61a81313ec7623121059dbf015ab7ae393e9fead1cb77`

omi-physics 0.3.0

omi_physics

Install

Quick start

Off-thread simulation

How it works

Working on omi_physics

Layout

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

Algorithm	Hash digest
SHA256	`be5fa9d00f1680bdb7381f571fcb9b34cf7d37e6fda5185d1c64bc0cd94e018d`
MD5	`66da8c0957ee2c957c00e6f6e14ba292`
BLAKE2b-256	`71bb3961d603429a2d3d08411fb4bd53d9d47d6b85989b8f3bcf0f668ec425c0`

Algorithm	Hash digest
SHA256	`89073cd37f69ee475164950a48cb332e1deee1b95550e89bbc075dcc3f91567c`
MD5	`7a451d83631f48965f4d61ead06d3075`
BLAKE2b-256	`9d520c04cc37cad9650e25f02c67bd63ed85f98187ccbc4cc4128afb28364259`

Algorithm	Hash digest
SHA256	`917a8d8882292220f83dcae50fafd884497f1002b72b3a8520835bb1eeb2b980`
MD5	`78612d1e2c3f1c08447bf517ed803219`
BLAKE2b-256	`9fc9fa6f8d6cf1df5d44ac59dccbce6efa94db898fdadbe611c3799ede74341f`

Algorithm	Hash digest
SHA256	`ea92ebcee08ba372e651a40fd2e322ad0903a203a00033010f2639c050edc3fa`
MD5	`f6b270d5a4acc03c0a34780dcd7b8f70`
BLAKE2b-256	`f09c58f5b47439292a534fc92b349eed8f1398e1dfba5e19a67084c5a48fdc56`

Algorithm	Hash digest
SHA256	`131cd27d82b8013281c7482757a4c911e563dffa6859a6c0c779a4aae43620e6`
MD5	`345630c8924c60dbf72b673fe6494c76`
BLAKE2b-256	`0a6fd33eb5c682932a6ed3268020ab698e0a2df872b054f1ac5bd87f5a39b5a1`