.NH 1 "INTRODUCTION"
.XS
\s12\*(SN  INTRODUCTION\s0
.XE
.sp 2
.PP
This chapter of the manual describes the source configuration
of the Khoros system and how it is managed in a development
environment.  An important goal in the design of Khoros has
been to create an environment that can change on a daily basis
but yet not fall apart. (Surprisingly, it works most of the time.)
The manager of the Khoros system will find this chapter useful,
as it provides information about the organization of the Khoros
system and on the utilities for installing and compiling the system.
.PP
Khoros is designed to work well in either a stand-alone environment 
or in a distributed environment.  Several tools are provided to help 
manage the Khoros system more efficiently.  Information is provided 
in this chapter on how to use the tools for different site configurations.
.PP
This chapter is organized into three sections.  Section A describes 
the organization of the Khoros directory structure, and gives a brief
explanation of the contents of each of the main directories in Khoros.  
Section B provides an overview of the Imake system necessary for installing and
compiling Khoros, including explanations on the use of the \fBimkmf\fP,
\fBmakemake\fP, and \fBmake\fP programs.  This is followed by section C, 
which provides information on building and maintaining the Khoros 
srcmach tree for the support of multiple machine architectures.
.sp 3
.NH 2 "ORGANIZATION OF THE KHOROS DIRECTORIES"
.XS
      \*(SN  ORGANIZATION OF THE KHOROS DIRECTORIES
.XE
.sp
.PP
An environment variable is used to define the path to the
top level of the Khoros directory. This environment variable is
termed \fBKHOROS_HOME\fP.

The Khoros directory structure is relatively complex because
it is designed to support both the development of new code (i.e. a 
working environment) and the distribution of the system.
The addition of new routines to Khoros is done in
separate directory structure called a \fItoolbox\fP. The 
directory structure of a toolbox is similar to the
directory structure of KHOROS_HOME.
The \fItoolbox\fP area is designed for the addition
of new routines provided by various users of Khoros outside of the
main development team.  Therefore all installation of new routines 
for Khoros should take place in the \fItoolbox\fP source tree, and
not in the KHOROS_HOME source tree.  
For more information on creating and installing new routines in 
your own \fItoolbox\fP, see Volume II, Chapter 1, specifically you should
read about \fIkraftsman, composer and kinstall\fP..
.PP
Please note that ANY ADDITIONS OR MODIFICATIONS TO THE KHOROS_HOME
SOURCE DIRECTORY WILL NOT ALLOW REVISIONS OR PATCHES TO BE MADE TO THE
KHOROS SYSTEM.
THE KHOROS_HOME SOURCE TREE SHOULD NOT BE CHANGED!
.PP
While not imperative for those who simply intend to utilize the Khoros
programs, it is most helpful for anyone who intends to add new programs
to Khoros to acquire an understanding of the Khoros system directory 
structure.
.bp
.LP
The following table provides a brief description of the Khoros system
directory structure.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
KHOROS SYSTEM DIRECTORY STRUCTURE
bin *:T{
.na
Location of Khoros binaries.  It may be set up as a symbolic link to binmach.
.ad
T}
binmach:T{
.na
Location of Khoros binaries if multiple machine architectures are supported.
For example, in binmach/ there may be directories of bindecmips, binsun4, etc.
.ad
T}
data:T{
.na
This directory contains sample data, plots and images.
.ad
T}
doc *:T{
.na
This directory contains "pop-up" help for xvroutines.
The files in doc are also used for creating the manual
sections located in manual/.
.ad
T}
dotfiles:T{
.na
The dotfiles directory provides the configuration files to 
run Khoros applications in a proper environment.
.ad
T}
include *:T{
.na
System include files are located in this directory.  See the descriptions
in README.h for a brief description of each file.
.ad
T}
lib *:T{
.na
Location of compiled libraries (.a's).  It may be set up as a symbolic 
link to libmach.
.ad
T}
libmach:T{
.na
Location of compiled libraries (.a's) if multiple machine architectures 
are supported.
For example, in libmach/ there may be directories of libdecmips, libsun4, etc.
.ad
T}
man *:T{
.na
Contains the man1 and man3 directories for "on-line" documentation on 
how to execute a program.  (Accessed using \fBvman\fP.)
.ad
T}
manual:T{
.na
This directory contains the documentation that is intended to be printed.
.ad
T}
repos *:T{
.na
A repository of all Khoros default files, UIS files, 
configuration mach files, and all template files for the Imake system.
.ad
T}
src *:T{
.na
The Khoros source tree is located here.
.ad
T}
srcmach:T{
.na
This directory is used for symbolically linked source trees
if multiple machine architectures are supported.
For example, in srcmach/ there may be directories of srcdecmips, srcsun4, etc.
.ad
T}
.TE
.sp 1
.LP
* These directories also present under {toolbox name}.
.sp 1
.PP
To run Khoros, a \fIminimal\fP system requires the contents of bin, repos, 
man, and doc.  It is likely that you will also want a data directory for 
examples.  If you plan on doing development within Khoros, you will also
need the contents of lib, include, and src.  
More detailed information about the contents and organization of the data, 
repos, and src directories are provided in the sections that follow.
.bp
.NH 3 "The Data Directory"
.XS
              \*(SN  The Data Directory
.XE
.sp
.PP
The \fIdata\fP directory contains images, kernels, look up tables,
masks, and overlays that may be used as sample input data.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
THE DATA DIRECTORY
annotate:T{
.na
Annotation files for \fBeditimage\fP, \fBxprism2\fP and \fBxprism3\fP.
.ad
T}
bitmaps:T{
.na
A couple of X bitmaps created with \fBviff2xbm\fP, suitable for icons.
.ad
T}
images:T{
.na
An assortment of VIFF (visualization/image file format) files.
.ad
T}
kernels:T{
.na
VIFF images appropriate for convolution.
.ad
T}
lut:T{
.na
An assortment of VIFF (visualization/image file format) files that have
interesting color maps.
.ad
T}
masks:T{
.na
Masks that can be used for the shape, clip and overlay functions in the
interactive display programs.
.ad
T}
morphokernel:T{
.na
VIFF images appropriate for morphology routines.
.ad
T}
plot_functions:T{
.na
Equations and data that can be used in \fBxprism2\fP and \fBxprism3\fP.
.ad
T}
sequences:T{
.na
Image time sequences in VIFF format.
.ad
T}
signals:T{
.na
One dimensional real and complex VIFF format signals.
.ad
T}
warp_coeffs:T{
.na
Example VIFF images that contain warping coefficients for \fBvwarp\fP.
.ad
T}
.TE
.sp 2
.NH 3 "The Repos Directory"
.XS
              \*(SN  The Repos Directory
.XE
.sp
.PP
The repos directory is a repository of required files.
Primarily it contains the User Interface Specification (UIS) files for
xvroutines.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
THE REPOSITORY DIRECTORY
Conventions:T{
.na
This directory contains template pane files for \fBcantata\fP and guidelines
for creating a .pane file.
.ad
T}
animate:T{
.na
The UIS file for \fBanimate\fP.
.ad
T}
annotation:T{
.na
The UIS file for annotation subforms that are used by \fBeditimage\fP,
\fBxprism2\fP and \fBxprism3\fP.
.ad
T}
cantata:T{
.na
The UIS file for \fBcantata\fP is broken into subforms. Each subform file (.sub)
refers to pane files (.pane).  The cantata/subform subdirectory structure 
mimics that of the source directory structure.
.ad
T}
composer:T{
.na
The UIS file for \fBcomposer\fP, and an example .prog file.
.ad
T}
config:T{
.na
This directory contains the machine configuration and template files for the 
Imake system, OS and compiler specific installation scripts, and site 
specific mach files.
.ad
T}
.TE
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
THE REPOSITORY DIRECTORY
editimage:T{
.na
The UIS file for \fBeditimage\fP.
.ad
T}
fonts:T{
.na
Includes the various vector fonts used by \fBxprism2\fP and \fBxprism3\fP.  
These are required because the X fonts can not be resized or rotated.
.ad
T}
preview:T{
.na
The UIS file for \fBpreview\fP.
.ad
T}
utils:T{
.na
This contains copyright templates and module header templates.
\fBGhostwriter\fP uses several of the files.
.ad
T}
viewimage:T{
.na
The UIS file for \fBviewimage\fP.
.ad
T}
warpimage:T{
.na
The UIS file for \fBwarpimage\fP.
.ad
T}
workspace:T{
.na
Several demo and test workspaces illustrating some of \fBcantata's\fP
visual programming capabilities.
.ad
T}
xprism:T{
.na
The UIS files for \fBxprism2\fP and \fBxprism3\fP.
.ad
T}
journal:T{
.na
Journal playback files for demos of xvroutines.
.ad
T}
.TE
.sp 3
.NH 3 "The Source Directory"
.XS
              \*(SN  The Source Directory
.XE
.sp
.PP
Within the \fIsrc\fP directory there are many levels of subdirectories. 
These subdirectories were chosen to categorize functions with similar 
functionality.  For instance, you will find a \fILib\fP
directory at the top of source and also in dspl, file_formats,
num_analysis, remote_gis, vipl and xvroutines.  The top level \fILib\fP 
contains libraries that are needed across the system.  The lower level 
\fILib\fP directories contain source for libraries local to that
functional category.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
THE SOURCE DIRECTORY
Lib:T{
.na
This directory contains several libraries that are required by the
entire system.
.ad
T}
dspl:T{
.na
Similar to vipl, except it contains one dimensional signal processing
algorithms.
.ad
T}
file_formats:T{
.na
This directory contains a collection of programs for converting to
and from VIFF format.
.ad
T}
num_analysis:T{
.na
This directory contains programs for matrix manipulations.
.ad
T}
public_domain:T{
.na
This directory contains subdirectories which contain the
public domain software which are used by Khoros.
.ad
T}
remote_gis:T{
.na
This directory contains routines specific to remote sensing and GIS
applications.
.ad
T}
scripts:T{
.na
This directory contains subdirectories of csh script files used by 
Khoros.
.ad
T}
.TE
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
THE SOURCE DIRECTORY
tools:T{
.na
This directory contains subdirectories of programs used to manage 
the Khoros source tree.
.ad
T}
vipl:T{
.na
This directory contains all the image processing driver programs.
Within this directory, each subdirectory is dedicated to a 
a specific area of image processing. Below each of these is a 
subdirectory named for a specific program.
.ad
T}
xvroutines:T{
.na
This directory contains all source for xvroutines.
Below this is a Lib directory and a subdirectory for each program.
.ad
T}
bootstrap:T{
.na
Programs necessary to boot the Khoros system.  The programs in this
directory must be compiled before anything else can be compiled.
.ad
T}
.TE
.sp 1
.LP
To get a better understanding of how the \fIsrc\fP directory is arranged,
the following diagram is provided to graphically illustrate the src 
directories and some of their subdirectories.  Under \fIsrc\fP we have 
several subdirectories containing 1D and 2D data processing algorithms,
file format conversion routines, and remote sensing/GIS routines.
The categories were chosen to accommodate the broad spectrum of 
algorithms that exist in Khoros.
.bp
.DS
.ps 9
.vs 11
\f(CW
                      |-ghost----------
                      |-verror---------
      |-Lib-----------|-vexpr----------
      |               |-vgparm---------
      |               |-*
      |
      |               |-Lib------------
      |               |-filter_1Dfreq--
      |-dspl----------|-filter_1Dtime--
      |               |-info-----------
      |               |-*
      |
      |               |-Lib------------
      |-file_formats--|-no_format------
      |               |-remote_gis-----
      |               |-standard-------
      |
      |-num_analysis--|-Lib------------
      |               |-matrix_algebra-
      |
      |               |-eispack--------
      |               |-imake----------
      |-public_domain-|-linpack--------
      |               |-makedepend-----
      |               |-tiff-----------
|-src-|
      |               |-Lib------------
      |-remote_gis----|-surface--------
      |               |-vector---------
      |               |-warp-----------
      |
      |-scripts-------|-cantata--------
      |               |-tools----------
      |
      |               |-formatdoc------
      |               |-ghostcheck-----
      |-tools---------|-helppage-------
      |               |-imkmf----------
      |               |-*
      |
      |               |-Lib------------
      |               |-arith_binary---
      |-vipl----------|-arith_logical--
      |               |-arith_unary----
      |               |-*
      |
      |               |-Lib------------
      |               |-animate--------
      |-xvroutines----|-cantata--------
                      |-composer-------
                      |-*
                                         * - more directories follow
\fP
.DE
.bp
.sp 2
.NH 4 "The \f(BIsrc/dspl\fP Directory"
.XS
              \*(SN  The \fIsrc/dspl\fP Directory
.XE
.sp
.PP
The table below describes the taxonomy for the 1D data processing
algorithms.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
1D DATA PROCESSING ORGANIZATION
filter_1Dfreq:T{
.na
These routines operate on signals in the frequency domain.
.ad
T}
filter_1Dtime:T{
.na
These routines operate on signals in the time domain.
.ad
T}
info:T{
.na
These routines are designed to provide the user with information
about a signal.
.ad
T}
input_create1D:T{
.na
These routines generate a signal based on functions or user specifications.
.ad
T}
linearop1D:T{
.na
A collection of routines that provide "classical" linear theory operations.
They include convolution, correlation, etc.
.ad
T}
modify_seq1D:T{
.na
A collection of routines designed to manipulate signals or portions
of signals.
.ad
T}
spectest1D:T{
.na
These routines provide several methods for estimating the spectral
content of a signal.
.ad
T}
transform1D:T{
.na
These routines are used to go to and from the Fourier Domain and
perform operations in the Fourier Domain.
.ad
T}
.TE
.sp 2
.NH 4 "The \f(BIsrc/vipl\fP Directory"
.XS
              \*(SN  The \fIsrc/vipl\fP Directory
.XE
.sp 1 
.PP
Because of historical reasons, \fIvipl\fP forms the base set of the
data processing programs in Khoros.  The categories of num_analysis,
remote_gis, dspl, and file_formats have some dependencies on \fIvipl\fP.
.PP
The table below describes the taxonomy for the 2D data processing
algorithms.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
2D DATA PROCESSING ALGORITHM ORGANIZATION
arith_binary:T{
.na
These routines use two images to produce a single output
image.  They also may use a masking image to gate what is used
from one of the input images.  The operations are arithmetic
operations performed on a pixel by pixel basis from the two
images or signals.
.ad
T}
arith_logical:T{
.na
These routines perform logic operations on a pixel by pixel basis.
.ad
T}
arith_unary:T{
.na
These routines use one image to produce a single output image.
The operations performed are arithmetic point operations done on a
pixel by pixel basis.  Several of the operations may be used with
an optional masking image or signal.
.ad
T}
classify:T{
.na
These routines are used to perform supervised or unsupervised
classification.
.ad
T}
.TE
.br
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
2D DATA PROCESSING ORGANIZATION
convert_color:T{
.na
These routines use images with multiple bands representing a 
specific color to create images which are mapped into other 
color spaces.
.ad
T}
convert_compr:T{
.na
Currently includes only a driver for existing
compression algorithms.  The purpose is to reduce the
amount of data needed to store an image.
.ad
T}
convert_data:T{
.na
These routines change the data storage size/type of VIFF image.
.ad
T}
feature:T{
.na
These routines calculate various feature measurements of images.
.ad
T}
filter_2Dfreq:T{
.na
These routines operate on images in the frequency domain.
.ad
T}
filter_2Dspatl:T{
.na
These routines operate on images in the time domain.
.ad
T}
filter_morph:T{
.na
These routines operate in the spatial domain using morphology filters.
.ad
T}
geomanip:T{
.na
These routines alter the location of pixels in an image or signal
by expanding, shrinking, rotating, etc.
.ad
T}
histogram:T{
.na
These routines modify the histogram of an image or display the current
histogram of an image.
.ad
T}
info:T{
.na
A collection of routines designed to provide the user with information
about an image.
.ad
T}
input_create2D:T{
.na
These routines generate an image based on functions or user specifications.
.ad
T}
map:T{
.na
These routines manipulate the color maps of an image.
.ad
T}
output_dither:T{
.na
These routines convert images to a black pixel/white pixel image for
use on monochrome screens or printers without pre-dithering algorithms.
.ad
T}
output_print:T{
.na
These routines are used to format and send an image to a printer.
.ad
T}
segment:T{
.na
These routines are intended to define regions of an image as a function
of grey level pixel values.
.ad
T}
subregion:T{
.na
These routines are designed to extract and manipulate subimages.
.ad
T}
transform2D:T{
.na
These routines are used to go to and from the Fourier Domain
and perform operations in the Fourier Domain.
.ad
T}
.TE
.sp 2
.NH 4 "The \f(BIsrc/file_formats\fP Directory"
.XS
              \*(SN  The \fIsrc/file_formats\fP Directory
.XE
.sp
.PP
The following table describes the taxonomy for the file format 
conversion algorithms.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
FILE FORMAT ORGANIZATION
no_format:T{
.na
These routines are for converting ascii and raw images to VIFF
format, and from raw to VIFF format.
.ad
T}
remote_gis:T{
.na
These routines are for converting to and from the VIFF format
to remote sensing and GIS file formats.
.ad
T}
standard:T{
.na
These routines are for converting to and from the VIFF format
to several other popular file formats.
.ad
T}
.TE
.sp 3
.NH 4 "The \f(BIsrc/remote_gis\fP Directory"
.XS
              \*(SN  The \fIsrc/remote_gis\fP Directory
.XE
.sp 2 
.PP
The table below describes the taxonomy for the remote sensing
and GIS algorithms.
.sp
.TS
tab(:) allbox;
c s
lw(1.0i) lw(4.5i).
REMOTE SENSING AND GIS ALGORITHM ORGANIZATION
surface:T{
.na
A collection of routines designed to compute surface normals
and correct the illumination gradient in an image.
.ad
T}
vector:T{
.na
These routines manipulate the color maps and bands of dlg images.
.ad
T}
warp:T{
.na
These routines are for performing image registration of images.
.ad
T}
.TE
.br
