pymunk.batch Module

The batch module contain functions to efficiently get and set space data in

a batch insteaf of one by one.

Note

This module is highly experimental and will likely change in future Pymunk verisons including major, minor and patch verisons!

To get data out

First create space and two bodies.

>>> import pymunk, pymunk.batch
>>> s = pymunk.Space()
>>> b1 = pymunk.Body(1, 1)
>>> b1.position = 1,2
>>> s.add(b1, pymunk.Circle(b1, 4))
>>> b2 = pymunk.Body(1,1)
>>> b2.position = 3,4
>>> s.add(b2, pymunk.Circle(b2, 4))

To get data out first create a Buffer holder object, which is used to reuse the underlying arrays between calls. Then call the batch method. Note that the fields on the body to extract need to be specified explicitly.

>>> data = pymunk.batch.Buffer()
>>> pymunk.batch.get_space_bodies(
...     s,
...     pymunk.batch.BodyFields.BODY_ID | pymunk.batch.BodyFields.POSITION,
...     data,
... )

The data is available in the Buffer object as cffi buffers. One that contains any int data, and one that contains floating point data. You can either use it directly like here, but also pass it in to 3rd parties that implements the buffer protocol like numpy arrays.

>>> list(memoryview(data.int_buf()).cast("P")) == [b1.id, b2.id]
True
>>> list(memoryview(data.float_buf()).cast("d"))
[1.0, 2.0, 3.0, 4.0]

Its also possible to get the arbiters with collision data. Note that we need to call step to run the simulation, and clear the data data buffers first so they can be reused:

>>> s.step(1)
>>> data.clear()
>>> pymunk.batch.get_space_arbiters(
...     s,
...     pymunk.batch.ArbiterFields.BODY_A_ID | pymunk.batch.ArbiterFields.BODY_B_ID,
...     data,
... )
>>> list(memoryview(data.int_buf()).cast("P")) == [b2.id, b1.id]
True
>>> list(memoryview(data.float_buf()).cast("d"))
[]

To set data

(see planet.py example)

TODO

class pymunk.batch.ArbiterFields(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Flag

Flag fields to specify arbiter properties to get.

ALL = 65535

All the fields

BODY_A_ID

pymunk.Body.id of body A. Value stored in int_buf.

BODY_B_ID

pymunk.Body.id of body B. Value stored in int_buf.

CONTACT_COUNT

Number of contacts (1 or 2)`. Value stored in int_buf.

DISTANCE_1

pymunk.ContactPoint.distance of contact 1. Value stored in float_buf.

DISTANCE_2

pymunk.ContactPoint.distance of contact 2. Value stored in float_buf.

IS_FIRST_CONTACT

pymunk.Arbiter.is_first_contact. Value (0 or 1) stored in int_buf.

NORMAL

pymunk.Arbiter.normal. X and Y stored in float_buf.

POINT_A_1

pymunk.ContactPoint.point_a of contact 1. X and Y stored in float_buf.

POINT_A_2

pymunk.ContactPoint.point_a of contact 2. X and Y stored in float_buf.

POINT_B_1

pymunk.ContactPoint.point_b of contact 1. X and Y stored in float_buf.

POINT_B_2

pymunk.ContactPoint.point_b of contact 2. X and Y stored in float_buf.

TOTAL_IMPULSE

pymunk.Arbiter.total_impulse. X and Y stored in float_buf.

TOTAL_KE

pymunk.Arbiter.total_ke. Value stored in float_buf.

class pymunk.batch.BodyFields(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Flag

Flag fields to specify body properties to get.

ALL = 65535

All the fields

ANGLE

pymunk.Body.angle. Value stored in float_buf.

ANGULAR_VELOCITY

pymunk.Body.angular_velocity. Value stored in float_buf

BODY_ID

pymunk.Body.id. Value stored in int_buf.

FORCE

pymunk.Body.force. X and Y stored in float_buf.

POSITION

pymunk.Body.position. X and Y stored in float_buf.

TORQUE

pymunk.Body.torque. Value stored in float_buf

VELOCITY

pymunk.Body.velocity. X and Y stored in float_buf.

class pymunk.batch.Buffer[source]

Bases: object

clear() None[source]

Mark the internal arrays empty (for reuse).

It is more efficient to reuse the BatchedData object and its internal arrays by calling clear, than to create a new object each step.

float_buf() pymunk._chipmunk.ffi.buffer[source]

Return a CFFI buffer object of the floating point data in the internal array.

int_buf() pymunk._chipmunk.ffi.buffer[source]

Return a CFFI buffer object of the integer data in the internal array.

set_float_buf(buffer: Any) None[source]

Set the floating point internal data to the supplied buffer.

buffer should be an array of floats, implmenting the buffer/memoryview interface like a numpy array or array.array.

(From Python 3.12 the buffer argument will be typed as collections.abc.Buffer)

set_int_buf(buffer: Any) None[source]

Set the integer internal data to the supplied buffer.

buffer should be an array of ints, implmenting the buffer/memoryview interface like a numpy array or array.array.

(From Python 3.12 the buffer argument will be typed as collections.abc.Buffer)

pymunk.batch.get_space_arbiters(space: Space, fields: ArbiterFields, buffers: Buffer) None[source]

Get data for all active arbiters in the space.

Filter out the fields you are interested in with the fields property.

The data is returned in the batched_data buffers.

pymunk.batch.get_space_bodies(space: Space, fields: BodyFields, buffers: Buffer) None[source]

Get data for all bodies in the space.

Filter out the fields you are interested in with the fields property.

The data is returned in the batched_data buffers.