6. Commands

This chapter describes the builtin commands which are implemented in the cgkit.cmds module and which are always available. New commands can be added via the register() function (for example, by plugins), so there might actually be more commands available than are listed here.

fitCone( pos, obj): Compute a cone that has its apex at pos and that includes obj. The generated cone is the minimal cone that entirely contains the bounding box of obj (which must be a WorldObject). pos is the apex of the cone given in world coordinates. The return value is a tuple (n, w) where n is the axis direction of the cone and w is the (full) angle in radians.

convertToTriMesh( objs): Convert all specified objects into triangle meshes. obj may be an individual world object or a sequence of objects. Each object may be specified by name or by reference.

setupObjectNames( )

Return a string that can be executed to 'import' all scene names. After executing the returned string you can access all top level objects via their name.

Example:

>>> listWorld()
Root
+---Bottom (Box/BoxGeom)
+---GLPointLight (GLPointLight/-)
+---GLPointLight1 (GLPointLight/-)
+---Middle (Sphere/SphereGeom)
+---TargetCamera (TargetCamera/-)
+---Top (Box/BoxGeom)
>>> exec setupObjectNames()
>>> Bottom
<cgkit.box.Box object at 0x094765D0>
>>> TargetCamera
<cgkit.targetcamera.TargetCamera object at 0x09470BD0>
>>> Top
<cgkit.box.Box object at 0x09476690>

group( *children, **name)

Group several world objects together. All non keyword arguments somehow refer to world objects that will all be grouped together. An argument may be either a WorldObject, the name of a world object or a sequence of world objects or names. The name of the new group may be given via the name keyword argument. The return value is the newly created Group object.

Example:

>>> b1=Box()
>>> b2=Box()
>>> s1=Sphere()
>>> listWorld()
Root
+---Box (Box/BoxGeom)
+---Box1 (Box/BoxGeom)
+---Sphere (Sphere/SphereGeom)
>>> group("Box", "Box1", s1, name="MyGroup")
>>> listWorld()
Root
+---MyGroup (Group/-)
    +---Box (Box/BoxGeom)
    +---Box1 (Box/BoxGeom)
    +---Sphere (Sphere/SphereGeom)

ungroup( group)

Break up a group in its individual components. group is a group object or the name of a group object. This function does not only work with Group objects but actually with any object that has no direct geometry assigned to it.

Example:

>>> listWorld()
Root
+---MyGroup (Group/-)
    +---Box (Box/BoxGeom)
    +---Box1 (Box/BoxGeom)
    +---Sphere (Sphere/SphereGeom)
>>> ungroup("MyGroup")
>>> listWorld()
Root
+---Box (Box/BoxGeom)
+---Box1 (Box/BoxGeom)
+---Sphere (Sphere/SphereGeom)

replaceMaterial( name, newmat): Iterate over all world objects and replace each material called name with material object newmat.

link( childs, parent=None, relative=False)

Link the world objects childs to parent. Previously existing links are removed. If parent is None then the links are just removed. The argument childs may be either a single world object or a sequence of world objects. Instead of world objects you can also pass the names of the world objects.

By default, the absolute position and orientation of the children is maintained (i.e. the local transform is modified). If you set relative to True the local transform is not modified which will change the position/orientation of the children (unless the parent transform is the identity).

Note: The function modifies the name of a child object if there would be a clash with an existing object under the new parent.

drawClear( ): Clear all drawing objects.

drawMarker( pos, col=(1,1,1), size=1): Draw a marker (a point). col is the color of the marker and size its radius.

drawLine( pos1, pos2, col=(1,1,1), size=1): Draw a line from pos1 to pos2. col is the color of the line and size its width.

drawText( pos, txt, font=None, col=(1,1,1))

Draw the text txt at position pos (3D position). col is the color of the text. The text is drawn using GLUT functionality. font is a GLUT font constant as defined in the OpenGL.GLUT module. It can take one of the following values:

GLUT_BITMAP_8_BY_13
GLUT_BITMAP_9_BY_15 (default)
GLUT_BITMAP_TIMES_ROMAN_10
GLUT_BITMAP_TIMES_ROMAN_24
GLUT_BITMAP_HELVETICA_10
GLUT_BITMAP_HELVETICA_12
GLUT_BITMAP_HELVETICA_18

listWorld( )

List the contents of the world as a tree. Example:

>>> load("demo4.py")
>>> listWorld()
Root
+---GLDistantLight (GLTargetDistantLight/-)
+---GLDistantLight1 (GLTargetDistantLight/-)
+---Sphere (Sphere/SphereGeom)
|   +---Box0 (Box/BoxGeom)
|   +---Box1 (Box/BoxGeom)
|   +---Box2 (Box/BoxGeom)
|   +---Box3 (Box/BoxGeom)
|   +---Box4 (Box/BoxGeom)
|   +---Box5 (Box/BoxGeom)
|   +---Box6 (Box/BoxGeom)
|   +---Box7 (Box/BoxGeom)
|   +---Box8 (Box/BoxGeom)
|   +---Box9 (Box/BoxGeom)
+---TargetCamera (TargetCamera/-)

load( filename, **options)

Loads the given file without deleting the scene, so the contents of the file is appended to the current scene. Any additional keyword argument is considered to be an option and is passed to the importer.

To be able to load the file there must be an appropriate import class (protocol: "Import") available in the plugin manager. The class is determined by examining the file extension. If no importer is found a NoImporter exception is thrown. See chapter 13.2 for the available standard importers.

Any exception generated in the importer is passed to the caller.

save( filename, **options)

Saves the current scene. Any additional keyword argument is considered to be an option and is passed to the exporter.

To be able to save the scene there must be an appropriate export class (protocol: "Export") available in the plugin manager. The class is determined by examining the file extension. If no exporter is found a NoExporter exception is thrown.

Any exception generated in the exporter is passed to the caller.

reset( ): Reset an animation/simulation. This function sets the global time back to 0 and signals the RESET event.

worldObject( obj): If obj is a string type this function searches the world object with that name and returns it. If obj is not a string, it is returned unchanged.

worldObjects( objs): Similar to worldObject() but the argument may be a sequence of objects or strings. The return value is always a list, even if only one object was specified as input.

register( cmds,...): Register functions in the cmds module. The function takes an arbitrary number of arguments which must be callable objects. Each such function is registered in the cmds module, so that other modules can call these functions as if they were implemented directly in the cmds module.

importDefaultPlugins( paths): Import the default plugins. The plugin files/directories specified by the CGKIT_PLUGIN_PATH environment variable (if it exists) are imported. The function already outputs error messages and returns a list of plugin descriptors.

splitPaths( paths)

Split a string containing paths into the individual paths. The paths can either be separated by ":" or ";". Windows drive letters are maintained, even when ":" is used as separator.

>>> splitPaths("&:c:\\shaders:c:\\more_shaders;")
['&', 'c:\\shaders', 'c:\\more_shaders']