You can run scripts from the command-line when starting K-3D, using the --script option:
$ k3d --script=my_script.py
When running scripts in this fashion you will often want to exit the program once the script has completed. To do so, use the --exit option:
$ k3d --script=my_script.py --exit
It is also typical to run K-3D as a strictly command-line application in this case, so you can perform batch processing on a headless server. Because user interfaces are a type of plugin in K-3D, it’s easy to substitute the Null User Interface plugin, which will consume fewer resources, startup faster, and avoid “flashing” windows as the program quickly runs and exits:
$ k3d --script-my_script.py --ui=none --exit
You can use the --script option multiple times, to run more-than-one script in-order:
$ k3d --script=first_script.py --script=second_script.py --ui=none --exit
Use a dash (“-”) as the script name to read the script source from stdin, allowing you to dynamically-generate scripts and pipe them into K-3D:
$ script_generator | k3d --script=- --ui=none --exit
You can combine scripting with the other command-line options such as --open, which you could use to open a K-3D file before running the script. For example you might create a “template” scene for rendering, then run a script that modifies the template, renders, then exits:
$ k3d --open=template_scene.k3d --script=modify_template.py --ui=none --exit
See Command Line Options for other useful options you can use with scripting.
To run a script from K-3D user interface, choose Scripting > Play - you will be prompted for the filename of the script to be run.
K-3D provides a wide variety of scripted nodes that allow scripts to become data sources, data modifiers, and data consumers within the Visualization Pipeline. To use these nodes, you simply create an instance of the node and modify its “Script” property to implement the desired behavior. The node’s inputs and outputs can be connected with the rest of the Visualization Pipeline in the normal way, and your script will be executed whenever the node needs to refresh its outputs. See Section A.47, “Script Plugins” for a list of scripted node types.
Scripts can be loaded by K-3D at startup and integrated into the plugin system so that - from the perspective of the end user - they are indistinguishable from “normal” C++ document plugins. To do this, script authors simply embed a few lines of plugin-related metadata into their script, and place the script in a known-location where it will be loaded by K-3D at startup.
The required plugin metadata is composed of name-value pairs that follow the syntax of an XML attribute and are embedded into the script source using whichever comment syntax is appropriate to the scripting language. See ??? for a detailed description of allowed metadata. As an example, the following lines define the beginning of a script that will appear as “MyCoffeeMugMeshSource” in the Create > Scripts menu, and will be executed by a Section B.164, “MeshSourceScript” plugin when selected by the user.
#python # k3d:plugin-class="document" # k3d:plugin-type="MeshSourceScript" # k3d:plugin-name="MyCoffeeMugMeshSource" # k3d:plugin-description="Creates a polygonal mesh shaped like a coffee mug" ...
Once the metadata is in place, the script can be put in one of two locations, and it will be automatically loaded when K-3D starts:
Once loaded, the script will appear in the Create > Scripts menu as a normal item that the user can click to create.
In addition to scripted document plugins that are created by the user and become part of a document, you can create "action" scripts that simply run and exit when selected. The following complete example will appear in the Scripting > Actions menu and creates a Section B.314, “QuadricCone” when run:
#python # k3d:plugin-class="application" # k3d:plugin-type="ActionScript" # k3d:plugin-name="Create Cone" # ngui:action="" import k3d # Create a cone primitive source cone = k3d.plugin.create("QuadricCone", context.document) cone.height = 1 cone.radius = 0.5 # Create a mesh instance that will place the cone primitive into the scene mesh_instance = k3d.plugin.create("MeshInstance", context.document) # Specify OpenGL and RenderMan painters for rendering the cone primitive mesh_instance.gl_painter = k3d.node.lookup_one(context.document, "GL Default Painter") mesh_instance.ri_painter = k3d.node.lookup_one(context.document, "RenderMan Default Painter") # Connect the cone source to the mesh instance k3d.property.connect(context.document, cone.get_property("output_mesh"), mesh_instance.get_property("input_mesh")) # Ensure that the mesh instance will be visible for every render engine in the scene k3d.node.show(context.document, mesh_instance)
You can also designate plugin scripts as “auto-start” scripts that will be automatically-run in response to certain events. Currently there are several categories of event, which are described in greater detail under ???:
Here is an example of an auto-start plugin that writes to a log file when the program is run:
#python # k3d:plugin-class="application" # k3d:plugin-type="ActionScript" # k3d:plugin-name="ApplicationLog" # k3d:application-start="" from datetime import datetime log = open("k3d.usage_log", "a") if context.command == "startup": log.write("K-3D started at " + str(datetime.now()) + "\n") elif context.command == "shutdown": log.write("K-3D closed at " + str(datetime.now()) + "\n")
Similarly, here is an example that displays time spent working with a document whenever the document is closed (but only if the normal graphical user interface is in use):
#python # k3d:plugin-class="application" # k3d:plugin-type="ActionScript" # k3d:plugin-name="DisplayBillingTime" # ngui:document-start="" import k3d from datetime import datetime if context.command == "startup": start_time = datetime.now() elif context.command == "shutdown": elapsed = datetime.now() - start_time k3d.ui().message("You worked on this document for " + str(elapsed.days) + " days, " + str(elapsed.seconds) + " seconds")