Provided by: via-bin_1.6.0-3_amd64 bug

NAME

       vconvert - convert an image's pixel representation

SYNOPSIS

       vconvert [-repn repn] [-option ...] [infile] [outfile]

DESCRIPTION

       vconvert  converts  Vista images to a specified pixel representation.  The images are read
       from an input file, converted to the representation specified by  the  -repn  command-line
       option, then written to an output file.

       vconvert  knows several ways of mapping input pixels to output pixels.  You can choose the
       mapping you want by means of a -map command  line  option.   If  you  don't  specify  that
       option,  however,  then  you'll  get  a  default  mapping that is usually appropriate. The
       default mapping is one that retains an image's appearance  as  accurately  as  possible  —
       i.e.,  a  particular  shade  of  gray in the input image will be mapped to nearly the same
       shade in the output image. Alternatively, you can use -map to specify some  other  mapping
       that  may  change  the  brightness  or contrast of an image while converting it to its new
       representation.

       The following describes, in some detail, the various mappings supported by vconvert.  Here
       the full range of pixel values capable of being represented in the source image is denoted
       [Smin,Smax]; the actual range of pixel values present  in  the  source  image  is  denoted
       [Amin,Amax];  and  the  full  range  of  pixel  values capable of being represented in the
       destination image is denoted  [Dmin,Dmax].  (For  float  and  double  pixels,  the  ranges
       [Smin,Smax]  and  [Dmin,Dmax] are taken to be [-1,+1].) Define Sabs = max ( |Smin|, |Smax|
       ), and similarly define Aabs. Then the various mappings supported by vconvert are:

       range   This is vconvert's default mapping, which preserves the appearance of an image. It
               maps  [-Sabs,Sabs] to [-Dmax,Dmax].  For example, a ubyte image is converted to an
               sbyte image by dividing each pixel value by 2.

       copy    This  copies  pixels  unchanged  without  scaling  them  according  to  their  new
               representation.  It  maps [-Sabs,Sabs] to [-Sabs,Sabs]. For example, a ubyte image
               is converted to an sbyte image by copying pixel values that are less than or equal
               to 127, and setting to 127 those that are greater than 127.

       opt1    This  enhances the contrast of an image while increasing all intensity levels by a
               constant multiple. It maps [-Aabs,Aabs] to [-Dmax,Dmax].

       opt2    This enhances the contrast of an image. It not only increases intensity levels  by
               a constant multiple, it also shifts the range of intensity levels by subtracting a
               constant term. The exact mapping depends on the values of Amin and Amax:

                 when Amin = Amax < 0     each destination pixel is Dmin.

                 when Amin = Amax = 0     each destination pixel is 0.

                 when 0 < Amin = Amax     each destination pixel is Dmax.

                 when Amin < Amax < 0     it maps [Amin,Amax] to [Dmin,-e].

                 when Amin < Amax = 0     it maps [Amin,0] to [Dmin,0].

                 when Amin < 0 < Amax     it maps [-Aabs,Aabs] to [-Dmax,Dmax].

                 when 0 = Amin < Amax     it maps [0,Amax] to [0,Dmax].

                 when 0 < Amin < Amax     it maps [Amin,Amax] to [e,Dmax].

               Here, e is 1 / (Amax - Amin + 1) if destination pixels are float or double, and it
               is 1 otherwise.

       opt3    This  enhances  the  contrast  of  an  image  but, unlike opt1 and opt2 it doesn't
               necessarily preserve the signs of pixel values. The exact mapping depends  on  the
               values of Amin and Amax:

                 when Amin = Amax < 0     each destination pixel is Dmin.

                 when Amin = Amax = 0     each destination pixel is 0.

                 when 0 < Amin = Amax     each destination pixel is Dmax.

                 when Amin < Amax         it maps [Amin,Amax] to [Dmin,Dmax].

       linear  This is an arbitrary mapping of the form:

                    destination-pixel := source-pixel * a + b

               where the values a and b are specified by command line options.

       When  floating  point  pixel  values  are  converted  to an integer representation each is
       rounded to the nearest integer after being mapped. Also,  if  a  destination  pixel  value
       falls  outside  the  range [Dmin,Dmax], it is set to Dmin or Dmax and a warning message is
       issued.

COMMAND LINE OPTIONS

       vconvert accepts the following options:

       -help          Prints a message describing options.

       -in infile     Specifies the Vista data file containing the images to be converted.

       -out outfile   Specifies where the converted images should be  written  as  a  Vista  data
                      file.

       -repn bit | ubyte | sbyte | short | long | float | double
                      Specifies  the  pixel  representation  to which images should be converted.
                      Default: ubyte.

       -map range | copy | opt1 | opt2 | op3 | linear
                      Specifies the mapping  of  input  pixel  values  to  output  pixel  values.
                      Default: range.

       -a a and -b b  Specify  the  values  a  and  b  to  be used when -map linear is the chosen
                      mapping.

       Input and output files can be specified on the command line or allowed to default  to  the
       standard input and output streams.

SEE ALSO

       VConvertImageCopy(3Vi), VConvertImageLinear(3Vi), VConvertImageOpt(3Vi),
       VConvertImageRange(3Vi)
       VImage(3Vi), Vista(7Vi)

AUTHOR

       Art Pope <pope@cs.ubc.ca>