| On this page |
Overview ¶
Various asData() methods on HOM objects generate or accept JSON-like data in the same format used by recipes. These data structures contain only types that map to JSON (floats, ints, booleans, None/null, dicts/objects, and lists/arrays). This page uses Python type names (for example, list instead of JSON’s array).
For more information, see Saving and using recipes.
Tip
To display recipe data nicely in the Python shell, you can use the indent argument to json.dumps() or the pprint function.
>>> from json import dumps >>> print(dumps(data, indent=4)) ... >>> from recipeutils import pprint >>> pprint(data)
json.dumps() puts dictionary values on separate lines, so it can use more vertical space. pprint tries to merge values onto the same line and matches the indentation of previous lines, so it can use more horizontal space.
Parm Value ¶
This stores the value of a parameter. A parameter can have one or more components, and each component can be a literal value (float, int, or string), Expression, or Keyframes Data. Parameters with a single component return one of these three types, while parameters with multiple components return a list that can contain any of these data types.
[ 1.0, { "expression": "sin($T)" }, { "keyframes": [ { "frame": 1, "value": 0.0, "slope": 0.0, "accel": 0.0, "inaccel": 0.33, "expression": "bezier()" }, { "frame": 48, "value": 1.0, "slope": 0.0, "accel": 0.0, "inaccel": 0.65, "expression": "bezier()" } ] } ]
See:
Expression ¶
This represents a parameter component when it contains an expression. It can have the following keys:
expression: str
The string representation of the expression.
language: str
The language of the expression.
An example of expression data:
{ "expression": "$F", "language": "Hscript" },
Keyframes ¶
This represents a parameter component when it contains keyframes.
keyframes: list[Keyframe Data]
A list of Keyframe Data.
frame: float
The keyframe’s frame number.
time: float
The keyframe’s time in seconds.
epxression: str
The keyframe’s expression.
value: float
The value leaving the keyframe.
invalue: float
The value entering the keyframe.
slope: float
The slope leaving the keyframe.
inslope: float
The slope entering the keyframe.
accel: float
The acceleration leaving the keyframe.
inaccel: float
The acceleration entering the keyframe.
accelasratio: bool
Whenever acceleration should be interpreted as ratio.
extrapolation_before: str
Returns extrapolation before the first keyframe which defines how a parm value is evaluated outside the keyframe range.
extrapolation_after: str
Returns extrapolation after the last keyframe which defines how a parm value is evaluated outside the keyframe range.
An example of keyframes data for a float parameter with two keyframes data:
{ "keyframes": [ { "frame": 1, "value": 1.0, "slope": 0.0, "accel": 0.0, "inaccel": 0.33, "expression": "bezier()" }, { "frame": 24, "value": 2.0, "slope": 0.0, "accel": 0.0, "inaccel": 0.33, "expression": "bezier()" } ] }
Parm ¶
While a parameter is most commonly associated with its value, the value is not the only property a parameter can hold. A parameter can have the following keys:
value: Parm Value Data
The value of each component of the parameter.
lock: bool | list[bool]
The locked state of each component of the parameter.
visible: bool
Whenever the parameter is visible in the parameter pane.
points: list[Ramp Point Data]
Ramp type parameters store a list of ramp point data under this key. The length of the list controls the number of points on the ramp.
A Ramp Point Data contains the following items:
pos: float
The point position on the ramp.
value: float | Sequence[float]
A single float for a Float Ramp or a tuple of three floats for a Color Ramp.
interp: str
The interpolation of the ramp point.
An example of the points key storing a Color Ramp set to Black To Orange:
[ { "pos": 0.0, "value": [ 0.0, 0.0, 0.0 ], "interp": "linear" }, { "pos": 1.0, "value": [ 1.0, 0.324, 0.1 ], "interp": "linear" } ]
See:
dictionary: dict[str, str]
A Key-Value Dictionary type parameter stores its dictionary under this key.
geometry: str
A Geometry Data type parameter stores its geometry under this key.
multiparms: list[Parameters]
An example of the multiparms key storing two sets of multi-parameter instances.
[ { "export_enable#": True, "export_fieldname#": "density", "export_visible#": "smoke" }, { "export_enable#": True, "export_fieldname#": "temperature", "export_visible#": "invisible" }, ]
See:
multiparmlinks: dict[str, str]
Stores the data for multiparm reference links.
metadata: Parm Meta Data
Stores additional information about the parameter.
type: str
The type of the parameter (for example, float or ramp_rgb).
label: str
The label of the parameter.
spare: bool
Stores whether the parameter is a spare (user-defined) parameter.
path: str
The full path to this parameter.
An example of the metadata key:
{ "type": "toggle", "label": "Enable Blending", "spare": False, "path": "/obj/geo1/attribblur1/enableblending" }
See:
Parameters ¶
This maps parameter names to Parm data.
The following is an example for a set of parameters:
{ "group": { "value": "group1" }, "attributes": { "value": "P" }, "method": { "value": "uniform" }, "iterations": { "value": 1 }, "mode": { "value": "laplacian" }, "frequency": { "value": 0.1 }, "stepsize": { "value": 0.5 } "blurramp": { "points": [ { "pos": 0.0, "value": 0.0, "interp": "monotonecubic" }, { "pos": 0.5, "value": 1.0, "interp": "monotonecubic" }, { "pos": 1.0, "value": 0.0, "interp": "monotonecubic" } ] } }
All .asData() functions have a brief (or parms_as_brief) option, which omits defaults and some single-key dicts for a more compact output. When you pass brief=True, where parm data would only have a single value, points, or multiparms key, the dict is replaced by just the value. For example:
{ "group": "group1", "attributes": "P", "method": "uniform", "iterations": 1, "mode": "laplacian", "frequency": 0.1, "stepsize": 0.5, "blurramp": [ { "pos": 0.0, "value": 0.0, "interp": "monotonecubic" }, { "pos": 0.5, "value": 1.0, "interp": "monotonecubic" }, { "pos": 1.0, "value": 0.0, "interp": "monotonecubic" } ] }
When a Parm Data would hold other keys (for example, lock alongside value key), the parm data is a full dict. For example:
{ "group": "group1", "attributes": "P", "method": "uniform", "iterations": { "value": 1, "locked": True }, "mode": "laplacian", "frequency": 0.1, "stepsize": 0.5, "blurramp": [ { "pos": 0.0, "value": 0.0, "interp": "monotonecubic" }, { "pos": 0.5, "value": 1.0, "interp": "monotonecubic" }, { "pos": 1.0, "value": 0.0, "interp": "monotonecubic" } ] }
See:
Parm Template ¶
This is data for a template to describe a parameter in the parameter pane.
type: str
The type of the parameter, based on hou.parmTemplateInterfaceType.
label: str
The label that’s displayed in the parameter pane.
num_components: int
The number of components for this parameter.
help: str
The help that Houdini displays when you hover over the parameter label in the parameter pane.
joins_with_next: bool
Whether this parameter is displayed on the same line as the next parameter in the parameter pane.
disable_when: str
The condition to turn off the parameter in the parameter pane.
hide_when: str
The condition to hide the parameter in the parameter pane.
no_cook_when: str
The no cook condition.
tab_disable_when: str
The condition to turn off the tab folder in the parameter pane.
tab_hide_when: str
The condition to hide the tab folder in the parameter pane.
script_callback: str
The script that Houdini runs when this parameter changes.
script_callback_language: str
The language of the script that Houdini runs when this parameter changes.
default_value: Parm Value Data
The default value for new parameter instances.
default_points: list[Ramp Point Data]
The default ramp points for new parameter instances.
min_value: float
The minimum value of the parameter.
max_value: float
The maximum value of the parameter.
strict_min: bool
Whether the maximum value is strictly enforced.
strict_max: bool
Whether the minimum value is strictly enforced.
icon_names: str
The icons corresponding to the menu items.
item_generator_script: str
The script used to generate menu items, or an empty string if there’s no script.
item_generator_script_language: str
The script language used to generate menu items.
column_labels: list[str]
The labels for each column of a label parameter template.
show_controls: bool
Whether this ramp parameter has the controls expanded by default.
color_type: str
The color space in which to interpolate color ramp keys.
folder_names: str
The names of the folders in this set.
tab_group_end: bool
Whether this folder is the last in the folder set.
tab_conditionals: str
The conditionals that affect the folder tab generated by this parameter template.
parmtemplates: Parm Template Data Dict
The nested dictionary of parmtemplates if this is a folder or multi-parm parmtemplate.
The following is an example of data for a parameter template:
{ "type": "integer", "label": "Start Frame", "tags": { "script_callback_language": "python" }, "menu_type": "normal", "default_value": 1, "min_value": 1, "max_value": 240, "strict_min": True }
Parm Templates ¶
This maps template names to Parm Template Data.
An example of a toggle and float parameter template:
{ "enablestartframe": { "type": "toggle", "label": "Enable Start Frame", "label_hidden": True, "joins_with_next": True, "tags": { "script_callback_language": "python" } }, "startframe": { "type": "integer", "label": "Start Frame", "disable_when": "{ enablestartframe != 1 }", "tags": { "script_callback_language": "python" }, "menu_type": "normal", "default_value": 1, "min_value": 1, "max_value": 240, "strict_min": True } }
Parm Template Block ¶
This dictionary indicates after which existing template to insert the contained templates.
When spare parameters are added to a node, this data helps to store only the continuous blocks of spare parameter templates.
insert_after: str
The name of the parameter template that’s placed before the block of parameter templates.
insert_first: str
The name of the folder parmtemplate when the block is the first in the folder.
parmtemplates: Parm Templates
The dictionary of continuous parmtemplates contained by this block.
Network Item ¶
This dictionary stores data for a network item such as nodes, sticky notes, network box, network dot, and subnetwork indirect inputs.
It can have the following keys:
Note
It’s possible to have both inputs and outputs keys, but if you're generating recipe data you should use only one. This means you consistently specify wires either as outputs on upstream items or inputs on downstream items. When Houdini creates recipes it only creates inputs keys on downstream items.
type: str
The type of the network item. For nodes this is the node type name (for example, box for a SOP Box node). For a sticky note, network box, or network dot this must be StickyNote, NetworkBox, or NetworkDot respectively.
inputs: list[Input Data]
This stores a list of Network Item Input Data that represent a connection that links the inputs of this node with the output of other nodes upstream.
Each Input Data has the following keys:
from: str
The name of the node to which this node’s input (given by to_index) connects.
from_index: int | str
The output index of the node (given by from) that connects to the input index (given by to_index) of this node. The index can also be a named output, which is used in the Vop context.
to_index: int | str
The input index of this node connects to the output index (given by from_index) of the node given by from. The index can also be a named input, which is used in the Vop context.
The following is an example of the inputs key:
{ "from": "box1", "from_index": 0, "to_index": 0 }
See:
outputs: list[Network Item Output Data]
This stores a list of Network Item Output Data that represent a connection that links the outputs of this node with the input of other nodes downstream.
A Network Item Output Data always has the following keys:
from_index: int | str
The output index of this node connects to the input index (given by to_index) of the node given by to. The index can also be a named output, which is used in the Vop context.
to_index: int | str
The input index of the node (given by to) that connects to the output index (given by from_index) of this node. The index can also be a named input, which is used in the Vop context.
to: str
The name of the node to which this node’s output (given by from_index) connects.
An example of a Network Item Output Data that connects downstream to a node named box1:
{ "from_index": 0, "to_index": 0, "to": "box1" }
See:
color: list[float]
The color of the item’s tile in the network editor.
size: list[float]
The size of the item’s tile in the network editor.
position: list[float]
The position of the item’s tile in the network editor.
user_data: dict[str, Any]
The user-defined dictionary data for this node.
parms: Parameters
A dictionary of Parm Data that contains data for the parameters of this node.
parmtemplates: Union[Parm Templates, Parm Template Block
Data, list[Parm Template Block Data]
This stores the parmtemplate data for this node.
flags: dict[str, bool]
This stores flags of this node.
children: Network Items
This stores a nested dictionary of child items (if any) for this node.
Note
When capturing the data, opened Digital Assets capture their content under the children key and closed Digital Assets are considered to have no children.
When setting a Network Item Data that contains a children key to a closed Digital Asset, the Digital Asset is opened and its content is replaced by the data in the children key.
See:
editables: Network Items
This stores a nested dictionary of editable dive-target items (if any) for this node.
See:
pinned: bool
The pinned state for a network dot item.
box_content: list[str]
This stores a list of network item names inside the network box.
text: str
The text displayed on a sticky note.
text_color: list[float]
The color of the text displayed on a sticky note.
text_size: float
The size of the text displayed on a sticky note.
draw_background: bool
The drawing of a colored background for a sticky note.
minimized: bool
The minimized state of a sticky note.
metadata: Network Item Metadata
This stores additional information for the network item.
The Network Item Metadata can have the following items:
category: str
The category type of this item (for example, Sop or Dop).
path: str
The full path to this item.
parent: bool
The full path to the parent of this item.
The following is an example of a network item’s metadata key:
{ "category": "Sop", "path": "/obj/geo1/box1", "parent": "/obj/geo1" }
The following is an example of data for a network item:
{ "type": "box", "parms": { "divrate": [2, 2, 2], } "inputs": { "from": "bound1", "from_index": 0, "to_index": 0 }, "position": [0, 2.63], "color": [0.58, 0.21, 0.47], "flags": { "colordefault": False }, }
See:
Network Items ¶
Data for multiple network items is collected under this dictionary, which stores the Network Item Data. The item’s name is the key.
The position values for each Network Item Data are captured as a global network space position by default. When capturing the data, you can provide the anchor_position (hou.Vector2) option to calculate all positions relative to that position.
{ "box1": { "type": "box", "position": [-0.5, 2.85], "parms": { "type": "polymesh", "divrate": [2, 2, 2] } }, "__dot1": { "type": "NetworkDot", "inputs": [ { "from": "box1", "from_index": 0, "to_index": 0 } ], "position": [0, 2], "color": [0.7, 0.7, 0.7] }, "OUT": { "type": "null", "inputs": [ { "from": "__dot1", "from_index": 0, "to_index": 0 } ], "position": [-0.5, 0.85], "flags": { "display": True, "render": True } } }
See:
Cluster ¶
This data type is a higher-level abstraction over the Network Item Data Dict to store more information along with the set of network items. It can contain the following items:
children: Network Items
This stores data for all the network items this cluster holds.
The following example shows the Cluster Data captured for the three selected nodes:
{ "tags": { "target_tag": "transform1", "frame_tags": ["OUT", ], "selected_tags": ["box1", "OUT"] "current_tag": ["OUT"] } "children": { "transform1": { "type": "xform", "inputs": [ { "from": "box1", "from_index": 0, "to_index": 0 } ], "position": [0, 0], }, "box1": { "type": "box", "position": [0, 1], "parms": { "type": "polymesh", "divrate": [2, 2, 2] } }, "OUT": { "type": "null", "inputs": [ { "from": "transform1", "from_index": 0, "to_index": 0 } ], "position": [0, -1], "flags": { "display": True, "render": True } } }, }
When the transform2 node is the target node (in the same network) that applies the captured data, the following items are created. The function returns a mapping between the item names in the data and the created Houdini objects.
{ "target_node": <hou.SopNode of type xform at /obj/geo1/transform2>, "items": { "box1": <hou.SopNode of type box at /obj/geo1/box2>, "OUT": <hou.SopNode of type null at /obj/geo1/OUT1> } }
See:
Recipe ¶
Recipes are stored in data Digital Assets. The recipe data is stored in the data.recipe.json section.
The recipe data can have the following items:
data
This stores the captured data based on the selected Houdini objects.
-
Parm preset stores a Parm Data that holds data for a parameter.
-
Node preset stores a Network Item Data that holds data for a node.
-
Decoration and Tool store a Cluster Data that holds multiple nodes, with one being designated as the central or anchor node.
properties
This stores essential information about this recipe so it can function.
The properties dictionary can have the following keys:
label: str
The label of the recipe that’s displayed in Houdini.
name: str
The internal name of the recipe. This is the name you can use to invoke the recipe from the Python shell.
nodetype_category: str
The category type of the node that captured the recipe.
nodetype_patterns: list[str]
Node Preset and Decoration recipes display in the recipe menu for the node types that the recipe is assigned to. This list defines those node types.
recipe_category: str
This defines the type of the recipe.
visible: bool
This sets when the recipe should be visible and usable in menus.
tool
For recipe categories such as Tool, this holds information about the tool that’s displayed in the tab menu.
The tool dictionary can have the following keys:
icon: str
The icon name to display in the tab menu.
options
Stores capture options used when the recipe was made.
info
Stores basic information about the recipe.
comment: str
An optional comment that describes the purpose of the recipe.
created: str
The date and time when the recipe was made.
data_version: str
The version number of the data model used to capture the recipe.
houdini_version: str
The Houdini version used to capture the recipe.
The following is an example of recipe data:
{ "data": { "type": "lsystem", "parms": { "angleinit": 27.0, "anglescale": 0.699999988, "picfile": "$HFS/houdini/pic/circle.pic", "premise": "A", "randscale": 0.5, "randseed": 3, "rule1": "A=-F+A:0.50", "rule2": "A=+F-A:0.50", "stepinit": 0.100000001, "stepscale": 0.5, "thickinit": 0.100000001, "thickscale": 0.899999976, "vertinc": 0.100000001 } }, "info": { "author": "sidefx", "comment": "", "created": "May 10, 2024 - 21:58:28", "data_version": "1.0", "houdini_version": "20.5.231" }, "options": { "children": False, "default_parmvalues": False, "editables": False, "evaluate_parmvalues": False, "flags": False, "metadata": False, "nodes_only": False, "parms_as_brief": True, "parmtemplates": "spare_only", "verbose": False }, "properties": { "label": "Crack", "name": "sop/lsystem::sidefx::crack", "nodetype_category": "Sop", "nodetype_name": "lsystem", "nodetype_patterns": [ "Sop/lsystem" ], "recipe_category": "node_preset_recipe", "visible": True } }
comment:strThe node’s comment string.