
viff2pbm(1)                  Khoros                   viff2pbm(1)

PROGRAM
     viff2pbm - Converts a VIFF image to a PBM image.

SYNTAX
     viff2pbm

     -i             input viff image file

     -o             output resulting pbm file definition

     [-r]           File format: ASCII(0) or RAW(1)

     [-V]           Gives the version for viff2pbm

     [-U]           Gives the usage for viff2pbm

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     viff2pbm converts a VIFF image to a PBM image.  The VIFF
     image is converted to one of the six possible types of PBM
     format images depending on the characteristics of the VIFF
     input image, and the output data storage type selected.

     There are three basic categories of PBM file formats with
     two types in each category.  The three categories of PBM
     file formats are "pbm", "pgm", and "ppm".  Within each
     category it is possible to store the data as either "ascii"
     or "raw", thus there are a total of six types of PBM file
     formats.  The resulting data storage type is user selectable
     between "ascii" and "raw".  If no selection is made, the
     default is to type "ascii".  The three categories of PBM
     file formats are explained as follows:

       pbm - portable bitmap file format

             This file format is used as the lowest common
             deonominator monochrome file format.

             The header contains the following information:

                                  ascii          raw
                                  -----         -----
             Magic Number -         P1     or     P4

             Whitespace   -    (blanks, TABs, CRs, LFs)

             Width        -  formatted as ASCII characters in decimal.

             Whitespace   -

             Height       -  formatted as ASCII characters in decimal.

             Whitespace   -

             Data:
              ASCII (P1)  -  characters '1' (black) or '0' (white)
                             starting in top left corner and proceeding
                             from left to right.  No line should exceed
                             70 characters.  Whitespace in this section
                             is ignored.

              RAW (P4)    -  the bits are stored eight per byte, high
                             bit first and low bit last.  No whitespace
                             is allowed in this section.  These files
                             are eight times smaller than the ASCII (P1)
                             files.

             Comments     -  begin with a '#' to the next end-of-line.
                             May be placed anywhere in the header.

       pgm - portable graymap file format

             This file format is used as the lowest common
             deonominator grayscale file format.

             The header contains the following information:

                                  ascii          raw
                                  -----         -----
             Magic Number -         P2     or     P5

             Whitespace   -    (blanks, TABs, CRs, LFs)

             Width        -  formatted as ASCII characters in decimal.

             Whitespace   -

             Height       -  formatted as ASCII characters in decimal.

             Whitespace   -

             Max Value    -  formatted as ASCII characters in decimal.

             Whitespace   -

             Data:
              ASCII (P2)  -  characters specifying the gray value in
                             ASCII decimal.  These values may range
                             anywhere from 0 to the maximum gray value.
                             Each character is separated by whitespace,
                             and starts at the top left corner of the
                             graymap.  A value of 0 means black, and
                             the maximum value means white.  No line
                             should be longer than 70 characters.

              RAW (P5)    -  The gray values are stored as plain bytes
                             instead of ASCII decimal.  No whitespace
                             is allowed in this section.  Note that
                             values in this section are limited to
                             maxvalues less than or equal to 255.

             Comments     -  begin with a '#' to the next end-of-line.
                             May be placed anywhere in the header.

       ppm - portable pixmap file format

             This file format is used as the lowest common
             deonominator color image file format.

             The header contains the following information:

                                  ascii          raw
                                  -----         -----
             Magic Number -         P3     or     P6

             Whitespace   -    (blanks, TABs, CRs, LFs)

             Width        -  formatted as ASCII characters in decimal.

             Whitespace   -

             Height       -  formatted as ASCII characters in decimal.

             Whitespace   -

             Max Value    -  formatted as ASCII characters in decimal.

             Whitespace   -

             Data:
              ASCII (P3)  -  characters specifying the maximum color-
                             component value, in ASCII decimal.  Three
                             values are required to represent each pixel.
                             One value for each component of "r" "g" "b".
                             Each character is separated by whitespace,
                             and starts at the top left corner of the
                             pixmap.  The three values for each pixel
                             represent red, green, and blue respectively.
                             A value of 0 means that the color is turned
                             off and the maxvalue represents the maximum
                             intensity for that color. No line should be
                             longer than 70 characters.

              RAW (P6)    -  The gray values are stored as plain bytes
                             instead of ASCII decimal.  No whitespace
                             is allowed in this section.  Note that
                             values in this section are limited to
                             maxvalues less than or equal to 255.

             Comments     -  begin with a '#' to the next end-of-line.
                             May be placed anywhere in the header.

     The PBM file formats described above were created by Jef Poskanzer,
     Copyright (C) 1989.

     The user has control over the output image data type (ASCII or RAW),
     but the PBM file category depends on the characterisics of the input
     VIFF image.  That is, if the input image is BIT, then the output
     image is "pbm", however if the input image is BYTE, SHORT, or INTEGER,
     the output image may be either "pgm" or "ppm".  This depends on whether
     the input VIFF image is a 1 or 3 band image, and has a color map.
     If the VIFF image is multiband, then the output image will be "ppm".
     If the VIFF image is 1-band, then the output image will be "pgm",
     unless a color map is present, in which case the output image will be
     "ppm".

     The acceptable VIFF input data types are BIT, BYTE, SHORT, or INTEGER.
     The input VIFF image may be either 1-band or 3-band, and contain a
     map scheme of NONE, SHARED, or ONEPERBAND.  If the input image contains
     a map, then the data will be mapped through the maps prior to conversion
     to a PBM file format.

REQUIRED ARGUMENTS
     -i     type: infile
            desc: input viff image file

     -o     type: outfile
            desc: output resulting pbm file definition

OPTIONAL ARGUMENTS
     -r     type: boolean
            desc: File format: ASCII(0) or RAW(1)
            default: false

EXAMPLES
     viff2pbm -i image.xv -o image.pbm

     this will convert the VIFF image "image.xv" to a PBM image
     "image.pbm" and store the data as "ascii", the default.

     viff2pbm -i image.xv -o image.pbm -t 1

     this will convert the VIFF image "image.xv" to a PBM image
     "image.pbm" and store the data as "raw".

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lviff2pbm(3)
     pbm2viff(1)

RESTRICTIONS
     will only work on BIT, BYTE, SHORT, or INTEGER images.

     will only accept VIFF images with bands = 1 or bands = 3,
     since PBM format will only handle bitmap, gray, or rgb color
     images.

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

Khoros                    Release: 1.0                          1

