[prev] [prev-tail] [tail] [up]

### 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 and then run it over a whole set of images, or use nip2 as part of a larger 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 Using --set

The --set option (which can be abbreviated to -=) lets you make changes to a workspace after loading it. Suppose the workspace test.ws has a row called A1 with the value 12. Then entering:

nip2 test.ws --set Workspaces.test.A1=45

Will, as normal, start nip2 and load test.ws. But before the first recalculation, nip2 will change the value of A1 to be 45. You can use --set to create new symbols as well.

#### 4.5.4 Other modes

A set of sub-options let you mix up other modes yourself. For example, it’s common to want to run a workspace on many files.

Suppose the workspace process.ws loads an image in A1, performs some processing and produces a result image A10. If you run nip2 with:

nip2 -bp \
-= 'Workspaces.process.A1=Image_file "fred.jpg"' \
-= main=Workspaces.process.A10 \
-o fred.jpg process.ws

This will start nip2 in batch (ie. no GUI) mode (the -b switch), load process.ws, change A1 to load another file, set main to be the value of A10 and save the value of A10 to fred.jpg (the -p switch).

[prev] [prev-tail] [front] [up]