User Properties
From K-3D
Overview
Nearly every K-3D node stores its state as a collection of Properties, which are determined by the node's author when the node is created. Users can modify a node's properties using the Node Properties Panel, and interconnect properties using the Visualization Pipeline. All of these actions can also be performed by scripts. Normally, the set of properties for a node is fixed by its design, but some special nodes can make use of custom User Properties, which are added to a node by an end-user. Some examples of user properties in action include:
- Shader parameters - the RenderMan shader plugins, RenderManDisplacementShader, RenderManImagerShader, RenderManLightShader, RenderManSurfaceShader, and RenderManVolumeShader all use user properties to store the parameters for their shaders. When you load a shader into one of these nodes, it automatically creates a user property for each shader parameter.
- Script parameters - the K-3D Category:Scripting plugins treat user properties as inputs, so users can hook scripted nodes into the Visualization Pipeline.
- RenderMan Attributes and RenderMan Options - the RenderMan standard allows render engine implementations to expose custom features as "Attributes" or "Options", and K-3D provides some special user property types to control them.
Note that user properties may be added to any node, but nodes that aren't written to take advantage of user properties (most) will simply ignore them.
Scripting and User Properties
You can add user properties to a node from a script:
node.create_property("k3d::bool_t", "a", "A", "Property A")
node.create_property("k3d::color", "b", "B", "Property B")
node.create_property("k3d::double_t", "c", "C", "Property C")
node.create_property("k3d::int32_t", "d", "D", "Property D")
node.create_property("k3d::matrix4", "e", "E", "Property E")
node.create_property("k3d::string_t", "f", "F", "Property F")
node.create_property("k3d::point3", "g", "G", "Property G")
... the first argument to create_property is the type of value that will be stored by the property. The second argument is the property name, which is used when accessing the property from a script. The third argument is the human-readable property label, which appears in the user interface, and the fourth argument is a human-readable property description, also visible in the user interface (typically as a tooltip).
After adding user properties to a node, you can access them immediately by name:
>>> node.e = k3d.identity3() >>> print node.e 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1
