H3DAPI with Python
Adding Python scripts to the scene graph
Python scripts can added to the scene graph using the PythonScript node.
<Scene> <PythonScript url="script1.py" /> <PythonScript url="script2.py" </Scene>
The code above adds two Python scripts defined in script1.py and script2.py to the scene graph. The scripts are run at least once on scene graph initialization.
Node references may be passed to a Python script by specifying the nodes as field values to references.
<Scene> <Shape DEF="S"> <Appearance> <Material DEF="M" /> </Appearance> <Sphere radius="0.1" /> </Shape> <PythonScript url="script.py"> <Shape USE="S" containerField="references" /> <Material USE="M" containerField="references" /> </PythonScript> </Scene>
References to Shape and Sphere nodes above are passed to the script by specifying them as values to the references field of PythonScript. This is done with containerField="references". containerField defines the field of the parent node to which the current node is assigned.
references is hence an MFNode field. The value of references can be obtained by calling the getValue field method in the script:
# script.py shape, mat = references.getValue()
The variables shape and mat now contains the references to the Shape and Material.
Obtaining and modifying field values
Having a field reference, we may use the getValue and setValue field methods to get and modify the field value. In the example above we have already used the getValue method to obtain the references to passed to the script.
mat.diffuseColor.setValue( RGB(1, 0, 0) )
Using the mat from the previous example, we access Material node's diffuseColor and change its value to red by calling the setValue method.
Creating and adding nodes to the scene graph
Users may create X3D nodes in Python with any of the following functions:
- createX3DFromURL( url )
- createX3DFromString( string )
- createX3DNodeFromURL( url )
- createX3DNodeFromString( string )
Each of the function returns a list of length two, the first element containing a node reference and the second a dictionary of DEF-ed nodes in the url/string. Functions beginning with "createX3DNode returns the reference of the topmost node in the url/string as the first list element, while the other two returns a Group node reference enclosing all the nodes in the url/string.
s, d = createX3DNodeFromString(" \ <Shape> \ <Appearance> \ <Material /> \ <SmoothSurface DEF=\"SURFACE\" /> \ </Appearance> \ <Box DEF=\"BOX\" size=\"0.1 0.2 0.1\" /> \ </Shape>")
s contains a reference to Shape and d is a dictionary containing the Surface and Box, with the DEF value as keys i.e. d["SURFACE"] and d["BOX"] refer to Surface and Box respectively.
Nodes may be added to the scene graph by setting them as values to already existing nodes in scene. For example, if we already have a grouping node in the scene that we have a reference to from the script, we may add the newly created Shape node above to the scene as a child of this grouping node. Suppose the reference to the grouping node is stored variable g_node:
g_node.addChildren.setValue( [s] )
The code above sets the Shape node s as a new child to g_node by calling setValue to g_node's addChildren field.
Routing and unrouting
If we have field references in a Python script, we may do routing and unrouting in Python as well using the route method.
field_1.route( field_2 ) field_1.unroute( field_2 )