Installation

Prerequisites

Before you begin, ensure you have met the following requirements:

• Your operating system should be Windows or Linux.
• You should have privileges to execute software.
• You should have a Vulkan Capable GPU as well as recent drivers.
• You should have a CPU with AVX2 instruction set support. You can check this with software such as HwInfo64/CPU-Z or by consulting the hardware specification.

Requirements

• Windows: Ensure you have the latest Microsoft Visual C++ Redistributable
• Linux: Ensure you have libvulkan1 and libgtk-3-0 installed.

Downloading the Tool

1. Visit the official download page to get the latest version of the tool.
2. Choose the appropriate version for your operating system.
3. Download the .zip file to your preferred directory.

Extracting the Tool

Windows

1. Right-click on the downloaded .zip file.
2. Select “Extract All…”
3. Choose a destination folder and click “Extract”.

Linux

1. Open a terminal.
2. Navigate to the directory where the .zip file is located.
3. Run the following command unzip ImageStacker.zip -d /path/to/destination

Choosing a Config

Copy one of the packaged configs for your DCC to <PathToImageStacker>/ImageStacker/Preferences and replace the current file in it

Running the Tool

1. Navigate to the directory where the tool was extracted.
2. Locate the executable file (ImageStacker.exe for Windows, ImageStacker for Linux).
3. Open the executable.

Post-Installation

After the installation is complete, you might want to:

• Create a Shortcut: For easier access, create a shortcut on your desktop or add ImageStacker to your PATH.
• Check for Updates: Regularly visit the official download page for updates and new features.
• Read the Documentation: Familiarize yourself with the Getting Started and How it works sections.

Troubleshooting

If you encounter any issues during installation please contact me at support@imagestacker.org or join the Discord and post your issues there.

Getting Started

To get started, simply open the ImageStacker, activate your license and start loading your images

Once you have activated your license, you can open the log (Window->Log or CTRL+L) to verify that your license was activated correctly

Once your license was successfully activated, you can press File->Open or CTRL+O to start loading a folder containing your AOVs. Make sure to monitor your log on the first load to check if there is any unaccounted for AOVs that might need to be added to the config. Please refer to the Preferences section on how to modify the AOV detection.

For easy visual inspection you can visualize each individual layer by selecting layers in the “Layer Stack” widget.

How it works

The ImageStacker works by identifying the AOV component of a file/channel name and assigning properties to it based on the rules specified in the Preferences. This identification is done in 3 levels in varying levels of leniency informing the user if the match was not found based on Level 1.

• Level 1: Direct match based on the AOV component (e.g. Filename.Cryptomatte.exr -> Cryptomatte)
• Level 2: Proximity match based on the AOV component (e.g. Filename.Cryptomat.exr -> Cryptomatte)
• Level 3: Direct match inside of the full filename (e.g. Some-Filename.Frame.Cryptomatte.exr -> Cryptomatte)
• No Match: Warning emitted and aov sorted into folder containing ‘…’ AOV

Once the AOV detection has happened, the files are then loaded into individual layers taking into account special layers such as Cryptomatte or Z-Depth.

These then have their properties (such as whether to color-manage the specified layer) applied to them after which an optional optimization step is applied.

This optimization attempts to remove the pixel difference between a layered 8- or 16- bit file as these do not compose back to the beauty exactly due to not having an addition in scene-linear space. Due to this limitation the closest blend mode which can represent this relationship is the “Screen” blend mode. This however does not add back up to the beauty.

To remedy this we insert a layer for each Beauty (as long as we detect AOVs for it) containing both an additive and subtractive layer which removes this difference as can be seen below removing any difference between the stacked layers as well as the beauty.

Once a stack has been written to disk, while it can still be previewed in the image preview, it is no longer stored in memory and therefore cannot be re-written out. To write it out again at a different bitdepth you must reload the stack or use the Command-Line with some automation.

Batch Processing

If you wish to stack multiple files without having to manually reset in between runs, the batch processing options will provide just that.

They can be found under File > Batch folders/files and will open a dialog asking you to select the root folder containing multiple folders or files to be stacked. Here, each folder/file would be a folder you would normally stack using the “Load Folder” option.

The batch process will then pick up each individual task and run it after each other notifying you of its progress in the log.

When batch processing, the resulting files are placed into each subdirectory with its name matching that of the directory. If we take the following directory structure where we would point the Batch process to BatchRoot/

• BatchRoot/
  • Stack_1/
  • Stack_2/
  • etc.

The output files would be created as follows:

• BatchRoot/
  • Stack_1/
    • Stack_1.psb
  • Stack_2/
    • Stack_2.psb
  • etc.

As the size of the stacks is not known beforehand the output format is always .psb to accomodate for all types of file sizes.

For batching files instead of folders this concept is identical, with the only difference being that insteack of having folders, we consider files

• BatchRoot/
  • Render_01.exr
  • Render_02.exr
  • etc.

Each of these files would then generate their own PSB

• BatchRoot/
  • Render_01.exr
  • Render_01.psb
  • Render_02.exr
  • Render_02.psb
  • etc.

Preferences

This section will cover the details of what you can customize using the preferences. We recommend using one of the base configs that come bundled according to your specific DCC and modifying your experience from there.

To navigate to the Preferences press Window->Preferences or CTRL+P. This tab may be docked to any part of the window or even dragged outside of the main window.

Output Settings

The Output Settings cover the basics such as colormanagement, bitdepth and what post-processing steps to apply to the data. These are the settings you are most likely to touch frequently.

Matching

The matching tab dictates how the filename is split up for detection. The basic principle is that a file/channel name can be separated into distinct components.

An example of this could be the following filename:

Where the “.” delimited parts of the strings each play a distinct role in how the file match is extracted. The same concept carries over to channelnames which in most cases are segmented in the following manner:

You may have noticed that sometimes the AOV component may not be present if e.g. we are dealing with the beauty the filename may just be ImageStackerExample.1001.exr and similarly the channelname could be only R.

To account for this the string detection allows for optional components to be specified in the match string. You can find examples of these below.

Delimiters

The delimiters are a list of comma separated, <> encapsulated characters that denote what to split the filename on. This may be multiple characters but it is recommended to have just a single delimiter controlling the filename to allow for other delimiters in the filename.

An example of this would be the filename: Image-Stacker-Example_V1.exr where it makes sense to only use <.> as a delimiter to avoid the other parts of the filename being split as well

Match Function

The match function defines how the filename is to be segmented into individual components as explained above. Each file component must be encapsulated by a <> and each non-delimiter file segment must be separated by a delimiter. See below for an example of valid and invalid functions.

Valid Match Function:

<file><delim><extension>

Invalid Match Function:

<file><extension>

To add optional components you may preface the component with “opt:”. If you wish to add an additional component keep in mind to have a matching optional delimiter either before or after.

You may preview all of the available options by right-clicking on the AOV match function section while previewing an example of how the string might look like in the preview tab below

Channel Match Function

The functionality of the Channel Match Function mirrors that of the regular Match Function.

AOV Detection

The AOV Detection Tab specifies what AOVs you wish to check for and what category they should be added to as well as the specific rules for that AOV.

The left tab shows you an overview over all the AOVs you wish to detect allowing you to freely add and delete AOVs. Multiple AOVs with the same type may be defined if you wish to handle e.g. some Utility AOVs like normals separately

The right tab on the other hand focuses on the assignment of each aov as well as the blend mode, color management and what names one might encounter

• 1: The type of AOV we are dealing with, this may be a specific AOV or a generic RGBUtil or RAWUtil if it is some other arbitrary aov without a specific purpose in the layer stack.
  Tip: Some render engines define e.g. the Background AOV separately in which case you could classify it as RGBUtil and add it at any position in the layer stack.
• 2: The blend mode of the AOV, note that Add is either “Screen” or “Add” depending on the context (8-/16-bit -> Screen; 32-bit -> Add)
• 3: Whether or not to apply color management to the AOV, if this is set to false the resulting image will not be converted to sRGB and instead stay in whichever rendering space you have chosen
• 4: The names the given AOV may have, you may add as many as you wish. However, the ImageStacker will automatically look for close matches in names so if the match string contains e.g. GlobalIllum but the filename contains GlobalIllumin the match will still succeed

List of all available AOVs

Layer Setup

The Layer Setup tab defines the final buildup of your stacked PSD/PSB file and how it is to be grouped. Items may be sorted in any order and the AOVs in the folder will dictate the blend mode of the folder rather than the blend mode of the individual AOVs.

This is in order to preserve a correct layer setup if you have multiple layers loaded into the same folder.

• 1: Add a folder under the current selection
• 2: Add an AOV under the current layer
• 3: Delete the currently selected item/tree (will delete children of groups as well)
• 4: Override the Blend Mode for the selected layer, this is useful if e.g. creating precomps where you want the blend modes to be on the AOV layers rather than the groups
• 5: Set the AOV type of the selected layer, only valid for AOV layers. Not for group layers

GUI

The GUI Tab holds information specific to the display of the ImageStacker and is stored separately from the other preferences (in Preferences/GUISettings.json rather than Preferences/Settings.json).

Preview Resolution

Controls the resolution of the preview images, if you wish to always view the images at full resolution choose the “Full” option. Keep in mind that this will increase memory requirements especially at large resolutions.

If an image is above the preview resolution no rescaling will be performed

Display Scaling (Windows Only)

Scale the whole GUI to optimize it for use on higher resolution screens.

This option is currently Windows Only

Command-Line

The ImageStacker comes with a command-line counterpart (ImageStackerCLI) offering the same feature set in a compact and easy to use executable.

The ImageStacker comes with a command-line counterpart (ImageStackerCLI) offering the same feature set in a compact and easy to use executable.

If you own a Complete license you can use the GUI as well as the CLI whereas if you own a Command-Line license you may only use the ImageStackerCLI.

Usage

Using the CLI is quite straightforward, loading of stacks requires only the -i | – – in argument to be passed. The output -o | – – out is optional and if not present the ImageStacker will generate an output file relative to the input directory for you.

$ ImageStackerCLI --in /Path/To/Folder --out /Path/To/OutFile

For ease of use you may also omit the – – in and – – out parameters and instead use positional arguments to point to the in and out path.

$ ImageStackerCLI /Path/To/Folder /Path/To/OutFile

If your paths contain special characters or spaces, the paths must be enclosed by quotation marks. When writing scripts working with the ImageStacker, it is safest to always contain quotation marks in order to avoid potential issues.

$ ImageStackerCLI "/Path/To/Folder With Spaces" /Path/To/OutFile

If you are running the tool as part of a pipeline and would like to point to a config file stored on a shared server etc. you may override the default config (Local to the executable) using the -c | – – config flag. Similarly you may override some of the variables such as bitdepth directly in the command-line. For a full list of flags and examples please refer to the Arguments section

Batch processing

Similar to the GUI the CLI offers batch processing through the -b | – – batch argument. If this argument is passed the input path must represent the root directory of multiple folders that we wish to load using the ImageStacker.

The – – out argument is ignored during batch processing and the finished PSD/PSB files are written into the folder it is currently processing with its name matching that of the folder.

$ ImageStackerCLI --in /Path/To/Multiple/Inputs --batch

Arguments

Below you can find a full list of all the commands availabe in the ImageStackerCLI executable. The order of these does not matter (except for in and output paths if they are not explicitly passed with – – in and – – out)

1st argument | -i {folder} | – – in {folder}

$ ImageStackerCLI --in Path/To/Folder

[Optional] 2nd argument | -o {.psd/.psb} | – – out {.psd/.psb}

$ ImageStackerCLI --in Path/To/Folder --out Path/To/File

-b | – – batch

$ ImageStackerCLI --in Path/To/Folder --batch

– – batch-folders

$ ImageStackerCLI --in Path/To/Folder --batch-folders

– – batch-files

$ ImageStackerCLI --in Path/To/Folder --batch-files

-c {config file} | – – config {config file}

$ ImageStackerCLI --in Path/To/Folder --config /Path/To/Config

-bd {8|16|32} | – – bitdepth {8|16|32}

$ ImageStackerCLI --in Path/To/Folder -bd 32

-psd

$ ImageStackerCLI --in Path/To/Folder -psd

-psb

$ ImageStackerCLI --in Path/To/Folder -psb

-v {Errors|Warnings|Info|Debug} | – – verbosity {Errors|Warnings|Info|Debug}

$ ImageStackerCLI --in Path/To/Folder --verbosity Debug

-h | – – help

$ ImageStackerCLI --help

– – activate {license_key}

$ ImageStackerCLI --activate CLI-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX

– – deactivate {[Optional]license_key}

$ ImageStackerCLI --deactivate 

$ ImageStackerCLI --deactivate CLI-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX

– – token

$ ImageStackerCLI --in Path/To/Folder --token 

Licensing

Unlike the GUI, which consumes and holds on to a license, the CLI instead picks up and releases licenses for each run. This means a single Command-Line license may be activated on any number of machines without any issues as long as there is only one concurrent instance actively running.

To activate a machine to use the ImageStackerCLI run the following command (without the curly braces). This will store the license locally and fetch it upon execution

$ ImageStackerCLI --activate {LicenseKey}

Similarly, to deactivate a license you can pass the – – deactivate argument. If no key is specified it will try to read the license key stored locally. This will clear out any activations, no matter if they were activated on the current machine or not.

Doing this might be necessary if a running process was interrupted through a user interrupt or an unexpected crash.

$ ImageStackerCLI --deactivate {optional:LicenseKey}

If the CLI is to be used alongside the GUI and the GUI is already activated, every invokation of the CLI must additionally have the – – token argument passed to it to not consume an additional licenses.

This signals that the activation token of the GUI is to be used for licensing of the Command-Line.

$ ImageStackerCLI --in {inpath} --out {outpath} --token

OCIO

The ImageStacker comes with a pre-packaged OCIO config that is found under ./colormanagement/ocio which may be extended to fit your needs and requirements. This OCIO config must define both the sRGB and sRGB-linear display transforms as an output format. These represent the 8- and 16- bit colourspaces (sRGB) as well as 32-bit (sRGB-linear) for the output file.

The output file is then assigned the appropriate ICC profile. If you wish to extend the render colourspaces please do so without modifying those two internal colourspaces and providing a transformation to scene-reference.

To compute any given colorspaces’ colour transform to scene-reference (which for the ImageStacker is ACES2065-1) you can refer to the excellent colour-science.org web app.