vizshape

Use functions available within the vizshape module to add various 2D and 3D shapes to your scene. Each one is built with on-the-fly objects included with Vizard. When adding these models you can specify their size and other properties. Once you've added the shape, you can treat it as you would any other 3D object. However, unlike on-the-fly objects you create with basic primitives you will not be able to access or manipulate individual vertices.

Function

Description

vizshape.addBox(size=(1.0,1.0,1.0)

right=True,left=True,

top=True,bottom=True,

front=True,back=True,

splitFaces=False)

When adding a box all faces by default are created. You can change that by passing in false for one or more faces. Setting the splitFaces argument to True will split up each face of the box into a separate sub-object with the following names: top, bottom, front, back, left, right.

vizshape.addCube(size=1.0)

Creates a box object with equal sides. This function also accepts the same parameters as the vizshape.addBox command.

vizshape.addQuad(size=(1.0,1.0),

axis=-vizshape.AXIS_Z,

cullFace=False,

cornerRadius=0.0)

Creates a 2D quad shape. When cullFace is set to False the quad will be visible when viewing it's backside. If cornerRadius is greater than 0, the quad will have rounded corners with the specified radius.

vizshape.addPlane(size=(50.0,50.0),

axis=vizshape.AXIS_Y,

cullFace=True)

Adds a 2D plane to the scene. When cullFace is set to True the plane will not be visible when viewing it's backside.

vizshape.addGrid(size=(50.0,50.0),

step=1.0,

boldStep=0.0,

axis=vizshape.AXIS_Y,

lighting=False)

The step argument defines the size of squares within the grid. boldStep defines which, if any, lines in the grid will be drawn in bold.

If boldStep is None, no bold lines will be drawn.

If boldStep < step, the center and outer lines will be bold.

Otherwise boldStep must be a multiple of step and those lines will be bold.

vizshape.addSphere(radius=1.0,

slices=20,

stacks=20

axis=vizshape.AXIS_Y)

The slices and stacks arguments specify how many circles are used to build the frame of the sphere in the vertical and horizontal planes and will determine the roundness of the surface.

vizshape.addCylinder(height=1.0,

radius=0.5,

topRadius=None,

bottomRadius=None,

axis=vizshape.AXIS_Y,

slices=20,

bottom=True,top=True)

A cylinder is created by default but you can also create a frustum of a cone by passing in values for the topRadius and bottomRadius. For a more planar surface reduce the number of slices.

vizshape.addCone(radius=0.5,height=1.0)

Add a cone with the specified radius at the base and height. This calls the vizshape.addCylinder function using a topRadius of 0.

vizshape.addTorus(radius=1.0,

tubeRadius=0.2,

sides=40, slices=40

axis=vizshape.AXIS_Y)

Add a torus where radius specifies the inner empty space. The sides and slices arguments specify how many circles are use to create the frame of the object in horizontal and vertical planes and will determine the roundness of the surface.

vizshape.addPyramid(base=(1.0,1.0),

height=1.0,

axis=vizshape.AXIS_Y,

splitFaces=False)

Add a pyramid with the specified base dimensions. Setting the splitFaces argument to True will split up each face of the pyramid into a separate sub-object with the following names: bottom, front, back, left, right.

In addition to the arguments listed above, all vizshape commands accept the following optional keyword arguments:

Argument

Description

transform = None

Apply the specified matrix transform to all the vertices.

xAlign = vizshape.ALIGN_NONE

Set the alignment of the shape along the X axis. See below for more details.

yAlign = vizshape.ALIGN_NONE

Set the alignment of the shape along the Y axis. See below for more details.

zAlign = vizshape.ALIGN_NONE

Set the alignment of the shape along the Z axis. See below for more details.

lighting = True

Enable/Disable lighting on the geometry.

cullFace = True

Enable/Disable back face culling on the geometry.

flipFaces = False

If True, all the faces of the geometry will be flipped so they are facing the opposite direction.

Orientation and alignment

With shapes that have an axis argument you can change their default orientation by passing in one of the following values

Value

Description

vizshape.AXIS_X

Shape will point toward the X axis when added

vizshape.AXIS_Y

Shape will point toward the Y axis when added

vizshape.AXIS_Z

Shape will point toward the Z axis when added

The alignment of each shape along one or more of the axes can be specified using the xAlign, yAlign, and zAlign arguments. The following table shows the values available.

Value

Description

vizshape.ALIGN_NONE

No alignment will be used

vizshape.ALIGN_CENTER

Align the center of the object with the 0 position of this axis

vizshape.ALIGN_MIN

Depending on the axis specified, align the left, bottom, or back side of the object with the 0 position of this axis

vizshape.ALIGN_MAX

Depending on the axis specified, align the right, top, or front side of the object with the 0 position of this axis

Example

The following example shows how to texture individual faces of a box.

import viz
import vizshape
viz.go()

#Create box with each face split into separate sub-node
box = vizshape.addBox([1,1,1],splitFaces=True,pos=(0,1.8,4))
box.addAction(vizact.spin(0,1,0,45))

#Create textures
t1 = viz.add('image1.jpg')
t2 = viz.add('image2.jpg')

#Apply first texture to front/back face
box.texture(t1,node='front')
box.texture(t1,node='back')

#Apply second texture to left/right face
box.texture(t2,node='left')
box.texture(t2,node='right')

The following adds a grid and torus to the scene.

import viz
import vizshape
viz.go()

vizshape.addGrid(color=[0.2]*3)
viz.clearcolor(viz.GRAY)

tex = viz.add('lake3.jpg')
torus = vizshape.addTorus(texture=tex)

import vizcam
vizcam.PivotNavigate(center=[0,2,0],distance=10)

By passing in a different value for the axis argument you can change the default orientation of the torus in the example above.

#point the shape along the X axis
torus = vizshape.addTorus(texture=tex,axis=vizshape.AXIS_X)

In the following example, changing the alignment of a box is shown.

import vizshape

grid = vizshape.addGrid(color=[0.2]*3)
viz.clearcolor(viz.GRAY)

#align the right side of the box with X = 0
#bottom of the box with Y = 0
#front of the box with Z = 0
box = vizshape.addBox(xAlign=vizshape.ALIGN_MAX,yAlign=vizshape.ALIGN_MIN,zAlign=vizshape.ALIGN_MAX, color = viz.BLUE)

import vizcam
vizcam.PivotNavigate(center=[0,2,0],distance=10)

Function	Description
vizshape.addBox(size=(1.0,1.0,1.0) right=True,left=True, top=True,bottom=True, front=True,back=True, splitFaces=False)	When adding a box all faces by default are created. You can change that by passing in false for one or more faces. Setting the splitFaces argument to True will split up each face of the box into a separate sub-object with the following names: top, bottom, front, back, left, right.
vizshape.addCube(size=1.0)	Creates a box object with equal sides. This function also accepts the same parameters as the vizshape.addBox command.
vizshape.addQuad(size=(1.0,1.0), axis=-vizshape.AXIS_Z, cullFace=False, cornerRadius=0.0)	Creates a 2D quad shape. When cullFace is set to False the quad will be visible when viewing it's backside. If cornerRadius is greater than 0, the quad will have rounded corners with the specified radius.
vizshape.addPlane(size=(50.0,50.0), axis=vizshape.AXIS_Y, cullFace=True)	Adds a 2D plane to the scene. When cullFace is set to True the plane will not be visible when viewing it's backside.
vizshape.addGrid(size=(50.0,50.0), step=1.0, boldStep=0.0, axis=vizshape.AXIS_Y, lighting=False)	The step argument defines the size of squares within the grid. boldStep defines which, if any, lines in the grid will be drawn in bold. If boldStep is None, no bold lines will be drawn. If boldStep < step, the center and outer lines will be bold. Otherwise boldStep must be a multiple of step and those lines will be bold.
vizshape.addSphere(radius=1.0, slices=20, stacks=20 axis=vizshape.AXIS_Y)	The slices and stacks arguments specify how many circles are used to build the frame of the sphere in the vertical and horizontal planes and will determine the roundness of the surface.
vizshape.addCylinder(height=1.0, radius=0.5, topRadius=None, bottomRadius=None, axis=vizshape.AXIS_Y, slices=20, bottom=True,top=True)	A cylinder is created by default but you can also create a frustum of a cone by passing in values for the topRadius and bottomRadius. For a more planar surface reduce the number of slices.
vizshape.addCone(radius=0.5,height=1.0)	Add a cone with the specified radius at the base and height. This calls the vizshape.addCylinder function using a topRadius of 0.
vizshape.addTorus(radius=1.0, tubeRadius=0.2, sides=40, slices=40 axis=vizshape.AXIS_Y)	Add a torus where radius specifies the inner empty space. The sides and slices arguments specify how many circles are use to create the frame of the object in horizontal and vertical planes and will determine the roundness of the surface.
vizshape.addPyramid(base=(1.0,1.0), height=1.0, axis=vizshape.AXIS_Y, splitFaces=False)	Add a pyramid with the specified base dimensions. Setting the splitFaces argument to True will split up each face of the pyramid into a separate sub-object with the following names: bottom, front, back, left, right.