Description
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.
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 CLI from a command prompt at any location, or from a batch file.
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
The graph must have been fully executed in the ArtEngine GUI application before exporting the graph. Otherwise, there may be issues with the connections between nodes when running in the CLI.
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 memory issues for large images due to some current technical limitations that we hope to resolve in the future.
CLI Supported Nodes
The following is the list of currently supported nodes. ComposeMaterial and AmendMaterial also have some edge cases that don’t work properly at the moment
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
Pattern Unwarp
Plane Generator
Resize
Roughness / Gloss Generation
Seam Removal
Shadow Mask
Sharpen
Solid Color
Up-Res
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.