Houdini 18.5 Python scripting

HOM Binary Data

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

On this page

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.CopNode.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

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 CopNode 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.

See also

Python scripting

Getting started

Next steps

Python viewer states

You can write viewer states in Python that let you customize user interaction in the viewport for your node.

Python viewer handles

You can write viewer handles in Python to draw controls to manipulate node values such as parameters.

Guru level

Reference

  • hou

    Module containing all the sub-modules, classes, and functions to access Houdini.

  • Alembic extension functions

    Utility functions for extracting information from Alembic files.