CommandLine Tool (Beta)

Description

This tool allows you to execute graphs with supported nodes from a command-line interface, allowing for processing of images. You can easily process different batches by either specifying a different base path for each run or by editing the paths in a configuration file between runs.

You can check out our video tutorial here.

Usage

The end-to-end process has these steps:

Create a graph in the ArtEngine GUI application.
Run the graph, ensuring all nodes have executed.
Export the graph and configuration file from the ArtEngine GUI application.
Edit the paths in the configuration file to match your naming conventions.
Run the command line interface (CLI) by specifying the configuration file to use.
1. You may wish to have your own batch file or exe that invokes the CLI repeatedly with different parameters or configuration files.

Exporting a graph

With a project opened in ArtEngine, ensuring that all nodes have been executed, select File > Export Graph or use the keyboard shortcut Ctrl+Shift+E to export the graph.

Select your output location and name the file. The graph file, and its corresponding configuration file will be created.

graphname.xml

graphname-config.xml

After saving an Exported Graph to your drive, you can run it again and again from the Command Line without having to open ArtEngine.

When you need to change and adjust one of the properties on one of the nodes, you can use an Override. To do this, you will need to hand edit the paired project.xml file.What this gives is the ability to change the Chrome Ball node config/calibration file path, or the amount of Blending, or one of the many properties you can see in a node in ArtEngine.The exported graph / CLI project-config.xml is how you change the inputs/outputs on subsequent runs.

This is beneficial because it allows an Artist to create the graph, and anyone can run it thereafter.

Configuration File

The configuration (aka “config”) file is an xml document that specifies the following things:

The relative path to the exported graph file. The graph file contains the nodes and connections of the graph.
The file paths to the input and output files. These paths can be either relative to the config file or absolute. The inputs and outputs can be either bitmaps or materials.

Setting Input/Output Paths

Within each <ConfigInputNode> or <ConfigOutputNode> tag, look for a <Location></Location> tag. Inside each such tag, set a value for a relative or absolute file location and then save the config file.

Bitmap

For a bitmap, you simply enter the path for the file. You can use any image file extension supported by ArtEngine.

Material

For materials, you can specify the file location either without a file extension or with the correct file extension (for example, .amtl for exporting Unity materials). Images will be saved relative to the material file just like they would in ArtEngine. Tag attributes can be separated by ‘-’ characters

Material output format:Possible tags - {Name}, {Type}, {Resolution}

E.g <Location>MyMaterial-{Name}-{Type}-{Resolution}.png</Location>

Output File Names:

MyMaterial_OutputNode_Diffuse_2048.png

MyMaterial_OutputNode_Normal_2048.png

MyMaterial_OutputNode_Height_2048.png

Program Location

You can find the command-line interface executable in the following folder:

ProgramFiles/Artomatix/Artomatix/ArtEngine.CLI/ArtEngine.CLI.exe

The installer will provide the option to add this folder to your user PATH system variable, so you can run the command prompt or batch file from any location.

Arguments

[required]

--config=[configpath]

Ex: ArtEngine.CLI.exe --config=“some folder/somegraph-config.xml” (required)

Specifies the path to the config file

[optional]

--basePath=[basePath]

Ex: ArtEngine.CLI.exe --config=”graph-config.xml” --basePath=”MyInputFolder”

Changes the base path for all relative paths specified in the config file. By default, the base path is the location of the config file itself. This applies to all relative input and output file paths. This does not apply to any absolute paths specified.

Known Limitations

It is not currently possible to change material shape between graph runs, for example if you have a node that has been setup to be able to process materials with Albedo, Normal, Height, AO, Gloss and you now want a Specular map it will be necessary to re-export the graph.

If you use nodes that can output either a Material or a Bitmap (such as Seam Removal), make sure it outputs a Material and not a Bitmap. Bitmap output from such a node is not currently supported. The workaround is to output a material and then use a Split Material node.

In addition, Up-Res and Jpeg Artifact Removal will be more likely to run into VRAM issues for large images due to some current technical limitations that we hope to resolve in the future.

The following is the list of currently supported nodes. NB Some of these nodes might not have all of their properties exposed to the CLI.

CLI Supported Nodes:

Albedo Generation

Ambient Occlusion Generation

Amend Material

Auto Levels

Baker

Basic Shape

Blend (partial support)

Blend (Material) (partial support)

Blend (Normal) (partial support)

Blur

Brightness / Contrast

Chrome Ball

Clone Stamp

Color Muse

Color Space Conversion

Color To Mask

Color Transfer

Compose Material

Content-Aware Fill

Crop

Detect Edges

Distort

Export Mesh

External Execution

Free Transform

Gradient

Gradient Removal

Grayscale

Hard Shadow Removal

Height Generation

High Pass

Histogram Scan

Hue / Saturation

Invert

JPEG Artifact Removal

Levels

Merge Channels

Multi-Angle to Texture

Mutation

Mutation (Structure) (partial support)

Mutation Revision

Noise

Normal Flip

Normal Generation

Normal Intensity Equalizer

Normal Vector Rotation

Offset

Output (Including Batching)

Pattern Unwarp

Plane Generator

Resize

Roughness / Gloss Generation

Seam Removal

Shadow Mask

Sharpen

Solid Color

Up-Res

ComposeMaterial and AmendMaterial also have some edge cases that don’t work properly at the moment. There are some issues with the blend nodes too, which we are planning to address.

Custom CLI overrides

The Artengine CLI also allows node properties and input file paths to be overridden using custom CLI parameters. In order to enable this, your graph.XML file will need to be manually modified to specify override names for node properties. Then the CLI call will use the specified override name to provide override values.

For example, this is part of a graph XML file exported from an Artengine graph, with a Levels node property, with a custom name 'levelsGamma' applied to it, for CLI overriding :

</InputLevels>

</OutputLevels>

</Model>

Then, when you call the CLI to run this graph, you can specify the value that you want that gamma property to take, for that run and only for that run, using the following syntax :

ArtEngine.CLI --config "<Path>\upres-config.xml" --basePath "<Path>" --overrides "levelsGamma=7.2"

It's possible to specify multiple override values using the following syntax, where in this example a second property has been made overridable with the name 'histogramContrast' :

ArtEngine.CLI --config "<Path>\upres-config.xml" --basePath "<Path>" --overrides "levelsGamma=7.2","histogramContrast=0.7"

N.B It’s important to not have any spaces between the two comma separated double-quoted override strings!

N.B You can override input paths too, using a similar process modifying your config.XML file.

Exit Codes & Errors

The following error codes are specific to the command-line interface (CLI):

14: CLI Bad Input - Could not open a config file, graph file, input image/material, missing argument for config file path, or bad input in the config file or graph file. Log output should provide more information.

15: CLI Graph Failure - Some error occurred during execution of the graph. There may be an unsupported node used, or there may be an undocumented error. Log output should provide more information.