User Guide

From DavinciWiki
Revision as of 18:36, 18 November 2016 by Rswinkle (Talk | contribs)

Jump to: navigation, search


Contents

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 symbolically 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 10 data formats:

  • uint8 - 8-bit unsigned integer
  • uint16 - 16-bit unsigned integer
  • uint32 - 32-bit unsigned integer
  • uint64 - 64-bit unsigned integer
  • int8 - 8-bit signed integer
  • int16 - 16-bit signed integer
  • int32 - 32-bit signed integer
  • int64 - 64-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"

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 third value is a string, all the remaining 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 interpreter 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.

When writing scripts, you may find it helpful to use an editor with syntax highlighting.

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)

Other Predefined Variables

The following variables are automatically defined when starting up davinci. In general, they should be treated as constants - you do not want to overwrite them or change their values, but there is nothing to prevent you from doing so.

From constants.dvrc:

  • pi - Mathematical constant π, in double precision (double format)
  • con - Structure containing values of various mathematical and physical constants; see conhelp
  • Sun, Earth, Moon, Mars, Phobos, Deimos - Structures containing values of various physical parameters of those Solar System bodies; see solsys
  • un - Structure containing various unit conversion factors; see unithelp

From math.dvrc:

  • intmax = 2,147,483,647 - Largest value that can be stored as an int32, equal to 2^31 - 1
  • eps = 1.19209e-07 - Floating point (single) precision
  • eps2 = 2.22045e-16 - Double precision

From time.dvrc:

  • months - Names of the months of the year
  • weekdays - Names of the days of the week
  • DeltaT - Values of TAI-UTC offset from before 1961; see DeltaT
  • TAI_UTC - Values of TAI-UTC offset since 1961
  • timezone - Local time zone (relative to UTC); the value is initially set to -25 but is changed to your system's time zone the first time you run clock

Also, many .dvrc files define a version, such as:

dv> spectral_tools_version
1.14000

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

Online 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). Depending on the function, this can be done by specifying a question mark as the only argument to the function, or by giving it no arguments:

dv> write(?)

dv> conhelp()

Command Line Options

Davinci recognizes the following command line options:

-V - dump version information
-i - force interactive mode
-w - don't use X windows
-q - quick startup.  Don't load history or .dvrc
-H - force loadig of history, even in quick mode
-h - print this help
-l logfile - use logfile for loading/saving history instead of ./.dvrc

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 informational output is shown to the user unless explicitly requested with the echo() function. The default value is 2.

-f filename - execute the specified script and exit 

The -f option specifies a file of commands to be executed 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: -e 'command' - execute the specified command and exit The -e option specifies a statement or a list of statements to be executed.

-- indicates this is the last command line option
Note: Any --option style options are always passed as $ARGV values

#!/usr/local/bin/davinci -f

Personal tools