ImageMagick TOP node

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

On this page	Overview Tips and notes Installation Top_attributes Parameters Node Schedulers Examples
Since	17.5

Overview ¶

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.

Before you can use this node, you must have ImageMagick installed on your system.

Note

We recommend that you use ImageMagick v7 or higher.

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 enabling batching. 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.
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.

Installation ¶

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

Note

We recommend that you install ImageMagick v7 or higher.

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.
  
  or
- You can define a PDG_IMAGEMAGICK environment variable. This should contain the path to the ImageMagick executable.
  
  or
- 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.).
  
  or
- You can manually enter the path to the executable in the ImageMagick Path parameter.

Tip

The $HH/help/files/pdg_examples/top_imagemanipulation example shows how you can use this node to create work items that modify images using the ImageMagick utility.

TOP Attributes ¶

`operation`	integer	The ImageMagick operation that will be performed (`convert`, `composite`, `montage`, `compare`, `import`, or `conjure`)
`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.
`enablemode`	integer	Indicates whether the `-mode` argument is enabled.
`mode`	string	The value of the `-mode` argument.
`overlaymode`	integer	The selected overlay mode.
`overlayattribute`	string	The name of the attribute array with the labels for each input image to the montage.
`montagecolumnsswitch`	integer	Indicates whether or not a column count should be specified in the ImageMagick montage command.
`montagecolumns`	integer	Specifies the number of columns when executing an ImageMagick montage command.
`montagerowsswitch`	integer	Indicates whether or not a row count should be specified in the ImageMagick montage command.
`montagerows`	integer	Specifies the number of rows when executing an ImageMagick montage command.
`compositeop`	string	The selected composite operation.
`enablebackground`	integer	Indicates whether the `-background` argument is enabled.
`background`	string	The value of the `-background` argument.
`enableresolution`	integer	Indicates whether the `-resize` argument is enabled.
`imgwidth`	integer	The width component of the `-resize` argument.
`imgheight`	integer	The height component of the `-resize` argument.
`preservear`	integer	Whether the aspect ratio should be preserved when resizing the image.
`enableimgquality`	integer	Indicates whether the `-quality` argument is enabled.
`imgquality`	integer	The value of the `-quality` argument.
`imagemagickbinary`	integer	The selected method for discovering the ImageMagick binary.
`customimagemagickbinary`	string	The file path to the ImageMagick binary when ImageMagick Binary is set to Custom Path.
`outputfile`	file	The output file that should result from the operation.
`imagemagickarguments`	string	The ImageMagick arguments built by the node based on the parameter configuration.
`enablecustomarguments`	integer	Indicates that the work item job should use the user-supplied custom arguments.
`customarguments`	string	The user-supplied custom arguments which will be used to construct the ImageMagick command when the Custom ImageMagick Arguments field is enabled.

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 take 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 ImageMagick 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 slightly 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.

Output

Output File Path

Specifies the file path of the output.

File Tag

Specifies the file tag of the output.

Operation

Chooses the ImageMagick operation to use (convert, composite, montage, compare, import, conjure).

Sort Input Files By

Chooses how the input files should be sorted.

None

No sorting will be performed on the input files.

Natural Filename

Uses a natural sort order based on the input filenames.

Montage

Mode

Specifies the value of the mode argument.

Overlay

Chooses what should be used as overlay text for each image in the montage.

None

No overlay will be used.

Input Filename

Each image in the montage will be captioned with its source filename.

Attribute Array

This option allows procedural text to be used as an overlay for each image in the montage. The Attribute Array Name attribute must be set when this option is selected.

Attribute Array Name

The value of this parameter should be set to the name of a string attribute which contains an array of labels. The number of entries in the string attribute must be equal to the number of inputs.

Columns

When enabled, this controls the number of tile columns in the produced montage image. If neither the Columns or Rows parameter is enabled, ImageMagick will auto-layout the montage image.

Rows

When enabled, this controls the number of tile rows in the produced montage image. If neither the Columns or Rows parameter is enabled, ImageMagick will auto-layout the montage image.

Composite

Composite Operation

Chooses the ImageMagick composite operation.

Options

Background

Specifies the -background argument.

Width

Specifies the width component of the -resize argument.

Height

Specifies the height component of the -resize argument.

Preserve Aspect Ratio

When Preserve Aspect Ratio is enabled, ImageMagick will preserve the aspect ratio of the input image(s). When this is disabled, the Width and Height values will be used with no attempt to preserve the original aspect ratio of the image(s).

Image Quality Percentage

Specifies the -quality argument.

Extra Arguments

This multiparameter can be used to specify additional arguments that will be added to the ImageMagick command line that is executed.

Argument Name

Specifies the name of the additional argument.

Argument Source

Chooses the source of the additional argument.

Attribute Name

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

Custom Value

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

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.

ImageMagick

ImageMagick Binary

Chooses the method for finding the ImageMagick binary on the job machine.

System Path

ImageMagick will be invoked assuming that it is on the system path.

$PDG_IMAGEMAGICK_DIR

ImageMagick will be found by using the value of a PDG_IMAGEMAGICK_DIR environment variable that must be set on the job’s machine. The value of the environment variable should be set to the directory where the ImageMagick executables are located. This method is useful for machines that have installations of ImageMagick that have separate executables for each subcommand (montage, convert, etc.).

$PDG_IMAGEMAGICK

ImageMagick will be found by using the value of the PDG_IMAGEMAGICK environment variable that must be set on the job’s machine. The value of the environment variable should be set to the filepath of the magick executable. If you have an installation of ImageMagick with separate executables for each subcommand, the PDG_IMAGEMAGICK_DIR option should be used instead.

Custom Path

ImageMagick will be invoked using the file path specified in the Imagemagick Binary Path parameter.

ImageMagick Binary Path

This should be used to specify the path to the ImageMagick exectutable when ImageMagick Binary is set to Custom Path.

Custom ImageMagick Arguments

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 will be used to call ImageMagick, rather than the set of arguments automatically constructed by the node. The arguments should begin after the ImageMagick subcommand. For example, to run a custom magick montage command, all the arguments that occur after magick montage should be supplied via this parameter.

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.

Examples ¶

example_top_imagemagick Example for ImageMagick TOP node

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