in

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

> emberanimate --in=C:\yourflames\testsequence.flame

opencl [false]

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

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.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.

> emberanimate --in=C:\yourflames\testsequence.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.

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_dp
> emberanimate --in=C:\yourflames\testsequence.flame --sp --suffix=_sp

prefix, suffix

Concatenate the supplied string to the beginning or end of every output filename. Note that EmberAnimate does not support the --name_enable field like EmberRender does, so the filenames will be based off of their index in the input sequence file.

The following would produce a sequence of output images with the names “myprefix_[time].png”:

> emberanimate --in=C:\yourflames\testsequence.flame --prefix=myprefix_

The following would produce a sequence of output images with the names “[time]_mysuffix.png”:

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_mysuffix

The two can be combined to produce a sequence of output images with the name “myprefix_[time]_mysuffix.png” like so:

> emberanimate --in=C:\yourflames\testsequence.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 all flames 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.

> emberanimate --in=C:\yourflames\testsequence.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.

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --quality=10

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

> emberanimate --in=C:\yourflames\testsequence.flame --quality=100 --suffix=_q100
> emberanimate --in=C:\yourflames\testsequence.flame --quality=1000 --suffix=_q1000
> emberanimate --in=C:\yourflames\testsequence.flame --quality=5000 --suffix=_q5000
> emberanimate --in=C:\yourflames\testsequence.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 sequence. You might want to run multiple animations in a script like so, then compare the outputs:

> emberanimate --in=C:\yourflames\testsequence.flame --supersample=1 --suffix=_ss1
> emberanimate --in=C:\yourflames\testsequence.flame --supersample=2 --suffix=_ss2
> emberanimate --in=C:\yourflames\testsequence.flame --supersample=3 --suffix=_ss3
> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --width=100 --height=100

ts

Override the temporal samples value from the Xml file with this value. This is useful for experimenting how much motion blur you want in the animation. Increasing this value will impact performance, so don’t use a higher value than is necessary to get smoothly blurred frames.

> emberanimate --in=C:\yourflames\testsequence.flame --ts=200 --suffix=_ts200

> emberanimate --in=C:\yourflames\testsequence.flame --ts=500 --suffix=_ts500

> emberanimate --in=C:\yourflames\testsequence.flame --ts=1000 --suffix=_ts1000

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.

> emberanimate --in=C:\yourflames\testsequence.flame --progress --dumpargs

earlyclip [false]

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

> emberanimate --in=C:\yourflames\testsequence.flame --earlyclip

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

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_lateclip
> emberanimate --in=C:\yourflames\testsequence.flame --earlyclip --suffix=_earlyclip

ignore-existing [false]

Skip rendering a frame if every image from all of the specified output file extensions for that frame already exist in the output folder like so:

> emberanimate --in=C:\yourflames\testsequence.flame --ignore-existing

Using this option can help save time when repeatedly rendering test images for a specific frame or range of frames.

transparency [false]

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

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_q1
> emberanimate --in=C:\yourflames\testsequence.flame --qs=2 --suffix=_q2
> emberanimate --in=C:\yourflames\testsequence.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. To render the original, plus double and triple the size, you could do the following:

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_size1
> emberanimate --in=C:\yourflames\testsequence.flame --ss=2 --suffix=_size2
> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_size1
> emberanimate --in=C:\yourflames\testsequence.flame --ws=2 --suffix=_w2
> emberanimate  --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --suffix=_size1
> emberanimate --in=C:\yourflames\testsequence.flame --hs=2 --suffix=_h2
> emberanimate --in=C:\yourflames\testsequence.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 or --hs is not 1. 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:

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

begin,end

By default, every frame in the file will be rendered. However, it can be useful for testing purposes to only render a subset of those frames. This can be done by using the --begin and --end options like so:

> emberanimate --in=C:\yourflames\testsequence.flame --begin=3 --end=10

Note the indices are 0-indexed.

If --begin is omitted, it defaults to the first frame in the file. If --end is omitted, it defaults to the last frame in the file.

To render the first 6 frames:

> emberanimate --in=C:\yourflames\testsequence.flame --end=5

To render the 4th through last frames:

> emberanimate --in=C:\yourflames\testsequence.flame --begin=3

frame

If you only want to render a single frame, use this option to specify the 0-based index in the file of the frame you want to render like so:

> emberanimate --in=C:\yourflames\testsequence.flame --frame=5

Note this value must be greater than or equal to zero and less than the number of flames in the file.

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:

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --priority=-2

To do the same on Linux:

> emberanimate --in=C:\yourflames\testsequence.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.

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:

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.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.

Since EmberAnimate uses multiple renderers when more than one device is specified with --opencl and --device, an offset value is added to each seed character for each renderer created.

yaxisup [false]

Flip the images upside down like so:

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.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

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:

> emberanimate --in=C:\yourflames\testsequence.flame --format=jpg

> emberanimate --in=C:\yourflames\testsequence.flame --format=png

> emberanimate --in=C:\yourflames\testsequence.flame --format=bmppngjpgpng16exr

threaded_write [true]

By default, EmberAnimate uses a separate thread to write images to disk. It gives better performance because it does not require the current image to be fully written to disk before starting on the rendering process for the next image. However, the downside is that it doubles the memory required for the final output buffer since a copy must be made.

Since you almost always want to use this, and the default is true, you will most likely never need this option. The only case where you would want to set it to false is if you are rendering an extremely large image and are low on memory. To disable it, do the following:

> emberanimate --in=C:\yourflames\testsequence.flame --threaded_write=false

dtime

The default behavior is to render every frame, however if you want to render every nth frame you can specify --dtime with a value greater than 1. This is unlikely to produce a desirable animation and is only useful for testing purposes. Render every other frame like so:

> emberanimate --in=C:\yourflames\testsequence.flame --dtime=2

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:

> emberanimate --in=C:\yourflames\testsequence.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.

> emberanimate --in=C:\yourflames\testsequence.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:

> emberanimate --in=C:\yourflames\testsequence.flame --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:

> emberanimate --in=C:\yourflames\testsequence.flame --pixel_aspect=0.90909

PAL:

> emberanimate --in=C:\yourflames\testsequence.flame --pixel_aspect=1.0925

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:

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