in

The most important parameter is --in, which specifies the path and filename of the flame you want to render. The following will place the rendered output as 0.png in the same folder as the flame file:

> emberrender --in=C:\yourflames\test.flame

name_enable [false]

The output images will be named numerically by default. However, if you would like to have them named according to the name field in the Xml, use the --name_enable option:

> emberrender --in=C:\yourflames\test.flame --name_enable

opencl [false]

Use the GPU to render with OpenCL instead of using the traditional CPU renderer like so:

> emberrender --in=C:\yourflames\test.flame --opencl

This will use the first device found on the system by default. If you are unsure what devices you have and in what order they are enumerated, run this program with just the --openclinfo argument.

To specify a different device, or more than one device, use the --device argument.

device [0] (ignored for CPU)

Specify the 0-based index of the device(s) to use when running with --opencl like so:

> emberrender --in=C:\yourflames\test.flame --opencl --device=1

If omitted, the –opencl argument will use the first device found on the system by default.

When running with multiple devices, supply them in a comma-separated list like so:

> emberrender --in=C:\yourflames\test.flame --opencl --device=0,2,3

The first device in the list will be considered the primary device. This means that it is responsible for reporting progress, summing the histograms from other devices once iteration is complete, density filtering, spatial filtering and final color correction. Since this device handles additional work, be sure to use the most powerful device in your system as the primary one.

verbose [false]

Whether to print additional information when rendering, such as the current flame information and rendering performance statistics.

> emberrender --in=C:\yourflames\test.flame --verbose

progress [false]

Whether to print rendering progress. This will slow down performance by about 10% so it shouldn’t be used when doing lengthy renders.

> emberrender --in=C:\yourflames\test.flame --progress

Note that when using OpenCL with multiple devices, only the first device reports progress, however the report is still an accurate combination of the progress of all devices.

sp [false]

Use the single precision data type when doing the calculations for iteration. The default value of false means that double precision is used if this argument is omitted. For most flames, there is no difference in output between the two. Regarding performance, SP will run slightly faster than DP on the CPU, and much faster on the GPU. You can test with whether it makes a difference for your flame by running the following which will also show the performance difference:

> emberrender --in=C:\yourflames\test.flame --suffix=_dp
> emberrender --in=C:\yourflames\test.flame --sp --suffix=_sp

nstrips

Split the render into horizontal chunks. This is useful for doing very large renders that exceed available memory, however it will greatly impact performance. It’s more applicable on the GPU than on the CPU, since CPU memory sizes often exceed 8 or 16GB today. Split a render into 4 strips like so:

> emberrender --in=C:\yourflames\test.flame --nstrips=4

Note that the number of strips must divide evenly into the height of the image. If it does not, the next highest divisor will be computed and used. If the height is a prime number, strips will not be used.

prefix, suffix

Concatenate the supplied string to the beginning or end of every output filename.

The following would produce an output image with the name “myprefix_01.png”:

> emberrender --in=C:\yourflames\test.flame --prefix=myprefix_

The following would produce an output image with the name “01_mysuffix.png”:

> emberrender --in=C:\yourflames\test.flame --suffix=_mysuffix

The two can be combined to produce an output image with the name “myprefix_01_mysuffix.png” like so:

> emberrender --in=C:\yourflames\test.flame --prefix=myprefix_ --suffix=_mysuffix

This is useful when you want to differentiate one batch of files from another, as illustrated in the examples throughout this page.

Although all of the information needed to render a flame is stored in the input Xml file, it is sometimes useful to ignore these values and use ones specified by the user immediately before beginning a render. This is useful for testing during preliminary renders and is accomplished via several arguments listed here.

demax

Override the maximum density filter width value from the Xml file with this value. Sometimes density filtering can cause an error on certain Nvidia GPUs, so it’s helpful to be able to reduce the size of the filter for all flames that will be rendered.

> emberrender --in=C:\yourflames\test.flame --demax=8

Note this does not have to be used in conjunction with demin. If omitted, the value in the input Xml file will be used. If used together, this value must be greater than or equal to demin.

demin

Override the minimum density filter width value from the Xml file with this value.

> emberrender --in=C:\yourflames\test.flame --demin=1

Note this does not have to be used in conjunction with demax. If omitted, the value in the input Xml file will be used. If used together, this value must be less than or equal to demax.

quality

Override the quality value from the Xml file with this value. It’s useful in situations where you want to do a very quick render, even though the Xml specifies a large quality value. If you’ve recently downloaded some params and want a quick render without bothering with the quality value in the file, you could do the following:

> emberrender --in=C:\yourflames\test.flame --quality=10

It’s also useful if you want to compare what the outputs look like at different qualities:

> emberrender --in=C:\yourflames\test.flame --quality=100 --suffix=_q100
> emberrender --in=C:\yourflames\test.flame --quality=1000 --suffix=_q1000
> emberrender --in=C:\yourflames\test.flame --quality=5000 --suffix=_q5000
> emberrender --in=C:\yourflames\test.flame --quality=10000 --suffix=_q10000

supersample [Range: 0 – 4]

Override the supersample value from the Xml file with this value. This will override the value specified in the Xml file if non-zero. Supersample affects different images differently. In some cases, not using it at all looks roughly the same as using a higher value. In other images, using a value of 2 makes a noticeable improvement over using 1 (disabled). Values of 3 and 4 rarely offer improvement, but are supported in the case they need to be used. So this option is useful when investigating the effect of supersample on a particular image. You might want to run multiple renders in a script like so, then compare the outputs:

> emberrender --in=C:\yourflames\test.flame --supersample=1 --suffix=_ss1
> emberrender --in=C:\yourflames\test.flame --supersample=2 --suffix=_ss2
> emberrender --in=C:\yourflames\test.flame --supersample=3 --suffix=_ss3
> emberrender --in=C:\yourflames\test.flame --supersample=4 --suffix=_ss4

Be careful when using this because it scales the memory needed for the histogram and density filtering buffer by the supersample squared. So the following memory increases will be observed:

supersample=2: 4x
supersample=3: 9x
supersample=4: 16x

width [0]

Absolute value for the image width. The default value of 0 means to render at the exact width specified in the Xml file. To render a 100×100 thumbnail, you could do the following:

> emberrender --in=C:\yourflames\test.flame --width=100 --height=100

height [0]

Absolute value for the image height. The default value of 0 means to render at the exact height specified in the Xml file. To render a 100×100 thumbnail, you could do the following:

> emberrender --in=C:\yourflames\test.flame --width=100 --height=100

dumpargs [false]

Print all arguments entered from either the command line or environment variables. This can be useful if you’ve entered many arguments and you want verification that they were parsed correctly on the command line. Once verified, it’s something you will unlikely use again.

> emberrender --in=C:\yourflames\test.flame --progress --dumpargs

dump_kernel [false] (only used with OpenCL, ignored for CPU)

Print the source code for the OpenCL kernel. This is useful if you are curious how the algorithm is implemented on the GPU, or if you’d like to know exactly what a certain variation is doing.

> emberrender --in=C:\yourflames\test.flame --opencl --dump_kernel > out.txt

earlyclip [false]

Perform clipping of RGB values before, rather than after, spatial filtering for better anti-aliasing like so:

> emberrender --in=C:\yourflames\test.flame --earlyclip

Using this option is not necessarily better or worse than not using it. Try experimenting with it when certain images have colors or lines that don’t look quite right like so:

> emberrender --in=C:\yourflames\test.flame --suffix=_lateclip
> emberrender --in=C:\yourflames\test.flame --earlyclip --suffix=_earlyclip

transparency [false]

Include alpha channel in final output of a PNG or EXR image like so:

> emberrender --in=C:\yourflames\test.flame --transparency

This is ignored for any image format other than PNG or EXR.

qs [1]

Quality scale, the amount to multiply the quality by. The default value of 1 means to render at the exact quality specified in the Xml file. However, you might want to try rendering at different qualities. To render the original, plus double and triple the quality, you could do the following:

> emberrender --in=C:\yourflames\test.flame --suffix=_q1
> emberrender --in=C:\yourflames\test.flame --qs=2 --suffix=_q2
> emberrender --in=C:\yourflames\test.flame --qs=3 --suffix=_q3

Using --qs with a value less than 1 is useful for doing quick tests with lower qualities.

ss [1]

Size scale, the amount to multiply the image size by. The default value of 1 means to render at the exact size specified in the Xml file. However, you might want to try rendering at different sizes. This is equivalent to adjusting the width or height spinner with Keep Aspect Ratio checked in the Scale group box on the Final Render Dialog in Fractorium. To render the original, plus double and triple the size, you could do the following:

> emberrender --in=C:\yourflames\test.flame --suffix=_size1
> emberrender --in=C:\yourflames\test.flame --ss=2 --suffix=_size2
> emberrender --in=C:\yourflames\test.flame --ss=3 --suffix=_size3

Using --ss with a value less than 1 is useful for doing quick tests with smaller sizes.

ws [1]

Width scale, the amount to multiply the image width by. This is equivalent to adjusting the width spinner with Keep Aspect Ratio unchecked in the Scale group box on the Final Render Dialog in Fractorium. The default value of 1 means to render at the exact width specified in the Xml file. However, you might want to try rendering at different widths. To render the original, plus double and triple the width, you could do the following:

> emberrender --in=C:\yourflames\test.flame --suffix=_size1
> emberrender --in=C:\yourflames\test.flame --ws=2 --suffix=_w2
> emberrender --in=C:\yourflames\test.flame --ws=3 --suffix=_w3

Note that you can specify –scaletype with this option to specify how the rest of the image scales in proportion to the width.

hs [1]

Height scale, the amount to multiply the image height by. This is equivalent to adjusting the height spinner with Keep Aspect Ratio unchecked in the Scale group box on the Final Render Dialog in Fractorium. The default value of 1 means to render at the exact height specified in the Xml file. However, you might want to try rendering at different heights. To render the original, plus double and triple the height, you could do the following:

> emberrender --in=C:\yourflames\test.flame --suffix=_size1
> emberrender --in=C:\yourflames\test.flame --hs=2 --suffix=_h2
> emberrender --in=C:\yourflames\test.flame --hs=3 --suffix=_h3

Note that you can specify --scaletype with this option to specify how the rest of the image scales in proportion to the height.

scaletype [none]

The type of scaling to use when using either --ws, --hs, --width or --height. This is equivalent to the scale type group box on the Final Render Dialog in Fractorium. The default value of none means just expand the dimension of the canvas without any corresponding change in the output image contents. However, you probably want to adjust either the width or height. To render the original, plus double the width scaled by width, then height, you could do the following:

> emberrender --in=C:\yourflames\test.flame --suffix=_size1
> emberrender --in=C:\yourflames\test.flame --ws=2 --scaletype=width --suffix=_w2ws
> emberrender --in=C:\yourflames\test.flame --ws=2 --scaletype=height --suffix=_w2hs

format [png]

Although the default image output format is PNG, you can also save as BMP, JPG, PNG16, EXR or EXR32. PNG is the superior choice due to its use of lossless compression. If you need extreme color precision for monitors capable of HDR display, you can use a value of png16. Alternatively for HDR display, you can use exr which is the format created by Industrial Light and Magic which uses 16-bit floats for each RGBA color channel. EXR32 is like EXR, but uses 32-bit floats and is only of engineering interest. You will likely never use any of the other formats. JPG leads to artifacts which contradicts the point of doing so many iterations to get a perfect looking image. BMP is uncompressed, so it delivers an image identical to PNG but larger in size. If you must change the format, you can do it with the --format option. Note that you can specify more than one at a time, which is useful for comparing how they look:

> emberrender --in=C:\yourflames\test.flame --format=jpg

> emberrender --in=C:\yourflames\test.flame --format=png

> emberrender --in=C:\yourflames\test.flame --format=bmppngjpgpng16exr

sbpctth [0.025] (ignored for CPU)

Specify the the percentage of a sub batch (usually 10k iters) to be performed per thread per kernel launch. Use when running with --opencl like so:

> emberrender --in=C:\yourflames\test.flame --opencl --sbpctth=0.5

If omitted, the value 0.025 will be used by default, which instructs each thread to run 256 iters per kernel launch when using the default sub batch size of 10k.

This is used to squeeze all possible performance out of the GPU by tasking it with more work per kernel launch.

In practice, this increases performance by about 1%, and values greater than 0.2 usually don’t offer any additional performance improvement.

Because operating system drivers only allow GPUs to do a limited amount of work per kernel launch, a value greater than the default of 0.025 runs the risk of crashing the OpenCL driver. So use this sparingly with complex flames, and especially when using double precision. Such a scenario can easily crash a laptop GPU driver when using any value above 0.2.

nthreads [number of available cores] (ignored for OpenCL)

The number of threads to use when running on the CPU. If not specified, the default is to use all available cores. This has the drawback of making your system rather unresponsive while doing a lengthy render. So if you plan to still use your machine while rendering, you might want to leave a core available for general usage. On an 8 core system, you’d do the following:

> emberrender --in=C:\yourflames\test.flame --nthreads=7

For maximum performance on the CPU, at the expense of system responsiveness, omit this option.

priority [0 (normal)] (ignored for OpenCL)

The priority to assign the threads when running on the CPU. This is similar to the --nthreads argument in that it’s useful if you want to continue using your machine while doing a lengthy render. The following accepted values on Windows/Linux are:

-2/1: Lowest

-1/25: Below normal

0/50: Normal

1/75: Above normal

2/99: Highest

Run with the lowest priority on Windows like so:

> emberrender --in=C:\yourflames\test.flame --priority=-2

To do the same on Linux:

> emberrender --in=C:\yourflames\test.flame --priority=1

If not specified, the default is to run at normal priority, which corresponds to a value of 0/50 for this argument.

use_mem

Specify the maximum amount of memory to use for the entire rendering process in terms of bytes. If the amount required is greater than the value specified, the render will be broken down into the appropriate amount of strips to accommodate the memory threshold. Use a maximum of 500MB like so:

> emberrender --in=C:\yourflames\test.flame --use_mem=524288000

id, nick, url

Image comments are disabled by default unless --enable_comments is set to true. When enabled, they can include identifying information about the user. By specifying one or more of these fields like so, they will be included in the comments inside of the JPG or PNG image file:

> emberrender --in=C:\yourflames\test.flame --enable_comments --id=JohnSmith --nick=jsmith --url=www.fractorium.com

Note that this will include the image Xml parameters in the output file which any user can read. Do not enable this option if you do not want to share your parameters.

isaac_seed

Random numbers are at the very core of the rendering algorithm, and all random number generators (RNG) start with a seed. Given the same seed, two sequences of random numbers will be identical. Ember creates a random seed every time it runs, so the random number sequences will always differ. However, if you want to run the exact same sequence, you can specify the seed to start with.

Ember uses a random number generator named ISAAC, which takes a string as its seed. You can specify it like so:

> emberrender --in=C:\yourflames\test.flame --isaac_seed=helloworldseed

Running the same image multiple times on the CPU, with --nthreads=1 with the same seed will produce the exact same output, pixel for pixel. Note the single threading requirement. This is because when multi-threading, even if the same seed is supplied, the same histogram bucket could be hit at the same time or in a different order by different threads.

yaxisup [false]

Flip the image upside down like so:

> emberrender --in=C:\yourflames\test.flame --yaxisup

print_edit_depth [0]

The depth to truncate the edit tag structure to when converting flame to Xml for storage in the image comments. The default value of 0 uses all edit tags. Truncate to a depth of 3 like so:

> emberrender --in=C:\yourflames\test.flame --print_edit_depth=3

Ignored if --enable_comments is omitted.

flam3_compat [false]

Use flam3/Apophysis formulas for the following variations: cos, cosh, cot, coth, csc, csch, sec, sech, sin, sinh, tan, tanh, else use Chaotica formulas when omitted:

> emberrender --in=C:\yourflames\test.flame --flam3_compat

flam3_palettes

The path to the palettes  file file. This is named flam3_palettes.xml and resides in the install folder by default on Windows. For Linux, it’s located at ~/.config/fractorium/flam3_palettes.xml. If for some reason you need to specify a different path to it, do it like so:

> emberrender --in=C:\yourflames\test.flame --flam3_palettes=C:\path\to\my\palette\flam3_palettes.xml

Note this is only used if the Xml file specifies the palette field and does not contain an embedded palette. This was a legacy format used long ago and has since been superseded by just embedding the palette data directly in the Xml file rather than having it index into a separate file. Anything saved from Fractorium, EmberAnimate or EmberGenome does not use the legacy format.

lock_accum [false]

Prevents any two threads from writing to the same histogram bucket at the same time while iterating, and applies to the CPU and GPU. This was mostly for an engineering test to see if there was any visible difference between running with and without locking. The end result is that there is no difference. This should never be used as it grinds performance to a halt, especially on the GPU.

> emberrender --in=C:\yourflames\test.flame --lock_accum

jpeg [95]

If you do choose to use JPG, you can specify the quality of the compression on a scale from 0 to 100, with the default being 95. Higher values lead to visually superior images. The following would be for rendering an image with a smaller file size and low quality:

> emberrender --in=C:\yourflames\test.flame --format=jpg --jpeg=65

pixel_aspect [1]

The width/height ratio of each pixel. This value is not to be confused with the aspect ratio of the image. For modern displays, this value should be left as 1. However, if you wish to change it just for the sake of experimentation, some common values are:

NTSC:

> emberrender --in=C:\yourflames\test.flame --pixel_aspect=0.90909

PAL:

> emberrender --in=C:\yourflames\test.flame --pixel_aspect=1.0925

out

The default behavior for output image file naming is to use the index of the flame in the Xml file. Or, if --name_enable is specified, then use the value in the name attribute. A third option is supported by specifying the exact name of the output file like so:

> emberrender --in=C:\yourflames\test.flame --out=c:\outputflames\myflame.png

This is mostly useful if you want to redirect where the output goes if you don’t want it placed in the default location which is the path of the input Xml file.

However, this presents a problem when rendering a file with more than one image in it. There cannot be a single name for all of them.

Custom naming should generally be done through the name field, so this option is not recommended. If it must be used, then it should only be done when rendering a file with a single image in it.

enable_comments [false]

Allow for comments containing the flame Xml and user identifying information to be inserted into the output JPG, PNG or EXR file. This is false by default because it reveals the flame parameters used to render the image which many artists guard closely. If you want to embed the flame parameters along with identifying information from the --id --nick and --url options in the output image file, then enable this feature like so:

> emberrender --in=C:\yourflames\test.flame --enable_comments --id=JohnSmith --nick=jsmith --url=www.fractorium.com

insert_palette [false]

Insert the palette into the top of the output image. This is strictly for engineering debugging purposes and will likely never be used. It was done as a quick way to see which palette was used for a particular image. Enable this for testing purposes like so:

> emberrender --in=C:\yourflames\test.flame --insert_palette