Filter Forge Help - Command-Line Renderer

The command-line renderer allows you to batch-render any number of saved filter presets. It is available as a separate executable file. Under Microsoft Windows, the file name is FFXCmdRenderer-x64.exe.Under Mac OS X, the file name is FFCmdRenderer. The only parameter the command-line renderer accepts is the path to an .xml file which describes rendering jobs.

A different way to process multiple images at once is to load an image sequence into an artboard. For details, see Artboard Properties.

Using the Command-Line Renderer under Windows

Prepare the .xml file containing the tasks to process (scroll down for an example). The example file is also available in the C:\Program Files\Filter Forge 12\Resources\System folder as batchsample.xml.
Open the Command Prompt (Start > Windows System > Command Prompt).
Type cd %ProgramFiles%\Filter Forge 12\Bin\ and hit Enter.
Type FFXCmdRenderer-x64.exe batch.xml, where batch.xml is the name or path to the .xml file you prepared earlier (you can use any other file name or path).

Using the Command-Line Renderer under Mac OS X

Prepare the .xml file containing the tasks to process (scroll down for an example). The example file is also available in the /Applications/Filter Forge 12/Resources/System directory as batchsample.xml.
Launch Terminal (Applications > Utilities > Terminal.app).
Type cd /Applications/Filter\ Forge\ 11/ and hit Enter.
Type ./FFCmdRenderer batch.xml, where batch.xml is the name or path to the .xml file you prepared earlier (you can use any other file name or path).

Error Handling and Logging

All errors that occurred while rendering are written down to the log file and shown in the console. The log file is named FFX CmdRenderer.log and located in the system temporary folder (under Windows 7 and newer, it is usually C:\Users\User Name\AppData\Local\Temp).Terminal window. The log file is named FFX CmdRenderer.log and located in the system temporary folder (under Mac OS, it is usually /tmp/).

When the renderer encounters a non-critical error, such as typos in the filter name or impossible bit depth values, it skips the invalid task and advances to the next task in the queue. Critical errors, such as invalid xml scheme, cause the renderer to abort all operations.

Xml File Example

<?xml version="1.0" encoding="utf-8" ?>
<Tasks>
    <Task>
        <Image value="" width="300" height="400" />
        <Selection value="" />
        <Result path="D:\Images\Wood.bmp" />
        <Filter value="C:\Users\User Name\AppData\Filter Forge 12\My Filters\myfilter-1.ffxml" />
        <Preset value="0" />
    </Task>
    <Task>
        <Image value="" width="300" height="400" />
        <Selection value="" />
        <Result path="D:\Images\WetStone.jpg" format="JPG" />
        <Filter value="C:\Users\User Name\AppData\Filter Forge 12\My Filters\myfilter-4.ffxml" />
        <Preset value="0" />
    </Task>
    <Task>
        <Image value="D:\1.jpg" />
        <Selection value="" />
        <Result path="D:\Images\ComicBook.bmp" format="BMP">
            <Options>
                <BitDepth value="32" />
                <FlipRowOrder value="false" />
            </Options>
        </Result>
        <RenderingOptions>
            <Dither value="false" />
            <AntiAliasBitmapComponentSources value="true" />
        </RenderingOptions>
        <Filter value="C:\Users\User Name\AppData\Filter Forge 12\My Filters\myfilter-2.ffxml" />
        <Preset value="0" />
    </Task>
    <GlobalSettings>
        <RenderingOptions>
            <UseMultithreading value="true" />
            <Dither value="true" />
            <Progressive value="true" />
            <OptimizeBlurs value="true" />
            <AntiAliasBitmapComponentSources value="false" />
            <Jitter value="0" />
            <TemporaryFilesLocation value="" />
            <RAMUsageLimit value="60" />
            <NormalMapFlipY value="false" />
        </RenderingOptions>
        <BitmapFormatOptions>
            <DefaultFormat value="JPG" />
            <BMP>
                <BitDepth value="32" />
                <FlipRowOrder value="false" />
            </BMP>
            <JPG>
                <Quality value="98" />
                <FullPrecision value="true" />
            </JPG>
            <TIF>
                <BitDepth value="8" />
                <FloatFormat value="false" />
                <IncludeTransparency value="true" />
                <ImageCompression value="LZW" />
            </TIF>
            <TGA>
                <BitDepth value="32" />
                <IncludeTransparency value="true" />
                <FlipRowOrder value="false" />
            </TGA>
            <PNG>
                <BitDepth value="16" />
                <IncludeTransparency value="true" />
                <ImageCompression value="BEST" />
            </PNG>
            <EXR>
                <BitDepth value="32" />
                <IncludeTransparency value="true" />
                <ImageCompression value="PIZ" />
                <FlipRowOrder value="false" />
            </EXR>
            <PFM />
        </BitmapFormatOptions>
    </GlobalSettings>
</Tasks>
<?xml version="1.0" encoding="utf-8"?>
<Tasks>
    <Task>
        <Image value="" width="300" height="400" />
        <Selection value="" />
        <Result path="~/Documents/Wood.bmp" />
        <Filter value="~/Library/Application Support/Filter Forge 12/My Filters/myfilter-1.ffxml" />
        <Preset value="0" />
    </Task>
    <Task>
        <Image value="" width="300" height="400" />
        <Selection value="" />
        <Result path="~/Documents/WetStone.jpg" format="JPG" />
        <Filter value="~/Library/Application Support/Filter Forge 12/My Filters/myfilter-4.ffxml" />
        <Preset value="0" />
    </Task>
    <Task>
        <Image value="~/Documents/1.jpg" />
        <Selection value="" />
        <Result path="~/Documents/ComicBook.bmp" format="BMP">
            <Options>
                <BitDepth value="32" />
                <FlipRowOrder value="false" />
            </Options>
        </Result>
        <RenderingOptions>
            <Dither value="false" />
            <AntiAliasBitmapComponentSources value="true" />
        </RenderingOptions>
        <Filter value="~/Library/Application Support/Filter Forge 12/My Filters/myfilter-2.ffxml" />
        <Preset value="0" />
    </Task>
    <GlobalSettings>
        <RenderingOptions>
            <UseMultithreading value="true" />
            <Dither value="true" />
            <Progressive value="true" />
            <OptimizeBlurs value="true" />
            <AntiAliasBitmapComponentSources value="false" />
            <Jitter value="0" />
            <TemporaryFilesLocation value="" />
            <RAMUsageLimit value="60" />
            <NormalMapFlipY value="false" />
        </RenderingOptions>
        <BitmapFormatOptions>
            <DefaultFormat value="JPG" />
            <BMP>
                <BitDepth value="32" />
                <FlipRowOrder value="false" />
            </BMP>
            <JPG>
                <Quality value="98" />
                <FullPrecision value="true" />
            </JPG>
            <TIF>
                <BitDepth value="8" />
                <FloatFormat value="false" />
                <IncludeTransparency value="true" />
                <ImageCompression value="LZW" />
            </TIF>
            <TGA>
                <BitDepth value="32" />
                <IncludeTransparency value="true" />
                <FlipRowOrder value="false" />
            </TGA>
            <PNG>
                <BitDepth value="16" />
                <IncludeTransparency value="true" />
                <ImageCompression value="BEST" />
            </PNG>
            <EXR>
                <BitDepth value="32" />
                <IncludeTransparency value="true" />
                <ImageCompression value="PIZ" />
                <FlipRowOrder value="false" />
            </EXR>
            <PFM />
        </BitmapFormatOptions>
    </GlobalSettings>
</Tasks>

Xml File Hierarchy

The .xml file has three hierarchy levels of nested sections. Some of them are mandatory, and some are optional.

<Tasks>
    <Task>
        <Options></Options>
        <RenderingOptions></RenderingOptions>
    </Task>
    <GlobalSettings></GlobalSettings>
</Tasks>

Xml File Contents

The .xml file describes rendering jobs. A single job renders a single filter preset and saves the result into an image file. The jobs are processed in the same order as they are listed in the .xml file. A single rendering job is enclosed in <Task></Task> tags. It has five mandatory tags:

<Image value="path_to_the_source_image.jpg" width="number" height="number"/>. Specifies the parameters of the source image to which the current filter will be applied. For Effect filters, the value attribute contains the path to the source image, and the width and height attributes may be omitted. For Texture filters that don't require the source image, the width and height attributes specify the new image dimensions, and the value attribute may be empty.
<Selection value=""/>. Specifies the path to the image which will be used as a selection for the current rendering task. If the filter doesn't require selection, the value attribute may be empty.
<Filter value="path_to_the_filter.ffxml"/>. Specifies the path to the filter to render. The filters are usually located in the C:\Users\User Name\AppData\Filter Forge\System\Library and in the C:\Users\User Name\AppData\Filter Forge 12\My Filters folders.~/Library/Application Support/Filter Forge 12/System/Library/ and in the ~/Library/Application Support/Filter Forge 12/My Filters directories. Note: user-added presets for library filters that are located in the AppData\Filter Forge\System\Library folder will be skipped. When preparing to render custom presets for a library filter you should first copy the filter to a custom folder, e.g. My Filters, and specify this location in the XML task file.
<Preset value="preset_number"/>. Specifies the saved preset number, starting from 0. All filter settings, such as controls, lighting, anti-aliasing, etc. are stored within the preset.
<Result path="path_to_the_result.jpg" format="JPG"/>. Specifies the path for the result image and its format. All formats supported by your Filter Forge edition are accepted. The format attribute is optional and specifies the result image format; if it is omitted (as in the first job in the sample .xml file above), the default Jpeg format is used. Also, the format attribute can have an additional <Options> section. For more information, see Image Format Options below.

Image Format Options

The <Result> tag can have an additional <Options> section which describes parameters for the image format specified by the format attribute in the <Result> tag. If the <Options> section is omitted, the format parameters are read from the <GlobalSettings> section, and if <GlobalSettings> is omitted, – from the C:\Documents and Settings\User Name\Application Data\Filter Forge 8\FileFormatOptions.xml file.~/Library/Application Support/Filter Forge 8/FileFormatOptions.xml file. If the format attribute itself is missing from the <Result> tag, the <Options> section is ignored.

These are possible tags for the <Options> section. The tags in this section should correspond to the format specified in the <Result> tag.

BMP format options

<BitDepth value="32"/>. Specifies the bit depth of the resulting image. Allowed values: 24 and 32.
<FlipRowOrder value="false"/>. When set to false, the row order is normal; when set to true, the order is reversed.

JPG format options

<Quality value="98"/>. Specifies the jpeg quality value. Allowed values: 0-100.
<FullPrecision value="true"/>. Setting this to true is equivalent to checking the 'Full-precision color encoding' checkbox in the JPEG Optons dialog in the Filter Forge GUI.

TIF format options

<BitDepth value="8"/>. Specifies the bit depth of the resulting image. Allowed values: 8, 16, and 32.
<FloatFormat value="false"/>. When set to false, the color channels are saved as integer values, otherwise half-precision float is used.
<IncludeTransparency value="true"/>. When set to false, the alpha channel is not saved.
<ImageCompression value="LZW"/>. Specifies the compression method. Allowed values: NONE, LZW, and DEFLATE.

TGA format options

<BitDepth value="32"/>. Specifies the bit depth of the resulting image. Allowed values: 24 and 32.
<IncludeTransparency value="true"/>. When set to false, the alpha channel is not saved.
<FlipRowOrder value="false"/> When set to false, the row order is normal; when set to true, the order is reversed.

PNG format options

<BitDepth value="16"/>. Specifies the bit depth of the resulting image. Allowed values: 8 and 16.
<IncludeTransparency value="true"/>. When set to false, the alpha channel is not saved.
<ImageCompression value="BEST"/>. Specifies the compression quality. Allowed values: NONE, FAST, and BEST.

EXR format options

<BitDepth value="32"/>. Specifies the precision of the resulting image. Allowed values: 16 (half-precision float) and 32 (single-precision float).
<IncludeTransparency value="true"/>. When set to false, the alpha channel is not saved.
<ImageCompression value="PIZ"/>. Specifies the compression method. Allowed values: NONE, RLE, ZIP, PIZ, and PXR24.
<FlipRowOrder value="false"/>. When set to false, the row order is normal; when set to true, the order is reversed.

PFM format options

The PFM image format has no options.

Rendering Options

<Task> can have an optional <RenderingOptions> section which describes rendering parameters for the output file. If the <RenderingOptions> section is omitted, the rendering parameters are read from the <GlobalSettings> section. If the <GlobalSettings> section is omitted, Filter Forge default parameters are used instead.

These are possible tags for the <RenderingOptions> section. The tags in this section correspond to the Rendering tab in the Options dialog in the Filter Forge GUI.

<UseMultithreading value="true" />. Switches the renderer between using a single CPU/core or all available CPUs/cores. When set to false, a single core/CPU is used.
<Dither value="true" />. When set to true, the renderer applies dithering to the output image.
<Progressive value="true" />. This tag has been added for compatibility and does not affect the command-line renderer.
<OptimizeBlurs value="true" />. When set to true, causes all blur-based components (such as Blur, High Pass or Sharpen) to use an integer blur radius instead of a floating-point radius in cases when the internal blur radius exceeds 40 pixels.
<AntiAliasBitmapComponentSources value="false" /> . When set to true, all bitmap-based components will operate on anti-aliased sources.
<Jitter value="0" />. When set to a value other than 0, randomizes sample positions within a pixel being anti-aliased, which helps eliminate unwanted artifacts that occur in high-frequency pattern textures during anti-aliasing. Allowed values: within the 0-1 range, accurate to 1 decimal place.
<TemporaryFilesLocation value="" />. Allows to specify the location for temporary files which Filter Forge may create during the rendering.
<RAMUsageLimit value="60" />. Sets the maximum percentage of physical memory available to Filter Forge. Allowed values: 10–90.
<NormalMapFlipY value="false" />. Defines how the normal maps are generated. When set to false, a DirectX-style map is generated; when set to true, an OpenGL-style map is generated.

Global Settings

The top <Tasks> section can have an optional <GlobalSettings> section which describes global rendering and image format parameters for the whole file. If the <GlobalSettings> section is omitted, Filter Forge default parameters are used instead.

The tags in the <GlobalSettings> section are the same as those in the <RenderingOptions> and <Options> sections above.