When trying to merge multiple AOVs as channels into one multichannel EXR file in Katana, you may encounter render failures and errors due to a known limitation of OpenEXR affecting the tool used by Katana to merge EXR images, ExrCombine.

The ExrCombine utility fails when attempting to merge images with different data windows.

This means errors will occur if the dataWindow header attribute of the EXR images to be merged do not match, and especially when the first merged AOV has a smaller pixel data window than subsequently merged AOVs.

To resolve this, please try taking the following troubleshooting steps:

Ensure the “primary” render output is set to output type “raw” or do not include the “primary” pass in the merged output

Ensure the rendered EXRs are not tiled, as Katana cannot merge tiled outputs

Please read on for more detailed information on each of these suggestions.

By default, Katana can only read and render four channels (RGBA) when working with image data. However, users can merge several images to create a multichannel EXR via an internal Katana utility called ExrCombine.

The ExrCombine utility was originally created for merging images with pixel data windows of the same size because OpenEXR has limitations when writing multiple channels into one EXR file:

The size of the image’s pixel data window is stored in the dataWindow EXR header attribute, and an EXR file can only contain one such attribute.This means that every channel/AOV has to share the same dataWindow attribute value and will not be able to keep its own value within the merged EXR.

Therefore, Katana does not support merging images with different pixel data window sizes.

If the chosen dataWindow attribute value does not encompass the data window sizes of all the AOVs being merged, the render will fail or Katana might crash.

There is an existing feature request for Katana to improve the ExrCombine functionality once OpenEXR offer extended support for multiple dataWindow header attributes within the same file. This is logged as: TP 75636 - ExrCombine: Better support for images with different pixel data windows

Please read on for more information on this as well as details on the workarounds suggested above which should hopefully resolve issues with merging, depending on your multichannel setup.

FURTHER INFORMATION

The EXR Data Window

Each OpenEXR file is described through a list of attributes found in the file’s header. Running a command like ‘exrinfo’ on a sample .exr file will print out the values of these attributes like so:

The value of the dataWindow attribute in this case is (0 0) - (511 511), meaning there are 512x512 pixels stored in the image file.

The displayWindow describes the area of the image that is displayed when viewing it. This area might be larger or smaller than the area for which data exists in the OpenEXR file.

Defining the dataWindow for “merge” outputs in Katana

When combining images with different data windows using a render output of type “merge”, the dataWindow attribute value of the first selected input in the RenderOutputDefine node’s mergeOutputs parameter dropdown will be used as the dataWindow of the final output.

In this screenshot of an example RenderOutputDefine node, the first selected input of the mergeOutputs parameter is the ‘primary’ output. This means that for the final merged EXR created by the ExrCombine utility, the dataWindow header attribute of the ‘primary’ pass will be used.

If this dataWindow header attribute is smaller than the dataWindow of the rest of the render outputs you intend to merge, the ExrCombine merge process may fail triggering the render errors referenced above.

WORKAROUNDS

There are a several options to try that may help resolve this issue.

Ensure the “primary” render output is set to output type “raw” or do not include the “primary” pass in the merged output

NOTE: Katana will always generate a “primary” pass by default, whether you request its creation via a dedicated RenderOutputDefine node or not.

The “primary” pass will be added to the mergeOutputs list as first entry, and any additional channels will be merged into it. If the “primary” pass data window does not encompass the overall data window sizes of all the AOVs you're merging, then the merge operation will fail.

This can sometimes be resolved by adding a RenderOutputDefine node for the “primary” pass and setting the type parameter to "raw".

If you don’t require the primary pass then you can disable it explicitly from the mergeOutputs list on the RenderOutputDefine node. The dataWindow of the second pass in the list will then be used for the merged EXR. In the example screenshot above, the dataWindow value used if ‘primary’ is deselected would be coming from the ‘diffuse’ pass.

Ensure all AOVs to be merged have the same dataWindow attribute value.

When all AOVs to be merged have a data window of the same size, the merge operation should be successful. Alternatively, the output that is merged first needs to have a large enough dataWindow attribute value to encompass all other outputs.

If you keep this in mind when defining your AOVs’ order in the merge process, you can avoid ExrCombine render failures due to trying to fit a wider dataWindow into a smaller dataWindow.

Two ways of influencing an AOV’s data window size using the settings on RenderOutputDefine nodes are described below:

By default, Katana post-processes rendered color outputs. This internal 2D image processing does not preserve EXR header attributes, but rather copies relevant attributes from the original image to the post-processed image.

The convertSettings.exrOptimize parameter is mainly used to optimize the image data window and 'shrinkwrap' the image by removing any areas without pixel data around the edges.

Comparison of EXR images and metadata rendered with exrOptimize on and off (viewed in Nuke)

Setting the exrOptimize parameter to ‘No’ will render out the entire image data window, skipping the optimization step and forcing the original data window to be used. This may avoid different dataWindow attribute values in the rendered AOVs, allowing them to be merged successfully.

In some cases the performance while processing the image may be slightly affected, depending on its size, as exrOptimize operations are aimed at improving memory usage and performance for programs which process images in tiles.

Set the type of render outputs to “raw”

Setting the type of the RenderOutputDefine node to ‘raw’ will allow rendering the image as received from the renderer and bypass any post-processing steps. Katana won’t perform any colour conversion or image optimisation on the output. This ensures that the file will be written using the header attributes as defined by the renderer, and prevents any changes to the dataWindow attribute caused by Katana’s internal image processing.

Ensure the rendered EXRs are not tiled, as Katana cannot merge tiled outputs

This is a default setting for some renderers like Arnold. Please check the renderer-specific output define node, for example ArnoldOutputChannelDefine, and make sure the driverParameters.tiled setting is disabled.

GETTING HELP

If none of these suggestions resolve the issue, please raise a Support request and let us know more about the problem you are encountering and the troubleshooting steps you have taken so far. For more information on how to open a Support request, please refer to this article: Q100064: How to raise a support ticket