Table of Contents

Batch API: Running Zerene Stacker From Another Application

Overview

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 T201001162110. It is intended for use only by advanced users and software developers.

The Batch Script

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”.

Launching

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.

For Microsoft Windows, 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 or desktop 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 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:

Mac OS X and Linux require somewhat different launch procedures. Contact support@zerenesystems.com for details.

Waiting

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.

Sample Java Code For Launch-and-Wait

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

Sample Batch Script

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.

image001.jpg

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.

Command Line Options

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

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.

Special Notes Regarding ImageJ

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 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.

Special Notes Regarding Cygwin, Linux, and Similar Environments

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.