IO Tool

The Colorway IO Tool is a command line tool that can be used to manipulate and optimize Deep Color Images. The tool allows artists to:

• Create new .dci files for use in Colorway,

• Unpack .dci files to disk for alteration and debugging,

• Add, remove, and update textures in .dci files,

• Optimize and crop textures in .dci files.

See Available IO Tool Commands for information on each command and argument.

Installing and Running the IO Tool

On Windows:

1.   Download ColorwayIOTool.exe from our website at https://www.foundry.com/products/colorway/download
2.   Drag the ColorwayIOTool.exe into a folder on disk of your choosing.
3.   Open a command line prompt and change directory to the directory containing the ColorwayIOTool as follows: 
cd C:\Users\<user>\<folder containing ColorwayIOTool.exe>

Tip:  On Windows, you can open a command line prompt by pressing the Windows key, type cmd and press Return/Enter.

4.   To run commands with the IO tool, type: 
ColorwayIOTool.exe <insert arguments here>

On macOS:

1.   Download the ColorwayIOTool binary file from our website at https://www.foundry.com/products/colorway/download
2.   Open Terminal.
3.   Change directory to the directory containing the ColorwayIOTool as follows: 
cd /Users/<user>/<folder containing ColorwayIOTool binary file>
4.   To ensure the ColorwayIOTool is executable, enter the following command: 
chmod a+x ColorwayIOTool
5.   To run commands with the IO tool, type: 
./ColorwayIOTool <insert arguments>

Tip:  Use the -h argument to see a list of available commands.

Unpacking .dci Files

Use the following arguments to unpack .dci files:

--dump <path to file>.dci <path to target folder> <create subdirectory>

For example:

ColorwayIOTool.exe --dump C:\Users\user_name\MyDocuments\my_file.dci C:\Users\user_name\MyDocuments\Dump 1

This creates a subfolder inside the target folder and unpacks the contents of the .dci file in the subfolder. The 1 at the end of the command specifies that a subdirectory should be created for the unpacked .dci file. If 0 is entered at the end of the command, the .dci file contents are unpacked into the target folder instead of a subdirectory.

This command can be useful if you need to analyze which textures are not rendering correctly in Colorway.

Creating .dci Files

Use the following arguments to create a new .dci file. The source folder should first be created by the Unpacking .dci Files operation:

--create <path to file>.dci <file type> <path to source folder>

For example:

ColorwayIOTool.exe --create C:\Users\user_name\MyDocuments\my_file.dci dci C:\Users\user_name\MyDocuments\Create

A new .dci file is created, packed with the contents of the source folder. See Unpacking .dci Files.

Note:  The --create command currently only works on macOS. A file is created on Windows, but the file is not populated with content.

Note:  When creating a file, if no file type is specified, a .dci file is created by default.

Cropping .dci File Textures

Use the following arguments to crop textures in a given .dci file:

--crop <path to file>.dci <threshold value>

For example:

ColorwayIOTool.exe --crop C:\Users\user_name\MyDocuments\my_file.dci 80

This reduces the size of the .dci file on disk, and helps minimize Colorway load times. You can enter a threshold value of a range between 0-255. Threshold values can help in improving render performance in Colorway and produces more optimized .dci files, especially files with reflection and refraction passes enabled. The higher the threshold value, the more pixels inside the .dci textures are cropped from the image.

Note:  The threshold range refers to 8-bit textures. If your textures are 16-bit, the input threshold value is multiplied by 255 to get the threshold value for 16-bit range.

Optimizing .dci File Textures

Use the following arguments to remove duplicate textures from the transparent and opaque passes in the .dci file:

--optimize <path to file>.dci <threshold value>

For example:

ColorwayIOTool.exe --optimize C:\Users\user_name\MyDocuments\my_file.dci 80

This helps improve both load and render times in Colorway. You can enter a threshold value of a range between 0-255. The higher the threshold value, the more likely textures in the transparent and opaque passes are found by the tool as duplicates and removed.

Note:  The threshold range refers to 8-bit textures. If your textures are 16-bit, the threshold value is multiplied by 255 to get the threshold value for 16-bit range.

Tip:  Run a --crop command and then an --optimize command to get the most effective optimization for your .dci files.

Available IO Tool Commands

Argument/Flag

Action

-h [ --help ]

Prints a help message. For example:

ColorwayIOTool.exe -h

-v [ --version ]

Prints the tool version. For example:

ColorwayIOTool.exe -v

--check <dci file>

Performs integrity check of given .dci file. For example:

ColorwayIOTool.exe --check C:\Users\user_name\MyDocuments\my_dci.dci

--create <output path> <file type> <source folder>

Creates empty file at specified folder location. The .dci file is populated with the source folder contents if provided. For example:

ColorwayIOTool.exe --create C:\Users\user_name\OutputFolder\ dci C:\Users\user_name\MyDocuments\my_dci.dci

Note:  The file type defaults to .dci if not specified.

-d [ --dump ] <dci file> <output path> <create subdirectory>

Unpacks .dci file contents to specified location. The create subdirectory value at the end of the command can be 0 or 1. When 1 is entered, a file subfolder is created in the output path and contents of the .dci file are unpacked there. For example:

ColorwayIOTool.exe --dump C:\Users\user_name\MyDocuments\my_dci.dci C:\Users\user_name\OutputFolder\ 1

When 0 is entered, a subdirectory is not created and the contents of the .dci file are unpacked directly into the output path.

-l [ --list ] <dci file>

Lists .dci file contents. For example:

ColorwayIOTool.exe -l C:\Users\user_name\MyDocuments\my_dci.dci

--update <dci file> <dci stored asset> <source file>

Adds or updates an asset within a .dci file with the source file contents. For example:

ColorwayIOTool.exe --update C:\Users\user_name\MyDocuments\my_dci.dci thumbnail.png C:\Users\user_name\MyDocuments\thumbnail.png

Note:  The --update command currently only works on macOS.

Tip:  Use the --list command to see the assets stored inside the .dci file.

--remove <dci file> <dci stored asset>

Removes a stored asset from a .dci file. For example:

ColorwayIOTool.exe --remove C:\Users\user_name\MyDocuments\my_dci.dci thumbnail.png

Note:  The --remove command currently only works on macOS.

--decrypt <input file> <output path>

Decrypts specified file to output location. For example:

ColorwayIOTool.exe --decrypt C:\Users\user_name\MyDocuments\my_dci.dci C:\Users\user_name\MyDocuments\Output

You can view the decrypted file contents using an application such as an SQL database viewer.

Note:  The output folder is created by the --decrypt command, so make sure the folder does not already exist on disk.

--crop <dci file> <threshold>

Crops textures in a given file. Threshold can be in the 0-255 range. For example:

 ColorwayIOTool.exe --crop C:\Users\user_name\MyDocuments\my_file.dci 80

 

--optimize <dci file> <threshold>

Removes duplicated textures from a given file. Threshold can be in the 0-255 range. For example:

ColorwayIOTool.exe --optimize C:\Users\user_name\MyDocuments\my_file.dci 80