
SPECTRUM(HELP)               Khoros                SPECTRUM(HELP)

     INPUT / OUTPUT SUBFORM

     The "Input/Output" subform allows you to read in VIFF images
     to be classified, write out VIFF images that have been clas-
     sified, read in legend files and write out legend files.

     VIFF FILES AS INPUT TO SPECTRUM

     Input files to spectrum must be VIFF images with image data
     of type BYTE.  They will fall into one of two categories:

     (1)  pre-clustered byte images with float "codebook" infor-
          mation stored in the map

     (2)  "normal" byte images that have no map

                ------------------------------------------
                           Pre-clustered Images

     Here, the cluster numbers of the pre-clustered image are
     stored in the byte image data of the VIFF image, and the
     float "codebook" values (additional columns of information
     obtained from the pre-clustering algorithms) are stored in
     the map data of the VIFF image.  Cluster numbers serve as
     indices into the codebook.  All columns of the map data must
     be of the same length, and there should be one row of map
     data for each cluster number. A maximum of 256 cluster
     numbers may be used at this time.  The imagedata must be of
     type BYTE, and the map data of type FLOAT.  Map data values
     may vary between 0 and 255 at this time.  One of the spare
     VIFF fields, ispare1, is be used to indicate the layout of
     the clustering information in the VIFF map data.

     The minimum required map information for pre-clustered
     images is the cluster center vectors (mean vectors).  Mean
     vectors may reflect any features of the clustered image that
     are of interest.  For instance, in a geological application,
     there might be 6 columns of map data where the first column
     stored values indicating the amount of water for that clus-
     ter, the second column stored values about the type of soil
     for that cluster, the third column stored values about the
     amount of vegetation for that cluster, and so on. When spec-
     trum run, three of these columns will be displayed at any
     given time; one will be represented as the red values in the
     colormap of the image, another as the green values, and the
     third as the blue values.  At any time, you may select which
     of the map columns you wish to display as which color;
     alternatively, you may elect to display a function of the
     values in the map columns as red, green, and/or blue (for
     more details, see the section on Display).

     If desired, the map information may also include a count
     array (in which the cluster number indexes the number of
     occurrances of that cluster number), a class array (in which
     the cluster number indexes the number ID of class category
     to which that cluster belongs, -1 if it is not assigned to a
     class), a covariance matrix (upper triangle) of the mean
     vectors, or a covariance diagonal of the mean vectors.  Note
     that the presence of a covariance matrix is mutually
     exclusive with the presence of a covariance diagonal; nei-
     ther the covariance matrix or the covariance diagonal is
     currently used by spectrum.  The total number of columns in
     the mean vectors must be provided in ispare2.  This number
     must be less than or equal to 256.  If ispare2 is zero,
     spectrum will assume that you have no codebook information
     (see "Normal" images).

     The VIFF structure's ispare1 integer field contains a mask
     that indicates the presence of a count array, a class array,
     a covariance matrix, or a covariance diagonal, when any of
     these elements are present.  Provide values for ispare1
     according to the information present in the map data, using
     the following values, which may be OR'ed together:
              0 0 0 0 0 0 - mean vectors only
              0 0 0 0 0 1 - count
              0 0 0 0 1 0 - class
              0 0 0 1 0 0 - covariance matrix (upper triangle)
              0 0 1 0 0 0 - covariance diagonal

     For example, image->ispare2 = 5 means that in addition to
     mean vectors, you have a covariance matrix (which will be
     ignored by spectrum) and a count column.  When the image is
     written out, spectrum will add in the class column, but
     leave the mean vectors, count column, and covariance matrix
     unchanged.

     The following diagram illustrates the layout of the codebook
     information as stored in the map data:

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

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

     n = #columns in mean vectors = vector dimension
       = image->ispare2

     m = # mean vectors total = M  (image->map_col_size)

     Notes:

     (a)  The order of the map columns MUST be as specified in
          the picture above.  All columns MUST be of the same
          size.  You specify which columns are present in your
          map data by using the mask described above in image-
          >ispare1.  For example, your map data might contain 5
          map columns of length 255, but nothing else.  In this
          case, N = n = image->ispare2 = 5;  M = 255;  and
          image->ispare2 = 0. Or, you might have  5 map columns
          of length 255 and a class column.  Again, in this case,
          n = image->ispare2 = 5, and M = 255; but now N = 6 and
          image->ispare2 = 2.

     (b)  Spectrum will create a count column and a class column
          for you if they do not exist, which will be written out
          when the image is output (with image->ispare2 set
          accordingly).  Spectrum will NEVER change the values in
          the other columns.

                ------------------------------------------
                              "Normal" Images

     Spectrum will also work with images that have not been pre-
     clustered, and therefore have no additional "codebook"
     information.  In this case, the image to be input must not
     have a map already associated with it -- ie, image-
     >map_scheme must be VFF_MS_NONE.  Spectrum will create three
     "mean vectors" for such an image;  that is, the number of
     pixels used in the image will be counted, and three identi-
     cal map columns of that size will be created with incremen-
     tal values.
              ------------------------------------------

     VIFF FILES OUTPUT FROM SPECTRUM

     When an image is written out with spectrum, the image data
     that was read in originally is written out untouched.  The
     header is written out as it came in, with the following
     modifications:  the color space model will be VFF_CM_NONE,
     the map scheme will be VFF_MS_NONE, and the map enable will
     be VFF_MAP_OPTIONAL.  The map data will contain the original
     mean vectors.  If there was a count column input, that count
     column will remain unchanged; otherwise, the count column
     will be automatically generated by spectrum.  In either
     case, the count column will be output as part of the map
     data, following the mean vectors.   The class column will be
     output according to the current class categories when the
     image is output.  Usually, a legend file should also be out-
     put at the same time, as the legend information and the
     class column together completely define the class categories
     at any given time.  If either a covariance matrix or a
     covariance diagonal was provided as part of the input map
     data, this information will be written out untouched.

     LEGEND FILES AS INPUT AND OUTPUT

     The legend file used by spectrum is a simple ascii file, in
     the following format:

     R G B 'title of class category' class_id

     The legend file, together with the class column that is
     maintained by spectrum, completely describe the class
     categories defined at any given time.  The class category
     consists of n entries, where n is specified in the input
     image with image->ispare1.  The index into the class column
     is the cluster number;  the entry it indexes is the class id
     of the class category to which that cluster number belongs.
     The class id is generated internally by spectrum, in order
     of creation. For instance, suppose cluster number 11 (pixel
     value 11) has been assigned to the fifth class category,
     named "vegetation".  Thus, class_column[11] = 5.  Suppose
     further that the "vegetation" category has been given the
     color green - RGB values of [0 255 0].  The legend file, if
     written out, will have the entry:

     0 255 0 'vegetation' 5

     Note that in order to save the image exactly as it appeared
     when it was written out, it is necessary to write out both
     the legend file (giving the color, title, and class id) and
     the image (which will specify the class column listing which
     cluster numbers belong in the "vegetation" class).  Later,
     to restore spectrum to its previous state, it is necessary
     to read in both the legend file and the image that were
     written out earlier.

     If a legend file is read in with one or more entries that do
     NOT have any associated clusters in the class column (eg, if
     we read in the legend file with the entry above but had not
     yet assigned five classes) this will be indicated by the
     colorboxes in the Legend display appearing in white (indi-
     cating an empty class).  On the other hand, the class column
     of the image has entries that are NOT matched with an entry
     in the legend file (eg, if we have assigned classes in the
     image that do not have entries in the legend file), this
     will be indicated by the titles in the Legend display
     appearing as "Unassigned class category ID", where ID is the
     class id automatically generated by spectrum.

     OUTPUT OF COLOR MAPS

     Note that the description of output images (above) makes no
     accomodation for output of colormaps.  The location where
     the colormap is usually stored in a VIFF image (the map
     data) has already been used for the "codebook" information.
     Thus, images output from spectrum may or may not be usable
     with display routines such as editimage and putimage, and
     even if it is is possible to use these programs to display
     such images, they will not have the colormap that you saw
     when using spectrum.  Therefore, you must use the special
     methods provided for writing out the image with its colormap
     (instead of its "codebook" data), or writing out the color-
     map by itself (to save space).

     USE OF THE INPUT / OUTPUT SUBFORM

     Input a new image to spectrum (with or without codebook
     data, as described above) by filling out the "Input File:"
     input file parameter box (that appears under the "Khoros
     Image Files (VIFF)" label) with the desired filename and
     hitting <cr>.

     Output an image with its mean vectors, count column, class
     column, (and covariance matrix/diagonal, if applicable) by
     filling out the "Output File:"  output file parameter box
     (that appears under the "Khoros Image Files (VIFF)" label)
     with the desired filename and hitting <cr>.

     Input a new legend file to spectrum by filling out the
     "Input File:" input file parameter box  (that appears under
     the "Legend Files" label) with the desired filename and hit-
     ting <cr>.

     Output a legend file by filling out the "Output File:" out-
     put file parameter box  (that appears under the "Legend
     Files" label) with the desired filename and hitting <cr>.

     Output the currently displayed image with its colormap as it
     appears on the screen by filling out the "Output Image &
     Colormap:"  output file parameter box  (that appears under
     the "Colormap Output" label)  with the desired filename and
     hitting <cr>.

     Output the colormap as it appears on the screen, without the
     image data, by filling out the "Output Colormap Only:"  out-
     put file parameter box  (that appears under the "Colormap
     Output" label)  with the desired filename and hitting <cr>.
     Note that the colormap can be transferred to an image later
     on by using the vmapxfer program;  this is a convenient way
     to save a colormap associated with the image without wasting
     the memory neccessary to save the image data twice (once
     with the "codebook" data, and once with the colormap).

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

Khoros                    Release: 1.0                          1

