Want to show your appreciation?
Please a cup of tea.

Sunday, February 03, 2013

Integrate Java and GraphicsMagick – Interactive or Batch Mode

Introduction

To overcome the performance problem with the im4java integration approach. We set out to implement our proposed solution. The first step is to develop a new GraphicsMagick (GM hereafter) feature: introducing the batch mode (or interactive mode) to GM.

After going through our internal prototyping, beta testing and production release. We finally have a patch submitted to official GM code base. (Update 3/19: Thanks to Bob Friesenhahn, GraphicsMagick 1.3.18 was officially released with batch support! This post was updated with the specs of the final 1.3.18 release.)

The Batch Command

Simply invoke the GM by running the “gm” command, you will notice the new “batch” command is now listed at the top of the command list.

C:\>gm
GraphicsMagick 1.3.18 2013-03-10 Q8 http://www.GraphicsMagick.org/
Copyright (C) 2002-2013 GraphicsMagick Group.
Additional copyrights and licenses apply to this software.
See http://www.GraphicsMagick.org/www/Copyright.html for details.
Usage: gm command [options ...]

Where commands include:
      batch - issue multiple commands in interactive or batch mode
  benchmark - benchmark one of the other commands
    compare - compare two images
  composite - composite images together
    conjure - execute a Magick Scripting Language (MSL) XML script
    convert - convert an image or sequence of images
       help - obtain usage message for named command
   identify - describe an image or image sequence
    mogrify - transform an image or sequence of images
    montage - create a composite image (in a grid) from separate images
       time - time one of the other commands
    version - obtain release version
   register - register this application as the source of messages

The new batch command is used to get GM into interactive mode or execute an batch GM command file. If a file is supply to the batch command as a parameter, GM executes the commands in the file in batch mode. Otherwise, GM enters interactive mode.

Any GM command you can run in POSIX shell or Windows command prompt can be executed in interactive or batch mode.

Interactive Mode

GM Interactive mode serves two purposes:

  1. You can test and get quick feedback of the commands that you plan to use in a GM batch file.
  2. Another process can control the GM via interactive mode to run multiple commands without restarting the GM command every time. This is the most important motivation of we developing this feature. It is also a topic that is big enough for a separate post.

In future, GM may also support using the result of the previous command as input of the next command.

Enter Interactive Mode

To start GM in interactive mode, just enter “gm batch” in command line. You get the GM default prompt: “"GM>”.

C:\>gm batch
GraphicsMagick 1.3.18 2013-03-10 Q8 http://www.GraphicsMagick.org/
Copyright (C) 2002-2013 GraphicsMagick Group.
Additional copyrights and licenses apply to this software.
See http://www.GraphicsMagick.org/www/Copyright.html for details.
GM>

In the interactive or batch mode, you can execute any and all GM commands except the “batch” command itself. You can use the same help command to get a list of commands supported, please note that you simply enter the command itself, i.e., to execute the help command, simply enter “help” instead of “gm help”.

You may also notice the new “set” command in the batch mode, this command is used to change the settings of the batch mode. We’ll cover the batch mode options and settings in the following sections.

GM> help
Usage: help command [options ...]

Where commands include:
  benchmark - benchmark one of the other commands
    compare - compare two images
  composite - composite images together
    conjure - execute a Magick Scripting Language (MSL) XML script
    convert - convert an image or sequence of images
       help - obtain usage message for named command
   identify - describe an image or image sequence
    mogrify - transform an image or sequence of images
    montage - create a composite image (in a grid) from separate images
        set - change batch mode option
       time - time one of the other commands
    version - obtain release version
   register - register this application as the source of messages

Invoke Commands

You can invoke any GM command in interactive mode as if you run them in the POSIX shell or Windows command prompt. The difference is that you don’t need to start the command with “gm”, you start with the command itself. For example, the convert command that is typically invoked like below

C:\>gm convert a.jpg –scale 400x300 b.jpg

can be executed in GM interactive mode without the preceding “gm”. 

GM>convert a.jpg –scale 400x400 b.jpg

Just like how you enter GM command parameters before, in the interactive or batch mode, parameters are separated by one more multiple SPACE or TAB characters. If a parameter itself contains space or tab, you need to use escape characters. I’ll devote a separate section for GM command escape in the later of this post.

Exist Interactive Mode

To exist the interactive mode, you just need to enter the EOF character. In Mac, Linux and other Unix like systems, EOF character is Ctrl-D. In Windows, EOF character is Ctrl-Z. Ctrl-Z must be the only character in the line and immediately followed by new line character.

You can also use Ctrl-C to exit the interactive mode.

Options

GM batch mode can be customized by various optional parameters. Those options can be specified as shell command line options when entering batch mode. Options can also be changed using “set” command after entering the batch mode.

To get a list of available options, you can use “gm batch –help” or “gm help batch” from POSIX shell or Windows command prompt. Or use “set –help” or “help set” in the GM batch mode.

C:\>gm batch -help
GraphicsMagick 1.3.18 2013-03-10 Q8 http://www.GraphicsMagick.org/
Copyright (C) 2002-2013 GraphicsMagick Group.
Additional copyrights and licenses apply to this software.
See http://www.GraphicsMagick.org/www/Copyright.html for details.
Usage: gm batch [options ...] [file|-]

Where options include:
  -echo on|off         echo command back to standard out, default is off
  -escape unix|windows force use Unix or Windows escape format for command line
                       argument parsing, default is platform dependent
  -fail text           when feedback is on, output the designated text if the
                       command returns error, default is 'FAIL'
  -feedback on|off     print text (see -pass and -fail options) feedback after
                       each command to indicate the result, default is off
  -help                print program options
  -pass text           when feedback is on, output the designated text if the
                       command executed successfully, default is 'PASS'
  -prompt text         use the given text as command prompt. use text 'off' or
                       empty string to turn off prompt. default to 'GM> ' if
                       and only if batch mode was entered with no file argument
  -stop-on-error on|off
                       when turned on, batch execution quits prematurely when
                       any command returns error

Unix escape allows the use backslash(\), single quote(') and double quote(") in
the command line. Windows escape only uses double quote(").  For example,

    Orignal             Unix escape              Windows escape
    [a\b\c\d]           [a\\b\\c\\d]             [a\b\c\d]
    [Text with space]   [Text\ with\ space]      ["Text with space"]
    [Text with (")]     ['Text with (")']        ["Text with ("")"]
    [Mix: "It's a (\)"] ["Mix: \"It's a (\\)\""] ["Mix: ""It's a (\)"""]

Use '-' to read command from standard input without default prompt.

You can also check the current option setting by using “set” command without parameter:

GM> set
escape        : windows
fail          : FAIL
feedback      : off
stop-on-error : off
pass          : PASS
prompt        : GM>

Each options will be discussed in the following sections in detail.

Echo Option

By default echo is turned off. Enabling -echo option asks GM to echo back every command entered in the interactive or batch mode. This is mainly for the debug purpose to what exactly is being received by GM as command and its parameters.

Feedback Options

This consists of a group of options, –feedback, –pass and –fail. The later two options are only effective when the feedback option is turned on. By default, the feedback is turned off. When the feedback is turned on, GM outputs the text defined by -pass or -fail option followed by a new line after execution of each GM command in interactive or batch mode. If the command was executed successfully, GM output the text defined by –pass option, otherwise output the text defined by –fail option.

The default text is “PASS” for –pass option and “FAIL” for –fail option.

The feedback options doesn’t seem to be very useful when the GM interactive session is controlled by human, but it is essential if another process need to interact with GM process.

Prompt Option

Option –prompt allow you to define a different GM prompt in the interactive mode, or turn the prompt off completely. By default, prompt is off if a batch file (or –) is passed to the GM batch command, otherwise “GM>” is the GM prompt text.

Stop-on-error Option

By default –stop-on-error option is off. GM will make the best effort to execute every command. When a given command fails, it will output the error message and GM will continue to accept and execute next command. Turning –stop-on-error option on will force GM to exit whenever command line syntax error occurred or a command failed to execute. This option is more useful in batch mode instead of interactive mode.

Escape Option

By default, GM uses Unix escape style unless it on Windows systems, where it uses Windows escape by default. Option –escape allows you to GM to use the escape style specified. We’ll discuss the detail of command line escape in the follow sections.

Command Line Escape

GM supports two different command line escape styles. By default, it recognizes Windows escape style in Windows system and Unix escape style in all other platforms.

In the bottom section of the help output (repeated below), GM provided the brief description of the two escape systems and a few of examples.

Unix escape allows the use backslash(\), single quote(') and double quote(") in
the command line. Windows escape only uses double quote(").  For example,

    Orignal             Unix escape              Windows escape
    [a\b\c\d]           [a\\b\\c\\d]             [a\b\c\d]
    [Text with space]   [Text\ with\ space]      ["Text with space"]
    [Text with (")]     ['Text with (")']        ["Text with ("")"]
    [Mix: "It's a (\)"] ["Mix: \"It's a (\\)\""] ["Mix: ""It's a (\)"""]

Unix Escape Style

Unix style escape recognizes three special characters, backslash(\), single quote(') and double quote("). This style gives you many conveniences but sometime can also introduce confusions.

In all use cases, you can use backslash to escape SPACE, TAB, newline, single quote, double quote and the backslash character itself. But if a parameter contains many of those characters, using backslash can be become very verbose and difficult to understand. In this case quotes are come in handy.

A parameter contains special characters can be entered by surrounding it with single quotes, as long as the parameter doesn’t contain the single quote itself. Text within the single quotes are taken by GM as is.

Double quote is different from single quote is that its content can be further escaped. Within the double quotes, you no longer need to escape SPACE, TAB, new line and single quote, but you still need to use backslash to escape the double quote and backslash itself if your parameter happen to contain any of them.

Below listed some valid use of Unix escape style.

Original Backslash Single Quotes Double Quotes
a\b\c\d a\\b\\c\\d\\ 'a\b\c\d' "a\\b\\c\\d\\"
Text with space Text\ with\ space 'Text with space' "Text with space"
Text with (") Text\ with\ (\") 'Text with (")' "Text with (\")"
Mix: "It's a (\)" Mix:\ \"It\'s\ a\ (\\)\" 'Mix: "It'\''s a (\)"' "Mix: \"It's a (\\)""
Multi
lines		 Multi\
lines		 'Multi
lines'		 "Multi
lines"

Windows Escape Style

Believe it or not, Windows escape style is much simpler. It only uses double quote (") characters. All you need to do is surround your parameter with double quotes. If the parameter itself contains double quote characters, use two continuous double quotes to represent every one double quote in the parameter. The batch help already provide good examples for Windows escape style.

Batch Mode

A text file contains GM commands is said to be a GM batch file. GM batch mode is activated by passing a GM batch file to the batch command. Bellow example illustrated how to use the batch mode. Batch mode is essentially the same as the interactive mode that we have discussed so far, except that the batch mode uses different default option. The file path parameter signifies the batch mode and activates the batch mode defaults.

C:\>del a-small.jpg b-tiny.jpg

C:\>type test.gm
# Test is a test GraphicsMagick batch command file.
convert a.jpg -scale 400x300 a-small.jpg
convert b.jpg -scale 200x150 b-tiny.jpg

C:\>gm batch test.gm

C:\>dir /b a-small.jpg b-tiny.jpg
a-small.jpg
b-tiny.jpg

Comments

GM ignores any characters between # character and newline, except that the # character is escaped. Also, an empty line or line contains only comments is simply skipped by GM.

# Test is a test GraphicsMagick batch command file.
convert a.jpg -scale 400x300 a-small.jpg # this is also a comment
convert b.jpg -scale 200x150 b-tiny.jpg "#this is NOT a comment"

Associate .gm Extension in Windows

It would be convenient to associate .gm file extension to GM. Copy and past the text below to a file named “gm.reg”, correct the installation location of the GM then save it. Double click on gm.reg file to import the registry settings. You are all set.

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\gm_auto_file]
@="GraphicsMagick Batch File"

[HKEY_CLASSES_ROOT\gm_auto_file\DefaultIcon]
@="C:\\Program Files (x86)\\GraphicsMagick-Q8\\gm.exe,0"

[HKEY_CLASSES_ROOT\gm_auto_file\shell]

[HKEY_CLASSES_ROOT\gm_auto_file\shell\open]

[HKEY_CLASSES_ROOT\gm_auto_file\shell\open\command]
@="\"C:\\Program Files (x86)\\GraphicsMagick-Q8\\gm.exe\" batch \"%1\""

(Note: Ideally this should be included as part of the Windows installer.)

Now you can double click on the test.gm file and it will run all the commands. You can also invoke test.gm from command line like below.

C:\>del a-small.jpg b-tiny.jpg

C:\>type test.gm
# Test is a test GraphicsMagick batch command file.
convert a.jpg -scale 400x300 a-small.jpg
convert b.jpg -scale 200x150 b-tiny.jpg

C:\>test.gm

C:\>dir /b a-small.jpg b-tiny.jpg
a-small.jpg
b-tiny.jpg

Executable GM Batch Script in Unix-like Systems

You can also use

shebang to make a GM batch script file executable in Unix-like systems. 

$ rm a-small.jpg b-tiny.jpg

$ cat test.gm
#!/usr/bin/gm batch
# Test is a test GraphicsMagick batch command file.
convert a.jpg -scale 400x300 a-small.jpg
convert b.jpg -scale 200x150 b-tiny.jpg

$ chmod a+x test.gm

$ ./test.gm

$ ls a-small.jpg b-tiny.jpg
a-small.jpg
b-tiny.jpg

Cross Platform Script

For a GM batch script that is intended to be executed on multiple platforms, the shebang interpreter directive should always be included in the script.

Also, you must explicitly specify the escape style with set command unless your script is compatible with both escape styles. As a good practice, you should always set the escape style in the beginning of the script.

#!/usr/bin/gm batch
# Test is a test GraphicsMagick batch command file.
set -escape windows
convert dot.png -resize 300x500! -font arial -pointsize 38 -draw "text 50 100 'NO IMAGE'" out.png
convert a.jpg -scale 400x300 a-small.jpg
convert b.jpg -scale 200x150 b-tiny.jpg

Pipeline Command

If you want to run GM batch commands that are output by another program through pipeline. You’ll need to use “-” in place of the file parameter. Otherwise the interactive mode option will be used and you’ll see prompts are echoed back to the screen.

C:\>type test.gm | gm batch
GraphicsMagick 1.3.18 2013-03-10 Q8 http://www.GraphicsMagick.org/
Copyright (C) 2002-2013 GraphicsMagick Group.
Additional copyrights and licenses apply to this software.
See http://www.GraphicsMagick.org/www/Copyright.html for details.
GM> GM> GM> GM> GM> GM>

C:\>type test.gm | gm batch -

C:\>

Summary

This is all about GM batch! In next few posts of this series, I’ll unleash the full power of GM interactive or batch mode.

Other Posts in the “Integrate Java and GraphicsMagick” Series

  1. Conception
  2. im4java Performance
  3. Interactive or Batch Mode
  4. gm4java
  5. gm4java Performance
Posted by Kenneth Xu at 2/03/2013 01:18:00 AM 2 comments
Labels: ,