| batchA | Run several Houdini tools in one call. Use it to build a network: many nodes, their wires and their parameters go
in one round trip and one undo group, and a person can undo the whole thing
with one keystroke.
Do not use it when a later step needs to read what an earlier step made.
The list runs without you in the middle, so nothing can branch on a result.
A failed batch changes nothing. Every step is checked before any step
runs, and a step with a wrong argument stops the batch. A step that fails
as it runs stops the list, and the steps before it are undone. A step whose
item failed is a failed step, and so is a parameter write that did not
apply. The error names the index of the step and its error.
Returns JSON with one result for each operation, in the order of the
operations, and the picture of every capture step.
A batch that works cooks the display node of each SOP network that it
touched: `check` gives its point and primitive counts, and the touched
nodes that have errors. Read it before you build on the result.
A capture step with no `output` writes to a file of its own, so one batch
can hold several captures.
|
| captureA | Make a picture of the scene and look at it. Use it to confirm your own work: numbers in a node do not tell you that the
result looks wrong. Use it before you report that a task is done.
Do not use it for a final picture: render does that through a ROP.
The view goes back to where the user left it when the picture is written.
Nothing here changes the scene for good.
mode:
"viewport" — the viewport as it is now.
"quad" — four pictures: top, front, right and perspective.
"camera" — through the camera node at `camera`.
"flipbook" — a sequence over `frame_range` [start, end]. Returns the
path of the files, not a picture.
"sheet" — `node` at many frames on one picture, a tile for each
frame with its number, all from one camera that does not
move. Frames: `frames`, or `count` frames from `start`
(the current frame) at `step` (1). A step over 2 hides
movement and gives a warning: look at a short range at
step 1. `reference` is a picture to put first, to
compare. `columns`, `tile_width` set the grid. The
frames cook in order, forward, and the result gives
the cook seconds of each one.
"movie" — `node` over `frames` or `frame_range` (the playbar
range) as an MP4 at `fps`, `resolution` [width] wide.
Returns the path; open it in a player.
Both draw with an OpenGL ROP, with or without a window, over a flat
grey `background`. To see where a point attribute lives, use
"sheet" with one frame and `color_by`, with `contour`, `slab` or
`vectors`.
A Houdini with no window has no viewport, and there an OpenGL ROP draws the
same picture from the same arguments over a grey background. It runs in a
new hython, so the scene gets no camera and no ROP.
There is no picture of the network editor: every Houdini pane is a native
GL drawable, and Qt draws nothing into it. Read the graph with node_inspect.
Aim the view with `frame` and `fill`, with `target`, `look_from` and
`radius`, with `direction`, with `azimuth` and `elevation`, or with
`camera`.
Returns the picture, plus JSON with the state of the window: the frame, the
open file, the selection, the network in front, and which nodes carry the
display, the render and the template flag. A picture that does not change
after an edit is almost always a display flag on another node.
Houdini without a GUI has no viewport: then the result says so and names
the next action.
|
| connectA | Change how nodes feed each other. Use it after node_edit made the nodes. A list of wires goes in one undo
group and one round trip.
Do not use it to wire a node that you make now: node_edit mode "create"
takes `input_path` and wires it in the same call. Do not use it to read the
wires: scene_overview mode "network" lists them.
mode:
"connect" — src_path feeds dst_path. dst_input_index chooses the
input, src_output_index the output. Both count from 0.
A wire into an input that has one replaces it.
"disconnect" — path loses the wire on input_index.
"reorder" — path takes its inputs in the order input_indices.
For several wires, give `items`: for "connect", each item has src_path and
dst_path, and can have dst_input_index and src_output_index; for
"disconnect", each item has path, and can have input_index.
Returns JSON, one line for each wire, with the paths that Houdini used.
An input index that the node does not have is reported, not dropped.
|
| consoleA | Read the Houdini log and the node errors. Use it when something did not do what you expected. A cook error often
hides behind an empty result: the geometry has no points, and the reason is
here.
Do not use it for the errors of nodes that you cook now: cook returns them,
with the nodes upstream that failed. scene_overview mode "errors" lists every
node with a cook error, without the log.
Each call takes the log entries away, so a call returns only what is new
since the call before it.
Returns JSON.
|
| cookA | Force work to happen, and report what the work said and what it cost. Use it to run a test: write a few parameters, cook a range of frames, and
read the seconds for each frame. That is one call, and it is the loop that
every look iteration needs.
Do not use it to read the result: geometry_inspect does that, and it cooks
the node as well.
mode:
"cook" — cook the nodes and return the errors, the warnings and
the time. `frames` or `frame_range` cooks over more
than one frame; the playbar goes back to where it was.
"cache_write" — write the file cache of the node. frame_range is
[start, end]; without it the node writes its own range.
"cache_clear" — remove the cached files of the node.
"sim_step" — step a DOP network num_steps frames.
"sim_reset" — clear the cache of a simulation, so that the next cook
runs it again. It accepts a DOP network and a solver
SOP such as a Pyro, FLIP, Vellum or RBD solver. After
you change anything inside a solver, reset it: the node
gives its old result back with no error and no warning.
On a solver SOP it cooks the sources first, cooks the
start frame after the reset, and reports the
primitives there. It fails when the result is empty
while the sources are not: that simulation stays
empty on every frame.
Returns JSON: the seconds in total, for each frame, and the slowest frame,
with the errors and the warnings of every node. Each frame also gives the
point count, the primitive count and the bounds of each SOP: one call
checks that a result moves or grows over a range. `ok` is false when a
node failed to cook, and `failed` then names each node upstream of it or
inside it that holds an error, with the text: the node that broke is
often another node than the one you cooked. A cook can take minutes:
the call waits, and a timeout does not stop the cook. Cook a long range in
parts of a few seconds, so that one call does not block Houdini past the
timeout.
|
| docsA | Read the official Houdini documentation. This is the authority on every node, parameter, VEX function and HOM call.
Read the page before you use an API that you have not confirmed in this
session: names and enum members change between Houdini releases, and a
wrong one often fails without a message.
Do not answer from memory, and do not read sidefx.com yourself.
The pages come from the Houdini install on this machine, so they match the
build exactly. The first search on a build indexes it once, which takes a
few seconds; the index stays on disk. A page read never waits for it.
Give exactly one of `query` (search), `page` (read a page from a hit) or
`node` (the page of a node type). A node path is the only input that needs
Houdini.
Returns markdown for a page, JSON for a search.
|
| executeA | Run code in Houdini, with the full hou module and no guard. Use it for what no other tool covers, and to confirm an API in the live
session, for example `print(dir(hou.Node))`. The code runs with the rights
of the Houdini process: it can write files, delete nodes and quit Houdini.
Prefer a named tool when one exists. A write in code to a parameter that
holds an expression, that is disabled or hidden, or whose range clamps the
value changes nothing, and a write to a channel reference changes another
node. The answer lists each such write in `write_warnings`; read it. If you
write the same script twice, the named tool for it is missing: say so in
the feedback at the end of the session.
mode:
"python" — run `source` as Python. Returns stdout and stderr, and
keeps them when the script raises. Print what you want
to see: the value of the last line does not come back.
"hscript" — run `source` as an HScript command.
"expression" — evaluate `source` as an expression. `language` is
"hscript" or "python".
"vex_check" — compile `source` as VEX and report the errors. Nothing
runs.
"env" — read the Houdini variable `name`, for example "HIP".
"job" — the state of the background job `job`: running, with
what it printed so far, or done, with its result.
Use `file` for a script that you run again with other values. Houdini
answers nothing while a script runs: for long work, such as a sweep, use
`background` with a large `timeout`. session action='interrupt' stops it.
|
| geometry_inspectA | Read the geometry that a node produces. This cooks the node. Use it to confirm that a node made what you expected: the point count, an
attribute that a wrangle wrote, the shape of a volume, the size of the
bounding box.
Do not use it to read parameters: node_inspect does that.
mode:
"summary" — counts, attributes, groups, volumes, bounds. Start
here. An empty result carries the errors and the
warnings of the node, which is where the reason is.
"points" — `count` points from `start`, with `attribs`.
"prims" — `count` primitives from `start`.
"attrib" — the values of `attrib_name` on `attrib_class`
("point", "prim", "vertex", "detail"): min, max
and mean of each component over every element,
and `limit` (10) values from `start`. A vector
attribute keeps its shape. unique=True returns each
value that occurs and how many elements carry it,
which is how you find the pieces in a geometry.
"groups" — the groups of `group_type`.
"group_members" — the members of `group_name`.
"bbox" — the bounding box.
"intrinsics" — the intrinsic values of primitive `prim_index`.
"nearest" — the point nearest to `position`, for example [0,1,0].
"skeleton" — a KineFX skeleton: each joint with its name, its
parent and its transform. `pattern` keeps the names
that match.
"compare" — the difference from the node at `against`. Points are
matched by `match_attrib` ("name" by default), not by
their order. Use it to prove that a new node gives
the result of the node it replaces.
"try" — run `steps`, a list of
{"node_type": ..., "parameters": {...}}, on the
geometry of `path` as verbs. Nothing changes in the
scene. Use it to learn what a node would make.
"volume_stats" — every volume or VDB: resolution, voxel size, the
extremes, the mean, the sum, percentiles. `name`
reads one, `bins` adds a histogram, `threshold`
counts the voxels below and above it and gives the
world box of the voxels above it.
"volume_voxels" — one field as an array indexed [z][y][x], with its
shape and its transform. `name` is the field.
`reduce` gives one answer instead: "sum", "mean",
"max", "min", or "project_x", "project_y",
"project_z" (the sum along that axis, a 2D array).
An array past `limit` numbers is thinned.
"volume_sample" — read `names` (fields) at `positions`, or at the
points of `from_node`, with no node added to the
scene. Returns min, max, mean, percentiles, a
histogram of `bins` (10), the counts on each side of
`threshold`, and the values when there are at most
`limit` (1000).
"volume_compare" — how much of the field `name` sits in each band of the
field `against`. The answer to "how much smoke is
inside the collider". `from_node` holds `against`
when another node does, such as the collider SDF.
"image" — a COP node: resolution, planes, and `plane_name`.
"volume" — the VDB grids in a COP node.
"export" — write the geometry to disk. `format` is "obj",
"bgeo" or another that Houdini writes, and `output`
is the file path. A file that is there is
overwritten. The other modes write nothing.
Returns JSON. A large read is slow: keep `count` small and page with
`start`.
|
| hdaA | Read and change Houdini digital assets. Use it when a node type comes from a .hda file: to find the file, to load a
new one, or to read the scripts and the help inside it.
Do not use it for the parameters of one node in the scene: node_inspect
does that.
mode:
"list" — the installed assets. `category` filters, for example
"Sop".
"get" — the definition of `node_type`: the file, the version
and the tools.
"install" — load the .hda file at `file_path` into the session.
"uninstall" — unload the .hda file at `file_path`.
"reload" — read the .hda file at `file_path` again, after an edit
on disk.
"update" — save the node at `node_path` back into its asset.
"create" — make an asset from the subnet at `node_path`, with
`name`, `label` and `file_path`.
"sections" — the section names inside `node_type`.
"section_get" — the text of `section_name`, for example "PythonModule".
"section_set" — write `content` into `section_name`.
Returns JSON. "install" and "uninstall" change every node of that type in
the session.
|
| node_editA | Change the nodes in a network. One item, or a list in one undo group. Use it to build a network. Then use parm_set for the values, and connect
for the wires.
Do not use it to set parameters: parm_set does that, and it reports a write
that had no effect.
mode, and the arguments that each mode reads:
"create" — node_type, parent_path, name, position,
parameters, input_path. context selects the
network kind: "sop" (default), "cop", "chop",
"lop", "material_network".
"delete" — path, of a node, a sticky note or a network box.
"copy" — paths (or path), destination_path, suffix,
names. Copies a set of nodes with the wires
between them; a wire from outside the set goes to
the same node. suffix is added to each name, or
names maps a source path or name to a new name.
Returns `copies`, each source path with the path
of its copy: use that map, never the order of a
list. Without destination_path the copies go to
the right of the sources.
"move" — path with destination_path to put it in another
network, or path with position to move it on the
canvas.
"rename" — path, new_name.
"flags" — path, display, render, bypass. The display flag
and the render flag are different flags.
"color" — path, color as [r, g, b] from 0 to 1.
"layout" — path: lay out the children of that network in
rows, each node under its inputs. Give `paths` to
place only those nodes next to what they connect
to. Without it the whole network moves, including
the nodes the user placed by hand, and the result
says so.
"wrangle" — parent_path with code to make a wrangle, or path
with code to write into one. code_file reads the
code from a file, so a long snippet travels once.
replace edits a snippet in place: a list of
{"old": ..., "new": ...}, and each `old` must
appear exactly once.
"material" — path, material_type, name, parameters.
"assign_material" — path, material_path.
"take" — name to make a take, or take_name to select one.
"current_network" — path: what the network editor shows.
"note" — parent_path, text, position, color: a sticky
note. Without position it goes to the right of
the nodes.
"box" — paths, text, color: a network box around those
nodes, with text as its comment.
Returns JSON. Houdini adds a numeric suffix when a name is already used, so
read the path in the result and use that path from then on. Never look the
node up again by the name you asked for.
|
| node_inspectA | Read one node, or a list of nodes, without changing anything. Use it before you write: to confirm a parameter name, to see whether a
parameter carries an expression, and to read what a node reports after a
cook.
Do not use it to list a network: scene_overview does that.
mode:
"info" — type, inputs, outputs, flags, changed parameters.
"parms" — every parameter, or one parameter when you give
`parm`. The result says whether the value comes
from an expression.
"schema" — the parameter templates: types, ranges, menus.
Read this before you write a menu parameter.
"changed" — only the parameters that a person set: not at the
default, or with an expression or keys. Folders,
labels, buttons and hidden fields are left out, and
a ramp is one entry with its keys.
"names" — the names of the parameters, and nothing else. Read
this first when you do not know the name to write.
"expression" — the expression on `parm`, and its language.
"keyframes" — the keys on `parm`.
"code" — the VEX snippet in a wrangle node.
"cook_chain" — what this node cooks from, upstream.
"explain" — a short account of what the node does here.
"material" — the shader parameters of a material node.
"image" — the COP node: resolution, planes, data type.
"channels" — CHOP channels. `channel`, `start` and `end` read
the samples of one channel.
"simulation" — the DOP network. `object_name` reads one object,
with `field_name` one field of it.
"render_settings" — the parameters of a ROP node.
"cache" — the file cache state of a node.
"time_dependency" — which nodes under this one cook again on every
frame, and what makes each one do it. With
`frames` it times each one and sorts by the time.
"validate" — the names in the parameters of the node that name
nothing: a group, an attribute or a volume that the
input geometry does not hold. That is the failure
that gives a wrong result with no error.
"layout" — for a network: each node that sits above its input,
and each pair of nodes in one slot, where one name
covers the other. Read it after you add nodes.
"readers" — the parameters that read `parm` through a channel
reference or an expression: what else a write to
it changes.
A solver has hundreds of parameters: give pattern or fields.
Returns JSON. A cook error comes back in the result: an empty geometry with
no error line means the node cooked and made nothing.
|
| parm_setA | Write parameter values, or press a button. One write, or a list in one
undo group. Use it after node_inspect has confirmed the parameter name and the type.
A write can be accepted and change nothing, and Houdini says nothing. This
tool looks for all six causes and names the one it found:
- the parameter carries an expression, which still decides the value;
- the parameter is animated, so the value became a new key;
- the parameter is locked;
- another parameter disables or hides it, so the cook does not read it;
- a strict range clamped the value;
- the parameter reads another node through a channel reference, so the
write would change that other node. It is refused; give
`follow_reference=true` to write the node at the other end.
Read `warnings` and `not_applied` in the result before you report success.
mode, and the arguments that each mode reads:
"value" — path, parm, value. Or path and parameters, a
dictionary of several names and values. A menu
takes its token, for example "custom". A
bit-field menu takes a token or a list of them.
"press" — path, parm: press a button, for example Save to
Disk on a File Cache, Reload on a File SOP, or
Resimulate on a solver. The result holds the errors
and the warnings of the node after the press,
because work that a button starts fails later and
in silence.
"expression" — path, parm, expression, language ("hscript" or
"python").
"keyframe" — path, parm, frame, value.
"keyframes" — path, parm, keyframes: a list of {frame, value}.
"delete_keyframe" — path, parm, frame.
"revert" — path, parm: back to the default, and the
expression goes away.
"lock" — path, parm, locked.
"link" — src_path, src_parm, path, parm: the parameter at
path follows the one at src_path.
"spare" — path, parameters: a list of controls to add, each
{name, label, type, default, min, max, strict,
help, value, expression, items}. type is "float",
"int", "vector", "toggle", "string", "menu" (with
items), "ramp" or "color_ramp" (default: a list of
[position, value]). One control can also come as
name, label, parm_type, default, expression.
On a wrangle it first does what the Create
Parameters button does, a parameter for each ch()
call, and puts every control in that folder above
the code. Use it instead of numbers typed into VEX:
the user tunes these. A control that exists is
replaced in place, so a second call is safe.
"render_settings" — path, settings for a ROP node.
"chop_export" — chop_path, channel_name, path, parm.
"snapshot" — name, paths: save every parameter of these nodes,
with expressions, keys and the bypass flag, to the
record `name` on disk. "/obj/geo1/*" names every
node in a network. It overwrites a record of the
same name.
"restore" — name: put the record back, and list what changed.
`paths` limits it to some of the nodes.
"diff" — name: list how the scene differs from the record.
Changes nothing.
In a sweep, restore before each variant, not once
at the end: a variant that does not name a
parameter keeps the value of the one before.
Returns JSON with the value before, the value after, and a reason when the
write did not take.
|
| pdgA | Cook a TOP network, and read what its work items did. Use it for a TOP network only. A TOP node does not cook like a SOP: it
makes work items, and each item runs on its own. For a SOP or a DOP, use
cook. For a ROP, use render.
mode:
"status" — the counts for each state, and whether a cook runs now.
"workitems" — the items. `state` filters, for example "failed".
"cook" — start the cook. The call comes back at once; read
"status" after it to follow the work.
"dirty" — mark the node dirty. `dirty_all` also removes the
outputs on disk.
"cancel" — stop the cook that runs now.
Returns JSON. A failed item holds the command and the log path: read those
before you change the network.
|
| playbarA | Read or set the time of the session. Use it before you read geometry that changes over time: a SOP cooks at the
current frame, so the frame decides what you see.
Do not use it only to read another frame: geometry_inspect, node_inspect
and stage_inspect take `frames` and put the playbar back after. A frame
that you set here stays for the person and for every later call, and
"range" also changes what a flipbook covers, and a ROP whose range
follows $FSTART and $FEND.
mode:
"get" — the current frame and time.
"frame" — go to `frame`.
"range" — set the scene frame range to `start` and `end`.
"playback" — set the playback range inside the scene range.
"play" — `action` is "play", "stop", "next", "previous", "start"
or "end". Playback needs a GUI.
Returns JSON.
|
| renderA | Start a render, read its settings, or watch it run. Use it for a final picture through a ROP node. For a fast look at the
viewport, use capture instead: it is much quicker.
mode:
"start" — render the ROP at `path`. `frame_range` is [start, end];
without it the node renders its own range. A render can
take a long time.
"progress" — what the ROP reports about the render.
"settings" — the output file, the camera, the resolution and the
renderer of the ROP.
"create" — make a ROP of `render_type` ("opengl", "karma", "mantra",
"ifd", …) named `name` under `parent_path`.
"watch" — count the husk and mantra processes on this machine, and
say whether the file at `output_path` is there and how big
it is. This mode does not need Houdini, so it also works
while Houdini is busy with the render.
Returns JSON. A render that writes no file, with no process running, has
failed: read the node with cook to see the error.
|
| scene_fileA | Read, save or load the scene file, or step its undo history. Use "save" before a change that is hard to undo, and use "info" to learn
whether the session holds work that is not saved.
mode:
"info" — the file name, the frame range, the counts, and whether the
session has changes that are not saved.
"save" — save to `path`, or over the open file when `path` is empty.
"load" — open the .hip file at `path`. Everything in the session goes
away, and the undo history with it.
"undo" — undo `count` steps. Each call of a tool that changes the
scene is one step. A batch is one step, except a batch with a
step that waits (capture, render): there each step is one.
Returns the labels it undid and the next ones.
"redo" — redo `count` steps.
Returns JSON.
|
| scene_overviewA | List what the scene holds. Start here, before you touch a node. Use it to find a node path, to see the shape of a network, or to learn
which node types this Houdini has.
Do not use it to read one node in detail: node_inspect does that. Do not
use it to read geometry: geometry_inspect does that.
mode:
"scene" — file, frame range, counts, and the top of the tree.
"network" — the children of one network, with their connections.
"children" — the children of `path`. recursive=True walks down.
"search" — nodes whose name matches `pattern`, under `path`.
node_type filters by type name.
"node_types" — the node types this Houdini has, for one `category`
such as "Sop", "Object", "Lop", "Driver".
"errors" — every node under `path` that has a cook error.
"materials" — the materials in `path` (default /mat) and the types.
"lights" — the lights on the USD stage of the LOP node `path`.
"takes" — the takes, and which take is current.
"caches" — file caches under `path` and their state on disk.
"render_nodes" — the ROP nodes in /out.
"viewports" — the panes, and what the scene viewer shows.
Returns JSON. A path that does not exist comes back as an error, not as an
empty list.
|
| selectA | Read the node selection, or set it. Use it to see what the person works on before you change the scene, and to
show them your result when you are done. Do not use it to find nodes:
scene_overview mode "search" does that.
A path is the full path of a node, for example "/obj/geo1/mountain1". A
path that is not a node stops the call with an error, and the selection
stays as it was.
Returns JSON with the selected paths.
|
| sessionA | Report the Houdini sessions, choose one, or start, stop or interrupt one. Use it first when a tool says that Houdini is not reachable, and use it to
learn the Houdini version before you use an API that changed between
releases.
Several Houdini sessions can listen at the same time: the graphical one that
holds the work of the user, and a headless one for your own tests. Every
tool result names the session that answered, in `_session`. Read that line
when a scene looks empty or wrong: an empty scene is usually the wrong
session, not a lost scene.
Do not use it to read the scene: scene_overview does that.
action:
"status" — the session that the bridge talks to now, the other
sessions, and the port. Starts nothing, and always
answers.
"list" — every Houdini that runs, with its version, its process
id, its .hip file, whether it has a window and whether it
answers; and the Houdini versions installed.
"attach" — send every later command to the Houdini on `port`. Use it
when "list" shows more than one.
"detach" — forget the attached port and let the bridge choose again.
"interrupt" — stop the call that runs now in the attached Houdini, or
in the one on `port`: a script past its budget, a loop
that will not end. Houdini answers again after it.
"start" — start a headless Houdini (hython) and attach to it.
`version` chooses the release, for example "21.0" or
"21.0.829"; without it, the version of the Houdini window
that runs. A Houdini that already runs is not touched, so
this is the safe way to test while a person works.
"start_gui" — start Houdini with its window and wait for the plugin to
answer, up to 4 minutes. It opens the .hip file at `hip`
when you give one, it stays open when the bridge stops,
and the bridge attaches to it. `version` as for "start".
"stop" — stop the headless Houdini that this bridge started. A
Houdini that you started yourself, or with "start_gui", is
not touched.
Returns JSON. The report says what to do next when nothing answers.
|
| stage_inspectA | Read the USD stage at a LOP node. This cooks the node. Use it in a Solaris (LOP) network to see the prims, the layers and the
composition that a node produces.
Do not use it for SOP geometry: geometry_inspect does that.
mode:
"stage" — the stage: prim count, layers, the default prim.
"prims" — the prim tree from `root_prim`, `max_depth` deep.
"prim" — one prim at `prim_path`. include_attrs=True adds its
attributes.
"search" — prims whose path matches `pattern`, filtered by
`type_name` such as "Mesh" or "SphereLight".
"layer" — the layer stack, and the layer at `layer_index`.
"attribute" — the value of `attr_name` on `prim_path`.
"composition" — where the opinions on `prim_path` come from.
"variants" — the variant sets on `prim_path` and the selection.
"stats" — counts under `prim_path`.
"modified" — the last `count` prims that this node changed. Use it
to see what one LOP did.
"lights" — the lights on the stage.
"transform" — where `prim_path` is in the world: translate, rotate
and scale composed through every parent. With
`frames`, the path of a moving prim.
Returns JSON.
|
