Houdini 20.5 Nodes TOP nodes

OpenImageIO TOP node

Provides easy access to the OpenImageIO’s command line tool, also known as oiiotool, to perform operations on images such as color space conversion, color mapping, resizing, text overlay, and box overlay.

On this page
Since 20.0

Overview

This node creates work items that use the oiiotool command line program to manipulate images. The Operation parameter chooses between different options of modifying images.

This allows for powerful color space manipulation functionality without requiring you to install any other programs.

How To

  1. Select your desired input and output file paths.

  2. Select your desired operation with the Operation parameter. Parameters denoting options specific to this operation will appear.

  3. Set both the operation-specific options and the general options for your desired output image.

Tips and notes

  • You can access the full set of oiiotool options by writing a custom command in the Custom Command parameter. Note: This overrides the input and output files as well.

  • You can also use Extra Operations to add additional operations that are a part of oiiotool but are not in the node interface.

  • If you need access to a specific copy of oiiotool, you can override the the binary used by the node in the Custom OpenImageIO Binary parameter.

hoiiotool

For information on all of the options and image operations that hoiiotool supports, the official OIIO page is very extensive, and has lots of examples. Use hoiiotool in place of oiiotool when following those recipes.

Houdini ships with version 2.3.14.0 of OpenImage IO.

TOP Attributes

operation

integer

The OpenImageIO operation that is performed (None=0, Color Convert=1, Color Map=2, Resize=3, Text=4, Box=5, Mosaic=6)

batchmode

integer

The selected batch mode.

cookwhen

integer

The selected Cook Batch When setting.

inputsort

integer

The selected Sort Input Files By setting.

inputsource

integer

The selected Input Source setting.

inputfiletag

string

The file tag of the input files to use in the operation.

inputfilepath

string

The file path of the input file to the operation.

outputfile

file

The output file that should result from the operation.

enablecustomargs

integer

Indicates the work item job should use the user-supplied custom arguments.

customargs

string

The user-supplied custom arguments to construct the OpenImageIO command when the Custom Arguments field is enabled.

openimageiobinarytype

integer

Indicates where to look for the OpenImageIO binary.

customopenimageiobinary

string

The file path to the OpenImageIO binary when OpenImageIO Binary is set to Custom Path.

openimageiocommand

string

The OpenImageIO command built by the node based on the parameter configuration.

Parameters

Node

Work Items

Generate When

Determines when this node will generate work items. You should generally leave this set to “Automatic” unless you know the node requires a specific generation mode, or that the work items need to be generated dynamically.

All Upstream Items are Generated

This node will generate work items once all of the input nodes have generated their work items.

All Upstream Items are Cooked

This node will generate work items once all of the input nodes have cooked their work items.

Each Upstream Item is Cooked

This node will generate work items each time a work item in an input node is cooked.

Automatic

The generation mode is selected based on the generation mode of the input nodes. If any of the input nodes are generating work items when their inputs cook, this node will be set to Each Upstream Item is Cooked. Otherwise, it will be set to All Upstream Items are Generated.

Cache Mode

Determines how the processor node handles work items that report expected file results.

Automatic

If the expected result file exists on disk, the work item is marked as cooked without being scheduled. If the file does not exist on disk, the work item is scheduled as normal. If upstream work item dependencies write out new files during a cook, the cache files on work items in this node will also be marked as out-of-date.

Automatic (Ignore Upstream)

The same as Automatic, except upstream file writes do not invalidate cache files on work items in this node and this node will only check output files for its own work items.

Read Files

If the expected result file exists on disk, the work item is marked as cooked without being scheduled. Otherwise the work item is marked as failed.

Write Files

Work items are always scheduled and the expected result file is ignored even if it exists on disk.

Cook Type

Determines how work items in the node should cook, e.g. if they should run in process, out of process, or using services.

Run on Service Block

Determines whether or not work items in this node should run on the parent service block, if one exists.

Always

Always run work items on the block’s service, regardless of any other service settings on this node.

Match

Only run work items on the block’s service if Service Name matches the service name that’s used by the block.

Never

Never run work items on the block’s service.

Service Name

When Cook Type is set to the Service, this parameter is used to specify the name of the service. For more information on using services, see the PDG Service Manager documentation.

Batch Mode

Determines the batch mode of generated work items.

Off

No batching is performed. Each work item is submitted as its own individual job.

All Items in One Batch

All work items are submitted as a single batch job and takes place in a single python session. This is useful for batch processing images (such as performing a file conversion on a folder of images).

Cook Batch When

Determines when batches of work items are scheduled.

All Items are Ready

The batch is only scheduled once all dependencies on all work items in the batch are satisfied.

First Item is Ready

The batch is scheduled as soon as the dependencies for its first work item are ready. The OpenImageIO job script communicates back to PDG as the job is running to check the status of the dependencies before cooking each work item in the batch. This incurs a bit more network overhead and requires ongoing communication between the job and PDG.

Input

Input Source

Specifies the input source.

Upstream Output Files

Sets the input to the output files from the upstream work item with the tag specified by the File Tag parameter.

Custom File Path

Sets the input to the file path specified by the File Path parameter.

File Tag

Specifies the file tag of the input source.

This parameter is only available when Input Source is set to Upstream Output Files.

File Path

Specifies the input file path.

This parameter is only available when Input Source is set to Custom File Path.

Sort Input Files By

Chooses how the input files should be sorted.

None

No sorting is performed on the input files.

Natural Filename

Uses a natural sort order based on the input filenames.

Output

Output File Path

Specifies the file path of the output. If the file extension of this path differs from Input File Path then hoiiotool will try to convert the file format.

File Tag

Specifies the file tag of the output.

Main Operation

Operation

Chooses the OpenImageIO operation to use.

None

Do nothing. This is useful if you want to convert the image format via the file extension of Output File Path or if you only want to use the Extra Arguments.

Color Convert

Converts the image from one color space to another.

Color Map

Creates an RGB color map based on the luminance of the input image.

Resize

Resizes the image.

Mosaic

Tiles multiple images side-by-side in a grid.

Text and Shape

Draws texts and shapes on the image.

Custom

Adds a custom string to the Open Image IO command line.

Color Convert

Input Color Space

Specifies the color space to interpret the input image as.

Output Color Space

Specifies the color space to convert to for the resulting output image.

Color Config Source

Chooses which OpenColorIO configuration file to use to get available color spaces for Input Color Space and Output Color Space.

Houdini Configuration

Use the default configuration file bundled with Houdini, for example $HFS/packages/ocio/cg-config-v1.0.0_aces-v1.3_ocio-v2.1.ocio. The file path used is the same one returned by the hou.Color.ocio_configPath method.

Custom Path

Use a path specified in the Custom Config File parameter.

Custom Config File

Specifies a custom path to an OpenColorIO configuration file.

Color Map

Color Map

Determines the color map to apply to the input image. It can either be the name of a color map or a list of comma-separated RGB triplets that form a color map curve. For example: .25,.25,.25,0,.5,0,1,0,0.

Resize

Resize Type

Chooses how to resize the image.

Absolute (Pixels)

The input image is resized so the output image has the specified dimensions.

Relative (Percent)

The output image is scaled the specified percentage of the input dimensions.

Resize Width Pixels

Specifies the width of the resulting output image in pixels.

Resize Height Pixels

Specifies the height of the resulting output image in pixels.

Resize Width Percent

Specifies the width of the resulting output image as a percentage of the width of the input image.

Resize Height Pixels

Specifies the height of the resulting output image as a percentage of the height of the input image.

Text

Position Type

Determines the units to use for specifying the position of the overlay text.

Absolute (Pixels)

Specify the position of the text in absolute pixel values, relative to the top left corner of the image.

Relative (Percent)

Specify the position of the text as a percentage of the image size, relative to the top left corner of the image.

Position (Pixels)

Specifies the position of the text in pixels. The top-left of the image corresponds to position (0, 0). Increase the X-position to move the text rightwards. Increase the Y-position to move the text downwards.

Position (Percent)

Specifies the position of the text as a percentage of the image size. The top-left of the image corresponds to (0%, 0%). Increase the X-percentage to move the text rightwards. Increase the Y-percentage to move the text downwards.

Text X-Align

Specifies the x-alignment of the text relative to the specified position.

Left

The left side of the text aligns to the position specified by X-Position.

Center

The center of the text aligns to the position specified by X-Position and __Y-Position.

Text Y-Align

Specifies the y-alignment of the text relative to the specified position.

Base

The base of the text aligns to the position specified by Y-Position.

Top

The top of the text aligns to the position specified by Y-Position.

Bottom

The bottom of the text aligns to the position specified by Y-Position.

Center

The center of the text aligns to the position specified by Y-Position.

Text Size

Determines the size of the text.

Text Shadow Size

Determines the size of the outline around the text used to improve text legibility on certain backgrounds.

Text Color

Specifies the RGBA color value of the text.

Text Font File

When enabled, specifies the path to the font file that should be used for text overlay. Supported file formats include: .ttf, .pfa, .pfb.

The dropdown menu displays all of the font files shipped with Houdini in $HFS/houdini/fonts. If you are cooking in an environment without Houdini, you need to specify a font file that doesn’t depend on Houdini and exists on the computer that cooks the node.

On MacOS, oiiotool cannot find system fonts, so text overlay operations fail without this parameter enabled.

Text

Determines the text to be overlayed on the image.

Box

Position Type

Determines the units to use for specifying the position of the overlay box.

Absolute (Pixels)

Enables absolute pixel units to position the box.

Relative (Percent)

Enables relative percentage of the image width andheigh to position the box.

X1-Position (Pixels)

Specifies the x-position of the first corner of the box in pixels.

Y1-Position (Pixels)

Specifies the y-position of the first corner of the box in pixels.

X2-Position (Pixels)

Specifies the x-position of the second corner of the box in pixels.

Y2-Position (Pixels)

Specifies the y-position of the second corner of the box in pixels.

X1-Position (Percent)

Specifies the x-position of the first corner of the box as a percentage of the image width.

Y1-Position (Percent)

Specifies the y-position of the first corner of the box as a percentage of the image width.

X2-Position (Percent)

Specifies the x-position of the second corner of the box as a percentage of the image height.

Y2-Position (Percent)

Specifies the y-position of the second corner of the box as a percentage of the image height.

Box Color

Specifies the RGBA color value of the box.

Fill Box

If enabled, the box is solid. If disabled, only the outline of the box renders.

Mosaic

Number of Tiles

Specifies the number of images to tile for the mosaic. The first value determines the width and the second value determines the height.

Tile Size

Specifies the size of each tile of the mosaic in pixels. The first value determines the width and the second value determines the height. Each image scales up or down so at least one dimension matches the tile, while still maintaining the same aspect ratio.

Padding

Determines the width of the black boundary between each tile of the mosaic in pixels. Use this when you want be clearly see the boundary between images.

Custom Operation

Custom Operation

When Operation is set to Custom Operation, you can use this parameter to specify a custom string that will be appended to the Open Image IO command line.

Subimages

Enable Mipmap

Enables mipmapping on the output. This option is only supported by certain file formats, such as .tif and .exr.

Subimages

Determines the subimages that oiiotool will apply the selected operation to.

This option is only available for the operations Color Convert and Color Map and Box.

Default

Perform operations on only the first subimage and output only the first subimage. Note: This behavior is true for most, but not all operations. See the oiiotool documentation for more details.

All Subimages

Perform operations on all of the subimages and output all of the subimages.

Specific Subimages

Perform operations on only the selected subimages and output all of the subimages.

Extra Operations

Extra Arguments

This multiparameter can be used to specify additional arguments that adds to the OpenImageIO command line that is executed. If these arguments denote operations, they run in top-to-bottom order.

For information on all of the options and image operations that hoiiotool supports, the official OIIO page is very extensive, and has lots of examples. Use hoiiotool in place of oiiotool when following those recipes.

Argument Name

Specifies the name of the additional argument.

Argument Source

Chooses the source of the additional argument.

No Value

The argument takes no corresponding value.

Attribute Name

The argument is set to the value of an attribute with the name specified by the Attribute Name parameter.

Custom Value

The argument is set to a custom value specified by the Argument Value parameter.

Argument Modifiers

Specifies additional modifiers to this extra argument.

Attribute Name

When the Argument Source is set to Attribute Name, this parameter is used to specify the name of the attribute to use.

Argument Value

When the Argument Source is set to Custom Value, this parameter is used to specify the value of the argument.

OpenImageIO

Custom Command

This parameter can be used to construct an entirely custom command line to be executed.

When this parameter is enabled, the custom set of arguments specified here is used to call oiiotool, rather than the set of arguments automatically constructed by the node.

For information on all of the options and image operations that hoiiotool supports, the official OIIO page is very extensive, and has lots of examples. Use hoiiotool in place of oiiotool when following those recipes.

Note: this overrides all automatically constructed arguments, including those that specify the input and output files.

OpenImageIO Binary

Chooses the method for finding the OpenImageIO tool binary on the job machine.

hoiiotool

OpenImageIO is invoked using the hoiiotool binary bundled with Houdini located at $HB/hoiiotool.

Custom Path

OpenImageIO is invoked using the file path specified in the Custom OpenImageIO Binary parameter.

Custom OpenImageIO Binary

Specifies the path to the oiiotool executable when OpenImageIO Binary is set to Custom Path.

Schedulers

TOP Scheduler Override

This parameter overrides the TOP scheduler for this node.

Schedule When

When enabled, this parameter can be used to specify an expression that determines which work items from the node should be scheduled. If the expression returns zero for a given work item, that work item will immediately be marked as cooked instead of being queued with a scheduler. If the expression returns a non-zero value, the work item is scheduled normally.

Work Item Label

Determines how the node should label its work items. This parameter allows you to assign non-unique label strings to your work items which are then used to identify the work items in the attribute panel, task bar, and scheduler job names.

Use Default Label

The work items in this node will use the default label from the TOP network, or have no label if the default is unset.

Inherit From Upstream Item

The work items inherit their labels from their parent work items.

Custom Expression

The work item label is set to the Label Expression custom expression which is evaluated for each item.

Node Defines Label

The work item label is defined in the node’s internal logic.

Label Expression

When on, this parameter specifies a custom label for work items created by this node. The parameter can be an expression that includes references to work item attributes or built-in properties. For example, $OS: @pdg_frame will set the label of each work item based on its frame value.

Work Item Priority

This parameter determines how the current scheduler prioritizes the work items in this node.

Inherit From Upstream Item

The work items inherit their priority from their parent items. If a work item has no parent, its priority is set to 0.

Custom Expression

The work item priority is set to the value of Priority Expression.

Node Defines Priority

The work item priority is set based on the node’s own internal priority calculations.

This option is only available on the Python Processor TOP, ROP Fetch TOP, and ROP Output TOP nodes. These nodes define their own prioritization schemes that are implemented in their node logic.

Priority Expression

This parameter specifies an expression for work item priority. The expression is evaluated for each work item in the node.

This parameter is only available when Work Item Priority is set to Custom Expression.

TOP nodes