Zerene Stacker can be launched, controlled, and terminated from another program, with no interaction needed between Zerene Stacker and a human user.

In general, this is accomplished by having the other program do the following steps:

1. Write a “batch script” that tells Zerene Stacker where to get its input files, how to stack them, and where to save its output images.
2. Launch Zerene Stacker as a command-line application, passing arguments that specify the batch script and various other controls.
3. Wait for Zerene Stacker to terminate.

Details of these steps depend on the operating system and the programming environment of the calling program. A sample calling program for Microsoft Windows, written in Java, can be downloaded as described below.

The facility described here is current as of Zerene Stacker Version 1.02 Build T2021-05-28-1930. It is intended for use only by advanced users and software developers.

Batch scripts are XML files that tell Zerene Stacker what to do. The easy way to generate a batch script is to use Batch > Show Batch Dialog… to specify the operations to be performed, then use Batch > Save Batch Script… to write the batch script as an XML file. If your program needs to provide adjustable parameters such as directory names, then it is far easier to have it use an existing batch script as a template, than to construct a script from scratch.

A sample batch script and the corresponding Batch Dialog are shown below.

There are two ways to provide a batch script:

1. Place the script file anywhere, and specify its location using the arguments –batchScript pathname
2. Place the script file in the same folder as input images, and name it specifically “ZereneBatch.xml”.

Zerene Stacker is a Java application, so launching Zerene Stacker really amounts to launching a copy of the Java Runtime Environment (JRE), passing appropriate arguments for both the JRE and Zerene Stacker.

A copy of Sun’s JRE is included as files in the Zerene Stacker installation tree. The necessary command line is long and complicated. Fortunately, you don’t have to generate it from scratch. Whenever Zerene Stacker is launched from Window’s Start menu, macOS Launchpad, or some other icon, a copy of the corresponding launch command is written into a file named ZereneStacker\zerenstk.launchcmd in that user’s %appdata% folder. What your launcher program should do is read that file, append whatever few arguments are needed for your situation, and use the result.

For reference, a typical launch command on Windows looks like this (broken across multiple lines for clarity):

"C:\Program Files\ZereneStacker\jre\bin\javaw.exe" -Xmx1600m -DjavaBits=32bitJava
  -Dlaunchcmddir="C:\Documents and Settings\Username\Application Data\ZereneStacker"
  -classpath "C:\Program Files\ZereneStacker\ZereneStacker.jar;C:\Program Files\ZereneStacker\JREextensions\*"
  com.zerenesystems.stacker.gui.MainFrame
  -noSplashScreen -exitOnBatchScriptCompletion -runMinimized
  c:/ZereneSystems/DemoFolder

Parameters on this command line have the following meanings:

• -Xmx1600m specifies the amount of memory that can be used by the Java heap.
• -DjavaBits tells Zerene Stacker which version of the JRE was executed
• -Dlaunchcmddir specifies a directory that holds the Zerene Stacker license key (LicenseKey.txt), configuration parameters (zerenstk.cfg), and a copy of the last launch command (zerenstk.launchcmd).
• -classpath tells the JRE where to find the Zerene Stacker application and libraries
• com.zerenesystems.stacker.gui.MainFrame contains the startup method for Zerene Stacker. Everything in the command line up to this point is what will be read from zerenstk.launchcmd, and should not be modified.
• -noSplashScreen -exitOnBatchScriptCompletion -runMinimized set Zerene Stacker options to avoid user interaction if possible. These arguments would be added by your launching program.
• c:/ZereneSystems/DemoFolder specifies a directory of source images and a batch script to be processed. (The batch script is implicitly named named “ZereneBatch.xml”.)

Launches on macOS and Linux have the same general structure as on Windows but differ in specific parameters. On macOS, a suitable command line can be obtained by launching Zerene Stacker from its icon, then looking in folder ~/Library/Preferences/ZereneStacker to find the file “zerenstk.launchcmd”. On Linux, a suitable command line can be obtained by running the executable program ZereneStacker/ZereneStacker, then looking in directory ~/.ZereneStacker to find the file “zerenstk.launchcmd”. (Note that directory ~/.ZereneStacker is normally “hidden” because of the leading dot in its name.) If this process does not provide adequate information, then contact support@zerenesystems.com to resolve any issues.

While the calling program is waiting for Zerene Stacker to finish, it must also dispose of whatever console output is produced by Zerene Stacker. If it fails to do this, then probably Zerene Stacker and the calling program will hang waiting for each other.

A sample launch-and-wait program written in Java can be downloaded from http://www.zerenesystems.com/stacker/docs/api/SampleLaunchProgram.java.

Here is a sample batch script that works well for simple stacking tasks. Notice that the output image naming template has been set to produce output files with simple predictable names, so that output files can be easily identified and read back by the calling program. This setting is done via Options > Preferences > Image Saving.

<?xml version="1.0" encoding="UTF-8"?>
<ZereneStackerBatchScript>
  <BatchQueue>
    <Batches length="1">
      <Batch>
        <Sources length="1">
          <Source value="%CurrentProject%" />
        </Sources>
        <ProjectDispositionCode value="101" />      New projects are temporary
        <Tasks length="1">
          <Task>
            <OutputImageDispositionCode value="2" />      Save in source folders
            <Preferences>
              ...
              <OutputImageNaming.Template value="ZS-OutputImage" />
              ...
            </Preferences>
            <TaskIndicatorCode value="1" />       Align and Stack All (PMax)
          </Task>
        </Tasks>
      </Batch>
    </Batches>
  </BatchQueue>
</ZereneStackerBatchScript>

The corresponding batch queue dialog looks like this.

As shown, the disposition of output images is set to “Save in source folders”. This is good for most routine processing, since it naturally keeps outputs associated with inputs. This strategy does have one drawback: it requires removing output images if the folder must be reprocessed. If you anticipate needing to reprocess folders, then probably it is better to specify outputs as “Save in designated folder”. In this case, the name of the source directory will be automatically added to the front of output image names.

For reference, here are all of the currently defined command line options:

• -autosafe is provided by the standard launch program to indicate recovery from a launch that failed because the Zerene Stacker configuration requested too much memory (Windows only). This parameter warns the user and immediately pops open Options > Preferences > Memory Usage.
• -batchScript path/foo.xml loads batch tasks defined in the specified file. May be repeated to process multiple scripts, analogous to Append Batch Script… in the graphical user interface.
• -exitOnBatchScriptCompletion automatically terminates after execution of the last batch task.
• -leaveLastBatchProjectOpen prevents automatic closing of the last project, even when “New projects are temporary (do not save)”. (This is useful for debugging.)
• -noSplashScreen suppresses the usual splash screen containing copyright and license information.
• -runMinimized makes the program start with its user interface iconified (appearing only on the taskbar). By default the usual progress bar then is displayed in its own small frame.
• -showProgressWhenMinimized=false stops Zerene Stacker from displaying its own progress bar. (The calling program can display its own progress bar by monitoring the Zerene Stacker console output stream as shown in the Sample Java Code For Launch-and-Wait .)
• -showProgressWhenMinimized=true forces Zerene Stacker to display its own progress bar when the main window is minimized, even when the program is initially launched without -runMinimized.
• -progressWindowText=“any text you like” replaces the default “Please wait, processing” in the progress bar window shown by Zerene Stacker.
• -showProgressPercentage forces the inclusion of a percent-complete indicator in the progress bar.
• -safe is provided by the standard launch program to indicate execution from the “safe” icon (Windows only). This parameter warns the user and re-initializes screen layout.
• -testlaunch makes Zerene Stacker immediately terminate after producing one line of console output, “Test OK”. (This is also used internally, as part of automatic memory configuration.)
• -lrplugin informs Zerene Stacker that it has been invoked as a Lightroom plugin. This alters a number of default settings, causes Zerene Stacker to automatically delete the folder of temporary files serving as source images, and causes saved projects to include an embedded copy of the source images.
• -sourcePath=<path> specifies the original location of input images that were copied to temporary files by the Lightroom plugin. It provides the default location for saving output files.

If image files or directories are specified on the command line, then a new project will be immediately opened and those images loaded into it.

If you are using ImageJ (http://rsbweb.nih.gov/ij/), then Zerene Stacker can be launched directly from an ImageJ macro using the built-in “exec” command. The arguments are long and arcane, and must be adjusted to reflect both the Zerene Stacker installation and the username of the current user.

On a typical 32-bit Windows XP system, the invocation looks like this (broken across multiple lines for clarity):

exec("\"C:\\Program Files\\ZereneStacker\\jre\\bin\\javaw.exe\" -Xmx1600m -DjavaBits=32bitJava 
  -Dlaunchcmddir=\"C:\\Documents and Settings\\username\\Application Data\\ZereneStacker\" 
  -classpath \"C:\\Program Files\\ZereneStacker\\ZereneStacker.jar;C:\\Program Files\\ZereneStacker\\JREextensions\\*\" 
  com.zerenesystems.stacker.gui.MainFrame -noSplashScreen -exitOnBatchScriptCompletion -runMinimized 
  C:\\ZereneSystems\\DemoFolder")

This is for a Zerene Stacker that is installed in Program Files and is currently being used by “username”.

This command probably looks like complete gibberish. The trick to understanding it is to take it apart a bit at a time.

Everything up through the com.zerenesystems.stacker.gui.MainFrame was obtained by reading the file %appdata%\ZereneStacker\zerenstk.launchcmd (after successfully launching Zerene Stacker from the Start > All Programs menu), then sticking an extra backslash in front of every existing backslash and quote-mark.

That is, what appears in zerenstk.launchcmd as

  ...\bin\javaw.exe"...

becomes in the exec command

  ...\\bin\\javaw.exe\"...

That leading portion of the exec command simply executes a copy of the Java runtime system, passing to it a bunch of parameters needed to make it load and execute Zerene Stacker. When you run Zerene Stacker from its regular icons, this is just what zerenstk.exe does behind the scenes.

The added parameters are

    -noSplashScreen -exitOnBatchScriptCompletion -runMinimized

which specify program options, and

    C:\\ZereneSystems\\DemoFolder

which specifies a directory containing images and a ZereneBatch.xml file to process them.

The reason the above command is so arcane it that it has to invoke Zerene Stacker by executing the Java runtime directly, rather than executing zerenstk.exe like the normal Zerene Stacker icon does. The problem with using zerenstk.exe is that zerenstk.exe terminates quickly and asynchronously, leaving behind Zerene Stacker and its GUI to execute at their leisure. As a result, if ImageJ uses zerenstk.exe, then ImageJ immediately goes on to do other tasks without waiting for the real Zerene Stacker to do its work. This would not be suitable for most types of automation.

Zerene Stacker can be executed as a command line application from shell programs such as bash. The exact arguments depend on the type of operating system and where Zerene Stacker is installed.

Using Cygwin on the same 32-bit Windows XP system described above for ImageJ, the proper invocation is this (broken across multiple lines for clarity):

"/cygdrive/c/Program Files/ZereneStacker/jre/bin/java.exe" -Xmx1600m -DjavaBits=32bitJava 
  -Dlaunchcmddir="C:/Documents and Settings/username/Application Data/ZereneStacker" 
  -classpath "C:/Program Files/ZereneStacker/ZereneStacker.jar;C:/Program Files/ZereneStacker/JREextensions/*" 
  com.zerenesystems.stacker.gui.MainFrame -noSplashScreen -exitOnBatchScriptCompletion -runMinimized 
  C:/ZereneSystems/DemoFolder

Note the use of “java.exe” instead of “javaw.exe”. This is required on Windows systems in order to produce console output that can be logged or examined. If javaw.exe is used, then the application runs silently.