3.0 Getting Started on LAS

This section addresses the following topics:

3.1 Introduction
3.2 UNIX Environment
3.3 Using the System
3.4 TAE Interface
3.5 Data Transfer
3.6 LAS/TAE Command Syntax
3.7 Error Handling and Aborting Processes
3.8 Procedure Definition Files (PDFs)
3.9 Software Packages Interfaced with LAS
3.10 Problem Reporting and Enhancement Requests

3.1 Introduction

In order to use LAS, a user must have an established account on the desired computer. All users should verify that they have access to sufficient disk space. Since a single image can take anywhere from 10 to over 200 megabytes, the quota provided for the user's home directory is not normally sufficient. The system manager can assign additional disk space on another file system.

The current version of the LAS system has been developed for UNIX environments. Knowledge of both the operating system and system utilities is not necessary but will allow a user more flexibility and improve the user's ability to use LAS.

3.2 UNIX Environment

Additional detailed information on the UNIX environment can be found in any of the UNIX manuals that are available for the computer system.

3.2.1 Setting up the UNIX Environment

LAS requires that a number of UNIX environment variables be defined to allow access to the LAS and TAE modules and support libraries. These are automatically defined when a user initiates a LAS session by typing las.

3.2.2 Basic UNIX Functions for the LAS User

There are several basic UNIX functions that the LAS user may wish to become familiar with before entering LAS.

The most basic of these is the ls command. This command lists the files in the current working directory or any other specified directory.

The second command is the cd command, invoked by cd <directory specification>. It allows the user to specify a new directory as the current working directory. For example:

     % cd test/image
Detailed descriptions of these commands and other shell commands can be obtained by using the man command (for manual) while in a shell. The format is man followed by the command name. The command name is required because the command man will not list all the available commands.

Unix shell commands may also be invoked from within an LAS session, with some restrictions. See Section 3.3.3.

3.2.3 File Versions

UNIX does not create multiple versions of the same file but simply overwrites the contents of the original file. Although LAS modules generally stop processing with an error message when a version of a specified output file already exists, this does not apply to some supporting files. In particular, when saving parameter values to a file, earlier parameter sets which were saved with the same name will be overwritten and lost.

3.3 Using the System

3.3.1 Logging on the System

In order to use any of the components of LAS, the user must first log on the host computer. Generally, the user is prompted for username and password. The user is then placed in the host command interpreter mode. Once logged on, the user has the following two options:

3.3.2 Entering and Exiting LAS

To enter LAS, simply type the command las while in the host command interpreter mode, indicated by either the % or $ prompt in UNIX, or other defined system prompt. The user will be placed under the Transportable Applications Environment (TAE) umbrella. The TAE user interface is described in greater detail later in Section 3.4.

Depending on how the system manager has set up LAS on the computer system, a user will go into either a menu or command mode; in either mode, on-line help is available at any point by typing help. To exit from LAS, the user may type exit when in TAE command mode. Alternatively, the user may enter logoff, in either command or menu mode. If an xterm window was created during LAS startup, the exit and logoff commands will cause the user to exit from both LAS and the window within which LAS was run.

Once the user is in TAE command mode (indicated by the LAS74> prompt), he or she may access the LAS modules in menu mode by typing menu or may access the LAS modules in tutor mode by typing tutor and a specific module name.

Example:

     LAS74> tutor pixcount
NOTE: LAS74> is the default TAE prompt. It may be changed by the system manager or a user may customize one for his/her own account (see the example of a customized user logon file, ulogon.pdf, in Section 3.8).

The first-time user of TAE may want to run through the tutorial supplied by the TAE Support Office. It can be accessed by typing taetutor at the LAS74> prompt. There is also a LAS tutorial which may be accessed by typing nut (new-user tutorial) at the LAS prompt.

3.3.3 Using Host Commands under TAE

One of the features of TAE is that one may enter into the host's command interpreter mode while still running under TAE and execute commands which the host's command interpreter understands. An example would be using the text editor in the UNIX shell.

To execute a UNIX shell command while under TAE, the user types ush (for user shell) while in TAE command mode. The prompt _% (or _$ if the user is using the Bourne shell) will appear indicating that the user can type shell commands. To return to TAE, the user types exit or keys in a CTRL-D sequence. The following are a few rules which apply to executing shell commands under TAE:

3.4 TAE Interface

3.4.1 Typical LAS Session

LAS processing is normally initiated from the Unix command prompt (% or $) by typing las. LAS creates a new window, if necessary, displays a welcome message, and then indicates it is ready to accept commands by displaying the TAE Command Language (TCL) command prompt, LAS74>.

At the TCL command prompt, the user will either select a LAS application module by tutoring on it, use TCL to execute a module directly, switch into menu mode, or execute Unix shell commands on the host computer. Parameters for an application module may be specified in one of two ways: by entering them on the TCL command line after the name of the module (see Section 3.6 ), or by using the TAE tutor. In tutor mode, which may be invoked directly from the TCL command line or indirectly via menu mode, TAE will list the required and optional parameters for the module. The user will enter values for one parameter at a time, perhaps invoking interactive help to get a complete description of the parameter. When all parameters have been specified, the application module is executed using the tutor run command.

Tutor mode and menus may be used interchangeably during the session. The user may switch from TCL command mode to menu mode by typing an m for menu in response to the TCL command mode prompt (LAS74>). Similarly, the user may switch from menu mode back to TCL command mode by entering a c for command mode in response to the menu mode prompt (?). Menu mode is especially convenient when the user is unsure of the name of the module which performs a certain function, or wishes to choose between modules which perform similar functions.

The LAS session ends when the user executes the exit or logoff command.

3.4.2 TAE Processing Options

TAE permits running LAS commands in three ways:

3.4.2.1 Interactive Processing

A user interacting with LAS is considered either a menu user or a TCL user. A menu user invokes application modules by locating and selecting them through a series of menus. Each menu displays a list of choices, either application modules to be executed or a list of other menus to be displayed. The user can either select one of the choices, or enter a command to request help for one of the choices, return to a previous menu, exit menu mode, or exit LAS altogether.

When an application is selected from the menu, TAE automatically enters tutor mode to prompt the user for the needed parameters. The user may also enter tutor mode from TCL command mode by typing tutor and the module name.

For example:

     LAS74> tutor isoclass
In either case, the user will then be presented with a tutor display consisting of the module parameters and their descriptions. The user then enters values for the parameters by typing <parameter name>=<value>.

For example:

     ? print=lp
The user may obtain additional information on any parameter by typing help <parameter name>. Once all required values are given, the user types run and the module will execute. Tutor mode is probably the most common method of executing LAS modules. While in tutor mode, a user may receive help on individual parameters as well as the module itself, including Algorithm/Description, Error Messages, and User Notes by typing help *.

When a help command is typed in any mode, a help screen is displayed and the user may then request more help or return to normal operations. The types of help information available are:

Under normal tutor mode (screen), the user is presented with a series of screens or pages containing parameter names, descriptions, etc. There is a second type of tutor mode called noscreen mode. It is ideal for nonCRT terminals or CRT terminals not supported by TAE. Noscreen tutor simply presents the user with a list of parameters and a prompt. The user has all the normal options except paging. Noscreen tutoring may be set for the entire interactive session by typing:

     LAS74>let $tutor="noscreen"
or for individual modules by typing:

     LAS74>tutor-noscreen isoclass
Also, in TCL the user may execute a module using a command string in TCL command mode, but the user needs to know the module name and the parameter names and values. Section 3.6 describes the syntax of TCL command strings.

The tutor mode and TCL command mode are described in detail in the TAE Command Language (TCL) User's Manual.

3.4.2.2 Noninteractive Processing

Noninteractive processing involves primarily three batch processing methods and a fourth method using a TAE script file. The batch methods include using the TAE batch command, the TAE runtype command, or a TAE proc file; the enable-script command is used to run a TAE script file. LAS batch jobs generate files with .log extensions, with .log being the primary product of the batch run.

TAE batch Command

The first method of running batch mode uses the TAE batch command. Only one LAS module can be run at a time. The following example shows how a user might run the module list in batch mode.

Example:

  LAS74>TUTOR LIST 
(While in tutor mode, set the following parameter, save this setup to a file, and exit the module.)
	IN=VALDEZ.LANDCOV
	PRINT=LP
	SAVE  LIST
	EXIT
Note the save list command creates the file list.par.
  LAS74>TUTOR BATCH-SUBMIT
(While in tutor mode, type the following.)
	PROC=LIST
	SAVEFILE=LIST
	RUNTYPE=BATCH
	RUN
Note the savefile value (list) is from the save statement in the first segment of this example.

This creates a temporary file list.job and submits it to the batch queue. After the job is completed, list.job is deleted, but a file called list.log remains in the user's directory. This file records the output from the run.

TAE runtype Command

The second method uses the TAE runtype command. This method also creates the log file, <proc>.log. This command is useful when a user wants to run one LAS module in batch mode from command mode without saving the .par file. The saved parameter file from the first method could also be used to demonstrate the second method. The second method can be done in any of the three following ways:

  LAS74> LIST |RUNTYPE=BATCH|  VALDEZ.LANDCOV LP 
or
  LAS74> LIST |RUNTYPE=BATCH  RESTORE=LIST| 
or
  LAS74> TUTOR LIST  |RUNTYPE=BATCH| 
(where the parameters for in and print were saved in a parameter file called list)

In the first example, a listing of the image valdez.landcov is printed to the line printer in batch mode. The second example uses the parameter file saved from a tutor session. The third example puts the user in a tutor session for list, but the module will be executed in batch mode.

TAE Procedure Proc File

The third method uses a TAE proc file. In this method the user sets up a proc file via the host text editor (such as emacs or vi under UNIX) and then executes the proc in batch mode. Several LAS commands or modules can be strung together in the proc file. The proc file cannot have the same name as an existing module under LAS and must have the .pdf file extension. Proc files are discussed in greater detail in Section 3.8 .

For example, the same list command as above, followed by the pixcount command to tally pixel frequencies, can be run as a proc. If the emacs text editor is used to create the proc file, the following commands would be used.

  % emacs  qlist.pdf 
(While in emacs type the following.)
	PROCEDURE  HELP=*
	BODY
	LIST  IN=VALDEZ.LANDCOV  +
	PRINT=LP
	PIXCOUNT-NO  IN=VALDEZ.LANDCOV +
	PRINT=LP
	END-PROC
	C-x C-c		(CTRL-X followed by CTRL-C
			is used to exit emacs)
Then run the proc as a batch job from the LAS74> prompt.
  LAS74>  QLIST |RUNTYPE=BATCH|
This example produces the same results as the example in method 1 and 2, followed by a list of the number of pixels which have each possible value. It creates a log file with the same name as the proc; i.e., for this example, qlist.log.

TAE Script File

Another processing option uses a TAE script file. A host text editor may be used to create a file of LAS commands as they would appear if the user was running in command mode.

For example, the commands executed by the proc file defined above can also be run by creating the script file (again using the emacs text editor) given below:

  % emacs  sample.scr

	LIST  IN=VALDEZ.LANDCOV +
	PRINT=LP
	PIXCOUNT-NO  IN=VALDEZ.LANDCOV +
	PRINT=LP
	C-x C-c		(CTRL-X followed by CTRL-C
			is used to exit emacs)
Then execute the script from the LAS74> prompt by typing

  LAS74> enable-script name=sample.scr 
Script files may only be run interactively.

3.4.2.3 Running LAS from the Unix Command Line

It is sometimes convenient to be able to run a single LAS command or a user-written procedure from the Unix command line. For example, Running a Single Command

To run a single LAS command from the Unix command prompt (% or $), type las followed by the LAS command you would execute from the TAE command prompt. For example

  % las dspddr myimg
will display information about image myimg.

When running LAS in this mode, the command is first parsed by the Unix shell, and then by a Unix script which creates a temporary .pdf file in the users home directory (pointed to by environment variable HOME). Accordingly, if any parameters for the command contain references to Unix environment variables, spaces, or commas, or if a parameter is a text string containing Unix "wildcard" characters (* or ?), it is necessary to protect the parameter string with single quotes. For example, the following command requires quotes as shown:

  % las copy 'in=$DEM_DIR/dem12(1,1,100,100)' out=nw_sect 'odtype=r*4'
It is sometimes difficult to get the quotes just right. The problem can be avoided by using a text editor to write a proc (cf. Section 3.8 ) which contains the LAS command(s) to be run. For example, the Unix command

  % las qlist 
will run the proc qlist.pdf defined above.

Including LAS Commands in Scripts

All the examples shown above of running LAS commands from the Unix prompt will also work when included in a Unix shell script, and may also be used in any other scripting language which permits execution of LAS shell commands. For example, system "las qlist"; in a Perl script, or &system las qlist in an Arc Macro Language script.

However, as noted below, there can be problems when running such a script in non-interactive mode unless processing messages are disabled. The easiest way to disable these messages is to incorporate the desired LAS command(s) into a proc (.pdf file).

Disabling Processing Messages

Most LAS functions print messages at fixed intevals of time, defined by the LAS global variable $MSGTIM, to indicate how many lines and/or bands of the image(s) have been processed. In non-interactive mode, these add clutter to the output. In addition, when these messages are enabled, the process will sometimes hang or abort. Accordingly, it is recommended that the messages be disabled for any proc which is to be run from a script or as a Unix background, at, or crontab process.

The messages can be disabled by setting $MSGTIM to zero at the beginning of the proc:

	procedure  help=*
	body
	let $msgtim = 0
	   .
	   .
	   .
	end-proc

3.4.3 TAE Utilities

A TCL command line is either the invocation of a proc or a TAE intrinsic command. The following TCL intrinsic commands are most often used in TCL. These utilities are available on both VAX and UNIX computer systems; however, the delgbl utility is currently not available under UNIX operating systems. The TAE help facility can be used to obtain more information about a command; e.g.

  LAS74> help chdir
will provide information about the chdir command. The TAE Command Language (TCL) User's Manual also describes the commands in more detail.

Command Description
abort Terminate current proc (after CTRL-C interrupt)
batch Batch queue manipulation
chdir Change working directory
continue Continue (after CTRL-C interrupt)
ush Switch to the UNIX shell
defcmd Define command
delcmd Delete command definition
delgbl Delete global
display Display variable value
disable Disable logging
enable Enable logging, script
exit Terminate TAE
help Obtain help information
let Assign a value to a variable
logoff Logoff TAE
menu Enter menu mode
setlib Set library search order
show Show status
tutor Enter tutor mode

3.5 Data Transfer

LAS contains software that transfers data from tape to disk, disk to disk, or disk to tape. It handles many types of tape files in a variety of formats.

Before running data transfers, users should verify that they have adequate disk and tape space to contain the output files that will be generated. The disk files handled by data transfer modules are compatible with LAS file format. LAS software also exists to transfer data between computer systems on a local area network. These modules are site specific and may not be available at your site. Contact your LAS system manager for more information. More details about data transfer are explained in the individual users guides.

Each computer represents data types such as integer and real*4 differently. The LAS input and output modules have the ability to convert data types from one computer representation to another. Many of the LAS modules also provide the ability to convert from one data type to another on the same computer system by use of the odtype parameter. The conversion from a higher (real) to lower (byte) data type is done by truncation and not scaling. Converting a real image to a byte image will set all pixel values below 0 and above 255 to 0 and 255, respectively. The map module should be used for rescaling of data.

3.6 LAS/TAE Command Syntax

LAS comprises a large number of modules representing many different types of image processing and support functions. In addition to invoking a module using the TAE tutor or menu modes, all LAS modules may be invoked directly from the LAS74> prompt using command mode.

The TAE command syntax for executing a LAS module has the following general format:

  LAS74> COMMAND_NAME|OPTIONS| PARMNAME1=VALUE1 +
         PARMNAME2=VALUE2 ...
The COMMAND_NAME may include a subcommand name, appended to it using a hyphen.

The most commonly used entries in the OPTIONS field are |runtype = batch| (discussed above) and |restore = <parmfilename>|. The restore option takes the parameters for the command from the named parameter file.

Each PARMNAME entry specifies one parameter for the command. If the parameters are entered in the same order in which they are displayed on the TUTOR screen for the module, it is sufficient to enter only the value of each parameter without the "PARMNAME=" string.

Parameters which are image names may contain specifications for spatial and/or spectral windows, as described in Section 4.2.2. In this case, the name of the image and its window specification must be enclosed in quotes; for example, "IN=MYIMAGE(100,100,512,512)".

If a command is too long for a single line, the plus sign ("+") should be entered as the last character on each line which is to be continued to a following line.

The online help for each module includes examples of how to invoke it from the command line. Help may be accessed directly from the LAS command line by typing help <module-name> or using the hypertext viewer (Web browser) invoked by the command lasdoc.

Examples of various ways to invoke module pixcount are given below:

Command mode:

  LAS74> PIXCOUNT-NO IN="MADTOWN.TM(200,300,1024,1027:2)" + 
         PRINT=(TERM,LP,MADTOWN)
Command mode, specifying execution in batch mode:
  LAS74> PIXCOUNT-NO |RUNTYPE=BATCH| +
         IN="MADTOWN.TM(200 300 1024 1027:2)"+
         PRINT=(TERM,LP,MADTOWN)
Command mode using previously stored parameters:
  LAS74> PIXCOUNT-NO|RESTORE=PIXCOUNT_MADTOWN|
Tutor mode:
  LAS74> TUTOR PIXCOUNT
Tutor mode accessed via menu:
  LAS74> MENU

3.7 Error Handling and Aborting Processes

All LAS errors during the interactive LAS session (nonbatch) will be displayed on the terminal in a uniform format. A fatal error will abort the module that is currently being executed and control is passed back to TAE. LAS was designed to produce uniform error messages. The format for each error message is a key followed by a short description of the error. An example might be:

	[copy-read] "Error encountered reading from input file"

The key is composed of a module or subroutine name followed by a hyphen ("-") and a short descriptor of the error such as "read" for a read error. In the example an error occurred reading a file in the LAS copy module. Further information on the error can be found by looking at the error message section of the user guide for the particular module. The user guide for any module may be viewed by typing help <module name>. All messages may be logged to a session log file; the command enable-log initiates the session logging and disable-log disables it. The session log or session history provides a record of the user's session. It contains a chronological listing of the modules run, the values of the module's parameters, and any informational or error messages that were generated. The session history is always written into a file called session.tsl unless the user changes the $LOG global variable.

A CTRL-C sequence suspends the currently running module. If the command abort is entered at the CTRL-C interrupt prompt, the module is aborted and the user will be sent back to the previous system status prior to the running of the module. The user may also use the help or continue commands at the CTRL-C interrupt. Help lists the processing choices at the interrupt while continue will restart the module at the point it was suspended.

3.8 Procedure Definition Files (PDFs)

TAE permits users to create their own procedure definition files (PDFs), using any standard text editor. User written PDFs are especially useful for

A PDF can contain any commands which can be executed from the LAS74> prompt, including most TAE Command Language (TCL) commands. Those TCL commands of use to the typical user are described in the TAE Command Language (TCL) User's Manual; commands intended primarily for use by programmers who are developing new applications functions are included in the TAE Command Language (TCL) Programmer's Manual.

Every procedure PDF must include three TCL commands in addition to those included in the body of the procedure. These are PROCEDURE, which indicates to TAE that a procedure definition follows, BODY, which introduces the TAE/LAS commands to be executed, and END-PROC, which signals the end of executable commands. Note that TAE does not distinguish between upper and lower case when interpreting the names of commands and parameters. The actual values of character-string parameters, on the other hand, are case sensitive unless they represent keywords which are to be matched against a list of possible values. In particular, Unix file names and commands passed to the Unix shell command for execution via the TCL ush command must be entered in the correct case.

Examples 1 and 2 below illustrate the use of ulogon and ulogoff procs for customizing the LAS environment. LAS automatically looks for ulogon.pdf file in the user's current working directory when starting up, and executes this file if it finds it. Similarly, when exiting, LAS executes the ulogoff.pdf file if it is present.

Example 1. User logon procedure file

PROCEDURE
REFGBL ($PROMPT, $MSGTIM, $PRINTER)
BODY
     LET $PROMPT="DR_LAS"
     LET $MSGTIM=10
     LET $PRINTER="earthlaser"

defcmd pix, string="pixcount-no print=lp" putmsg-notrace "---------------------------","ulogon-msg" putmsg-notrace " Log enabled, printer=earthlaser","ulogon-msg" putmsg-notrace " Defined commands are: pix","ulogon-msg" enable-log END-PROC

The REFGBL command is required when TAE/LAS global variables are to be set or referenced. In the example above, the LET command is used to set the prompt which LAS will display in command mode, to request that image-processing functions display a message showing the current line and/or band being processed every 10 seconds, and to specify that ASCII output should be directed to printer "earthlaser". Appendix B contains a list of all the global variables used in LAS. The DEFCMD command declares that "pix" is a shorthand form of the pixcount command. PUTMSG writes a message to the user's terminal in a standard format, and ENABLE-LOG causes the commands, parameters, and messages from the session to be saved in a log file, session.tsl.

Example 2. User logoff procedure file

procedure
    body
    !     Disable session history and print it
    disable-log
    ush lp session.tsl
    end-proc 

This PDF disables session logging when the users exits from the LAS session. After logging is disabled, the log file is released by TAE, so that it can be queued for printing. The exclamation point ("!") may be used to introduce a comment in the PDF file; all text on the line at and after the exclamation point is ignored by TAE. The DISABLE-LOG command closes the logging file, and the ush lp command invokes the Unix shell to send it to the log file to the printer.

3.9 Software Packages Interfaced with LAS

In order to use SAS, ARC/INFO, or other software packages interfaced with LAS, a user should consult with the local system manager for access information to each specific system. A few LAS modules (such as arc2las and las2arc for converting between Arc/Info grids and LAS images) directly execute commands in the other software package. More typically, LAS interfaces to these software packages through the labelled table (LT). In some instances, the use of the LT is hidden from the user as in the case of the gof2stat module. The user should be familiar with the manuals and documentation of the systems that he or she is transferring data bewteen, especially each system's limitations or system requirements.

3.10 Problem Reporting and Enhancement Requests

Users encountering problems with the LAS software should file problem reports. Blank problem reports are available from the local LAS user representative or system manager. They should be filled out with the requested information and then returned to your LAS user representative for evaluation and resolution. The user should include with the problem report any pertinent information related to the problem such as printouts, hard copies of terminal displays, session histories, exact error messages, and the computer system on which the error occurred. Suggestions for enhancements to LAS modules or for new capabilities should be written up and submitted to the local person responsible for LAS.

Users or LAS support personnel at the local site may implement enhancements and new modules to be made available to all LAS users. This software development should follow the standards established in the LAS Programmer's Guide. Software adhering to these standards can then be reviewed and included in the baseline version of LAS. Computer software that does not meet these standards will be included in the LAS Contributed Library. The Contributed Library is distributed with LAS but is not supported and is made available under a "user beware" category. The guidelines and procedures for software development are described in detail in the LAS Programmer's Guide.


Last change: 1999 Nov 02, R. A. White / raw@essc.psu.edu