Isis 3 Documentation

Command Line Usage

Invoking Isis programs from the Unix command line

Introduction

This section describes how to run Isis programs on the command line, instead of the GUI. This is particularly useful if 1) you desire to setup shell scripts or other batch job mechanisms to run a sequence of programs on cubes or 2) you are a power user who prefers keyboarding over mousing.

Invoking a Program

To start an ISIS program, simply type it’s name, for example, "ratio". This starts the program under the GUI, however, if you provide anything after the program name it will be assumed the program is running under the command line. For example,

lowpass from=moon.cub to=moon.lpf.cub lines=5 samples=5 minimum=1
stats from=moon.lpf.cub

The programs will immediately attempt to run and if parameters are missing or wrong, an error will be output. For example,

lowpass from=moon.cub lines=4 samples=5 minimum=1
**USER ERROR** Parameter [TO] must be entered.

lowpass from=moon.cub to=moon.lpf.cub lines=4 samples=5 minimum=1
**USER ERROR** Value for [LINES] must be odd.

Parameter-Value Pairs

For consistency, all Isis command lines take the form of:

program parameter1=value parameter2=value …parameterN=value

The parameters can occur in any order, can be abbreviated so long as they are unique, are case insensitive, and can be omitted if they have a default value. The values can be integers, doubles, strings, or booleans [Future Option] The values can also be homogenous arrays of these types. Using the GUI for lowpass in the below figure as a guide, we can present several examples:

lowpass f=moon.cub t=moon.lpf.cub s=5 l=5 minimum=1
lowpass f=moon.cub t=moon.lpf.cub s=5 li=5
lowpass f=moon.cub t=moon.lpf.cub s=5 lin=5

Parameter-Value Pairs Example

420x627, 22KB

The first example would fail with a uniqueness error as "l" could mean parameter line, lis, lrs, or low.

lowpass f=moon.cub t=moon.lpf.cub s=5 l=5 minimum=1
**USER ERROR** Invalid command line
**USER ERROR** Parameter [l] is not unique.

The second example would fail with a uniqueness error as "li" could mean parameter lines or lis.

lowpass f=moon.cub t=moon.lpf.cub s=5 li=5 minimum=1
**USER ERROR** Invalid command line
**USER ERROR** Parameter [li] is not unique.

The third example would succeed; note the minimum parameter is not required as it has a default of one, the parameters are case insensitive, and their order has changed.

lowpass S=5 LIN=5 F=moon.cub T=moon.lpf.cub
Working
100% Processed

Integer and Double Parameters

The application documentation indicates the type of each parameter. Integer and Double parameters are trivial taking the form of:

samples=5
minimum=0.679

Often there will be error check conditions performed by the application to ensure they have a valid range. For example,

lowpass f=moon.cub t=moon.lpf.cub s=0 lin=5
**USER ERROR** Parameter [SAMPLES] must be greater than or equal to [1]

Similarly, two parameters may be required to be ordered

lowpass f=moon.cub t=moon.lpf.cub s=5 lin=5 low=5 hi=3
 **USER ERROR** Parameter [LOW] must be less than parameter [HIGH]

String Parameters

String parameters can be slightly more complicated because of operating system intricacies. The difference is in one word strings versus multiple word strings. The following example would cause problems:

foobar comment=Hello world
**USER ERROR** Invalid command line
**USER ERROR** Unknown parameter [world].

Therefore multiple word strings must be quoted. We would expect the following to work, but receive the same error:

foobar comment="Hello World"
**USER ERROR** Invalid command line
**USER ERROR** Unknown parameter [world].

Unfortunately, the Unix shell pre-parses command lines and removes the quotes. To alleviate this problem use the following:

Foobar comment=\"Hello World\"

Lists of String Parameters

Some applications will restrict the values of string parameters to a pre-defined list. We will use the below "raw2isis" GUI as an example. In this particular case, both BITTYPE and BYTEORDER are strings restricted to certain values. Those values are given in parenthesis to the right of the radio buttons. Two examples of valid command lines are:

raw2isis byteorder=lsb bittype=real from=file.raw to=file.cub nl=500 ns=500
raw2isis byteorder=lsb bittype=R from=file.raw to=file.cub nl=500 ns=500

When radio buttons appear the GUI, the value can be abbreviated to uniqueness and is case insensitive as well. The second example, bittype=R implies bittype=real. The following example would fail because of uniqueness issues matching both UnsignedByte and UnsignedWord:

raw2isis bittype=unsigned from=file.raw to=file.cub nl=500 ns=500
**PROGRAMMER ERROR** Value of [BITTYPE] does not match a list option uniquely

Lists of String Parameters Example

503x627, 24KB

Boolean Parameters

These parameters are represented by check boxes in the GUI. Command line examples of the use of a boolean parameter are:

foobar option=yes
foobar option=no
foobar option=true
foobar option=false
foobar option=t
foobar option=f

The values are case insensitive. That is, Yes, YES, True, T, etc work as well.

Inclusive and Exclusive Parameters

The GUI has the ability to include or exclude parameters via stipling (graying out parameters). The application programs will complain if you get it wrong in command line mode. Using our "raw2isis" example,

raw2isis fr=my.raw to=my.cub li=500 sa=500 min=0 max=255
**USER ERROR** Parameter [CREATESPECIAL] must be used
  if parameter [MINIMUM] is used.

raw2isis fr=my.raw to=my.cub li=500 sa=500 createspecial=yes
**USER ERROR** Parameter [MINIMUM] must be used
  if parameter [CREATESPECIAL] equates to true.

Cube Attributes

When a parameter is an input or output cube the GUI presents two extra buttons […] and [att]. The […] button which gives a file selection dialog is not implemented on the command line. However, the [att] button is fully implemented in order to select the attributes for the input and output cube.

Output Cube Attributes

The user can specify properties of the output cube. They include:

Pixel Type
Output Pixel Range
Label Format
Pixel Storage Order
Storage Format

On the command line, the user supplements the output parameter with the attributes. Some examples are:

highpass to=temp.hpf.cub+detached+bsq
highpass to=temp.hpf.cub+16bit
highpass to=temp.hpf.cub+8bit+-5.0:5.0

Pixel Type

This defines the output pixel type. There are three types of output pixels: UnsignedByte, SignedWord, and Real. Valid values and synonyms are given below:

+UnsignedByte
+8bit
+8-bit

+SignedWord
+16bit
+16-bit

+Real
+32-bit

The default value depends upon the type of program. Most geometry-like programs such as crop, rotate, cam2map, pad, etc will simply propagate the input pixel type. Programs which fiddle with the pixel values such as derive, highpass, grad, etc will generally output real pixels.

Output Pixel Range

When choosing an output pixel type other than Real/32-bit the user must define the expected range of output pixels. The form is +minimum:maximum. For example,

moccal to=cal.cub+0.0:0.3

It is important to select a good minimum and maximum. If the window is too tight, pixels in the output file will be saturated (many LRS or HRS special pixels). If the window is wide then quantization can occur. That is, all the pixels are mapped to one value in the output cube. It can be a difficult problem that can be alleviated by outputting real images, understanding that the sacrifice is utilizing more disk space.

Label Format

The option exists to create attached or detached labels. This is facilitated through:

crop from=input.cub to=output.cub+detached
crop from=input.cub to=output.cub+attached

Detached labels will be put in a separate file with an .lbl extension. The default option is read from the system-wide/user IsisPreference file.

Pixel Storage Order

The output order of 16-bit and 32-bit pixels can be selected in the following manner:

crop from=input.cub to=output.cub+lsb
crop from=input.cub to=output.cub+msb

The two formats, lsb and msb are for least and most significant byte orders respectively. The default is to use the format native to the machines architecture.

Storage Format Format

The storage format of the file can be tiled or band sequential. The default format is tiled which is preferable for most geometric processing programs. To select the format use:

lowpass from=input.cub to=output.cub+tiled
lowpass from=input.cub to=output.cub+bsq
lowpass from=input.cub to=output.cub+bandSequential

Combining

lowpass from=input.cub to=output.cub+bandSequential+detached

gives a raw file that can be easily imported into other image processing packages.

Input Cube Attributes

Input cube attributes are significantly less complicated than those of output. They allow the user to select the bands on which to operate. The below example divides all bands by band 5:

ratio num=input.cub den=input.cub+5 to=dividebyband5.cub

There are several forms of band selection:

+singleBand
+startBand-endBand
[Future Option] +filtername

The selections can be combined by comma separation. Below are several examples,

+9
+3-5
+3,8,10-12
+3-1
+8,4,2

Reserved Parameters

All Isis applications have a suite of reserved parameters. These parameters are

-webhelp, -help or -help=parameterName
-last
-restore=file
-gui
-nogui
-batchlist=file
-errlist=file
-onerror=abort | continue
-preference=file
-log or -log=file
-info or -info=file
-save or -save=file
-verbose

These parameters may be typed out in full or until the command is distinct. For instance:

equalizer -pref=myPreferences -s=ttt –g
equalizer -l

The first command line is acceptable because each parameter is distinct. However, the second command line would cause an error. The -l could have been intended to be the -last or -log parameter. In this case, the -l must be extended to -lo for log or -la for last. If you choose to use the shortened version of the parameters, be sure to watch for conflicts of this sort.

-webhelp and -help Parameters

This parameter is used to obtain help on the program. Typing the -webhelp parameter will launch a browser containing the documentation for the application. Typing the -help parameter will give a list of the programs parameters with their default value. For list parameters, all the possible options will be output, and there will be a * denoting the default option. Typing -help=parameterName will give a brief description of the parameter, its default value, inclusion/exclusion information, and any other information given in the xml. The three possible options and the resulting output are seen below:

equalizer –webhelp

This command will cause a web browser to be launched with the documentation for the "equalizer" program.

equalizer -help

The above command will cause the following terminal output to appear on the screen.

FROMLIST = Null
TO       = Null
HOLDLIST = Null
APPLY    = TRUE
ADJUST   = (*BOTH, CONTRAST, BRIGHTNESS)
CMODE    = (*PCA, SD)
MINCOUNT = 1000
WEIGHT   = FALSE

To gain more information on the CMODE parameter, the following command can be used.

equalizer -help=cmode

This command will cause the following terminal output to appear on the screen.

ParameterName = CMODE
Brief         = "The constrast mode to use for the equalization"
Type          = string
Default       = PCA

Group = PCA
  Brief = "Principal Component Analysis Fit Mode"
End_Group

Group = SD
  Brief = "Standard Deviation Fit Mode"
End_Group

-last Parameter

This parameter will run the program using the parameters from the last time a program was run in the GUI. For example,

highpass –last

Additionally, parameters can be modified in the following manner:

highpass –last from=next.cub to=next.hpf.cub

-restore Parameter

This parameter allows the user to run the programs with the parameters from a file. In particular, a file saved using the GUI save mode or a session log. For example,

highpass –restore=guiSave.par
highpass –restore=print.prt

Either will look for the last occurrence of Group=UserParameters in Object=highpass in the specified file. Parameters will be loaded from that group.

-gui Parameter

This parameter forces the GUI to run. It can be used in combination with parameters and reserved parameters. For example,

highpass from=input.cub to=output.cub lines=5 –gui
highpass –last –gui
highpass –restore=print.prt –gui

All examples cause the GUI to be shown with the values filled into the appropriate fields.

-nogui Parameter

This parameter forces the GUI not to run. Its main intention is to be used on a program with no parameters For example,

csspck2spk –nogui

All examples cause the GUI to be shown with the values filled into the appropriate fields.

-batchlist Parameter

This parameter allows the user to run a program multiple times on a list of input parameters. It can be used in combination with all parameters. It cannot be used with the -last, -restore, or -gui reserved parameters. The batchlist file must be a text file containing one or more columns of data. The columns can be used in the other parameters by using a '\$' followed by the column number. An example of what the batchList.txt file might look like can be seen below.

/work2/eribelin/viking/   f387a06.cub
/work2/eribelin/viking/   f348b26.cub
/work2/eribelin/viking/   f319b19.cub

An example commandline would look similar to the following:

highpass -batchlist=batchList.txt from=\$1\$2 to=\$1/hpf/\$2 lines=5 samples=5

The commandlines that would be run from the above command would be:

highpass from=/work2/eribelin/viking/f387a06.cub to=/work2/eribelin/viking/hpf/f387a06.cub  lines=5 samples=5
highpass from=/work2/eribelin/viking/f348b26.cub to=/work2/eribelin/viking/hpf/f348b26.cub  lines=5 samples=5
highpass from=/work2/eribelin/viking/f319b19.cub to=/work2/eribelin/viking/hpf/f319b19.cub  lines=5 samples=5

-errlist Parameter

This parameter will save the lines from the batchlist that an error occurs on in an error file in addition to writing the errors out to the screen. It can be used in combination with all parameters and the -batchlist and -onerror reserved parameters. All lines that were not run successfully will be propagated to the errorfile.

highpass -batchlist=batchList.txt from=\$1\$2 to=\$1/hpf/\$2 lines=5 samples=5 -errlist=errList.txt

This errorlist can be read back in as the batchlist once the errors are corrected.

-onerror Parameter

This parameter can be used with all parameters, and the -batchlist and -errlist reserved parameters. If the continue option is selected, it allows the user to run the program on several different files, without stopping if an error occurs on one of the commandlines. If the abort option is selected or it is ran without being set (the default is abort), the program will halt when the first error occurs.

highpass -batchlist=batchList.txt from=\$1\$2 to=\$1/hpf/\$2 lines=5 samples=5 -onerror=continue

In this example, any errors that occur will be printed out to the screen and the program will continue to the next command.

-preference Parameter

This parameter can be used with all parameters, and reserved parameters. It overrides the current preference file with the file input by the user. For example,

highpass from=input.cub to=output.cub lines=5 samples=5 -preference=myHighpassPrefs

In this example, anything currently in the preference file will be overridden with the preferences in the file myHighpassPrefs.

-log Parameter

This parameter can be used with all parameters, and reserved parameters. It overrides the current log file in the preferences with the file input by the user. If the -preference option is also used, the log file entered will override the session log loaded in the preference file. When -log is used without specifying a filename, the session log will be save to the print.prt file. If the session log output is turned off in the preferences, using the -log option will override it for the command line being run. Examples of each use follow.

highpass from=input.cub to=output.cub lines=5 samples=5 -log
highpass from=input.cub to=output.cub lines=5 samples=5 -log=temp.prt

In the first example, the session log will be saved in the print.prt file in the current directory (even if the session log output is turned off in the preferences). In the second example, the current session log file in the preference file will be overridden with temp.prt, and the session log information will be saved there.

-info Parameter

This parameter can be used with all parameters, and reserved parameters. It gathers debugging information necessary to help the Isis developers understand user problems. When -info is used without specifying a filename, the debugging information will be displayed to the console through standard output. PLEASE NOTE: The user should remove any data from this file that they consider to be personal and do not want publicly available before posting the file on the Isis Support Forums Examples of each use follow.

highpass from=input.cub to=output.cub lines=5 samples=5 -info
highpass from=input.cub to=output.cub lines=5 samples=5 -info=debug.log

In the first example, the debugging information will be output to standard out. In the second example, the debugging information will be written to debug.log.

-save Parameter

This parameter can be used with all parameters, and reserved parameters except the -batchlist and -errlist options. It saves the command line parameters to a file in Pvl format. The output file can be read back in to the program using the -restore option. The default save file name is programName.par. If the -save option is not used, the history file will be saved by default in the location specified in the preference file under HistoryPath. If only -save is used, the file will be saved in the current directory, and if the -save option is used with a specific filename, it will be saved in that location.

highpass from=input.cub to=output.cub lines=5 samples=5 -save=hpf/saveFile.par
highpass from=input.cub to=output.cub lines=5 samples=5 -save

In the first example, the program will save the parameters information in the saveFile.par file in the hpf directory. The second example would save the same parameters in the highpass.par file in the current directory.

-verbose Parameter

This parameter can be used with all parameters, and reserved parameters. If the terminal output preference is turned off in the preferences, the -verbose option will override it, and print the terminal output to the screen for the current command only. For example,

highpass from=input.cub to=output.cub lines=5 samples=5 -verbose

The terminal output would be written out to the screen as the program was executed.

Error Status

Command lines programs exit with a status indicating success or failure. Further information regarding the status can be found in the Isis Error Handling Facility.

Isis 3

Isis 2

Search