On this page |
The hapi
package contains the classes and functions for the Python wrapping of the Houdini Engine C API
Houdini Engine is an API that enables Houdini digital assets to be used directly inside of the host application. This allows artists to leverage the power of Houdini directly inside of whichever environment they are most comfortable working in.
From a technical point of view, Houdini Engine is a C API designed for binary compatibility. It is able to integrate into a host application even if compiler choice or versions don’t match. For instance, Houdini Engine can integrate into both managed environments, such as C# and Python as well as a native C++ applications.
Finally, compared to the C++ HDK, Houdini Engine is a flat and small API that is easy to learn.
Tip
When writing an engine integration it can be very useful to connect to a live session of interactive Houdini instead of HARS. This can be done with Houdini Engine SessionSync
Tip
The Houdini Engine C API documentation can be useful even when using the Python API because the same concepts and functions apply.
Getting Started
To... | Do this |
---|---|
Create a Session |
A session is an instance of the HARS executable, which is a complete headless Houdini. You can automatically start HARS and then attach to it. import hapi options = hapi.ThriftServerOptions() process_id = hapi.startThriftSocketServer(options, 9090) session = hapi.createThriftSocketSession('localhost', 9090) |
Attach to a Session |
A session is an instance of the HARS executable, which is a complete headless Houdini. It can also be a running Houdini instance with SessionSync active. You can attach to the session using a named pipe (for example import hapi session = hapi.createThriftSocketSession('localhost', 9090) cook_options = hapi.CookOptions() hapi.initialize(session, options) |
Load an HDA |
If the HDA file is accessible to the server you can load it with hapi.loadAssetLibraryFromFile. If the HDA is only accessible to the client, you can send it as bytes with hapi.loadAssetLibraryFromMemory. # Read myhda.hda into memory so we can send it over hda_bytes = open('/tmp/myhda.hda', 'rb').read() lib_id = hapi.loadAssetLibraryFromMemory(session, hda_bytes, len(hda_bytes), True) |
Create a Node |
# Assuming we have a loaded an asset which defines a SOP type `MyType` node_id = hapi.createNode(session, -1, 'Sop/MyType') # Get a hapi.NodeInfo for the new node node_info = hapi.getNodeInfo(session, node_id) # Getting a string is a two step process str_len = hapi.getStringBufLength(session, node_info.nameSH) node_name = hapi.getString(session, node_info.nameSH, str_len) print('Created {}'.format(node_name)) |
Save scene data to file |
It can be very useful for users to save out a hip file of the scene when debugging problems. hapi.saveHIPFile(session, '/tmp/debug.hip') hapi.saveGeoToFile(session, node_id, '/tmp/debugGeo.bgeo.sc') |
Next Steps
API Reference
classes
-
Class hapi.MaterialInfo
functions
-
Add an attribute.
-
Add a group to the input geo with the given type and name.
-
Binds a new implementation DLL to one of the custom session
-
Cancel the PDG cooking operation.
-
Recursively check for specific errors by error code on a node.
-
Clean up memory. This will unload all assets and you will
-
Clears the connection error. Should be used before starting
-
Closes a session. If the session has been established using
-
Commit the current input geometry to the cook engine. Nodes
-
Commits any pending workitems.
-
Compose a list of child nodes based on given filters.
-
Compose the cook result string (errors and warnings) of a
-
Compose a list of child object nodes given a parent node id.
-
Connect two nodes together.
-
Converts a 4×4 matrix into its TRS form.
-
Converts a 4×4 matrix into its TRS form.
-
Converts the transform described by a hapi.TransformEuler
-
hapi.convertTransformEulerToMatrix
Converts hapi.TransformEuler into a 4×4 transform matrix.
-
hapi.convertTransformQuatToMatrix
Converts hapi.Transform into a 4×4 transform matrix.
-
Initiate a cook on this node. Note that this may trigger
-
Starts a PDG cooking operation. This can be asynchronous.
-
Creates the required node hierarchy needed for heightfield inputs.
-
hapi.createHeightfieldInputVolumeNode
Creates a volume input node that can be used with Heightfields
-
Creates a new in-process session. There can only be
-
Creates a simple geometry SOP node that can accept geometry input.
-
Create a node inside a node network. Nodes created this way
-
hapi.createThriftNamedPipeSession
Creates a Thrift RPC session using a Windows named pipe
-
hapi.createThriftSocketSession
Creates a Thrift RPC session using a TCP socket as transport.
-
Creates a new pending workitem for the given node. The workitem
-
Delete an attribute from an input geo
-
Remove a group from the input geo with the given type and name.
-
Delete a node from a node network. Only nodes with their
-
Dirties the given node. Cancels the cook if necessary and then
-
Disconnect a node input.
-
Disconnect all of the node’s output connections at the output index.
-
Extract a rendered image to a file.
-
Extract a rendered image to memory.
-
Get the number of currently active caches.
-
Get the names of the currently active caches.
-
hapi.getAssetDefinitionParmCounts
Get the number of asset parameters contained in an asset
-
hapi.getAssetDefinitionParmInfos
Fill an array of hapi.ParmInfo structs with parameter
-
hapi.getAssetDefinitionParmValues
Fill arrays of parameter int values, float values, string values,
-
Fill an asset_info struct from a node.
-
hapi.getAttributeFloat64ArrayData
Get array attribute 64-bit float data.
-
Get 64-bit attribute float data.
-
hapi.getAttributeFloatArrayData
Get array attribute float data.
-
Get attribute float data.
-
Get the attribute info struct for the attribute specified by name.
-
hapi.getAttributeInt64ArrayData
Get array attribute 64-bit integer data.
-
Get attribute 64-bit integer data.
-
Get array attribute integer data.
-
Get attribute integer data.
-
Get list of attribute names by attribute owner. Note that the
-
hapi.getAttributeStringArrayData
Get array attribute string data.
-
Get attribute string data. Note that the string handles
-
Get the number of assets contained in an asset library.
-
Get the names of the assets contained in an asset library.
-
Get the box info on a geo part (if the part is a box).
-
Lets you inspect specific properties of the different memory
-
Get the composed list of child node ids from the previous call
-
hapi.getComposedNodeCookResult
Return cook result string message on a single node.
-
Fill an array of hapi.ObjectInfo structs.
-
hapi.getComposedObjectTransforms
Fill an array of hapi.Transform structs.
-
Return the connection error message.
-
Return the length of string buffer storing connection error
-
Get current number of nodes that have already cooked in the
-
Get total number of nodes that need to cook in the current
-
Retrieve the number of vertices for each curve in the part.
-
Retrieve any meta-data about the curves, including the
-
Retrieve the knots of the curves in this part.
-
Retrieve the orders for each curve in the part if the
-
Get the display geo (SOP) node inside an Object node. If there
-
Gives back a certain environment integers like version number.
-
Get the array of faces where the nth integer in the array is
-
Iterate through a volume based on 8×8×8 sections of the volume
-
Get the geometry info struct (::HAPI_GeoInfo) on a SOP node.
-
Cache the current state of the geo to memory, given the
-
hapi.getGroupCountOnPackedInstancePart
Get group counts for a specific packed instanced part.
-
Get group membership.
-
hapi.getGroupMembershipOnPackedInstancePart
Get group membership for a packed instance part
-
Get group names for an entire geo. Please note that this
-
hapi.getGroupNamesOnPackedInstancePart
Get the group names for a packed instance part
-
Gets the number of nodes that were created as a result of loading a
-
Fills an array of HAPI_NodeIds of nodes that were created as a
-
Fill an array of hapi.HandleBindingInfo structs with information
-
Fill an array of hapi.HandleInfo structs with information
-
Get the height field data for a terrain volume as a flattened
-
Get the file name that this image would be saved to
-
Get information about the image that was just rendered, like
-
Fill your allocated buffer with the just extracted
-
Get the number of image planes for the just rendered image.
-
Get the names of the image planes of the just rendered image.
-
hapi.getInstanceTransformsOnPart
Fill an array of hapi.Transform structs with the transforms
-
Get the node ids for the objects being instanced by an
-
Get the part ids that this instancer part is instancing.
-
hapi.getInstancerPartTransforms
Get the instancer part’s list of transforms on which to
-
Get the root node of a particular network type (ie. OBJ).
-
Get the material info.
-
hapi.getMaterialNodeIdsOnFaces
Get material ids by face/primitive. The material ids returned
-
Iterate through a volume based on 8×8×8 sections of the volume
-
Fill an hapi.NodeInfo struct.
-
Get the name of an node’s input. This function will return
-
Get the name of an node’s output. This function will return
-
Get the node absolute path in the Houdini node network or a
-
Gets the number of workitems that are available on the given node.
-
Get the object info on an OBJ node.
-
Get the tranform of an OBJ node.
-
Gets the node id of an output node in a SOP network.
-
Returns PDG events that have been collected. Calling this function
-
Get the PDG graph context for the specified TOP node.
-
Return an array of PDG graph context names and ids, the first
-
Gets the state of a PDG graph
-
Fill an array of hapi.ParmInfo structs with parameter
-
Fill an array of hapi.ParmChoiceInfo structs with parameter
-
Get single integer or float parm expression by name
-
Extract a file specified by path on a parameter. This will copy
-
Get single parm float value by name.
-
Fill an array of parameter float values. This is more efficient
-
All parameter APIs require a HAPI_ParmId but if you know the
-
Get the parm info of a parameter by parm id.
-
Get the parm info of a parameter by name.
-
Get single parm int value by name.
-
Fill an array of parameter int values. This is more efficient
-
Get a single node id parm value of an Op Path parameter. This is
-
Get single parm string value by name.
-
Fill an array of parameter string handles. These handles must
-
Get the tag name on a parameter given an index.
-
Get the tag value on a parameter given the tag name.
-
Get the first parm with a specific, ideally unique, tag on it.
-
Get a particular part info struct.
-
Generates a preset for the given asset.
-
Generate a preset blob of the current state of all the
-
Get environment variable from the server process as an integer.
-
Get environment variable from the server process as a string.
-
Provides the number of environment variables that are in
-
Provides a list of all of the environment variables
-
Gives back a certain session-specific environment integers
-
Get the hapi.SessionSyncInfo for synchronizing SessionSync
-
Get the sphere info on a geo part (if the part is a sphere).
-
Gives back the status code for a specific status type.
-
Return status string message.
-
Return length of string buffer storing status string message.
-
Gives back the string value of the string with the
-
Gives back the values of the given string handles.
-
Gives back the length of the buffer needed to hold
-
Gives back the string length of the string with the
-
hapi.getSupportedImageFileFormatCount
Get the number of supported texture file formats.
-
hapi.getSupportedImageFileFormats
Get a list of support image file formats - their names,
-
Gets the global time of the scene. All API calls deal with
-
Gets the current global timeline options.
-
Get the specified node’s total cook count, including
-
Returns whether the Houdini session will use the current time in
-
Get array containing the vertex-point associations where the
-
Get the hapi.Viewport info for synchronizing viewport in
-
Get the bounding values of a volume.
-
Retrieve any meta-data about the volume primitive, including
-
Retrieve floating point values of the voxels pointed to
-
Retrieve integer point values of the voxels pointed to
-
Retrieve the visualization meta-data of the volume.
-
Retrieve floating point values of the voxel at a specific
-
Retrieve integer point values of the voxel at a specific
-
Gets the length of the workitem data member.
-
Gets float data from a work item member.
-
Retrieves the info of a given workitem by id.
-
Gets int data from a work item member.
-
Gets the info for workitem results.
-
Gets string ids from a work item member.
-
Gets the list of work item ids for the given node
-
Create the asset manager, set up environment variables, and
-
Insert an instance of a multiparm before instance_position.
-
Interrupt a cook or load operation.
-
Check whether the runtime has been initialized yet using
-
Determine if your instance of the node actually still exists
-
Checks whether the session identified by hapi.Session.id is
-
Loads a Houdini asset library (OTL) from a .otl file.
-
hapi.loadAssetLibraryFromMemory
Loads a Houdini asset library (OTL) from memory.
-
Loads a geometry file and put its contents onto a SOP
-
Loads a geometry from memory and put its
-
Loads a .hip file into the main Houdini scene.
-
Loads and creates a previously saved node and all
-
Loads a .hip file into the main Houdini scene.
-
See if a parameter has an expression
-
See if a parameter has a specific tag.
-
Pause the PDG cooking operation.
-
hapi.pythonThreadInterpreterLock
Acquires or releases the Python interpreter lock. This is
-
Query which node is connected to another node’s input.
-
hapi.queryNodeOutputConnectedCount
Get the number of nodes currently connected to the given node at
-
hapi.queryNodeOutputConnectedNodes
Get the ids of nodes currently connected to the given node
-
Removes the specified string from the server
-
Remove the instance of a multiparm given by instance_position.
-
Remove the expression string, leaving the value of the
-
Rename a node that you created. Only nodes with their
-
Render a single texture from a COP to an image for
-
Render only a single texture to an image for later extraction.
-
Resets the simulation cache of the asset. This is very useful
-
Remove all changes that have been committed to this
-
Revert single parm by name to default
-
Revert all instances of the parm by name to defaults
-
Saves a geometry to file. The type of file to save is
-
Saves the cached geometry to your buffer in memory,
-
Saves a .hip file of the current Houdini scene.
-
Saves the node and all its contents to file.
-
Set an animation curve on a parameter of an exposed node.
-
Set 64-bit attribute float data.
-
Set attribute float data.
-
Set 64-bit attribute integer data.
-
Set attribute integer data.
-
Set attribute string data.
-
Lets you modify specific properties of the different memory
-
Set the number of vertices for each curve in the part.
-
Set meta-data for the curve mesh, including the
-
Set the knots of the curves in this part.
-
Set the orders for each curve in the part if the
-
Adds the given string to the string table and returns
-
Set the array of faces where the nth integer in the array is
-
Set group membership.
-
Set the height field data for a terrain volume with the values from
-
Set image information like resolution and file format.
-
Set the specified node’s display flag.
-
Set the transform of an individual object. Note that the object
-
Set (push) an expression string. We can only set a single value at
-
Set single parm float value by name.
-
Set (push) an array of parameter float values.
-
Set single parm int value by name.
-
Set (push) an array of parameter int values.
-
Set a node id parm value of an Op Path parameter. For example,
-
Set (push) a string value. We can only set a single value at
-
Set the main part info struct (::HAPI_PartInfo).
-
Sets a particular asset to a given preset.
-
Set environment variable for the server process as an integer.
-
Set environment variable for the server process as a string.
-
Enable or disable SessionSync mode.
-
Set the hapi.SessionSyncInfo for synchronizing SessionSync
-
Sets the global time of the scene. All API calls will deal
-
Sets the global timeline options.
-
A specialized convenience function to set the T,R,S values
-
Sets whether the Houdini session should use the current time in
-
Set array containing the vertex-point associations where the
-
Set the hapi.Viewport info for synchronizing viewport in
-
Set the volume info of a geo on a geo input.
-
Set the values of a float tile: this is an 8×8×8 subsection of
-
Set the values of an int tile: this is an 8×8×8 subsection of
-
Set the values of a float voxel in the volume.
-
Set the values of a integer voxel in the volume.
-
Adds float data to a pending PDG workitem data member for the given node.
-
Adds integer data to a pending PDG workitem data member for the given node.
-
Adds integer data to a pending PDG workitem data member for the given node.
-
hapi.startThriftNamedPipeServer
Starts a Thrift RPC server process on the local host serving
-
Starts a Thrift RPC server process on the local host serving
types
-
Enumeration hapi.attributeOwner
-
Enumeration hapi.attributeTypeInfo
-
Enumeration hapi.choiceListType
-
Enumeration hapi.curveOrders
-
Enumeration hapi.curveType
-
Enumeration hapi.errorCode
-
Enumeration hapi.geoType
-
Enumeration hapi.groupType
-
Enumeration hapi.imageDataFormat
-
Enumeration hapi.imagePacking
-
Enumeration hapi.inputType
-
Enumeration hapi.license
-
Enumeration hapi.nodeType
-
Enumeration hapi.packedPrimInstancingMode
-
Enumeration hapi.partType
-
Enumeration hapi.permissions
-
Enumeration hapi.presetType
-
Enumeration hapi.rampType
-
Enumeration hapi.result
-
Enumeration hapi.rstOrder
-
Enumeration hapi.sessionType
-
Enumeration hapi.state
-
Enumeration hapi.statusType
-
Enumeration hapi.statusVerbosity
-
Enumeration hapi.storageType
-
Enumeration hapi.transformComponent
-
Enumeration hapi.volumeType
-
Enumeration hapi.volumeVisualType
-
Enumeration hapi.xyzOrder