These objects represent an active or potential connection to a Houdini clone process, either on the local machine or a remote machine. A connection can be connected and disconnected repeatedly, but the object continues to be valid. As with hou.Node objects, objects of thie type are references to the underlying connection object owned by the Houdini cloning framework. This means that all instances of this class that refer to the same underlying clone connection will affect each other. The underlying object can even be deleted in which case almost all methods on this object will raise exceptions (though the hou.clone.Connection.isValid method can be used to test if the underlying object still exists without raising an exception).
Clone connections are identified by a unique session id string which behaves much like a Houdini node name. At any given time, the session id for each clone connection is unique. But session ids can be reused if a connection is deleted and a new one created. Clones connections are saved to the hip file, and are automatically disconnected when Huodini is shut down or a new hip file is opened. When opening a hip file, the loaded connection objects are always left in a disconnected state, and must be explicitly connected to start the clones processes.
New connections can only be created by calling hou.clone.createClone() or hou.clone.Connection.duplicate. Existing connection can be accessed using hou.clone.clone() or hou.clone.clones().
Methods ¶
isValid()
→ bool
Return True if the connection associated with this object is still valid. Valid simply means that the underlying connection has not been deleted. This method and hou.clone.Connection.sessionId are the only methods that will not raise an exception when run after the underlying connection has been deleted.
sessionId()
→ str
Return the unique string that can be used to identify this connection object, or fetch it from the cloning framework using the hou.clone.clone() method. This value is set when constructing the connection and cannot be changed. This value has limitations like those for node names.
name()
→ str
Return the user-facing name for this clone.
setName(name)
Checng the user-facing name for this clone. This is the name shown in the Clone control pane, and does not have any restrictions on its value (spaces and punctuation are allowed).
lopNode()
→ hou.LopNode
Return the LOP node that defines the stage which will be rendered by this clone.
setLopNode(lop)
Set the LOP node that defines the stage which will be rendered by this clone. This value must be set for the clone to generate an image.
cameraPath()
→ str
Return the USD primitive path of the camera prim that defines the view that will be rendered by this clone.
setCameraPath(camerapath)
Set the USD primitive path of the camera prim that defines the view that will be rendered by this clone. This path should point to a USD Camera primitive on the stage defined by the hou.clone.Connection.lopNode. This value must be set for the clone to generate an image.
renderer()
→ str
Return the name of the Render Delegate this clone will use.
setRenderer(renderer)
Set the name of the Render Delegate this clone will use. This can be the internal name or label of any render delegate installed on the computer running this clone.
renderSettings()
→ str
Return the USD primitive path of the render settings prim that controls therendering configurations for this clone.
setRenderSettings(rendersettings)
Return the USD primitive path of the render settings prim that controls therendering configurations for this clone. This path should point to a USD Render Settings primitive on the stage defined by the hou.clone.Connection.lopNode.
availableAovs()
→ tuple
of str
Return the names of all AOVs generated by the clone render. This will return an empty tuple if the clone has not yet returned an image.
displayAov()
→ str
Return the name of the AOV this clone should return to the host. This string may contain wildcards in which case multiple matching AOVs may be returned.
setDisplayAov(aov)
Set the name of the AOV this clone should return to the host. A string matching pattern can be specified to return multiple AOVs. Passing an empty string or None for the aov parameter instructs the clone to return all AOVs.
resolutionScale()
→ float
Return the override resolution scale factor. This scaling is applied to the resolution set on the render settings for this clone. A value of 0 indicates that the render settings resolution will be used. A non-zero resolution scale value takes precedence over an override resolution explicitly set using setResolution.
setResolutionScale(resolution_scale)
Set the resolution scale for the image generated by this clone. This scale value is always applied to the resolution set on the render settings primitive. The value can be less than one to render a lower resolution image, or greater than one to render a higher resolution image. A value of 0 disables the resolution scaling.
resolution()
→ (int
, int
)
Return the override resolution set for the clone’s returned image. If no override resolution has been set, this method returns (0, 0). In this case, the clone will generate an image with a resolution determined by the render settings primitive. A non-zero resolution scale value takes precedence over an override resolution explicitly set using setResolution, but the resolution scale setting does not affect the value returned by this method.
setResolution(width, height)
Set the resolution of the image generated by this clone. Specifying a width and height of 0 instructs the clone to generate an image with a resolution determined by the render settings primitive. A non-zero resolution scale value set with setResolutionScale takes precedence over an override resolution explicitly set using this method.
frameExpression()
→ str
Return a string specifying the expression that is run to generate the frame to which this clone should be set when cooking. If the returned string is empty, the frame number used by the clone will match the host’s current frame number.
setFrameExpression(expression)
Set the expression that is run to generate the frame to which this clone should be set when cooking. The expression must always be a string, but can be any hscript expression that returns a number. For example, $F + 10 instructs the clone to cook ten frames ahead of the host’s current frame. The expression is run in the host process, and the resulting value is sent to the clone.
contextOptionExpression(opt)
→ str
Return a string specifying the expression that is run to generate the value for the context option opt that this clone will use when cooking. If the returned string is empty, the context option value used by the clone will match the host’s value for this option.
setContextOptionExpression(opt, expression)
Set the expression that is run to generate the the value for the context option opt that this clone use when cooking. The expression must always be a string, but can be any hscript expression that returns a number or string. For example, $SHOT + 1 instructs the clone to cook with a value for SHOT that is one more than the host’s value for this option. The expression is run in the host process, and the resulting value is sent to the clone.
contextOptionsWithExpressions()
→ str
Return a tuple of context option names that have expressions set for this clone, and thus where the clone’s value for these context options may differ from the host process.
setProcessUpdates(process_updates)
Configure the clone process to ignore updates from the host process, and continue rendering whatever stage is currently being rendered.
processUpdates()
→ bool
Return a boolean value indicating whether the clone will restart its render in response to updates from the host.
setLauncherConfig(config)
Store the dictionary of launcher configuration options that should be used when launching this clone process. The contents and interpretation of this dictionary is under the discretion of the launcher plugin. It is stored with the clone connection object for convenience since launching a clone process is generally a pre-requisite to connecting to the clone.
launcherConfig()
→ dict
Return a dictionary of configuration options that control the launcher plugin when starting up this clone process.
connect(host, port)
→ bool
Connect this host to a running clone process on the specified host machine accessible through the provided TCP/IP port number. The connection attempt lasts for one second. If the connection is made, this method returns True. Returns False if the connection cannot be made for any reason. The host and port values are generally provided by the launcher plugin, which starts the clone process and reads the output from the process to determine the port number (which is output by the hou.clone.runAsClone() method.
isConnected()
→ bool
Return true if this clone connection object represents an active connection to a clone process.
host()
→ str
Return the name of the host machine on which the connected clone process is running. Returns an empty string if there is no connected clone process.
port()
→ int
Return the port number used to connect to this object’s clone process. Returns 0 if there is no connected clone process.
setWaitingToConnect(waiting_to_connect)
Sets a flag on this connection indicating that it is waiting to connect to a clone process. This flag is only used as a visual hint and does not affect the operation of the clone framework. This flag can be set whether the clone is connected or disconnected. Only launcher plugins should set this flag, and only while waiting for a clone process to initialize or for a connection to be made to the clone process. Calling disconnect will also set this flag to False.
isWaitingToConnect()
→ bool
Return true if setWaitingToConnect(True) has been called on this connection.
disconnect()
Disconnects from a connected clone process. Does nothing if the clone is not currently connected.
imagePath()
→ str
Returns a string that can be used to access the image most recently returned by this clone. This string generally does not change when new images are sent from the clone, but this is not guaranteed. The format of this string will be of the form membuf:XXXXX. This unusual “path” value indicates that the image is not written to disk, but instead exists only as a block of memory. But Houdini nodes and HOM methods which can load images from disk will also be able to load the rendered image using this membuf path.
imageSize()
→ tuple
of int
Returns a tuple of two integers that are the width and height of the image most recently returned by this clone. Note that the image size may change any time a new image is sent to the host if the resolution parameters or render settings primitive has changed. Becuase this is the true size of the most recently sent image, this value may differ from the resolution requested from this clone through the setResolution method.
imageVersion()
→ int
A number that is increased every time a new image is sent to the host by this clone. This number can be used to detect when the image needs to be reloaded, redrawn, or otherwise re-processed to account for the updated image.
percentComplete()
→ float
Indicates the progress of the render as reported through the render statistics.
renderGalleryDataSource()
→ hou.AssetGalleryDataSource
If this clone is currently connected and rendering, the resulting images are placed into the snapshot gallery for the target LOP Network. This method returns a hou.AssetGalleryDataSource that provides access to the snapshot gallery database in which the image metadata is stored. If this clone is not connected or has not generated any image data yet, this method returns None.
renderGalleryItemId()
→ str
If this clone is currently connected and rendering, the resulting images are placed into the snapshot gallery for the target LOP Network. This method returns the unique identifier of this image’s entry in the snapshot gallery database. This identifier can be passed to the hou.AssetGalleryDataSource object returned by the renderGalleryDataSource method to look up additional information about the image. If this clone is not connected or has not generated any image data yet, this method returns an empty string.
createSnapshot()
→ str
If this clone is currently connected and rendering, this method creates a snapshot in the LOP Network’s snapshot gallery database, along with the current state of the LOP Network’s nodes, just as when hitting the snapshot button to save the current viewport contents. The snapshot will contain all AOVs currently being sent from the clone process. Returns the snapshot gallery item identifier of the newly created snapshot. Returns an empty string if no snapshot could be created, or the clone is not connected or doesn’t have image data avilable.
duplicate()
→ hou.clone.Connection
Makes a copy of this clone object. All the settings and configuration information is duplicated. The new clone does not launch or connect to a new clone process even if this clone connection is currently active. This must be done explicitly, after creating the duplicate.