...
This tool allows you to execute graphs with supported nodes from a command-line interface, allowing for batch 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.
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
Once your graph is exported, the next step is to override the input and output locations. This is done in the configuration file.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:
...
MyMaterial_OutputNode_Height_2048.png
Program Location
You can find the command-line interface executable in the following folder:
...
The installer will provide the option to add this folder to your user PATH system variable, so you can run the CLI from a command prompt at any location, or from a 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.
...
In addition, Up-Res and Jpeg Artifact Removal will be more likely to run into memory 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. ComposeMaterial and AmendMaterial also have some edge cases that don’t work properly at the momentNB Some of these nodes might not have all of their properties exposed to the CLI.
CLI Supported Nodes:
Albedo Generation
Ambient Occlusion Generation
...
Normal Vector Rotation
Offset
Output (Including Batching)
Pattern Unwarp
Plane Generator
...
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 :
<Model xsi:type="LevelsModel">
<InputLevels>
<X>22</X>
<Y>255</Y>
</InputLevels>
<OutputLevels>
<X>0</X>
<Y>241</Y>
</OutputLevels>
<Gamma CliName="levelsGamma">1.5514209</Gamma>
</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.
...