HOM Binary Data

How to get binary data from the HOM API in Python 3.

On this page

Overview
Converting bytes to/from str binary data objects in Python 3
Tips and notes

Overview ¶

The HOM API was originally designed for Python 2, so functions that return binary data, such as hou.AgentClip.data, hou.Parm.clipData, and hou.ChopNode.clipData, return str objects in Python 2.
Similarly, functions that accept binary data, such as hou.Cop2Node.setPixelsOfCookingPlaneFromString and hou.Parm.setClipData, expect str objects in Python 2.
In Python 3, these functions use bytes objects to represent binary data.
When passing binary data between HOM functions, you do not need to modify your code when migrating from Python 2 to Python 3. For example, this code works in both the Python 2 and Python 3 Houdini builds:
```
#
# Works for both Python 2 and 3.
#

parm = hou.parm("/obj/geo1/tx")
binary_clip_data = parm.clipData(1, 100)

parm2 = hou.parm("/obj/geo1/ty")
parm2.setClipData(binary_clip_data)
```

In Python 3, you do have to be mindful when passing binary data to Python functions that expect a str object rather than a bytes object.

For example:

parm = hou.parm("/obj/geo1/tx")
binary_clip_data = parm.clipData(1, 100)

# Works in Python 2, but fails in Python 3.
# The file is opened in text mode and expects `str` objects to write.
str_file = open("anim.bclip", "w")
str_file.write(binary_clip_data)

# Works in both Python 2 and Python 3.
# The file is opened in binary mode and expects `bytes` objects to write
# in Python 3, but still `str` objects in Python 2.
str_file = open("anim.bclip", "wb")
str_file.write(binary_clip_data)

You can convert from bytes objects to str objects in order to pass binary data to Python string functions using the method described below. Similarly, you can convert str objects containing binary data to bytes objects that can be passed into HOM binary data functions.

Converting bytes to/from str binary data objects in Python 3 ¶

To... Do this

To...	Do this
Convert `bytes` returned from HOM into `str`	Use `bytes.decode(errors="surrogateescape")`. For example: # Get binary data from AgentClip method. binary_data = agent_clip.data(True) # Convert to a `str` object. str_binary_data = binary_data.decode(errors="surrogateescape") # Write `str` object out to an opened file in text mode. open("agent.bclip", "w").write(str_binary_data)
Convert `str` into `bytes` to pass into HOM	Use `str.encode(errors="surrogateescape")`. For example: # Convert `str` binary data to `bytes`. binary_pixel_data = str_binary_pixel_data.encode(errors="surrogateescape") # Pass binary data to HOM Cop2Node method. cop_node.setPixelsOfCookingPlaneFromString(binary_pixel_data)
Get an array of numbers from a `bytes` object	Often, instead of raw bytes, you want the sequence of numbers represented by the bytes. The Python `array` object lets you interpret packed binary as regular Python ints or floats. import array data_bytes = cop_node.pixelsOfCookingPlaneAsString() # "i" for ints, "f" for floats, "q" for 64 bit ints, "d" for double floats # See Python documentation for the array module arry = array("i") arry.frombytes(data_bytes) for x in arry: print(x)

Convert bytes returned from HOM into str

Use bytes.decode(errors="surrogateescape"). For example:

# Get binary data from AgentClip method.
binary_data = agent_clip.data(True)

# Convert to a `str` object.
str_binary_data = binary_data.decode(errors="surrogateescape")

# Write `str` object out to an opened file in text mode.
open("agent.bclip", "w").write(str_binary_data)

Convert str into bytes to pass into HOM

Use str.encode(errors="surrogateescape"). For example:

# Convert `str` binary data to `bytes`.
binary_pixel_data = str_binary_pixel_data.encode(errors="surrogateescape")

# Pass binary data to HOM Cop2Node method.
cop_node.setPixelsOfCookingPlaneFromString(binary_pixel_data)

Get an array of numbers from a bytes object

Often, instead of raw bytes, you want the sequence of numbers represented by the bytes. The Python array object lets you interpret packed binary as regular Python ints or floats.

import array

data_bytes = cop_node.pixelsOfCookingPlaneAsString()

# "i" for ints, "f" for floats, "q" for 64 bit ints, "d" for double floats
# See Python documentation for the array module
arry = array("i")
arry.frombytes(data_bytes)

for x in arry:
    print(x)

Tips and notes ¶

This escaping results in a very large unicode string compared to the raw bytes (often one byte of data is expanded to 5 escape characters).
The hou.convertClipData() function is for “converting binary clip data to and from ASCII”. Note that this has nothing to do with str or bytes. Instead, it refers to the ASCII (“human readable”, .clip) version of the Houdini animation clip format, and the binary (.bclip) version.

HOM Binary Data

Overview ¶

Converting bytes to/from str binary data objects in Python 3 ¶

Tips and notes ¶

Python scripting

Getting started ¶

Next steps ¶

Reference ¶

Guru level ¶

Python viewer states ¶

Python viewer handles ¶

Plugin types ¶