| 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 ¶
-
Select your desired input and output file paths.
-
Select your desired operation with the Operation parameter. Parameters denoting options specific to this operation will appear.
-
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
oiiotooloptions 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
oiiotoolbut 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 ¶
|
|
integer |
The OpenImageIO operation that is performed ( |
|
|
integer |
The selected batch mode. |
|
|
integer |
The selected Cook Batch When setting. |
|
|
integer |
The selected Sort Input Files By setting. |
|
|
integer |
The selected Input Source setting. |
|
|
string |
The file tag of the input files to use in the operation. |
|
|
string |
The file path of the input file to the operation. |
|
|
file |
The output file that should result from the operation. |
|
|
integer |
Indicates the work item job should use the user-supplied custom arguments. |
|
|
string |
The user-supplied custom arguments to construct the OpenImageIO command when the Custom Arguments field is enabled. |
|
|
integer |
Indicates where to look for the OpenImageIO binary. |
|
|
string |
The file path to the OpenImageIO binary when OpenImageIO Binary is set to Custom Path. |
|
|
string |
The OpenImageIO command built by the node based on the parameter configuration. |
Parameters ¶
Node ¶
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 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 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.
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.
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
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 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.
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.
Right
The right 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.
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.
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
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.
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 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.
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.
