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 ProcsIn 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>exitThe 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>showFor 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.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 LOGICALor
setenv
and alias
in UNIX.Syntax:
% setenv % aliasBEWARE 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.
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-valuedExamples: Possible keyword=value pairs.
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.