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, cook_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 ¶
Animation ¶
-
Set an animation curve on a parameter of an exposed node.
-
A specialized convenience function to set the T,R,S values
Assets ¶
-
hapi.getAssetDefinitionParmCounts
Get the number of asset parameters contained in an asset
-
hapi.getAssetDefinitionParmInfos
Fill an array of structs with parameter
-
hapi.getAssetDefinitionParmValues
Fill arrays of parameter int values, float values, string values,
-
Fill an asset_info struct from a node.
-
Get the number of assets contained in an asset library.
-
Get the names of the assets contained in an asset library.
-
Loads a Houdini asset library (OTL) from a .otl file.
-
hapi.loadAssetLibraryFromMemory
Loads a Houdini asset library (OTL) from memory.
Attributes ¶
-
Get the attribute info struct for the attribute specified by name.
-
Get list of attribute names by attribute owner. Note that the
Caching ¶
-
Get the number of currently active caches.
-
Get the names of the currently active caches.
-
Lets you inspect specific properties of the different memory
-
Cache the current state of the geo to memory, given the
-
Loads a geometry file and put its contents onto a SOP
-
Loads a geometry from memory and put its
-
Loads and creates a previously saved node and all
-
Saves a geometry to file. The type of file to save is
-
Saves the cached geometry to your buffer in memory,
-
Saves the node and all its contents to file.
-
Lets you modify specific properties of the different memory
classes ¶
-
Class hapi.MaterialInfo
Curves ¶
-
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
-
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
Environment ¶
-
Gives back a certain environment integers like version number.
-
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
-
Set environment variable for the server process as an integer.
-
Set environment variable for the server process as a string.
Geometry ¶
-
Get the box info on a geo part (if the part is a box).
-
Get the sphere info on a geo part (if the part is a sphere).
GeometryGetters ¶
-
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.
-
hapi.getAttributeInt16ArrayData
Get array attribute 16-bit integer data.
-
Get attribute 16-bit integer data.
-
hapi.getAttributeInt64ArrayData
Get array attribute 64-bit integer data.
-
Get attribute 64-bit integer data.
-
hapi.getAttributeInt8ArrayData
Get array attribute 8-bit integer data.
-
Get attribute 8-bit integer data.
-
Get array attribute integer data.
-
Get attribute integer data.
-
hapi.getAttributeStringArrayData
Get array attribute string data.
-
Get attribute string data. Note that the string handles
-
hapi.getAttributeUInt8ArrayData
Get array attribute unsigned 8-bit integer data.
-
Get attribute unsigned 8-bit integer data.
-
Get the display geo (SOP) node inside an Object node. If there
-
Get the array of faces where the nth integer in the array is
-
Get the geometry info struct (::HAPI_GeoInfo) on a SOP node.
-
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
-
Get the part ids that this instancer part is instancing.
-
hapi.getInstancerPartTransforms
Get the instancer part’s list of transforms on which to
-
Get a particular part info struct.
-
Get array containing the vertex-point associations where the
GeometrySetters ¶
-
Add an attribute.
-
Add a group to the input geo with the given type and name.
-
Commit the current input geometry to the cook engine. Nodes
-
Delete an attribute from an input geo
-
Remove a group from the input geo with the given type and name.
-
Remove all changes that have been committed to this
-
Set 64-bit attribute float data.
-
Set attribute float data.
-
Set 16-bit attribute integer data.
-
Set 64-bit attribute integer data.
-
Set 8-bit attribute integer data.
-
Set attribute integer data.
-
Set attribute string data.
-
Set unsigned 8-bit attribute integer data.
-
Set the array of faces where the nth integer in the array is
-
Set group membership.
-
Set the main part info struct (::HAPI_PartInfo).
-
Set array containing the vertex-point associations where the
HeightFields ¶
-
Creates the required node hierarchy needed for heightfield inputs.
-
hapi.createHeightfieldInputVolumeNode
Creates a volume input node that can be used with Heightfields
HipFiles ¶
-
Gets the number of nodes that were created as a result of loading a
-
Fills an array of HAPI_NodeId of nodes that were created as a
-
Loads a .hip file into the main Houdini scene.
-
Loads a .hip file into the main Houdini scene.
-
Saves a .hip file of the current Houdini scene.
Materials ¶
-
Extract a rendered image to a file.
-
Extract a rendered image to memory.
-
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.
-
Get the material info.
-
hapi.getMaterialNodeIdsOnFaces
Get material ids by face/primitive. The material ids returned
-
hapi.getSupportedImageFileFormatCount
Get the number of supported texture file formats.
-
hapi.getSupportedImageFileFormats
Get a list of support image file formats - their names,
-
Render a single texture from a COP to an image for
-
Render only a single texture to an image for later extraction.
-
Set image information like resolution and file format.
Nodes ¶
-
Compose a list of child nodes based on given filters.
-
Connect two nodes together.
-
Initiate a cook on this node. Note that this may trigger
-
Creates a simple geometry SOP node that can accept geometry input.
-
Create a node inside a node network. Nodes created this way
-
Delete a node from a node network. Only nodes with their
-
Disconnect a node input.
-
Disconnect all of the node’s output connections at the output index.
-
Get the composed list of child node ids from the previous call
-
Get the root node of a particular network type (ie. OBJ).
-
Get the id of the node with the specified path.
-
Fill an 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 node id of an output node in a SOP network.
-
Get the specified node’s total cook count, including
-
Determine if your instance of the node actually still exists
-
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
-
Rename a node that you created. Only nodes with their
-
Set the specified node’s display flag.
Objects ¶
-
Compose a list of child object nodes given a parent node id.
-
Fill an array of structs.
-
hapi.getComposedObjectTransforms
Fill an array of structs.
-
hapi.getInstanceTransformsOnPart
Fill an array of structs with the transforms
-
Get the node ids for the objects being instanced by an
-
Get the object info on an OBJ node.
-
Get the tranform of an OBJ node.
-
Set the transform of an individual object. Note that the object
Parms ¶
-
Fill an array of structs with information
-
Fill an array of structs with information
-
Fill an array of structs with parameter
-
Fill an array of 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.
-
Insert an instance of a multiparm before instance_position.
-
See if a parameter has an expression
-
See if a parameter has a specific tag.
-
Remove the instance of a multiparm given by instance_position.
-
Remove the expression string, leaving the value of the
-
Revert single parm by name to default
-
Revert all instances of the parm by name to defaults
-
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
PDG ¶
-
Cancel the PDG cooking operation.
-
Commits any pending workitems.
-
Starts a PDG cooking operation. This can be asynchronous.
-
Creates a new pending workitem for the given node. The workitem
-
Dirties the given node. Cancels the cook if necessary and then
-
Gets the number of workitems that are available on the given node.
-
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
-
Return the total number of PDG graph contexts found.
-
Gets the state of a PDG graph
-
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
-
Pause the PDG cooking operation.
-
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.
Presets ¶
-
Generates a preset for the given asset.
-
Generate a preset blob of the current state of all the
-
Sets a particular asset to a given preset.
Sessions ¶
-
Binds a new implementation DLL to one of the custom session
-
Clean up memory. This will unload all assets and you will
-
Closes a session. If the session has been established using
-
Creates a new in-process session. There can only be
-
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.
-
Create the asset manager, set up environment variables, and
-
Check whether the runtime has been initialized yet using
-
Checks whether the session identified by is
-
hapi.startThriftNamedPipeServer
Starts a Thrift RPC server process on the local host serving
-
Starts a Thrift RPC server process on the local host serving
SessionSync ¶
-
Get the for synchronizing SessionSync
-
Get the info for synchronizing viewport in
-
Enable or disable SessionSync mode.
-
Set the for synchronizing SessionSync
-
Set the info for synchronizing viewport in
Status ¶
-
Recursively check for specific errors by error code on a node.
-
Clears the connection error. Should be used before starting
-
Compose the cook result string (errors and warnings) of a
-
hapi.getComposedNodeCookResult
Return cook result string message on a single node.
-
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
-
Gives back the status code for a specific status type.
-
Return status string message.
-
Return length of string buffer storing status string message.
-
Interrupt a cook or load operation.
Strings ¶
-
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
-
Removes the specified string from the server
-
Adds the given string to the string table and returns
Time ¶
-
Gets the global time of the scene. All API calls deal with
-
Gets the current global timeline options.
-
Returns whether the Houdini session will use the current time in
-
Resets the simulation cache of the asset. This is very useful
-
Sets the global time of the scene. All API calls will deal
-
Sets the global timeline options.
-
Sets whether the Houdini session should use the current time in
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
Utility ¶
-
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.convertTransformEulerToMatrix
Converts into a 4×4 transform matrix.
-
hapi.convertTransformQuatToMatrix
Converts into a 4×4 transform matrix.
-
hapi.pythonThreadInterpreterLock
Acquires or releases the Python interpreter lock. This is
Volumes ¶
-
Iterate through a volume based on 8×8×8 sections of the volume
-
Get the height field data for a terrain volume as a flattened
-
Iterate through a volume based on 8×8×8 sections of the volume
-
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
-
Set the height field data for a terrain volume with the values from
-
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.