peng3d.model - Model and Animation system

peng3d.model.grouper(iterable, n, fillvalue=None)

Allows for iteration over multiple elements of a iterable at once.

iterable may be any iterable, its values will be returned. Note that this may be iterated over more than once.

n is the size of each group. May be any positive integer.

fillvalue is optionally used to fill any groups that do not have enough items, for example if the length of the iterable is not divisible by n.

Example:

>>> for i in grouper("foobarbaz",2,fillvalue=" "):
...     print(i)
fo
ob
ar
ba
z  # Note the extra space after the z

peng3d.model.calcSphereCoordinates(pos, radius, rot)

Calculates the Cartesian coordinates from spherical coordinates.

pos is a simple offset to offset the result with.

radius is the radius of the input.

rot is a 2-tuple of (azimuth,polar) angles.

Angles are given in degrees. Most directions in this game use the same convention.

The azimuth ranges from 0 to 360 degrees with 0 degrees pointing directly to the x-axis.

The polar angle ranges from -90 to 90 with -90 degrees pointing straight down and 90 degrees straight up.

A visualization of the angles required is given in the source code of this function.

peng3d.model.v_magnitude(v)

Simple vector helper function returning the length of a vector.

v may be any vector, with any number of dimensions

peng3d.model.v_normalize(v)

Normalizes the given vector.

The vector given may have any number of dimensions.

class peng3d.model.Material(rsrcMgr, name, matdata)

Object that describes a single material of a model.

This object stores all relevant data and caches. Note that this object is only created once for each model and shared between all rendered instances of it.

See Model for more information about the model system.

id

Read-only property storing the numerical ID of the texture of this material.

Used to manipulate the texture behind this material.

Commonly used in binding the texture: glBindTexture(material.target,material.id).

target

Read-only property storing the OpenGL constant representing the target of the texture of this material.

Commonly GL_TEXTURE_2D or GL_TEXTURE_3D.

Used in texture manipulation and activation, e.g. glEnable(material.target).

tex_coords

Read-only property storing the texture coordinates to use when drawing with this texture.

Should not be used directly, see transformTexCoords().

Enables substitution of pyglet pyglet.graphics.Texture objects with Materials in many places, e.g. in pyglet.graphics.TextureGroup.

texdata

Read-only property equivalent to a 3-tuple containing target, id and tex_coords.

Should be faster than getting each value directly. Useful if all of these values are needed.

transformTexCoords(data, texcoords, dims=2)

Transforms the given texture coordinates using the internal texture coordinates.

Currently, the dimensionality of the input texture coordinates must always be 2 and the output is 3-dimensional with the last coordinate always being zero.

The given texture coordinates are fitted to the internal texture coordinates. Note that values higher than 1 or lower than 0 may result in unexpected visual glitches.

The length of the given texture coordinates should be divisible by the dimensionality.

class peng3d.model.Bone(rsrcMgr, name, bonedata)

Object that represents a single bone of a model.

This object stores all relevant data and caches. Note that this object is only created once for each model and shared between all rendered instances of it.

Actual bone rotation and length is stored per entity and not per model allowing for different bone rotations for multiple entities using the same model.

See Model for more information about the model system.

addRegion(region)

Register a vertex Region as a dependent of this bone.

region must be an instance of Region.

ensureBones(data)

Helper method ensuring per-entity bone data has been properly initialized.

Should be called at the start of every method accessing per-entity data.

data is the entity to check in dictionary form.

getLength(data)

Returns the length of this bone in the given entity.

data is the entity to query in dictionary form.

getPivotPoint(data)

Returns the point this bone pivots around on the given entity.

This method works recursively by calling its parent and then adding its own offset.

The resulting coordinate is relative to the entity, not the world.

getRot(data)

Returns the rotation of this bone in the given entity.

data is the entity to query in dictionary form.

setLength(data, blength)

Sets the length of this bone on the given entity.

data is the entity to modify in dictionary form.

blength is the new length of the bone.

setParent(parent)

Sets the parent of this bone for all entities.

Note that this method must be called before many other methods to ensure internal state has been initialized.

This method also registers this bone as a child of its parent.

setRot(data, rot)

Sets the rotation of this bone on the given entity.

data is the entity to modify in dictionary form.

rot is the rotation of the bone in the format used in calcSphereCoordinates().

setRotate(data)

Sets the OpenGL state required for proper drawing of the model.

Mostly rotates and translates the camera.

It is important to call unsetRotate() after calling this method to properly unset state and avoid OpenGL errors.

transformVertices(data, vertices, dims=3)

Currently unused method that transforms the given vertices according to the rotation of the bone.

Currently just returns the vertices unmodified, will be implemented in the future.

unsetRotate(data)

Unsets the OpenGL state that was set before calling setRotate().

Note that this method may cause various OpenGL errors if called without setRotate() having been called.

class peng3d.model.RootBone(rsrcMgr, name, bonedata)

Special bone that represents the root of a entity.

This bone is immutable and cannot be rotated or otherwise modified.

getLength(data)

Returns the length of this bone in the given entity.

data is the entity to query in dictionary form.

getPivotPoint(data)

Returns the point this bone pivots around on the given entity.

This method works recursively by calling its parent and then adding its own offset.

The resulting coordinate is relative to the entity, not the world.

setRotate(data)

Sets the OpenGL state required for proper drawing of the model.

Mostly rotates and translates the camera.

It is important to call unsetRotate() after calling this method to properly unset state and avoid OpenGL errors.

unsetRotate(data)

Unsets the OpenGL state that was set before calling setRotate().

Note that this method may cause various OpenGL errors if called without setRotate() having been called.

class peng3d.model.Region(rsrcMgr, name, regdata)

Object that represents a vertex region of a model.

A vertex region is associated with a specific bone of the same model it is associated with. It has a list of vertices and optionally texture coordinates. The texture coordinates are transformed using the material it is associated with.

Most regions will use quads as their primitive type, but it is also possible to use triangles, lines and points.

To use quads as the geometry type, specify either quads, quad or GL_QUADS as its geometry_type.

To use triangles as the geometry type, specify either tris, triangles, triangle or GL_TRIANGLES as its geometry_type.

To use lines as the geometry type, specify either lines, line or GL_LINES as its geometry_type.

To use points as the geometry type, specify either points, point, dots, dot or GL_POINTS as its geometry_type.

Note that the number of vertices must be divisible by the number of vertices required per primitive, e.g. 4 for quads, 3 for triangles, 2 for lines and 1 for points.

Additionally, the number of vertices and texture coordinate pairs must also match.

If any of these conditions are not fulfilled, a ValueError will be raised.

getGeometryType(data)

Returns the OpenGL constant representing the type of primitives used by this region.

May be one of GL_QUADS, GL_TRIANGLES, GL_LINES or GL_POINTS.

getTexCoords(data)

Returns the texture coordinates, if any, to accompany the vertices of this region already transformed.

Note that it is recommended to check the enable_tex flag first.

Internally uses Material.transformTexCoords().

getTexInfo(data)

Returns informations about the texture of this region.

Internally uses Material.texdata, exact specification available there.

getVertices(data)

Returns the vertices of this region already transformed and ready-to-use.

Internally uses Bone.transformVertices().

class peng3d.model.Animation(rsrcMgr, name, anidata)

Object that represents an animation of a model.

Animations can be either static or animated using keyframes.

See Model for more information.

setBones(bones)

Sets the internal dictionary of bones in the parent model.

Must be a dictionary, else errors may appear later on.

startAnimation(data, jumptype)

Callback that is called to initialize this animation on a specific actor.

Internally sets the _anidata key of the given dict data.

jumptype is either jump or animate to define how to switch to this animation.

tickEntity(data)

Callback that should be called regularly to update the animation.

It is recommended to call this method about 60 times a second for smooth animations. Irregular calling of this method will be automatically adjusted.

This method sets all the bones in the given actor to the next state of the animation.

Note that startAnimation() must have been called before calling this method.

class peng3d.model.JSONModelGroup(model, data, obj, parent=None)

Pyglet group that sets the state required by a specific actor.

This group should always be set during any draw operations for the assigned actor. This can either be done by setting it as the group of a vertex list, the parent group of a group of a vertex list or manually calling set_state() and unset_state().

set_state()

Sets the state required for this actor.

Currently translates the matrix to the position of the actor.

unset_state()

Resets the state required for this actor to the default state.

Currently resets the matrix to its previous translation.

class peng3d.model.JSONRegionGroup(model, data, region, parent=None)

Pyglet group that manages the state required by a specific vertex region of an actor.

This group and the associated JSONModelGroup should always be set during any draw operation for the assigned region.

See JSONModelGroup for more information about how to do this.

set_state()

Sets the state required for this vertex region.

Currently binds and enables the texture of the material of the region.

unset_state()

Resets the state required for this actor to the default state.

Currently only disables the target of the texture of the material, it may still be bound.

class peng3d.model.Model(peng, rsrcMgr, name)

Object that represents the model of an actor.

Note that this object is not bound to an actor but rather to a collection of materials, bones, vertex regions and animations.

A single instance of this class may be used by multiple actors at the same time. See Actor.setModel() for more information.

A test model is available at assets/peng3d/model/test.json and a demo program using it under test_model.py.

Todo

Document the format of .json model files.

cleanup(obj)

Cleans up any left over data structures, including vertex lists that reside in GPU memory.

Behaviour is undefined if it is attempted to use this model with the same object without calling create() first.

It is very important to call this method manually during deletion as this will delete references to data objects stored in global variables of third-party modules.

create(obj, cache=False)

Initializes per-actor data on the given object for this model.

If cache is set to True, the entity will not be redrawn after initialization.

Note that this method may set several attributes on the given object, most of them starting with underscores.

During initialization of vertex regions, several vertex lists will be created. If the given object has an attribute called batch3d it will be used, else it will be created.

If the batch already existed, the draw() method will do nothing, else it will draw the batch.

Memory leaks may occur if this is called more than once on the same object without calling cleanup() first.

draw(obj)

Actually draws the model of the given object to the render target.

Note that if the batch used for this object already existed, drawing will be skipped as the batch should be drawn by the owner of it.

ensureModelData(obj)

Ensures that the given obj has been initialized to be used with this model.

If the object is found to not be initialized, it will be initialized.

redraw(obj)

Redraws the model of the given object.

Note that currently this method probably won’t change any data since all movement and animation is done through pyglet groups.

remove(obj)

Called if the actor is removed from the world.

Can be extended for custom features, currently calls cleanup().

setAnimation(obj, animation, transition=None, force=False)

Sets the animation to be used by the object.

See Actor.setAnimation() for more information.