
vcmtrans(1)                  Khoros                   vcmtrans(1)

PROGRAM
     vcmtrans - Linear color space conversions with a specified
     3x3 matrix

SYNTAX
     vcmtrans

     -i1            input image

     -i2            input conversion image

     -o             output resulting image

     [-n]           specifies normalization factor (default =
                    255)

     [-V]           Gives the version for vcmtrans

     [-U]           Gives the usage for vcmtrans

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     vcmtrans will take a multi-spectral input image and output
     an image of color space model GENERIC by applying a user
     specified color space conversion matrix.

     The input image must be of data storage type FLOAT, and con-
     tain three data bands. The color space model for the input
     image can be set to any type.  The input image will be nor-
     malized by the value specified by the -n option. The default
     is 255.

     The second input image specifies the transformation matrix.
     This image  must be of data storage type float and must be a
     3x3 image. The format of this image must be:

        { 11, 12, 13 }
        { 21, 22, 23 }
        { 31, 32, 33 }

     This image can be created using vcustom. It is important to
     remember that the input image will be normalized by the nor-
     malization option. The default is 255.0. The conversion is
     performed as follows:

     o    Band 1 of the input image is updated by:
          pixel = matrix[0][0]*(t1) + matrix[0][1]*(t2) +
          matrix[0][2]*(t3)

     o    Band 2 of the input image is updated by:
          pixel = matrix[1][0]*(t1) + matrix[1][1]*(t2) +
          matrix[1][2]*(t3)

     o    Band 3 of the input image is updated by:
          pixel = matrix[2][0]*(t1) + matrix[2][1]*(t2) + matrix[2][2]*(t3)
               where t1 = pixel from band 1
               where t2 = pixel from band 2
               where t3 = pixel from band 3

     When converting between the different color spaces, care
     must be taken in regards to the normalization factor. If the
     image had been scaled by using vscale, then the scale factor
     used in vscale should be the normalization factor used in
     this routine.  The resulting image should not be normalized
     by using vnormal, if the inverse transformation is desired.
     The data will be corrupted.  NOTE: The output values of some
     of the transformations will be negative, and some values
     will be greater than 1. If conversion to BYTE is desired,
     then a possible solution is:

     1.   use vbandspt3 to obtain 3 grey level images

     2.   use voffset to offset the image by the maximum negative
          value.  The offset value will most likely be different
          for each of the three images.

     3.   use vstats to get the maximum pixel value in the image
          and divide that by the maximum desired pixel value.
          This gives the scale factor. (EX. 3.2/255 = scale fac-
          tor).

     4.   now use vconvert to scale (NOT NORMALIZE) by the com-
          puted scale factor and convert to BYTE.

     5.   vbandcomb can be used to create a multi-spectral image.

     The reverse of the steps above may be followed to obtain the
     original image (scale by the inverse of the scale factor).

     We really do not know what it means to manipulate this data
     as explained above, except to make it displayable?

REQUIRED ARGUMENTS
     -i1    type: infile
            desc: input image

     -i2    type: infile
            desc: input conversion image

     -o     type: outfile
            desc: output resulting image

OPTIONAL ARGUMENTS
     -n     type: float
            desc: specifies normalization factor (default = 255)
            default: 255
            bounds: value > 0.0

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

RESTRICTIONS
     The input image must be of data storage type FLOAT.  The
     user specified matrix image must have a data storage type
     for float.

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

Khoros                    Release: 1.0                          1

