Working with TeraScan Functions
Working with TeraScan Functions |
You can use one of three modes to invoke a TeraScan function: (1) interactive mode, (2) command line mode, and (3) mixed mode.
In interactive mode, TeraScan presents you with a series of prompts that you must respond to. To invoke a function interactively, you type the name of the function at the UNIX prompt and press <Return>. The first prompt will appear on the screen. You respond to the prompt and press <Return> and the next prompt appears, and so forth.
An example of a function invoked via interactive mode is shown below. The function is llcontr2 which generates four prompts that will be explained in the following paragraphs.
% llcontr2 in/out files: char(75) ? big10 llcontr2.meta master_file: char(75) ? avhrr_ch2 z_variable: char(15) ? avhrr_ch2 iso_values: real(30) ? [0]The first prompt to appear for llcontr2 is in/out_file(s). Many TeraScan functions act on data that has already gone through some type of processing by another TeraScan function. This processed data is stored in files. These files of processed data are referred to as datasets. In cases where a function acts on one or more datasets, the function must be told the names of the files to act on. These files are referred to as input files. Likewise, a function that produces a dataset must be told the names of the files in which the dataset is to be stored. These files are referred to as output files.
In interactive mode, if the names of input and/or output files are required, the prompt for the file name(s) (either input file(s), output file(s), or in/out file(s)) will be the first prompt to appear when you initiate a function. You must supply the appropriate file name. If more than one file name is asked for, the names must be separated by a blank space. In the example shown for the llcontr2 function, big10 is the input file name and llcontr2.meta is the output file name.
The second, third, and fourth prompts for llcontr2 are referred to as parameter prompts. Each prompt asks you to supply a piece of information that will determine the outcome of the processing carried out by the function. Each prompt consists of the parameter name, followed by an indicator of the type of information being requested. These indicators are: char, int, or real, meaning, respectively, an alphanumeric character string, an integer, and real number. The information-type indicator will often include a number in parentheses. For char, this number indicates the maximum number of characters, including blanks, that the response can consist of. For example, the master_file parameter generated by the llcontr2 function is prompting for a character string, which can be up to 75 characters long. For int and real, the number in parentheses indicates the maximum number of integers or real numbers allowed in a response. In responses consisting of more than one number, the numbers must be separated either by spaces or by commas. For example, the iso_values parameter generated by the llcontr2 function is prompting for one or more real numbers. A list of up to 30 numbers separated either by spaces or commas is allowed.
Some parameters have default values. If a parameter has a default value, this will be indicated by a pair of brackets at the end of the prompt line. In some cases, the default will be a specific value and this value will be enclosed in the pair of brackets. In other cases, the default will be dependent on the responses to other prompts, and the default brackets will be empty. This manual explains parameter defaults in the Parameter Definitions section of each function's description.
You can either accept the default for a parameter by pressing <Return>, or you can type in a response that is different from the default. For a parameter that has no default, you must enter a response. In the llcontr2 example, the parameters master_file and iso_values have defaults, and these defaults have been accepted. The parameter z_variable has no default and the response, avhrr_ch2, has been typed in.
Another method of invoking a TeraScan function is to use the command line mode. This means that you list all parameters and their appropriate values on the command line. Each parameter must be connected to its value with an equals sign "=". If input or output file names are required, these must follow the parameters at the end of the command line with a space between file names.
For example, to invoke llcontr2 in command line mode, you would type at the UNIX prompt:
% llcontr2 master_file=Master z_variable=avhrr_ch2 \ iso_values=0 big10 llcontr2.metaThis command line would give you the same results as the example shown for the interactive invocation of this function. (Notice the use of the shell line continuation character "\". This must be immediately followed by a <Return>.)
The command line shown above could also be included in a UNIX script with the input and output file names specified by $1 and $2 respectively. For example, if the command line
llcontr2 master_file=Master z_variable=avhrr_ch2 iso_values=0 $1 $2were to be included in a UNIX script named contour, the command line
% contour big10 llcontr2.metawould produce the same results as the previous examples.
If a parameter requires more than one input value, the parameter and its values must be enclosed in single quotes. For example to enter the values of 25, 26, and 27 instead of 0 for the parameter iso_value, you would type the command line as follows:
% llcontr2 master_file=Master z_variable=avhrr_ch2 \ 'iso_values=25 26 27' big10 llcontr2.metaMixed mode means that you provide some of the parameters and/or the input and output file names on the command lines and then let TeraScan generate prompts for the other parameters. Parameters included on the command line do not generate prompts. For example, if you type the following command line and press <Return>:
% llcontr2 master_file=MasterTeraScan will prompt you for the other parameter responses as follows:
in/out files: char(75) ? big10 llcontr2.meta z_variable: char(15) ? avhrr_ch2 iso_values: real(30) ? [0]The results will be the same as the original example.
You can also type the input and output file names on the command line, and let TeraScan generate the prompts for the parameters as follows:
% llcontr2 big10 llcontr2.meta master_file: char(75) ? [Master] z_variable: char(15) ? avhrr_ch2 iso_values: real(30) ? [0]Again, the results will be the same as the original example.
Some parameters are optional. Optional parameters do not generate prompts when you run a function in interactive mode. In order to change the value of an optional parameter, you must place the parameter and its value in the command line. For example, llcontr2 has four optional parameters. One of these, num_div, specifies the number of contour divisions. To change the number of contour divisions from the default of 2 to 8, you would type the following command line and respond to the prompts as shown.
% llcontr2 num_div=8 in/out files: char(75) ? big10 llcontr2.meta master_file: char(75) ? [Master] z_variable: char(15) ? avhrr_ch2 iso_values: real(30) ? [0] big10: processing a 120 X 141 gridThe results of this invocation of the function will be different than the results of the previous examples because the value for num_div has been changed.
In some cases, the response to an optional parameter is simply the name of the parameter.
It is possible to process multiple datasets in a single invocation of a function because many functions support both wild cards (* and ?) and directories for processing. The general form is:
% function input output % function input_1 input_2 . . . input_N outputwhere output may be a directory name. For example, if you have two directories named images and reg, and images contains the datasets big10, big11, and big12, the following command line would produce registered datasets named big10, big11, and big12 in the directory reg.
% fastreg images/big1? reg master_file: char(75) ? [Master] polysize: real ? [100]Note that the original input names are retained. Only the input and output directory names are different.
Data Types
TeraScan supports five data types: 8-bit unsigned byte data, 16-bit short integers, 32-bit long integers, 32-bit floats (real numbers), and 64-bit double precision real numbers. Complex numbers are implemented as two-dimensional variables of any data type within a TeraScan dataset.
Time Formats
Time can be entered in the following formats:
hh:mm:ss hh mm sswhere hh is the hour, mm is minutes, and ss is seconds. Valid delimiters are the blank and the colon. For example, 23:16:00 indicates 23 hours and 16 minutes GMT (Greenwich Mean Time). Note that zeros are required as right-hand place holders, since 23:16 would indicate 0 hours, 23 minutes, and 16 seconds GMT, NOT 23 hours, 16 minutes.
Date Formats
Date can have the following formats:
yyyy/mm/dd yyyy mm dd yyyy.jjj yy/mm/dd yy mm dd yy.jjjwhere yyyy or yy is the year, mm is the month, dd is the day, and jjj is the Julian day (1 to 365 or 366). Valid delimiters are the blank and the slash (/). For example, December 31, 1987 can be entered as any of the following:
1987/12/31 87/12/31 87 12 31 87.365Latitude and Longitude Input Formats
Latitude and longitude can be entered in the following formats:
ddd mm ss[.ss] D ddd mm[.mm] ddd[.dd] Dwhere ddd is degrees, mm is minutes, and ss is seconds. The fractional parts .dd, .mm, and .ss are optional. D is the first letter of the direction and can take the following values: n or N for north, s and S for south, e or E for east, and w or W for west. Negative values are not allowed. The following examples illustrate these formats:
32 44 19.8 n 32 44.33 N 32.739 N 117 44 19.8 w 117 44.33 W 117.739 WNote that to enter minutes or seconds without degrees, you must use leading zeros. For example:
2 S is 2 degrees south 0 2 S is 2 minutes south 0 0 2 S is 2 seconds south
Last Update: $Date: 2001/05/17 18:22:53 $