<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html >
<head><title>Command-line interface</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)">
<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)">
<!-- 3,html -->
<meta name="src" content="nipguide.tex">
<meta name="date" content="2010-06-30 13:34:00">
<link rel="stylesheet" type="text/css" href="nipguide.css">
</head><body
>
<!--l. 512--><div class="crosslinks"><p class="noindent">[<a
href="nipguidese12.html" >prev</a>] [<a
href="nipguidese12.html#tailnipguidese12.html" >prev-tail</a>] [<a
href="#tailnipguidese13.html">tail</a>] [<a
href="nipguidech4.html#nipguidese13.html" >up</a>] </p></div>
<h3 class="sectionHead"><span class="titlemark">4.5 </span> <a
id="x21-390004.5"></a>Command-line interface</h3>
<!--l. 513--><p class="noindent" ><a name="nip_label_sec:cmdline"></a>
<!--l. 515--><p class="indent" > You can use <span
class="pcrr7t-">nip2 </span>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 <span
class="pcrr7t-">nip2 </span>as part of a larger system. We’ve make
websites which use <span
class="pcrr7t-">nip2 </span>as the back-end.
<!--l. 520--><p class="indent" > In command-line mode <span
class="pcrr7t-">nip2 </span>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.
<!--l. 524--><p class="indent" > These notes are for the Unix command-line, but they
should work for Windows as well.
<!--l. 527--><p class="indent" > <span
class="pcrr7t-">nip2 </span>has three main modes of operation from the
command-line:
<dl class="description"><dt class="description">
<span
class="pcrb7t-">nip2 </span><span
class="ptmbi7t-">filename1 </span><span
class="ptmb7t-">…</span> </dt><dd
class="description">Start <span
class="pcrr7t-">nip2 </span>in GUI mode, loading
the command-line arguments as files. Filenames
can be images, workspaces, matricies, toolkits, and
so on.
</dd><dt class="description">
<span
class="pcrb7t-">nip2-e </span><span
class="ptmbi7t-">expression arg1 </span><span
class="ptmb7t-">…</span> </dt><dd
class="description">Start in no-GUI mode,
print the value of <span
class="ptmri7t-">expression</span>. The list <span
class="pcrr7t-">argv </span>is set
to be <span class="obeylines-h"><span class="verb"><span
class="pcrr7t-">["filename","arg1",..]</span></span></span>.
</dd><dt class="description">
<span
class="pcrb7t-">nip2-s </span><span
class="ptmbi7t-">filename arg1 </span><span
class="ptmb7t-">…</span> </dt><dd
class="description">Start in no-GUI mode, read
in <span
class="ptmri7t-">filename </span>as a set of definitions, print the value
of symbol <span
class="pcrr7t-">main</span>. The list <span
class="pcrr7t-">argv </span>is set to be
<span class="obeylines-h"><span class="verb"><span
class="pcrr7t-">["filename","arg1",..]</span></span></span>.
</dd></dl>
<!--l. 546--><p class="indent" > You can use the <span
class="pcrr7t-">-o </span>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 <span
class="pcrr7t-">nip2</span>
behaves with a set of other options: see the man page for
details.
<!--l. 551--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">4.5.1 </span> <a
id="x21-400004.5.1"></a>Using expression mode</h4>
<!--l. 553--><p class="noindent" >The <span
class="pcrr7t-">-e </span>option is very easy to use. For example:
<div class="verbatim" id="verbatim-11">
nip2 -e "2 + 2"
</div>
<!--l. 557--><p class="nopar" >
<!--l. 559--><p class="noindent" >Prints 4 to stdout.
<div class="verbatim" id="verbatim-12">
nip2 -e "99 + Image_file argv?1" -o result.png fred.jpg
</div>
<!--l. 564--><p class="nopar" >
<!--l. 566--><p class="noindent" >Loads argv1 (<span
class="pcrr7t-">fred.jpg</span>), adds 99, writes the result to
<span
class="pcrr7t-">result.png</span>.
<div class="verbatim" id="verbatim-13">
nip2 -e "Matrix [[1,2],[4,5]] ⋆⋆ -1" -o poop.mat
</div>
<!--l. 571--><p class="nopar" >
<!--l. 573--><p class="noindent" >Invert the 2x2 matrix and write the result to <span
class="pcrr7t-">poop.mat</span>.
<!--l. 576--><p class="indent" > If the result of the expression is a list, each item is printed
on a new line. For example:
<div class="verbatim" id="verbatim-14">
nip2 -e "[1..5]"
</div>
<!--l. 581--><p class="nopar" >
<!--l. 583--><p class="noindent" >Will print the numbers 1 to 5, each on a new line.
<!--l. 586--><p class="indent" > If you have a list result and you are using <span
class="pcrr7t-">-o </span>to direct the
output to a file, the filename will be incremented each time
you write. For example:
<div class="verbatim" id="verbatim-15">
nip2 -e "map (add (Image_file argv?1)) [10, 20 .. 50]" -o result1.png fred.jpg
</div>
<!--l. 591--><p class="nopar" >
<!--l. 593--><p class="noindent" >Will load <span
class="pcrr7t-">fred.jpg</span>, add 10, 20, 30, 40 and 50, then save
those images to <span
class="pcrr7t-">result1.png </span>to <span
class="pcrr7t-">result5.png</span>.
<!--l. 597--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">4.5.2 </span> <a
id="x21-410004.5.2"></a>Using script mode</h4>
<!--l. 599--><p class="noindent" >With the <span
class="pcrr7t-">-s </span>option you can use <span
class="pcrr7t-">nip2 </span>as a Unix script
interpreter.
<!--l. 601--><p class="indent" > Create a file in your favourite text editor called <span
class="pcrr7t-">brighten</span>
containing:
<div class="verbatim" id="verbatim-16">
#!/usr/bin/nip2 -s
 <br />
 <br />main
 <br />  = clip2fmt infile.format (infile ⋆ scale), argc == 3
 <br />  = error "usage: infile scale -o outfile"
 <br />{
 <br />  infile = Image_file argv?1;
 <br />  scale = parse_float argv?2;
 <br />}
</div>
<!--l. 613--><p class="nopar" >
<!--l. 615--><p class="noindent" >The first line needs to be the path to <span
class="pcrr7t-">nip2 </span>on your
system. Use <span
class="pcrr7t-">which nip2 </span>to find the path if you don’t
know it. Mark the file as executable with <span
class="pcrr7t-">chmod +x</span>
<span
class="pcrr7t-">brighten</span>, then use it on one of your image files
with:
<div class="verbatim" id="verbatim-17">
brighten fred.jpg 1.5 -o bright_fred.png
</div>
<!--l. 622--><p class="nopar" >
<!--l. 624--><p class="noindent" >See Chapter <a
href="nipguidech6.html#x31-570006">6<!--tex4ht:ref: sec:program --></a> 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).
<!--l. 630--><p class="indent" > <span
class="pcrr7t-">nip2 </span>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.
<!--l. 634--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">4.5.3 </span> <a
id="x21-420004.5.3"></a>Using <span
class="pcrr7t-">--set</span></h4>
<!--l. 636--><p class="noindent" >The <span
class="pcrr7t-">--set </span>option (which can be abbreviated to <span
class="pcrr7t-">-=</span>) lets
you make changes to a workspace after loading it. Suppose
the workspace <span
class="pcrr7t-">test.ws </span>has a row called <span
class="pcrr7t-">A1 </span>with the value
12. Then entering:
<div class="verbatim" id="verbatim-18">
nip2 test.ws --set Workspaces.test.A1=45
</div>
<!--l. 642--><p class="nopar" >
<!--l. 644--><p class="noindent" >Will, as normal, start <span
class="pcrr7t-">nip2 </span>and load <span
class="pcrr7t-">test.ws</span>. But before
the first recalculation, <span
class="pcrr7t-">nip2 </span>will change the value of <span
class="pcrr7t-">A1 </span>to
be 45. You can use <span
class="pcrr7t-">--set </span>to create new symbols as
well.
<!--l. 649--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">4.5.4 </span> <a
id="x21-430004.5.4"></a>Other modes</h4>
<!--l. 651--><p class="noindent" >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.
<!--l. 654--><p class="indent" > Suppose the workspace <span
class="pcrr7t-">process.ws </span>loads an image in
<span
class="pcrr7t-">A1</span>, performs some processing and produces a result image
<span
class="pcrr7t-">A10</span>. If you run <span
class="pcrr7t-">nip2 </span>with:
<div class="verbatim" id="verbatim-19">
nip2 -bp \
 <br />  -= 'Workspaces.process.A1=Image_file "fred.jpg"' \
 <br />  -= main=Workspaces.process.A10 \
 <br />  -o fred.jpg process.ws
</div>
<!--l. 662--><p class="nopar" >
<!--l. 664--><p class="noindent" >This will start <span
class="pcrr7t-">nip2 </span>in batch (ie. no GUI) mode (the <span
class="pcrr7t-">-b</span>
switch), load <span
class="pcrr7t-">process.ws</span>, change <span
class="pcrr7t-">A1 </span>to load another
file, set <span
class="pcrr7t-">main </span>to be the value of <span
class="pcrr7t-">A10 </span>and save the value of
<span
class="pcrr7t-">A10 </span>to <span
class="pcrr7t-">fred.jpg </span>(the <span
class="pcrr7t-">-p </span>switch).
<!--l. 1--><div class="crosslinks"><p class="noindent">[<a
href="nipguidese12.html" >prev</a>] [<a
href="nipguidese12.html#tailnipguidese12.html" >prev-tail</a>] [<a
href="nipguidese13.html" >front</a>] [<a
href="nipguidech4.html#nipguidese13.html" >up</a>] </p></div>
<!--l. 1--><p class="indent" > <a
id="tailnipguidese13.html"></a>
</body></html>
