1. Choose File ▸ New operator type.

2. Set the Operator style to Python, then set Network type to Compositing Filter or Compositing Generator.

3. Use the Save to library option to set an OTL library file to save the new node type into.

4. Click Accept.

   The type properties window appears.

5. Use the options in the type properties window to define the interface for your new node type.

6. Click the Code tab to view and edit the Python code that defines the COP’s behavior.

A Python COP filter produces new image data based on image data from one or more input nodes. Each node in COPs stores a number of image planes, and each plane is cooked separately. Every COP has a C (color) and an A (alpha) plane, but a cop may create more planes. Image planes in COPs are cooked on demand, so some planes may not cook unless the viewer or an output COP asks for those planes.

Writing a COP node type using Python is different than writing, say, a SOP or Object node type in Python. While Python SOPs and Objects evaluate the Python code in the Code tab whenever the node cooks, Python COPs instead call specially-named functions defined in the Code tab.

When writing a Python COP filter, provide definitions of the following functions in the Code tab:

Notes:

• When calling allPixels\[AsString\] or setPixelsOfCookingPlane\[FromString\], scanlines are ordered with the bottom scanline first.

• You must pass in the correct data size to setPixelsOfCookingPlane*, or Houdini will raise a hou.OperationFailed exception. This function can accept interleaved data or set the red, green, and blue components in three separate calls. See hou.CopNode.setPixelsOfCookingPlane() for more information.

• allPixels returns each component (e.g. red, green, blue, alpha, etc.) in each pixel of the input image planes as a 32-bit float value, regardless of the bit depth the input cop uses to store the data. For example, if the input cop stores the "C" plane as an 8-bit unsigned value for the red component, another 8-bit value for the green, and another for the blue, asking for the "C" plane of the input using allPixels will return a 32-bit float red component, a 32-bit float blue, and so on.

• allPixelsAsString can return each component in each pixel of an input image plane in any of the image depths supported by the compositor: 8-bit integer, 16-bit integer, 32-bit integer, 16-bit float, or 32-bit float. To request a particular bit depth, set the depth parameter to a hou.imageDepth enumerated value. If the depth parameter is not specified, the image depth will be the same as the plane being cooked by the COP.

• If your cop says that it cooks a plane by listing it in the return value from output_planes_to_cook but does not call setPixelsOfCookingPlane* from the cook function, Houdini will fill all the pixels of the missing component(s) with zeros.

• Python COPs only allow you to get and set pixels in the frame, not in the full canvas area. In COPs, the frame is the visible region of the plane and corresponds to the image’s resolution. However, a node can store additional pixels outside the frame, and the region of all possible pixels is called the canvas. For example, if you use a transform cop to move the pixels off to the right of the frame, then use another transform cop to move pixels back left, the original pixels will appear in the frame. The reason is that the first transform cop’s canvas extends beyond the frame, so it can cook the pixels outside the frame when the second transform cop asks for them. To make Python COPs simpler, their canvas is always the same size as the frame, and they can only ask for input data that lies within the input’s frame.

• You cannot access pixel data from a cop that is not an input to your node. In other words, do not call allPixels* on a COP node that is not an input to your Python COP.

• If your Python COP has multiple inputs and there may be gaps in the connected inputs, use the hou.Node.inputConnectors() method. For example, if your COP has a maximum of 2 inputs but a minimum of 0, it is possible for the first input to be disconnected and the second to be connected. If you call hou.Node.inputs() it will return only one entry. The following code lets you access an input even when there are gaps:

  input_connections = cop_node.inputConnectors()[input_index]
  if len(input_connections) == 0:
      input_node = None
  else:
      input_node = input_connection[0].inputNode()
  

The difference between a generator and a filter is simply the minimum number of inputs. The same Python COP node type can act as both a filter and a generator. For this section, a generator is simply a COP node without an input and with a minimum number of inputs of zero.

Python COP generators usually override the output_planes_to_cook, resolution, depth, and cook methods.

If Python COP generators do not override resolution, the resolution will be 1×1. If they do not override frame_range, they will generate a still image. If they do not return the "C" and "A" planes from output_planes_to_cook, Houdini will still call cook with those plane names.

By default, planes created by Python COP generators are always 32-bit float. However, by providing a depth function you can make them return any of the image depths supported by the compositor.

This Python COP generator produces a constant color and can take an optional input. When an input is connected, the resolution parameter is ignored and it uses the resolution of the input.

def output_planes_to_cook(cop_node):
    return ("C", "A")

def required_input_planes(cop_node, output_plane):
    return ()

def resolution(cop_node):
    # If we don't have an input, use the value of the resolution parameter.
    if len(cop_node.inputs()) == 0:
        return cop_node.parmTuple("resolution").eval()

    # Use the resolution of the first connected input.
    input_cop = cop_node.inputs()[0]
    return (input_cop.xRes(), input_cop.yRes())

def cook(cop_node, plane, resolution):
    num_pixels = resolution[0] * resolution[1]
    rgba = cop_node.parmTuple("color").eval()
    pixel = (rgba[3:] if plane == "A" else rgba[:3])
    cop_node.setPixelsOfCookingPlane(pixel * num_pixels)

The following Python COP filter does not process any image data, but instead shifts the input sequence by the specified number of frames and then stretches the timing by the specified scale factor. It assumes the node has the following parameters:

import math

def frame_range(cop_node):
    input_cop = cop_node.inputs()[0]
    if input_cop.isSingleImage():
        return None

    start_frame = int(input_cop.sequenceStartFrame() + cop_node.evalParm("frameshift"))
    length_in_frames = int(math.floor(
        input_cop.sequenceFrameLength() * cop_node.evalParm("framescale")))
    return (start_frame, length_in_frames)

def remap_frame(cop_node, frame):
    """Return the frame number in the input required to cook the given frame
    in this node.
    """
    input_cop = cop_node.inputs()[0]
    input_start_frame = input_cop.sequenceStartFrame()
    frame_scale = cop_node.evalParm("framescale")
    frame_shift = cop_node.evalParm("frameshift")

    original_index_in_input = frame - input_start_frame
    remapped_frame_in_input = ((original_index_in_input / frame_scale) +
        input_start_frame - frame_shift)
    return remapped_frame_in_input

def output_planes_to_cook(cop_node):
    # By returning that no planes are cooked, they will be passed through
    # from the input.
    return ()

def cook(cop_node, plane, resolution):
    pass

For a more complicated example that uses the numpy module (included with Houdini) to composite the same foreground image in multiple locations over a background, see the Multi Stamp Python COP example from the HOM cookbook.

Python’s overhead when constructing a list or tuple of many floats can be slow. So, when possible, it is better to use hou.CopNode.allPixelsAsString() instead of hou.CopNode.allPixels(). Using Python’s array module, you can efficiently convert the string data into a sequence of 32-bit floats, as illustrated by the following code:

import array
str_data = input_cop_node.allPixelsAsString("C")
float_data = array.array("f", str_data)

Similarly, it is more efficient to call hou.CopNode.setPixelsOfCookingPlaneFromString() instead of calling hou.CopNode.setPixelsOfCookingPlane() with a list or tuple of floats. While you could convert from an array into a string by calling float_data.tostring(), setPixelsOfCookingPlaneFromString can accept the array object directly:

cop_node.setPixelsOfCookingPlaneFromString(float_data)

Houdini includes the numpy library. You can use it to reinterpret the contents of a binary string as a sequence of 32-bit floats, without having to construct a new copy of the data:

import numpy
str_data = input_cop_node.allPixelsAsString("C")
read_only_float_data = numpy.frombuffer(str_data, dtype=numpy.float32)

String data that has been reinterpreted as float data is read-only. If you want to make a copy of the data to modify it, though, simply call copy() on it:

writable_float_data = read_only_float_data.copy()

To convert the numpy array into a string, you could write str(writable_float_data.data). However, you can pass the numpy array directly into setPixelsOfCookingPlaneFromString:

cop_node.setPixelsOfCookingPlaneFromString(writable_float_data)

Processing one pixel at a time inside a Python loop can be slow. numpy's arrays provide efficient ways to operate on multiple pixels without requiring Python’s looping constructs. The following example implements a node that brightens the pixels in an image. It assumes the COP has a float parameter named bright.

import numpy

def output_planes_to_cook(cop_node):
    return ("C",)

def required_input_planes(cop_node, output_plane):
    if output_plane == "C":
        return ("0", "C")
    return ()

def cook(cop_node, plane, resolution):
    input_cop = cop_node.inputs()[0]

    # Grab the pixels from the corresponding plane in the input, then build
    # a numpy array from the data.
    pixels = numpy.frombuffer(
        input_cop.allPixelsAsString(plane), dtype=numpy.float32).reshape(
        resolution[1], resolution[0], 3).copy()

    # Use numpy to scale all values by the brightness.
    pixels *= cop_node.evalParm("bright")

    # Store the contents of the numpy array back into the pixel data.
    cop_node.setPixelsOfCookingPlaneFromString(pixels.data)

Houdini’s inlinecpp module lets you easily write a portion of your COP in C++.

If you construct an array.array object containing the image data from an input plane, you can pass the address of the array’s underlying buffer into a C++ function and modify the contents of the array with C++ code. The buffer_info method of array objects will return an (address, length) tuple for the underlying buffer, and you can pass the address into an inlinecpp C++ function expecting a float *.

The following example also brightens the pixels in an image, using C++ code instead of the numpy module. It assumes the COP has a float parameter named bright.

import array
import inlinecpp

def output_planes_to_cook(cop_node):
    return ("C",)

def required_input_planes(cop_node, output_plane):
    if output_plane == "C":
        return ("0", "C")
    return ()

def cook(cop_node, plane, resolution):
    input_cop = cop_node.inputs()[0]
    color_pixels = array.array("f", input_cop.allPixelsAsString(plane))

    cpp_lib = inlinecpp.createLibrary("py_brighten_cop", function_sources=["""
    void brighten(float *color_pixels, int num_pixels, float amount)
    {
        for (int i=0; i<num_pixels; ++i)
        {
            color_pixels[0] *= amount;
            color_pixels[1] *= amount;
            color_pixels[2] *= amount;
            color_pixels += 3;
        }
    }
    """])
    cpp_lib.brighten(
        color_pixels.buffer_info()[0], resolution[0] * resolution[1],
        cop_node.evalParm("bright"))

    cop_node.setPixelsOfCookingPlaneFromString(color_pixels)

To get the address of the data of a numpy array, simply call .ctypes.data on the numpy array. To use numpy instead of the array module in the above example, create the numpy array with:

color_pixels = numpy.array(input_cop.allPixelsAsString("C", dtype=numpy.float32))

and call the C++ function with:

cpp_lib.brighten(color_pixels.ctypes.data, cop_node.evalParm("bright"),
    resolution[0] * resolution[1])

Note that the examples presented here use interleaved data (the color data is stored as a sequence of RGBRGBRGB...). However some algorithms are easier to write using non-interleaved data (RRR..., GGG..., BBB...), and it is possible to ask the input cop for data in this format and to set the cooked data using this format.

The following example brightens the pixels of the input plane by operating on one component at a time:

import array
import inlinecpp

def output_planes_to_cook(cop_node):
    return ("C",)

def required_input_planes(cop_node, output_plane):
    if output_plane == "C":
        return ("0", "C")
    return ()

def cook(cop_node, plane, resolution):
    input_cop = cop_node.inputs()[0]
    component_values_dict = dict(
        (component, array.array(
            "f", input_cop.allPixelsAsString(plane, component)))
        for component in input_cop.components(plane))

    cpp_lib = inlinecpp.createLibrary("py_brighten_cop", function_sources=["""
    void brighten(float *component_values, int num_pixels, float amount)
    {
        for (int i=0; i<num_pixels; ++i)
            component_values[i] *= amount;
    }
    """])

    for component, component_values in component_values_dict.items():
        cpp_lib.brighten(
            component_values.buffer_info()[0], resolution[0] * resolution[1],
            cop_node.evalParm("bright"))
        cop_node.setPixelsOfCookingPlaneFromString(component_values, component)

The following simple example COP converts all input image planes to the format specified in a menu parameter. It assumes the menu parameter is named "depth" and that it has the values "Int8", "Int16", "Int32", "Float16", or "Float32". (Note that Houdini already provides a convert COP to convert the image depth.)

import inlinecpp

def output_planes_to_cook(cop_node):
    return cop_node.inputs()[0].planes()

def required_input_planes(cop_node, output_plane):
    return ("0", output_plane)

def depth(cop_node, plane):
    return getattr(hou.imageDepth, cop_node.parm("depth").evalAsString())

def cook(cop_node, plane, resolution):
    # If we don't specify a particular depth when calling allPixelsAsString,
    # it will convert the input plane depth into the depth of the cooking
    # plane (which is determined by the return value from the depth function
    # above).
    input_cop = cop_node.inputs()[0]
    pixels = input_cop.allPixelsAsString(plane)
    cop_node.setPixelsOfCookingPlaneFromString(pixels)

The following example illustrates how to preserve the depth of input planes. Each input plane is converted to 32-bit float point data while the Python COP processes it, and the result is converted back into the depth of the input plane.

import numpy

def input_cop(cop_node):
    return cop_node.inputs()[0]

def output_planes_to_cook(cop_node):
    input_planes = input_cop(cop_node).planes()
    return [plane for plane in cop_node.evalParm("planes").split()
        if plane in input_planes]

def required_input_planes(cop_node, output_plane):
    return ("0", output_plane)

def depth(cop_node, plane):
    return input_cop(cop_node).depth(plane)

def cook(cop_node, plane, resolution):
    input = input_cop(cop_node)
    pixels = numpy.frombuffer(
        input.allPixelsAsString(plane, depth=hou.imageData.Float32),
        dtype=numpy.float32)

    # Perform some operation here to modify the contents of pixels.

    cop_node.setPixelsOfCookingPlaneFromString(
        pixels, depth=hou.imageData.Float32)

The following table lists the array format specifiers corresponding to the different image depths supported in COPs:

The following example illustrates how to create a numpy array of the input plane in its native format, for manipulation with numpy:

import numpy

def input_cop(cop_node):
    return cop_node.inputs()[0]

def output_planes_to_cook(cop_node):
    input_planes = input_cop(cop_node).planes()
    return [plane for plane in cop_node.evalParm("planes").split()
        if plane in input_planes]

def required_input_planes(cop_node, output_plane):
    return ("0", output_plane)

def depth(cop_node, plane):
    return input_cop(cop_node).depth(plane)

depths_to_numpy_types = {
    hou.imageDepth.Int8: numpy.uint8,
    hou.imageDepth.Int16: numpy.uint16,
    hou.imageDepth.Int32: numpy.uint32,
    hou.imageDepth.Float16: numpy.float16,
    hou.imageDepth.Float32: numpy.float32
}

def cook(cop_node, plane, resolution):
    input = input_cop(cop_node)
    pixels = numpy.frombuffer(
        input.allPixelsAsString(plane),
        dtype=depths_to_numpy_types[input.depth(plane)]).copy()

    # Perform some operation here to modify the contents of pixels.

    cop_node.setPixelsOfCookingPlaneFromString(pixels)

If your Python COP node generates an exception, the node will turn red with an error and you can view the stack trace of the error by middle-clicking on it.

If you would like to generate an error message to the user that doesn’t contain a Python stack trace, raise a hou.NodeError exception. For example, running

raise hou.NodeError("Invalid parameter settings")

will turn the node red with an error message of "Invalid parameter settings". Similarly, you can add node warnings by raising instances of hou.NodeWarning.

For reference, here are the functions with special meaning:

• output_planes_to_cook(cop_node)

• required_input_planes(cop_node, output_plane)

• cook(cop_node, plane, resolution)

• remap_frame(cop_node, frame)

• frame_range(cop_node)

• resolution(cop_node)

• output_planes_to_cook(cop_node)

• depth(cop_node, plane)

• frame_range(cop_node)