User Guide

Overview

DaVinci is a C-like interpreter designed to allow rapid, symbolic and algebraic manipulation of multidimensional data sets, such as images or image cubes. DaVinci can also be used to write scripts, providing a programmable interface to all of the package's functionality.

---

Getting Started

An interactive session with daVinci is usually stated by invoking the programs name directly from the shell prompt:

prompt% davinci

dv>

DaVinci presents the user with the interactive prompt, and is now ready to accept commands. In its simplest form, daVinci can be used as a calculator:

dv> 20/0.89 22.4719

DaVinci also has named variables, to store intermediate results:

dv> a=2 dv> b=-6 dv> c=-40 dv> quad = (-b + sqrt(b*b - 4*a*c)) / (2*a) 6.21699

The real power however, lines in daVinci's ability to symbolicly manipulate large data sets. The following example loads two spectra and an image cube, performs a multiplier and offset correction on the cube using the two spectra, and writes the results to a file. 	dv> mult = load("spd014",51)

dv> offset = load("spd014",57) dv> cube = load("data.qbe") dv> cube = (cube - offset)/mult dv> write(cube, filename="output.dat", type=ISIS); To exit daVinci, use the quit command, or enter an EOF. Language Components DaVinci uses a C-like language interpreter, and provides many of the constructs available in the C language, such as:

• constants
• variables
• numeric operators
• boolean operators
• compound statements
• if/else statements
• while/for loops

Variables and Constants There are two types of variables and constants in daVinci, data objects and strings. Data Objects Every data object in daVinci is actually a three dimensional array of values. Constants are also three dimensional arrays, but they have a dimension of 1 along each axis, producing a 1x1x1 array. The axes are labeled X, Y and Z, which correspond to samples, lines and bands, respectively.

The dim() function can be used to determine the size of each axis of an object.

Variable Names

Variable names can be any combination of letters, numbers or underscores, but cannot begin with a number. Names can be of any length, and are case sensitive. The following are all valid names:

d
data17
high_pass_filter

Ranges Individual elements of an object can be accessed using the range operator: []. The range operator takes a pair of values for each axis (a low and a high value) separated by a colon, with the pairs being separated by commas, as follows:

[xlo : xhigh , ylo : yhi , zlo : zhi]
Not all the values need to be specified all the time:

• If the low and high values for an axis are the same, the colon and one of the values can be omitted.
• If the low value for an axis is 1, or the upper value is the limit of the axis, that value can be omitted.
• If the low and high values specify the entire range of the axis, they can both be omitted, along with the semicolon.

As an example, these two range specifications are the same, assuming a 10x10x10 array. Both specify the entire X axis, the plane Y=2 and the range of Z values, 1 to 5.

[1:10 , 2:2 , 1:5]
[,2,:5]
Data Representations In most cases, daVinci provides the user with a virtual representation of data. That is, the user does not need to know how the data is organized, or what format it is in. In some special cases however, the user will want to know these things, and potentially, to change them.

Organization The organization of an object describes the ordering of its elements. The data in daVinci can be stored in one of three possible organizations:

• • bsq - Band sequential (XYZ)
  • bil - Band interleaved by line (XZY)
  • bip - Band interleaved by pixel (ZXY)

The org() function can be used to determine or change an object's organization.

Format

The format of an object determines the size of each element in an object, and the type of data being represented (ie: integer vs real)

DaVinci supports 5 data formats:

• • byte - 8-bit unsigned integer
  • short - 16-bit signed integer
  • int - 32-bit signed integer
  • float - 32-bit signed real
  • double - 64-bit signed real

When converting from a larger format to a smaller one, if a value exceeds the range of the new format, it is set to the closest representable value. When converting from a real to an integer format, fractional values are truncated.

The format() function can be used to determine or change an object's format.

Strings The only operation allowed on strings is the addition of two strings, as follows: dv> a = "string1" + "string2"

"string1string2"
A string and a data object can be added, as long as the data object has a dimension of 1 along each axis. The data object is first converted to a string, and the two strings are added, as above. This can cause confusion when mixing string addition and numeric addition on the same line. In the following example, the first two values are numeric and are added numerically, however since the thrid value is a string, all the remaming values are added as strings:  dv> 4 + 5 "=" 4 + 5
9=45
Operators DaVinci supports most of the C operators. The complete list of those operators supported, and their precedence, is listed below:

() - grouping
[] - subset
* / - multiplication
+ - - addition
< <= > >= == != - boolean relations
&& - logical and
|| - logical or
= += -= - equivalence, increment, decrement
When an operator is applied to a multidimensional object, the operator is actually applied to each element in the object. Likewise, when an operator is applied between two objects, the operator is applied to the pair of values at each location. If the two objects do not have the same dimension along each axis, at least one of the objects must have a dimension of 1, along the differing axis.

	Currently, relational operators can only be applied to objects 	containing a single value.

Expressions

Variables, constants and operators can be combined to form expressions. There are two types of expressions, mathematical and relational. Mathematical expressions contain mathematical operators: +, -, *, /, etc). Relational expressions contain relational operators (==, <, >, etc). Relational expressions can only produce values of 1 or 0, corresponding to true and false.

Statements

A simple statement is a complete expression, terminated by a newline or a semicolon. Simple statements can be grouped together, forming compound statements, by surrounding them with curly braces, as follows:

{ statement1; statement2; }
or  {
statement1
statement2
}
If/Else Statement The if statement has the following syntax:

if (' expression ')' statement1
'if (' expression ')' statement1 'else' statement2  The test condition expression is evaluated and if it is true, statement1 is executed. If expression is found to be false, statement2 is executed, if it exists. Either statement can be a compound statement as described above.

The interpreter will not execute any portion of the if/else block until it has received all of it. Since the else is optional, the interpreter will pause after receiving statement1, until it receives the next line and determines whether it is or isn't an else. When interactively entering an if without an else, it may be necessary to enter an empty expression to inform the interpreteter that the else is not being supplied.

While/For Loops

The while statement has the following syntax:

'while (' expression ')' statement  Expression is evaluated, and if true, statement is executed. Expression is then reevaluated, and if still true, statement is again executed. This is repeated until expression evaluates to false.

Statement can be a compound statement, as described above.

Foreach Loops

The foreach loop is not currently implemented.

Writing Scripts DaVinci commands can be placed in script files and executed directly from the shell. DaVinci scripts must begin with the line:

#!/usr/local/bin/davinci -f This mechanism causes the shell, upon seeing the #! construct, to invoke the program /usr/local/bin/davinci with the -f option. It also passes the name of the current script, and any arguments that were given to it, on the end of the line. DaVinci then reads the script file, and executes its contents exactly as if they had been typed to the command interpreter.

Command line arguments

Any values specified on the command line when invoking daVinci or a daVinci script, are available as numbered variables. These values are access by prefixing their position on the command line with a '$': the first argument is $1, the second is $2, etc. The programs name is always $0.

Numbered arguments are string constants. To use these arguments in calculations, you must first convert them using the atoi() or atof() functions. Scripts are where the argument variables ($1, $2, etc), become most useful, allowing the user to change a script's inputs at runtime, without having to edit the file.

The following script finds the factorial of a number given on the command line:

#!davinci -f

#
# compute the factorial of a number
#
i = atoi($1)
sum = 1
while(i) {
sum = sum * i
i=i-1
}
echo(sum)

Special Variables Environment Variables Any environmental variable can be accessed as a string value, by prefixing the variables name with '$'.

Reserved Variables

Some variables have a special predefined meaning, and should not be used for general calculations. These 'reserved' variables are:

• scale - Number of digits to print after decimal point
• verbose - How much output to display
• order - User ordering of axis (not implemented yet)

Functions Most functions taking more than one argument can take those arguments in any order, provided a keyword is specified with each argument. As an example, the write() function requires 3 arguments, an object to be written, a filename to write the data to, and a file type:

write(object=var,filename="file.qbe",type=ISIS) Since each of these arguments has a keyword specified with it, they can be presented in any order. The following three lines are identical in functionality to the one above:

write(object=var, filename="file.qbe", type=ISIS)

write(filename="file.qbe", type=ISIS, object=var)
write(object=var, type=ISIS, filename="file.qbe")

Additionally, if the arguments are presented in the order specified by the function definition, no keywords are necessary. The following line is identical in function to all of those above:

write(var, "file.qbe", ISIS) The function reference contains the complete documentation for each function, as well as the order of arguments.

Getting Help On line help is available for many topics. The help command will display a list of topics, and can be used to view the text on those topics. Additionally, the user can request a short description of a function (including the arguments it accepts) by specifying a question mark as the only argument to the function, as follows:

dv> write(?)'

Command Line Options DaVinci recognizes the following command line options: 

-l filename - specify log file

Every command entered into davinci is recorded in a log file. The default log file is ".dvlog", in the current directory. The log file can be changed to another filename by specifying the -l option on the command line.

-v N - set level of verbosity (0-3)

The special variable verbose determines how much information is output to the user. At a level of 0, no informaitonal output is shown to the user unless explicitly requested with the echo() function. The default value is 2.

-f filename - file of commands to execute

The -f option specifies a file of commands to be exectued rather than taking commands from the user directly. This option is required when creating executable scripts, and must be the last option on the line, as follows: '' #!/usr/local/bin/davinci -f

-e 'command' - single command to execute

The -e option specifies a statement or a list of statements to be executed.