Houdini 18.0 Nodes TOP nodes

ImageMagick TOP node

Provides easy access to ImageMagick functionality such as mass image convert, resize, and image mosaics.

On this page


Before you can use this node you must install ImageMagick.

This node creates work items that call functions in the ImageMagick library to manipulate images. The Operation parameter chooses between different built-in methods of editing or combining images.

Tips and notes

  • This node will perform the given operation for the list of output result files on each incoming work item, even when it’s a montage or composite.

    If you have multiple incoming work items each representing one file you want to montage or composite (for example, you generate work items from files using File Pattern and then want to merge them into an image mosaic), insert a Wait for All node before this node to merge them into a single work item.

  • When resizing/converting, if you have multiple incoming work items each representing one file, by default (no Wait for All) the node will perform the operations in parallel. However, it’s much faster to convert all files in one process (by putting a Wait for All before the ImageMagick node). This avoids the overhead of scheduling and executing separately for each file.

  • Montage (image mosaic) works best when all input images are the same size. You can pipeline two ImageMagick nodes, one to resize all input images to the same size, and one to create the montage.

  • The Montage operation has an option for overlaying the result of an expression on each cell. You might think to use this to overlay wedge settings, however because the node requires you to first merge work items representing individual files, the wedged attributes are lost. You can work around this by overlaying the wedge settings on each input image separately using an ROP Composite Output before merging them for this node.

  • You can access the full set of ImageMagick options by writing a custom command line. For example, you can change the background for overlays from black to transparent (-background 'rgba(0,0,0,0)'), or change the pixel filter used when resizing.


Before you can use this node, you must install the ImageMagick software, either from the website (Mac/Windows) or using a package manager (Linux).

  • You must manually install ImageMagick on each machine where work items will run. (If you're using the local scheduler, you must install ImageMagick on the local machine. If you're using a render farm, you must install ImageMagick on all host machines on the farm.)

  • The work items must be able to find the ImageMagick executable.

    • The imagemagick executable should be on the command path for the remote user.


    • You can define a PDG_IMAGEMAGICK environment variable. This should contain the path to the imagemagick executable.


    • You can define a PDG_IMAGEMAGICK_DIR environment variable. This should contain the path to the folder where the ImageMagick executables are located. This variable should be used instead of PDG_IMAGEMAGICK when your installation of ImageMagick has separate executables for each subcommand (montage, convert, etc.).


    • You can manually enter the path to the executable in the ImageMagick Path parameter.

TOP Attributes



The ImageMagick operation that will be performed (montage, convert, or composite)



The file tag of the result data.



Whether the node explicitly specifies a path to the imagemagick executable in the imagemagickbin attribute.



The file path of the imagemagick executable. This is only used if overridebin is set to 1.



Whether the node should run the custom command line in the customcommand attribute.



A custom command line to run. This is only used if usecustomcommand is set to 1.



For montage and composite operation: specifies the output image.



For montage: the type of overlay to add to the montage (0=no overlay, 1=filename, 2=custom expression).



For montage: contains an expression to evaluate to get an image overlay. This is only used when overlaymode is set to 2.



For montage: how to order the images in the block (0=by index, 1=by filename).



A list of images to use to generate the output.



For convert: if this is 1, the image resolution will be set to the values specified by the imgwidth and imgheight attributes.



For convert: specifies the new image width. Only used if updateresolution is set to 1.



For convert: specifies the new image height. Only used if updateresolution is set to 1.



For convert: if this is 1, adjust the imgwidth and imgheight attribute values to preserve the aspect ratio of the original image.



For convert: the image quality of the output image (1-100). This is used by output drivers for certain file formats, such as JPEG.



For convert: a list of the output image file paths.



For composite: the ImageMagick compositing operation name (overylay, softlight, or multiply).




How the node should manipulate the input images. Each operation has different parameters.


Shrinks the images to thumbnail size and arranges them in a square grid. This gives you an overview of the multiple images at once. This is usually called a mosaic, but montage is the ImageMagick term.


Converts images to a different format, and/or resizes them.


Composites multiple images over each other. This can be useful for comparing similar images.


Order By

The order in which incoming images appear in the output image grid (from left-to-right, then top-to-bottom). You can sort by the index attribute on the work item, or by the input image file name.


This node can overlay text on each "cell" in the image grid. For example, if you are comparing renders, you could overlay the image file name to make it easy to find the original. See the tips and notes section for information on overlaying wedged settings.


Don’t overlay any text on the cells.


Overlay the image filename on the cells.

Custom Expression

Overlay the output of an expression.


When Overlay mode is "Custom expression", this expression is evaluated and overlayed onto the cells.



The width of the output image(s).


The height of the output image(s).

Preserve Aspect Ratio

When this is on, ImageMagick will resize the original image within the specified width and height (possibly leaving blank space) to preserve its aspect ratio. When this is off, ImageMagick will stretch the image to fit in the exact width and height.

Image Quality

The image quality to use when outputting JPEG files.

Output Filename

The output filename. You can embed {attributename} strings in this filename and the node will replace them with the appropriate value for each image. You can also use {inputfilename} which is the base file name (without extension) of the file being converted.

Split Results into New Tasks

If an incoming work item has multiple output results being converted (for example, you put a Wait for All before this node to convert all images in one go), you can turn this on to separate them back out into separate work items for each output file.


Composite Operation

How to composite the incoming images together.


Copies each image on top off the previous one, with any alpha transparency allowing the previous images to show through.

Soft Light

Bright pixels lighten, dark pixels darken, but with a smooth gradient between them.


Multiplies the existing pixel values by the pixel values in each image, so darker colors will darken the image, and white pixels have no effect. This is sometimes useful for diffing or overlaying text.

Command Line

You can turn this on and write a custom command line. You can embed certain {keywords} in the command line string and the node will replace them with the appropriate values. You can rewrite the command line to access extra ImageMagick options not provided by the parameters of this node, such as different pixel filters when resizing, or different compositing methods.

  • {imagemagick} – the path to the imagemagick executable.

  • {input_images} – the list of input images as a space-separated string (ordered according to the parameters).

  • {output_image} – the file path of the output image.

File Tag

Specifies the file tag of the result files.

Output Filename

The output file path for montage and composite images. The should be relative to __PDG_DIR__. For intermediate results, include a `@pdg_name` expression in the name. This makes the work item’s name a part of the output filename. This makes it unique across the TOP network.

ImageMagick Path

Turn this on to specify an exact path to the ImageMagick executable. See installation above.


TOP Scheduler Override

This parameter overrides the TOP scheduler for this node.

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 is only available when Work Item Priority is set to Custom Expression.

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


example_top_imagemagick Example for ImageMagick TOP node

This example demonstrates how to use Image Magick to montage and convert images.

TOP nodes