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 errors might look like the following:
Running command: ExrCombine
/tmp/katana_tmpdir_7664/sphere_diffuse5_Render_primary_rgba_square_512_linear.1.exr primary
/tmp/katana_tmpdir_7664/sphere_diffuse5_Render_direct_diffuse_direct_diffuse_square_512_linear.1.exr direct_diffuse
/tmp/katana_tmpdir_7664/sphere_diffuse5_Render_sss_sss_square_512_linear.1.exr
sss /tmp/merge.exr
Render stopped by signal: 6
CommandLineRender Error: doRender problem
Reason = Render stopped by signal: 6
Render error. Time elapsed: 6.33 s
Node 'Render': Render failed with a rendering error: Render stopped by signal: 6
The render failing might even result in a Katana crash with the following error in the stack trace:
[INFO python.MainBatch]: *** Error in 'ExrCombine': free(): invalid pointer: 0x0000000000e8f1e0 ***
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 all AOVs to be merged have the same dataWindow attribute value
- Bypass post render EXR optimisations by using "raw" output type and/or disable exrOptimize
- 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. This is due to the limitation of OpenEXR where only one data window can be stored in the header. 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.
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: ID 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:
> exrinfo image.exr
image.exr:
file format version: 2, flags 0x0
channels (type chlist):
B, 16-bit floating-point, sampling 1 1
G, 16-bit floating-point, sampling 1 1
R, 16-bit floating-point, sampling 1 1
compression (type compression): piz
dataWindow (type box2i): (0 0) - (511 511)
displayWindow (type box2i): (135 125) - (377 409)
lineOrder (type lineOrder): increasing y
pixelAspectRatio (type float): 1
screenWindowCenter (type v2f): (0 0)
screenWindowWidth (type float): 1
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.
Known issues with Cryptomatte in Katana
Cryptomatte uses meta-data stored in cryptomatte/foo/bar in the EXR header for each cryptomatte channel. ExrCombine does not merge the cryptomatte meta-data, so the resulting merged EXR does not display the cryptomatte channels in Nuke. Pixar's exrmerge only copies the cryptomatte meta-data for the first EXR.
However, you should now be able to combine all Cryptomatte channels into one EXR as of Katana 4.5v6 and future releases.
For reference, this feature request was logged as: ID 428053 - ExrCombine: Support for merging Cryptomatte channels
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 the 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:
Bypass post render EXR optimisations by using "raw" output type and exrOptimize settings
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.
These attributes are defined via the RenderOutputDefine node’s convertSettings parameters. Please see the Katana Online Help’s RenderOutputDefine node reference for more information on these settings.
Set the exrOptimize parameter to “No”
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)
The exrOptimize flag is mainly used to optimize the image data window and 'shrinkwrap' the image by removing the redundant clear information around the edges. 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
We're sorry to hear that
Please tell us why