For technical or integration tasks that would be difficult to express using LOP nodes, you can use this node to access the full power of the USD API to read and modify the scene graph tree, the power of HOM to access and control the rest of Houdini, as well as the full power of Python and its libraries to access external data and integrate with your pipeline and other systems.

This node is often useful to script custom pipeline-specific tasks.

See Pixar’s Python API tutorials for help with the APIs.

• Call hou.pwd() to get a reference to this node as a hou.Node. You can get either the current stage through this reference (see below). You can also use it to access spare parameters you might add to this node.

• Call hou.pwd().editableStage() to get an editable pxr.Usd.Stage object. This represents the output of this node, including any changes you make using the API.

  (The USD Edit Target is automatically set to the active layer for you. Do not change the edit target. Doing so will have unpredictable negative consequences.)

• Call hou.pwd().inputs()[0].stage() to read from an input stage, then stash any evaluated prim patterns or other values, **before** calling hou.pwd().editablestage(). When this happens in the wrong order, Houdini will still usually run the code, but will not be as efficient.

• Instead of manipulating the stage using Usd APIs, you can edit the active layer using lower-level Sdf APIs. You cannot do both in the same script.

• You probably only want to do this if you have a reason to prefer the lower-level APIs. pxr.Usd methods are higher level methods that can be much easier to use. They perform more error checking and data validation. However the pxr.Sdf APIs can be dramatically faster, especially when creating new USD primitives.

• To get an editable pxr.Sdf.Layer reference to the active layer, call hou.pwd().editableLayer(). If you do this, do not also call hou.pwd().editableStage() in the same script (doing so will just return None).

• The returned editable layer is not on any USD stage while the python LOP is cooking, so there is no need to use Sdf.ChangeBlock objects to batch change notifications when making edits.

• After calling editableLayer, you may call hou.pwd().uneditableStage() to get access to a read-only Usd.Stage. This stage will be the output of the node connected to this node’s input. But unlike calling hou.pwd().stage() or hou.pwd().input(0).stage(), this approach will not trigger recursion errors or warnings about getting a read lock for an already locked stage. The returned stage can be used to access information about the current state of the stage to inform the edits being made to the editable layer. Because the editable layer is not composed onto this uneditable stage, changes made to the layer will not affect the content of this stage.

• When you are editing code, the node will cook if you click outside the editor, or press Alt + Enter.

• You can add spare parameters onto the node to give the node a graphical interface. For example, you could add a text box named primpath that takes a primitive path. Then you can access the parameter value in the script:

  node = hou.pwd()
  primpath = node.evalParm("primpath")
  

• If you make a useful Python Script node you want to share, you can turn a node instance into a LOP digital asset. Right-click the node in the network editor and choose Create digital asset. The script is stored as part of the digital asset, and the node functions the same way, but as an asset that can be shared and versioned.

• The pop-up menu button to the right of the editor pulls snippets from any PythonScripts.txt files in the Houdini path. You can create a $HOUDINI_USER_PREFS_DIR/PythonScripts.txt file and add snippets to have them appear in this menu. Read $HFS/houdini/PythonScripts.txt to see the required file format.

• If your script needs to “find all prims that…”, instead of using the USD traversal methods, consider using hou.LopSelectionRule. This object implements Houdini’s USD prim pattern matching. It generates a list of Sdf.Path objects. You can turn an Sdf.Path into a Usd.Prim object using stage.GetPrimAtPath(pathstring). When using this approach you can either evaluate the selection rule on the input node, or directly on the Usd.Stage returned by pwd().editableStage(). If using the input node, evaluate the selection rule before getting this node’s editable stage to avoid an expensive duplication of the input stage.

• It is almost always a bad idea to call hou.setContextOption() from within the script of a Python LOP. This causes a global context option to be created. Global context options are accessible anywhere in the hip file, which means cooking this LOP and running its script can potentially cause nodes anywhere else in the hip file to become dirty, if they use this context option. Further, the global context option will only be set when the node cooks, but changing the global context option value in the context option editor or using Python code (in a python shell or in another Python LOP) will not dirty this node, and so it will not recook and reset the option value as might be expected. Instead, setting context options locally within a LOP network should be done using the Edit Context Options LOP.

• You must not edit the root layer of the stage. Although this root layer is accessible through the Python API, the LOP cooking architecture requires that it be free to manage that root layer free from interference from any single LOP node. The most common use case that leads to this mistake is wanting to add a sublayer to the root layer, which can instead be done using the hou.LopNode.addSubLayer method.