4 Basic VICAR Concepts

Contents
4.1   Entering/Exiting VICAR
4.2   Getting Started
4.3   VICAR Datasets
    4.3.1   Dataset Names
	4.3.1.1 Temporary Datasets
    4.3.2   Dataset Structure
    4.3.3   Pixel Data Formats
4.4   VICAR  Labels
    4.4.1 VICAR Label Structure 
4.5   Procs
In this section, the user is introduced to some of the fundamental concepts of the VICAR image processing system. The new user will learn how to enter and exit VICAR and be introduced to VICAR datasets, labels and "procs". An understanding of these concepts is essential to effectively use VICAR and is assumed in subsequent sections.

4.1 Entering/Exiting VICAR

A VICAR session starts when a user invokes the VICAR executive by typing the command vicar at the prompt (% or $).

Syntax:

    % vicar	(UNIX) 
or
    $ VICAR	(VMS)
The user is then prompted for a VICAR command (Section 7.1) with a VICAR prompt, VICAR>.

The session ends when a user exits VICAR by typing the command exit at the VICAR prompt.

Syntax:

    VICAR>exit
The user is then returned to the UNIX shell or DCL.

4.2 Getting Started

Once in VICAR, a user is able to execute VICAR commands (Section 7.1) using the following command line syntax. Each required and optional term is explained in Section 7.2.

Syntax:

    VICAR>name[-subcommand] [|qualifiers|] [parameter_list] +
    VICAR>+[comments]
The most common and simplest form of a command line consists only of the proc or command name followed by a list of parameters.

Syntax:

    VICAR>name[-subcommand] [parameter_list] 
The following are examples to show how most procs and commands are invoked.

Example: Try these and see what happens.

    VICAR>gen a 10 10
    VICAR>list a
    VICAR>usage	(should be available on UNIX with V12.2)
    VICAR>show
For those anxious users who would like to jump right in, we suggest invoking the Menu system (Section 6.3) or going through the New User Tutorial (NUT - Appendix 10.14).

Syntax: Invoking the Menu mode.

    VICAR>menu

4.3 VICAR Datasets

A VICAR dataset is a file with fixed length records (Section 4.3.2). This dataset can be categorized as image data, which is a digital representation of a visual "picture", or as non-image data. The dataset structure for both types of data is the same, thus simplifying the VICAR interface.

4.3.1 Dataset Names

The VICAR user should name disk datasets with care.

BEWARE Unlike the VAX/VMS operating system, the UNIX operating system is case sensitive. While VICAR commands are not case sensitive, the filenames still are. Therefore, planet.img and PLANET.IMG are two different files on a UNIX system.

BEWARE VICAR users should avoid using system assigned logical names (on VMS systems) or environment variables and aliases (on UNIX systems) for dataset names. Assigned logical names can be obtained by typing the SHOW LOGICAL command in DCL,

Syntax:

    $ SHOW LOGICAL
or setenv and alias in UNIX.

Syntax:

    % setenv
    % alias
BEWARE When VICAR is required to write an output dataset, the VICAR executive I/O routines will check the directory for an existing dataset of the same name. If one exists, it will write the new dataset directly over the old dataset instead of creating a new version. For example, if a dataset named over.byt was created at 10:15, and another image with the same name was created at 10:18, there would be only a single entry in the current directory:

UNIX:

    -rw-r--r--  1 edd         10400 Aug  5 10:18 over.byt
not
    -rw-r--r--  1 edd         10400 Aug  5 10:18 over.byt
    -rw-r--r--  1 edd           550 Aug  5 10:15 over.byt.old

VMS:

    OVER.BYT;1               21   5-AUG-1994 10:15:34.38
not
    OVER.BYT;2               21   5-AUG-1994 10:18:41.23
    OVER.BYT;1                2   5-AUG-1994 10:15:34.38

BEWARE On VMS systems, when a file is overwritten, the space allocation is updated, but the creation date is not. On UNIX systems, both are updated.

4.3.1.1 Temporary Datasets

Temporary files are special files that are deleted when a user logs off. Under the old VMS VICAR, temporary files were specified by leaving off the filename extensions and assigning instead a .Zxx extension, where xx was based on the process ID. While that approach still works under VMS, files that begin with a plus sign (+) will now be recognized as temporary files on both UNIX and VMS systems.

Under the old system, temporary files were distinguised only by their name, and could be generated anywhere. The new style is to collect them all in one directory. Prepending a plus sign (+) to the name tells the VICAR RTL to put the files in the temporary directory. This directory is pointed at by the $VTMP environment variable in UNIX, and the VTMP: rooted logical name in VMS. VTMP is set up by vicset2 for both systems. (It normally points at /tmp/username for UNIX and a scratch directory for VMS). On VMS machines, because VTMP: is a rooted directory, accessing the directory outside of VICAR is a little awkward; you must use vtmp:[000000].

BEWARE The automatic deletion of the /tmp/username directory contents has not yet been established in UNIX VICAR. Therefore, in order to delete those files when you exit VICAR, you will need to place a ush /bin/rm /tmp/username/* command in your ulogoff.pdf. (See Section 5.4.2 for details on how to do this.)

Subdirectories of VTMP are permitted. Under UNIX, they are referenced by +sub_dir/file, while under VMS, they are referenced by +[sub_dir]file. The subdirectories are not automatically created; they must be created in advance using mkdir $VTMP/sub_dir under UNIX and cre/dir vtmp:[sub_dir] under VMS. Because of these differences, the use of subdirectories is not portable between systems.

Currently, all processes using the same login id share the same temporary directory. This may be changed in the future so concurrent independent jobs will have separate directories. In the meantime, a workaround can be used, which is to redefine VTMP to use a process-specific directory name.

4.3.2 Dataset Structure

A standard structure has been established for VICAR datasets and all VICAR programs operate with this structure by calling standard interface subroutines. (See the VICAR Run-time Library Reference Manual and The VICAR File Format.)

A VICAR dataset is a file of fixed-length records consisting of five parts:

Although the exact structure of a VICAR dataset varies depending on the presence of the three optional parts (binary label header, binary label prefix, and EOL), all VICAR datasets follow the same structure.

The VICAR label is an ASCII string containing information describing the size, origin, processing history and attributes of the dataset.

The binary label header and prefix are optional areas for storing information about a dataset in free form binary format.

The pixel data portion of the dataset is made up of samples (pixels) of specified data format (Section 4.3.3). The data dimensions are described in terms of "number of samples" (NS - record length), "number of lines" (NL - number of records of length NS), and "number of bands" (NB - number of NL x NS data planes).

The end-of-dataset label is an optional area for continuation of the VICAR label.

For a more comprehensive discussion of dataset structure, refer to Section 9.1.

4.3.3 Pixel Data Formats

Each sample of a dataset contains the same number of bytes, as defined by the FORMAT item in the VICAR label (Section 9.2). The allowed values for FORMAT and the characteristics of these pixel format types are defined in the following table.

			Table 4.3.3 

Bytes Bits Format per per Description Sample Sample BYTE 1 8 unsigned, binary integer (data range: 0 to 255) HALF 2 16 signed, binary integer (data range: -32,768 to +32,767) FULL 4 32 signed, binary integer REAL 4 32 floating point COMP 8 64 a pair of REAL values DOUB 8 64 double precision floating point

Note: There may still be a few programs which use the old convention of WORD instead of HALF, and COMPLEX instead of COMP. VICAR will continue to support these programs until they are converted to use the proper formats.

4.4 VICAR Labels

A VICAR label contains dynamic information that describes the size, origin, processing history and attributes of the associated dataset. All VICAR application programs are designed to read information from the VICAR labels of the input datasets and dynamically update them.

All VICAR datasets must be in "VICAR format" which means they are required to have a standard VICAR label in order to be processed. Data received from other facilities with "foreign" (non-VICAR) formats require a special purpose program, called a "logging" program, to read and convert the data into VICAR format (Section 8.3.3).

4.4.1 VICAR Label Structure

A VICAR label is an ASCII string composed of label items which are keyword=value pairs separated by spaces.

Syntax:

    keyword=value

	where:	 keyword   is a text keyword that identifies 
			    the label item

		 value	   is the information portion of the 
			    label item; may be of type string, 
			    integer, real, or double, and may be 
			    multi-valued
Examples: Possible keyword=value pairs.
NL=800
FORMAT='HALF'
SIZE=(1,1,800,800)
A VICAR label contains 3 different classes of keyword=value label items:

The system portion consists of those items that are independent of the history of the dataset. These items include: size of the image, its organization, its pixel format, host type and items indicating the existence of the optional sections of the dataset.

The property portion of the label contains items that describe properties of the image in the image domain, such as the map projection, lookup table, and latitude/longitude information.

The history label portion consists of information relating to the processing history of the data. Each time a program processes a dataset, VICAR adds history items to the label. The history items include: processing task name, user's identification, processing date and time. Thus, a sequence of subsets are recorded chronologically in the dataset label.

For a detailed description of the VICAR label structure, refer to Section 9.2. For examples explaining how to list labels, see Appendix 10.12.

4.5 Procs

When commanding VICAR, the user either issues intrinsic commands or invokes procedures or processes. Intrinsic commands are predefined operations used to manage a session. A procedure is a collection of VICAR commands that may be executed as one function. A process is a program which gets activated by VICAR.

Procedures and processes are collectively referred to as "procs" because they are identical in invocation syntax. Therefore, throughout this document "proc" will be used whenever it is not necessary to distinguish between procedures and processes (Section 7.3).


If you wish to return to the Contents page, click here.