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.

Modes: viewport, quad, camera, flipbook, sheet, movie, network.

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.
                 `azimuths` (a list of angles) draws each frame from
                 each angle: one frame and 8 angles is a turntable.
                 `bounds` [xmin, ymin, zmin, xmax, ymax, zmax] is the
                 box to frame, for example the hands only.
    "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.
    "network"  — a drawing of the network `node` from the scene data:
                 node colors, flags, names, comments, path text, dots,
                 network boxes, sticky notes, and the wires in the wire
                 style of the network (straight or rounded, Shift+S).
                 `paths` are the items to frame (default all). It does
                 not touch the screen and works without a window.
    sheet and movie 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.

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.

Modes: connect, disconnect, reorder.

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.
                   Either end can be a network dot.
    "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.

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.

Modes: cook, cache_write, cache_clear, sim_step, sim_reset, recook.

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.
    "recook"      — cook again each node at or under `paths` that holds
                    an error or a warning, the deepest first, and say
                    which messages were stale (gone) and which are
                    current. Use it when an error names a cause that the
                    network does not have, such as "Infinite recursion"
                    with no cycle.

Cook frames here, not in an execute loop of hou.setFrame and geometry():
the viewport cooks the same nodes during the loop, and that can leave
false errors on the nodes inside a solver.

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.

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.

Modes: python, hscript, expression, vex_check, env, job.

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.

Do not use it to build a network: one batch of node_edit create, connect
and parm_set is also one round trip, and each step reports its errors.
`hou.Node.inputs()` skips network dots and gives the node behind them; use
`inputConnections()` and `inputItem()` for the real wiring before you
rewire or delete.

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.
                   `wait` waits for the end, up to that many seconds.

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.

Modes: summary, points, prims, attrib, groups, group_members, bbox, intrinsics, nearest, skeleton, compare, try, volume_stats, volume_voxels, volume_sample, volume_compare, image, volume, export, fingerprint, stretch, inside, crossings.

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 ("|" between alternatives, * as a
                       wildcard). A KineFX import holds the skeletons on
                       output 1 and 2: give `output`.
    "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. A
                       menu takes its token ("poly") or its index. A type
                       with no verb, such as an asset, runs as a temporary
                       node in a hidden network that is then deleted.
                       `attrib_name` reads that attribute on the result,
                       as mode "attrib" does, `unique` included.
    "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 `file`
                       is the file path. A file that is there is
                       overwritten. The other modes write nothing.
    "fingerprint"    — for each node of `path` and each frame: counts,
                       bounds, a hash of P and of the attribute names.
                       `name` saves it. After a refactor, call it again
                       with `against` (the saved name) and `renamed`, and
                       read `compare`: what differs, or same=true.
    "stretch"        — how much each edge grew against the same edge of
                       the rest mesh `against`: max, percentiles, the
                       count over `threshold`, the worst edges and the
                       places where they are, on the rest mesh.
    "inside"         — the points of `path` inside the closed mesh
                       `against`: the count, the depth, where they are.
                       Run it before a cloth sim.
    "crossings"      — the points where the surfaces of `path` cross,
                       themselves or `against`, counted for each pair of
                       parts of `split_by`. A part with itself is a self
                       crossing.

Returns JSON. A large read is slow: keep `count` small and page with
`start`.

Modes: list, get, install, uninstall, reload, update, create, sections, section_get, section_set.

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.

Modes: create, delete, copy, move, rename, flags, color, layout, insert, place_chain, wrangle, material, assign_material, take, current_network, note, box, split.

Use it to build a network. Then use parm_set for the values, and connect
for the wires.

Do not compute positions: create with input_path, insert and place_chain
place the nodes the way the user lays out a graph, move a node of the user
only down to make room, and return every node that moved with its old and
new position. Each returns the layout faults it sees.

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 or paths: nodes, dots, sticky notes or
                         network boxes. A node that still feeds a node
                         outside paths is refused, with the list of its
                         readers, unless force=true.
    "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:
                         each node under its first input (a straight
                         wire), side inputs from the right in port order,
                         a source one row above its reader, long wires down
                         a lane through dots. Give `paths` to lay out only
                         those nodes. Without it the whole network moves,
                         including the nodes the user placed by hand, and
                         the result says so.
    "insert"           — node_type (or path of a node), input_path, and
                         reader: put the node on every wire from
                         input_path into reader (all streams of a Vellum
                         chain), or into every reader. The nodes below
                         move down only by the room it needs.
    "place_chain"      — paths (in order), reader, input_index: wire the
                         chain into that input and place it as a side
                         chain, its own column right of the reader, last
                         node one row above it. Wire a side result into
                         the node that really reads it, not through
                         pass-through ports of a chain.
    "split"            — path (a SOP network) and stages: move the nodes
                         of each stage into a subnet of that name. Each
                         result that another stage reads gets an OUT_
                         Null, and each reader an IN_ Object Merge.
                         Node paths in parameters, expressions and VEX
                         code are rewritten for the new places. Returns
                         each rewrite and each path it could not
                         resolve. Undo puts it back in one step.
    "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.

Modes: info, parms, schema, changed, names, expression, keyframes, code, cook_chain, explain, material, image, channels, simulation, render_settings, cache, time_dependency, validate, layout, readers.

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.

Modes: value, press, expression, keyframe, keyframes, delete_keyframe, revert, lock, link, spare, render_settings, chop_export, snapshot, restore, diff.

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.

Modes: status, workitems, cook, dirty, cancel.

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.

Modes: get, frame, range, playback, play.

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.

Modes: start, progress, settings, create, watch, stats, compare.

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. `output_path`
                 and `res_scale` hold for this render only: the ROP keeps
                 the output and the size of the user. Use them for test
                 renders. `wait=true` returns when every image is
                 complete (husk ended; up to about 28 minutes), with the
                 render stats of the last one. Without wait, husk can go
                 on after the call.
    "progress" — what the ROP reports about the render.
    "settings" — the output file, the camera, the resolution and the
                 range of the ROP; the render delegate that really runs
                 (`engine` cpu or xpu, and `engine_from`: the ROP
                 renderer, else husk:default_delegate on the render
                 settings prim); a warning when a Karma settings node
                 says another engine; and the changed Karma settings,
                 split into the ones that engine reads and the ones it
                 ignores, with the reason. Karma XPU shows the CPU
                 Quality controls and ignores them; its Limits tab
                 counts. parm_set and execute warn on a write that the
                 engine of the node ignores.
    "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.
    "stats"    — what husk wrote into the image at `output_path`
                 (husk:render_stats): render time, the engine that really
                 ran, each XPU device with its share of the samples,
                 shader compiles, peak memory, the AOVs. A GPU at 0 %
                 with compiles in progress is not a slow GPU.
    "compare"  — the mean and the largest absolute difference of each AOV
                 of `output_path` against `reference`, to tune samples
                 against a clean render.

Returns JSON. A render that writes no file, with no process running, has
failed: read the node with cook to see the error.

Modes: info, save, load, undo, redo.

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.

Modes: scene, network, children, search, node_types, errors, materials, lights, takes, caches, render_nodes, viewports, changes.

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 by name, with their
                     wires, flags and dots. Each input names the dot it
                     comes through, then the node behind the dot.
                     `pattern` and `node_type` keep some nodes;
                     compact=True gives only the wires.
    "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". `pattern`
                     keeps the names or labels that match.
    "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.
    "changes"      — what the user changed in the network `path` since
                     your last call: nodes added, deleted, renamed or
                     moved, wires, flags and parameter values. Your own
                     changes are not listed. The first call starts to
                     watch the network; call it at the start of each
                     turn, before you change anything there.

Returns JSON. A path that does not exist comes back as an error, not as an
empty list.

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.

Actions: status, list, attach, detach, interrupt, start, start_gui, stop.

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. A
                  single long cook does not return to Python; then, in a
                  Houdini with a window on Windows, it sends Escape to
                  the window, as the user would. A stopped simulation
                  keeps a partial cache.
    "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.

Modes: stage, prims, prim, search, layer, attribute, composition, variants, stats, modified, lights, transform.

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: each
                    layer of its prim stack, strongest first, with the
                    node that wrote it (the SOP behind an op: layer) and
                    its references and payloads.
    "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.