
spectrum(1)                  Khoros                   spectrum(1)

PROGRAM
     spectrum - An interactive signal/image classification sys-
     tem.

SYNTAX
     spectrum

     [-i]           input image filename

     [-l]           input legend filename

     [-fn]          Specifies the font for spectrum (use %
                    xlsfonts for available fonts)

     [-jr file.jp]  Creates a journal recording for spectrum

     [-jp file.jp]  Executes a journal playback for spectrum

     [-V]           Gives the version for spectrum

     [-U]           Gives the usage for spectrum

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called spectrum.ans
                    or file1

     [-a [file1]]   Uses spectrum.ans or file1 as the answer file

DESCRIPTION
     This program is an interactive application that aides the
     user in classifying image data.  An image may be displayed,
     and then pixels in the image assigned to class categories;
     for identification, class categories are given a name and an
     unique color.   A class category may contain as many pixels
     as desired; pixels may be moved from one category to another
     as desired.  When the classification procedure is complete,
     a legend file may be written out for later use.

INPUT VIFF IMAGES
     Spectrum takes a VIFF file as input;  in most cases, the
     input image is pre-processed with clustering algorithms so
     that when the image is displayed, it has already been
     clustered as desired.  The map data of the input VIFF image
     contains the information needed by spectrum to display the
     clustered image;  this data is frequently referred to as the
     codebook.  The map data (codebook information) of the VIFF
     image must be stored as follows:

                                       codebook info stored in
     VIFF map
       |-----------|               |---------
     ---------------------------------|
       |        | 2|-------        |  .  .  .  |  |  |        | d
     |          |
       |cluster ---|       ---------->.  .  .  | c| c|        | i
     |          |
       | numbers   |               |  .  .  .  | o| l|        | a
     |          |
       | stored    |               |mean vector| u| a|        | g
     |          |
       | in VIFF   |               |  .  .  .  | n| s| covar  | o
     |          |
       | imagedata |               |  .  .  .  | t| s|        | n
     |          |
       |           |             | |  .  .  .  |  |  |        | a
     |          |  |
       |  values   |             | |  .  .  .  |  |  |        | l
     |          |  |
       | 0 - (m-1) |             V |  .  .  .  |  |  |        |
     |          |  V
       |-----------|             m |---------
     ->n----------------------------->N  M

     N = # cols in entire map (image->map_row_size)
     M = # rows in entire map (image->map_col_size)

     n = #columns in mean vectors = vector dimension = image-
     >ispare2
     m = # mean vectors total = M  (image->map_col_size)

     Usually, the image data is pre-clustered before use as input
     to spectrum. The imagedata of the VIFF image is made up of
     cluster numbers.  If the range of cluster numbers is between
     0 and 255, the cluster numbers will match 1-to-1 with the
     pixels on an 8-plane display;  if the range of cluster
     numbers lies outside the (0 - 255) range, an mapping algo-
     rithm must be used to match cluster numbers with one of the
     available pixels on an 8-plane display (use of a 24-plane
     display eliminates this problem).

     The codebook information is stored in the VIFF mapdata.
     This information must consist of at least 3 columns of mean
     vector data -- these are the values that are originally
     displayed as Red, Green, and Blue values.  In fact, these
     columns of information may represent any pertinent informa-
     tion - land analysis application, for example, might have
     values representing healthy vegetation stored in column 0,
     values representing rock stored in column 1, and values
     representing moisture stored in column 2.  The number of
     mean vectors is m -- this value must be equal to M, the
     total size of each column in the map data.  The number of
     columns in each mean vector may be as large as desired -
     however, note that this number must always be stored in the
     VIFF header in image->ispare2.

     Following the mean vectors can be a varying amount of
     optional information.  This information includes a count
     column, a class column, a covariance matrix, or a covariance
     diagonal.  Note that the last two entries are mutually
     exclusive -- the codebook information may include a covari-
     ance matrix or a covariance diagonal, but never both.  The
     input VIFF image must have in its header the image->ispare1
     field set properly to indicate to spectrum which of these
     optional columns of information is present, if any.  The
     image->ispare1 field is set according to the following
     rules:

     0 0 0 0 0 0 - mean vectors only  (image->ispare2 = # columns
     in vectors)
     0 0 0 0 0 1 - a count column is present
     0 0 0 0 1 0 - a class column is present
     0 0 0 1 0 0 - covariance matrix (upper triangle)
     0 0 1 0 0 0 - covariance diagonal

     When an output image is created with spectrum, it will be
     identical to the input image with one important exception:
     the class column will be modified according to any classifi-
     cation that was done during the course of the program, thus
     enabling the user to save the classification information for
     later use.

LEGEND FILE
     A separate ascii file contains legend info, each line with 3
     pieces of information: the RGB triple, the associated text,
     and the class number.  As spectrum is used to classify the
     image data, a legend is kept internally, storing the name
     assigned to each class category, the RGB triple defining the
     color that it is currently displayed in, an identifying
     class number, and the cluster numbers that are currently
     assigned to that class. When desired, this information may
     be written out in the form of an ascii file; however, the
     cluster numbers associated with the class are not written
     out;  instead, these are saved in the class column of the
     image that should be output at the same time as the legend
     file.  Since it is the class column of the VIFF image's map
     data that is used to look up the cluster numbers that belong
     to each class (thereby endowing the legend file with mean-
     ing), it is imperative that the user keep output legend
     files and output VIFF images consistent with each other.

REQUIRED ARGUMENTS
     none

OPTIONAL ARGUMENTS
     -i     type: infile
            desc: input image filename

     -l     type: infile
            desc: input legend filename

EXAMPLES
SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lspectrum(3)

RESTRICTIONS
COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

