shape Package

A range of standard shapes of varying complexity. These all inherit from the pi3d.Shape class and create an array of Buffer objects (generally containing just one!) that hold the vertex information for drawing each of them.

Building Module

class pi3d.shape.Building.xyz(x, y=None, z=None)

Bases: object

Encapsulates a 3D point-type triple.

Constructor Can be initialised either with one of these or by with three things that can be cast to floats.

class pi3d.shape.Building.Size(x, y=None, z=None)

Bases: pi3d.shape.Building.xyz

Encapsulates a 3D size. Works together with Position to provide intelligent typing. A position plus a size is a position, whereas a position minus a position is a size.

class pi3d.shape.Building.Position(x, y=None, z=None)

Bases: pi3d.shape.Building.xyz

Encapsulates a 3D position. Works together with Size to provide intelligent typing. A position plus a size is a position, whereas a position minus a position is a size.

setvalue(p)

class pi3d.shape.Building.ObjectCuboid(name, s, p, bulk)

Bases: object

An ObjectCuboid has a size and position (of its centre) and a bulk. The size is its extent beyond the centre on the three axes, the position is the position of its centre. Note that this is different from the size of an ObjectCuboid. The bulk is an aura around it that the auras of other objects can not enter. The bulk can be zero.

Constructor

x()

Returns the x coordinate of the centre of this object

y()

Returns the x coordinate of the centre of this object

top_y()

Returns the y coordinate of the top of this object

bottom_y()

Returns the y coordinate of the top of this object

z()

Returns the x coordinate of the centre of this object

w()

Returns size of this object along the x axis – its width

h()

Returns size of this object along the y axis – its height

d()

Returns size of this object along the z axis – its depth

move(p)

Moves this object to the given position.

Overlaps(o, pos=None)

Returns true if the current ObjectCuboid overlaps the given ObjectCuboid. If the pos argument is specified then it is used as the position of the given ObjectCuboid instead of its actual position.

Clear as mud?

Without a pos argument: “does object o overlap me?” With a pos argument: “would object o overlap me if it was at position ‘pos’?”

class pi3d.shape.Building.SolidObject(name, s, p, bulk)

Bases: pi3d.shape.Building.ObjectCuboid

A solid object is one that the avatar can not walk through. It has a size, a position and a bulk. The size is its total size on the three axes, the position is the position of its centre. The bulk is the aura around it into which the avatar’s aura is not allowed to enter. A zero bulk works fine.

Each solid object can have an optional model associated with it. Each SolidObject created is added to a list of SolidObjects. All the models of all the objects in the list can be drawn with a single method call (drawall). If a solid object does not have an associated model then drawall() does not attempt to draw it. That applies to the avatar and to any objects that are part of merged shapes for example.

Constructor

objectlist = []

remove()

CollisionList(p)

Returns a list of the objects that would overlap with the current oject, if the current object was at the given position. (With the exception of the current oject of course.) This can be used for any moving object to ensure that its proposed new position is available, or maybe to determine when a missile should explode and what it should destroy.

setmodel(model, details)

Sets the associated model and the details with which to draw it. If the model is set then drawall() will draw this object. If it isn’t, it wont.

classmethod drawall()

Draw all solid objects to which models (and detailss) have been associated.

class pi3d.shape.Building.createMyCuboid(w, h, d, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.shape.Cuboid.Cuboid

A bodge because my cuboids appear to be out of position with respect to my collision system. Fortunately it does not seem to happen with planes. Probably my fault.

pi3d.shape.Building.corridor(x, z, emap, width=10, length=10, height=10, details=None, walls='ns', name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. All walls and ceiling is a cuboid, 1 unit thick. There is no floor.

Use this function when having the walls as planes is a problem, such as when their zero thinkness is visible. Otherwise corridor_planes() is more efficient.

Which walls to create are specified by the string argument “walls”. This should contain the letters n,e,s,w to draw the corresponding wall, or “o” (for open) if no ceiling is required. For example a N-S corridor section would use “ew”, and a simple corner in the SE with no roof would be “seo”

If mergeshape is None then the resulting objects are drawn with SolidObject.drawall(), if mergeshape is set then the objects are added to it and SolidObject.drawall() will not draw it.

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

class pi3d.shape.Building.Building(mapfile, xpos, zpos, emap, width=10.0, depth=10.0, height=10.0, name='building', draw_details=None, yoff=0.0, scheme=None)

Bases: object

Creates a building at the given location. Each pixel of the image is one cell of the building If the cell is white then the cell is open, if it is black then it is wall. If it is grey then it is open and has no ceiling. The building is centred at xpos, zpos (which gets renamed herin to x,y to match the image coords) Each cell is width on the x axis and depth on the z axis, and the walls are height high on the y axis.

The function returns a merged shape with the entire building in it.

baseScheme = {'#models': 1, (0, None): [['R', 0]], (1, None): [['R', 0], ['C', 0]], (0, 0, 'edge'): [['W', 0], ['CE', 0]], (1, 0, 'edge'): [['W', 0], ['CE', 0]], (1, 0): [['W', 0], ['CE', 0]]}

openSectionScheme = {'#models': 1, (0, None): [['R', 0]], (2, None): [['C', 0], ['R', 0]], (0, 0, 'edge'): [['W', 0], ['CE', 0]], (1, 0, 'edge'): [['W', 0], ['CE', 0]], (2, 0, 'edge'): [['W', 0], ['CE', 0]], (2, 2, 'edge'): [['CE', 0]], (2, 0): [['W', 0]], (1, 0): [['W', 0], ['CE', 0]], (1, 2): [['CE', 0]]}

remove_walls()

drawAll()

Draws all the models that comprise the building

set_draw_details(details)

Set the shader, textures, ntiles and reflection strength

north_wall(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

north_edge(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

south_wall(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

south_edge(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

east_wall(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

east_edge(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

west_wall(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

west_edge(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

ceiling(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None, makeroof=True, makeceiling=True)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The resulting object is added to the given mergeshape

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

roof(x, y, z, width=10, length=10, height=10, details=None, name='wall', mergeshape=None, makeroof=True, makeceiling=True)

Creates a cell consisting of optional north, south, east and west walls and an optional ceiling. The north and south walls are parallel with the x axis, with north being more positive. The east and west walls are parallel with the z axis, with east being more positive. The cell is centred at (x,y,z). The cell is “width” along the z axis, (so north and south walls are that far apart,) “length” along the x axis, and “height” high. Each wall is a plane, but the ceiling is a cuboid, 1 unit high. There is no floor.

The objects are named with the given name argument as a prefix and a globally incrementing number as the suffix.

The resulting objects are added to the given mergeshape

Canvas Module

class pi3d.shape.Canvas.Canvas(camera=None, light=None, name='', z=0.1)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. The simplest possible shape: a single triangle designed to fill the screen completely

Uses standard constructor for Shape but only one position variable is available as Keyword argument:

z

The depth that the shape will be constructed as an actual z offset distance in the vertices. As the Canvas is intended for use with 2d shaders there is no way to change its location as no matrix multiplication will happen in the vertex shader.

set_texture(tex)

repaint(t)

Cone Module

class pi3d.shape.Cone.Cone(camera=None, light=None, radius=1.0, height=2.0, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

radius

radius at bottom

height

height

sides

number of sides

Cuboid Module

class pi3d.shape.Cuboid.Cuboid(camera=None, light=None, w=1.0, h=1.0, d=1.0, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0, tw=1.0, th=1.0, td=1.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

w

width

h

height

d

depth

tw

scale width

th

scale height

td

scale depth

The scale factors are the multiple of the texture to show along that dimension. For no distortion of the image the scale factors need to be proportional to the relative dimension.

Cylinder Module

class pi3d.shape.Cylinder.Cylinder(camera=None, light=None, radius=1.0, height=2.0, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. This class uses the Shape._lathe() method to ‘wrap’ the texture around the cylinder in a similar way to the Sphere. If the texture mapping on the top and bottom need to be flat, or different from the sides, then the pi3d.Extrude class should be used

uses standard constructor for Shape extra Keyword arguments:

sides

number of edges for the end polygons

Disk Module

class pi3d.shape.Disk.Disk(camera=None, light=None, radius=1, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

radius

Radius of disk.

sides

Number of sides to polygon representing disk.

ElevationMap Module

pi3d.shape.ElevationMap.file_pathify(file_path)

class pi3d.shape.ElevationMap.ElevationMap(mapfile, camera=None, light=None, width=100.0, depth=100.0, height=10.0, divx=0, divy=0, ntiles=1.0, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0, smooth=True, cubic=False, texmap=None)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape

Arguments:

mapfile

Greyscale image path/file, string. If multiple bytes per pixel only the first one will be used for elevation. jpg files will create slight errors that will cause mis-matching of edges for tiled maps (i.e. use png for these) NB also see divx, divy below i.e. div=64x64 requires image 65x65 pixels

Keyword arguments:

width, depth, height

Of the map in world units.

divx, divy

Number of divisions into which the map will be divided. to create vertices (vertices += 1) NB if you want to create a map with 64x64 divisions there will be 65x65 vertices in each direction so the mapfile (above) needs to 65x65 pixels in order to specify elevations precisely and avoid resizing errors.

ntiles

Number of repeats for tiling the texture image.

smooth

Calculate normals with averaging rather than pointing straight up, slightly faster if false.

texmap

Image file path or PIL.Image to be used to represent each of four textures and normals using the uv_elev_map shader. The image is converted to greyscale and apportioned between darkest (first and second entries in Buffer.textures list) and lightest (seventh and eighth entries). The resulting 0.0, 1.0, 2.0 or 3.0 is added to the uv texture coordinate i.e. Buffer.array_buffer[:,6:8]

dropOn(px, pz)

determines approximately how high an object is when dropped on the map (providing it’s inside the map area)

calcHeight(px, pz, inc_normal=False, regular_map=True)

accurately return the height of the map at the point specified

Arguments:

px, pz

Location of the point in world coordinates to calculate height.

inc_normal

optionall return a tuple with height and normal vector (h, (nx,ny,nz))

regular_map

setting this to False allows the method to be used with maps constructed with irregular vertex locations - i.e. increased vertex density around areas of detail. TODO implement functionality to generate this type of map.

clashTest(px, py, pz, rad, span=None)

Works out if an object at a given location and radius will overlap with the map surface. NB it is possible for tunnel through the mesh. Returns four values:

• boolean whether there is a clash
• x, y, z components of the normal vector
• the amount of overlap at the x,z location

Arguments:

px, py, pz

Location of object to test in world coordinates.

rad

Radius of object to test.

span

size of the square around the point to select faces from - defaults to 2 x rad

pitch_roll(px, pz)

works out the pitch (rx) and roll (rz) to apply to an object on the surface of the map at this point

• returns a tuple (pitch, roll) in degrees

Arguments:

px

x location

pz

z location

EnvironmentCube Module

pi3d.shape.EnvironmentCube.loadECfiles(path, fname, suffix='jpg', nobottom=False)

Helper for loading environment cube faces. TODO nobottom will redraw the top on the bottom of cube. It really should substitute a blank (black) texture instead!

Arguments:

path

to the image files relative to the top directory.

fname

The stem of the file name without the _top, _bottom, _right etc.

Keyword arguments:

suffix

String to add after the ‘_top’,’_bottom’ has been added to the stem.

nobottom

If True then only load five parts into array the bottom will be drawn with the previous image i.e. top.

class pi3d.shape.EnvironmentCube.EnvironmentCube(camera=None, light=None, size=500.0, maptype='HALFCROSS', name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0, nobottom=False)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

size

Dimensions of the cube

maptype

HALFCROSS (default) or CROSS any other defaults to CUBE type and will require 6 (or 5 with nobottom) image files to render it

set_draw_details(shader, textures, ntiles=0.0, shiny=0.0, umult=1.0, vmult=1.0)

overrides this method in Shape to cope with nobottom option

Extrude Module

class pi3d.shape.Extrude.Extrude(camera=None, light=None, path=None, height=1.0, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape NB this shape has an array of three Buffers representing each end face and the sides of the prism. Each can be textured seperately for drawing.

uses standard constructor for Shape extra Keyword arguments:

path

Coordinates defining crossection of prism [(x0,z0),(x1,z1)..]

height

Distance between end faces in the y direction.

Helix Module

class pi3d.shape.Helix.Helix(camera=None, light=None, radius=1.0, thickness=0.2, ringrots=6, sides=12, rise=1.0, loops=2.0, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

radius

Radius of helix.

thickness

Radius of ‘bar’ being ‘bent’ to form the helical shape.

ringrots

Number of sides for the circlular secon of the ‘bar’.

sides

Number of sides for Shape._lathe() to use.

rise

Distance between ‘threads’.

loops

Number of turns that the helix makes.

Lathe Module

class pi3d.shape.Lathe.Lathe(camera=None, light=None, path=None, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. Makes a shape by rotating a path of x,y locations around the y axis NB the path should start at the top of the object to generate the correct normals also in order for edges to show correctly include a tiny bevel i.e. [..(0,2),(2,1),(1.5,0)..] has a sharp corner at 2,1 and should be entered as [..(0,2),(2,1),(2,0.999),(1.5,0)..] to get good shading

uses standard constructor for Shape extra Keyword arguments:

path

Array of coordinates rotated to form shape [(x0,y0),(x1,y1)..]

sides

Number of sides for Shape._lathe() to use.

Lines Module

class pi3d.shape.Lines.Lines(camera=None, light=None, vertices=[], material=(1.0, 1.0, 1.0), line_width=1, closed=False, name='', x=0.0, y=0.0, z=0.0, sx=1.0, sy=1.0, sz=1.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0, strip=True)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. The ends of these lines are either horizontal or vertical (switching over as the line passes 45 degrees. For thick lines it might be better to use PolygonLines.

uses standard constructor for Shape extra Keyword arguments:

vertices

array of tuples [(x0,y0,z0),(x1,y1,z1)..]

material

tuple (r,g,b)

line_width

set to 1 if absent or set to a value less than 1

closed

joins up last leg i.e. for polygons

strip

use GL_LINE_STRIP otherwise GL_LINES - needs pairs for line ends

LodSprite Module

class pi3d.shape.LodSprite.LodSprite(camera=None, light=None, w=1.0, h=1.0, name='', x=0.0, y=0.0, z=20.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0, n=1)

Bases: pi3d.Shape.Shape

3d model inherits from Shape, differs from Plane in being single sided Also has the ability to divide into more triangle (than 2) to allow some post processing in the vertex shader

Uses standard constructor for Shape. Extra Keyword arguments:

w

Width.

h

Height.

n

How many cells to divide the plane into

repaint(t)

MergeShape Module

class pi3d.shape.MergeShape.MergeShape(camera=None, light=None, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. As there is quite a time penalty for doing the matrix recalculations and changing the variables being sent to the shader, each time an object is drawn, it is MUCH faster to use a MergeShape where several objects will always remain in the same positions relative to each other. i.e. trees in a forest.

Where the objects have multiple Buffers, each needing a different texture (i.e. more complex Model objects) each must be combined into a different MergeShape

uses standard constructor for Shape

merge(bufr, x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, bufnum=0)

merge the vertices, normals etc from this Buffer with those already there the position, rotation, scale, offset are set according to the origin of the MergeShape. If bufr is not a Buffer then it will be treated as if it is a Shape and its first Buffer object will be merged. Argument additional to standard Shape:

bufr

Buffer object or Shape with a member buf[0] that is a Buffer object. OR an array or tuple where each element is an array or tuple with the required arguments i.e. [[bufr1, x1, y1, z1, rx1, ry1….], [bufr2, x2, y2…],[bufr3, x3, y3…]] this latter is a more efficient way of building a MergeShape from lots of elements. If multiple Buffers are passed in this way then the subsequent arguments (x,y,z etc) will be ignored.

x, y, z, rx, ry, rz, sx, sy, sz

Position rotation scale if merging a single Buffer

bufnum

Specify the index of Buffer to use. This allows a MergeShape to contain multiple Buffers each with potentially different shader, material, textures, draw_method and unib

add(bufr, x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, bufnum=0)

wrapper to alias merge method

cluster(bufr, elevmap, xpos, zpos, w, d, count, options, minscl, maxscl, bufnum=0, billboard=False)

generates a random cluster on an ElevationMap.

Arguments:

bufr

Buffer object to merge.

elevmap

ElevationMap object to merge onto.

xpos, zpos

x and z location of centre of cluster. These are locations RELATIVE to the origin of the MergeShape

w, d

x and z direction size of the cluster.

count

Number of objects to generate.

options

Deprecated.

minscl

The minimum scale value for random selection.

maxscl

The maximum scale value for random selection.

billboard

If True then all Buffers are set rotated 180 degrees so that they turn to face Camera location when billboard() called

radialCopy(bufr, x=0, y=0, z=0, startRadius=2.0, endRadius=2.0, startAngle=0.0, endAngle=360.0, step=12, bufnum=0)

generates a radially copied cluster, axix is in the y direction.

Arguments:

bufr

Buffer object to merge.

Keyword arguments:

x,y,z

Location of centre of cluster relative to origin of MergeShape.

startRadius

Start radius.

endRadius

End radius.

startAngle

Start angle for merging 0 is in +ve x direction.

andAngle

End angle for merging, degrees. Rotation is clockwise looking up the y axis.

step

Angle between each copy, degrees NB NOT number of steps.

billboard(cam_location)

rotates all merged shapes to face camera

cam_location

tuple of x,y,z location of camera

Model Module

class pi3d.shape.Model.Model(camera=None, light=None, file_string=None, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape loads vertex, normal, uv, index, texture and material data from obj or egg files at the moment it doesn’t fully implement the features such as animation, reflectivity etc

uses standard constructor for Shape extra Keyword arguments:

file_string

path and name of obj or egg file

clone(camera=None, light=None)

create a new Model but buf points to same array of Buffers so much quicker to create than reloading all the vertices etc

reparentTo(parent)

MultiSprite Module

class pi3d.shape.MultiSprite.MultiSprite(textures, shader, camera=None, light=None, w=1.0, h=1.0, name='', x=0.0, y=0.0, z=20.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape, this is a series of Sprites edge to edge to allow larger images than the maximum size of 1920 imposed by the Texture class

Uses standard constructor for Shape. Arguments: textures

must be a two dimensional list of lists of textures or strings (which must be the path/names of image files) The array runs left to right then down so six textures in spreadsheet notation would be

[[R1C1, R1C2], [R2C1, R2C2], [R3C1, R3C2]]

shader

shader to use

Extra keyword arguments:

w

Width.

h

Height.

Plane Module

class pi3d.shape.Plane.Plane(camera=None, light=None, w=1.0, h=1.0, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape, differs from Sprite in being two sided

uses standard constructor for Shape extra Keyword arguments:

w

width

h

height

Points Module

class pi3d.shape.Points.Points(camera=None, light=None, vertices=[], material=(1.0, 1.0, 1.0), point_size=1, name='', x=0.0, y=0.0, z=0.0, sx=1.0, sy=1.0, sz=1.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0, normals=[], tex_coords=[])

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

vertices

array of tuples [(x0,y0,z0),(x1,y1,z1)..]

material

tuple (r,g,b)

point_size

set to 1 if absent or set to a value less than 1

Polygon Module

pi3d.shape.Polygon.is_in_triangle(p, p0, p1, p2)

is p inside the triangle formed by p0, p1, p2

pi3d.shape.Polygon.is_convex(p, prior, post, return_angle=False)

checks if this corner is convex (turns right for a clockwise polygon or left for an anticlockwise polygon, arguments are two tuples for this vertex and the one before and after. Can return the angle turned

class pi3d.shape.Polygon.Polygon(camera=None, light=None, path=[], horizontal=False, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. N.B. There is no check that lines do not cross.

uses standard constructor for Shape extra Keyword arguments:

path

list of (x,y) values

horizontal

default False. If set to True then y values of path will be used as z values so the polygon is horizontal.

Sphere Module

class pi3d.shape.Sphere.Sphere(camera=None, light=None, radius=1, slices=12, sides=12, hemi=0.0, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0, invert=False)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

radius

radius of sphere

slices

number of latitude edges

hemi

if set to 0.5 it will only construct the top half of sphere

sides

number of sides for Shape._lathe() to use

invert

normals will face inwards, Texture will need flip=True

Sprite Module

class pi3d.shape.Sprite.Sprite(camera=None, light=None, w=1.0, h=1.0, name='', x=0.0, y=0.0, z=20.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0, flip=False)

Bases: pi3d.Shape.Shape

3d model inherits from Shape, differs from Plane in being single sided

Uses standard constructor for Shape. Extra Keyword arguments:

w

Width.

h

Height.

flip

If set to True then the Sprite is flipped vertically (top to bottom)

repaint(t)

class pi3d.shape.Sprite.ImageSprite(texture, shader, **kwds)

Bases: pi3d.shape.Sprite.Sprite

A 2D sprite containing a texture and shader. The constructor also calls set_2d_size so that ImageSprite objects can be used directly to draw on a Canvas shape (if shader=2d_flat). Additional arguments:

texture

either a Texture object or, if not a Texture, will attempt to load a file using texture as a path and name to an image.

shader

a Shader object

class pi3d.shape.Sprite.ButtonSprite(camera=None, light=None, w=1.0, h=1.0, corner=0.1, name='', texture=None, shader=None, x=0.0, y=0.0, z=20.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

Stretches the middle part of an image to allow increased detail around edges and in corners

Uses standard constructor for Shape. Extra Keyword arguments:

w

Width.

h

Height.

corner

The size that the edge thirds will be. Used for mapping textures to plane

repaint(t)

TCone Module

class pi3d.shape.TCone.TCone(camera=None, light=None, radiusBot=1.2, radiusTop=0.8, height=2.0, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape, creates truncated cone axis y direction

uses standard constructor for Shape extra Keyword arguments:

radiusBot

Radius of the bottom.

radiusTop

Radius at the top.

height

Height.

sides

Number of sides to divide edges of polygons.

Tetrahedron Module

class pi3d.shape.Tetrahedron.Tetrahedron(camera=None, light=None, name='', corners=((-1.0, -0.57735, -0.57735), (1.0, -0.57735, -0.57735), (0.0, -0.57735, 1.1547), (0.0, 1.1547, 0.0)), x=0.0, y=0.0, z=0.0, sx=1.0, sy=1.0, sz=1.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. The simplest 3D shape

Uses standard constructor for Shape with ability to position corners. The uv mapping is taken from four equilateral triangles arranged on a square forming an upwards pointing arrow ^. Starting at the left bottom corner of the image the first three triangles are unwrapped from around the top of the tetrahedron and the right bottom triangle is the base (if the corners are arranged as per the default) Keyword argument:

corners

A tuple of four (xyz) tuples defining the corners

Torus Module

class pi3d.shape.Torus.Torus(camera=None, light=None, radius=2.0, thickness=0.5, ringrots=6, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

radius

Major radius of torus

thickness

Minor radius, section through one side of torus

ringrots

Sides around minor radius circle

sides

Number of sides for Shape._lathe() to use

Triangle Module

class pi3d.shape.Triangle.Triangle(camera=None, light=None, name='', corners=((-0.5, -0.28868), (0.0, 0.57735), (0.5, -0.28868)), x=0.0, y=0.0, z=0.0, sx=1.0, sy=1.0, sz=1.0, rx=0.0, ry=0.0, rz=0.0, cx=0.0, cy=0.0, cz=0.0)

Bases: pi3d.Shape.Shape

3d model inherits from Shape. The simplest possible shape: a single triangle

Uses standard constructor for Shape with ability to position corners. The corners must be arranged clockwise (for the Triangle to face -z direction)

Keyword argument:

corners

A tuple of three (xy) tuples defining the corners

Tube Module

class pi3d.shape.Tube.Tube(camera=None, light=None, radius=1.0, thickness=0.5, height=2.0, sides=12, name='', x=0.0, y=0.0, z=0.0, rx=0.0, ry=0.0, rz=0.0, sx=1.0, sy=1.0, sz=1.0, cx=0.0, cy=0.0, cz=0.0, use_lathe=True)

Bases: pi3d.Shape.Shape

3d model inherits from Shape

uses standard constructor for Shape extra Keyword arguments:

radius

Radius of to mid point of wall.

thickness

of wall of tube.

height

Length of tube.

sides

Number of sides for Shape._lathe() to use.

use_lathe

Default to using Shape._lathe() for backwards compatibility but actually better to set this false, especially for washer like tubes.