4.5 Command-line interface

You can use nip2 from the command-line as well as from the GUI. This can be handy for automation: you can build a workspace, then run it over a whole set of images, or use the results as part of a larger automated system. We’ve make websites which use nip2 as the back-end.

In command-line mode nip2 runs without a GUI of any sort: it doesn’t even need a window system to be installed on the machine. This makes it possible to use it in a server or batch context.

These notes are for the Unix command-line, but they should work for Windows as well.

nip2 has three main modes of operation from the command-line:

nip2 filename1
Start nip2 in GUI mode, loading the command-line arguments as files. Filenames can be images, workspaces, matricies, toolkits, and so on.
nip2-e expression arg1
Start in no-GUI mode, print the value of expression. The list argv is set to be ["filename","arg1",..].
nip2-s filename arg1
Start in no-GUI mode, read in filename as a set of definitions, print the value of symbol main. The list argv is set to be ["filename","arg1",..].

You can use the -o option to send output somewhere other than the screen. If these modes don’t do quite what you need, you can get finer control of how nip2 behaves with a set of other options: see the man page for details.

4.5.1 Using expression mode

The -e option is very easy to use. For example:

nip2 -e "2 + 2"

Prints 4 to stdout.

nip2 -e "99 + Image_file argv?1" -o result.png fred.jpg

Loads argv1 (fred.jpg), adds 99, writes the result to result.png.

nip2 -e "Matrix [[1,2],[4,5]] ⋆⋆ -1" -o poop.mat

Invert the 2x2 matrix and write the result to poop.mat.

If the result of the expression is a list, each item is printed on a new line. For example:

nip2 -e "[1..5]"

Will print the numbers 1 to 5, each on a new line.

If you have a list result and you are using -o to direct the output to a file, the filename will be incremented each time you write. For example:

nip2 -e "map (add (Image_file argv?1)) [10, 20 .. 50]" -o result1.png fred.jpg

Will load fred.jpg, add 10, 20, 30, 40 and 50, then save those images to result1.png to result5.png.

4.5.2 Using script mode

With the -s option you can use nip2 as a Unix script interpreter.

Create a file in your favourite text editor called brighten containing:

#!/usr/bin/nip2 -s  
 
main  
  = clip2fmt infile.format (infile ⋆ scale), argc == 3  
  = error "usage: infile scale -o outfile"  
{  
  infile = Image_file argv?1;  
  scale = parse_float argv?2;  
}

The first line needs to be the path to nip2 on your system. Use which nip2 to find the path if you don’t know it. Mark the file as executable with chmod +x brighten, then use it on one of your image files with:

brighten fred.jpg 1.5 -o bright_fred.png

See Chapter 6 for details on the programming language. This program multiplies each input pixel by the constant, producing a floating point image, then then clips the result back to the same format as the original image (usually 8-bit unsigned).

nip2 takes a while (a few seconds) to start up, so this isn’t going to be appropriate for small images or simple calculations. But for complex operations, or operations on large images, this mode can be very useful.

4.5.3 Other modes

A set of sub-options let you mix up other modes yourself. One I’ve used lets me run a workspace repeatedly over a directory of images. First, create a file called main.def (you need the .def suffix) containing:

main = Workspaces.myworkspace.A1;

Where A1 is the name of the row in your workspace that you want to save, and myworkspace is the name of your workspace. Now run nip2 with:

nip2 -bp main.def myworkspace.ws -o fred.jpg

This will start nip2 in batch (ie. no GUI) mode (the -b switch), load myworkspace.ws, and save the value of A1 to fred.jpg (the -p switch).

The remaining problem is how to pass the name of the file to be processed to the workspace. The easiest solution is to use environment variables. In your workspace, type:

if expand "$FILE" != [] then expand "$FILE" else "default.jpg"

This will expand to either the value of the $FILE environment variable, or the empty list if $FILE is not defined. Now, if that was row B27, change the row that loads the workspace’s input image to be:

Image_file B27

And you now have a workspace that processes the image default.jpg if you run nip2 normally, but if you run at the command-line, you can enter:

FILE="another.jpg" nip2 -bp main.def myworkspace.ws -o fred.jpg

And it will process another.jpg instead. You can use the Widgets / File Chooser widget to make it a little prettier.