
raw2viff(1)                  Khoros                   raw2viff(1)

PROGRAM
     raw2viff - Transforms RAW data into the VIFF file format.

SYNTAX
     raw2viff

     -i             input raw data file

     -o             resulting output image (viff file)

     -r             number of rows

     -c             number of columns

     [-l]           if yes the input file is supposed to be
                    interleaved; if no (default) it is considered
                    as not interleaved

     [-m]           increment factor for skipping rows

     [-n]           increment factor for skipping columns

     [-b]           specify the number of data bands in the image

     [-d]           specify the number of location bands or the
                    dimension

     [-h]           number of points to offset from the start of
                    the data file

     [-s]           number of points to offset from the first
                    point of each band

     [-t]           lets user choose output data type:
                     'byte' (choose byte data type),
                     'bit' (choose bit data type),
                     'short' (choose short data type),
                     'int' (choose integer data type),
                     'float' (choose float data type),
                     'complex' (choose complex data type),
                      or 'double' (choose double data type)
                       [default = byte]

     [-mt]          choose input data machine type:
                     'Local Machine' (choose machine type),
                     'DECstation' (choose machine type),
                     'Mips cpu, big endian mode' (choose machine
                    type),
                     'Encore, Sequent, NS32000' (choose machine
                    type),
                     'MIPS' (choose machine type),
                     'MC680x0' (choose machine type),
                     'Sun' (choose machine type),
                     'MacII' (choose machine type),
                     'NeXT' (choose machine type),
                     'Sony News' (choose machine type),
                     'Vax' (choose machine type),
                     'Cray' (choose machine type),
                     'Convex' (choose machine type),
                     'Apollo' (choose machine type),
                     'Silicon Graphics' (choose machine type),
                     'Titan' (choose machine type),
                     'IBM RT' (choose machine type),
                     'IBM032' (choose machine type),
                     'RISC 6000' (choose machine type),
                     'Motorola 88000' (choose machine type),
                     'hp9000' (choose machine type),
                      or 'Data General' (choose machine type)
                       [default = Local Machine]

     [-V]           Gives the version for raw2viff

     [-U]           Gives the usage for raw2viff

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     raw2viff is a comprehensive routine that transforms RAW data
     into a VIFF file format.  Since very little can be deter-
     mined from the input raw file it is left to the user to
     describe how the file is laid out.  This will in turn dic-
     tate how the VIFF file will be laid out.

     In describing the input raw file the user must consider
     whether the data is interleaved.  How many data (image)
     bands as well as location bands there are.  They must also
     consider how many rows and columns the image contains as
     well as header offset, band offset, increment factors, and
     data type.  The best way to explain these issues is to dis-
     cuss each topic and then to give some examples of different
     configurations.

     interleaved - This field is a boolean that describes if the
     raw data is interleaved or not.  If the data is not inter-
     leaved this means that each band of data is specified before
     the next band of data starts. ie)

                             x1  x2  x3  x4  x5 ....
                             y1  y2  y3  y4  y5 ....
                             z1  z2  z3  z4  z5 ....
                             w1  w2  w3  w4  w5 ....

     Each x point is given, then each y point, then each z point,
     and finally all w points are specified.

     If the data is interleaved that means that each set of
     points (from each band) is specified before the next set
     starts.  Data points are given as sets (pairs, triplets,
     etc). ie)

                             x1  y1  z1  w1
                             x2  y2  z2  w2
                             x3  y3  z3  w3
                             x4  y4  z4  w4
                             x5  y5  z5  w5
                                  ....
                                  ....

     number of rows & columns The user is required to specify the
     number of rows and the number of columns of the raw data.
     The rows times the columns indicates the size of the data to
     be extracted from the raw data file.  By specifying the
     number of rows or columns to be one, this indicates that the
     data is a 1D image or a single scan line.  By specifying the
     rows and columns greater than one the image is a 2D image or
     multiple scan lines.  You can specify either one as zero and
     an attempt will be made to determine the size.

     data bands This field describes the image data band.  For an
     implicit image, an image with implied location, this would
     be the image pixel values.  For example, if the raw input
     file consisted of three bands (triplets) which were Red
     Green Blue values then each of these would be considered a
     data band.  Each of the fields (Red,Green,Blue) represent a
     different set of values.  The fields do not interrelate to
     make one value, each can be represented with out the other
     values being present.  Although, this does change the
     overall meaning of the image.

     location bands The location data bands provide the data
     bands with a direction.  The location data can be considered
     the vector for some data band value.  This means that it can
     use the location data to position the data band values in
     space.  This is useful in describing sparse images, where
     the user may not want to describe every point within an
     image, just the ones that have a value. For example, if the
     raw input file consisted of three bands (triplets) which
     were X, Y, Z points to be plotted.  They would specify that
     the file contained two location bands and one data band.
     The X, Y fields would be used for describing the location
     for the value Z.  This configuration is typically used to
     plot 3D data with xprism3.  For a 2D plot we would have one
     location band, X, and one data band, Y.

     NOTE:  raw2viff expects the location data  bands to be before the data
            bands.  Thus, if we had an interleaved raw input file with three
            location bands and two data bands the file would be in the following
            format:

                     Location1  Location2  Location3  Data1  Data2    (first  point)
                     Location1  Location2  Location3  Data1  Data2    (second point)
                                            .....
                     Location1  Location2  Location3  Data1  Data2    (last   point)

     header offset The header offset should be used to offset a
     certain number of bytes from the beginning of the file.
     Thus, if you wish to skip the first 100 bytes of the file
     you would specify the header offset as 100.

     band offset The band offset should be used to skip a certain
     number of points from each band of data.  Thus, if you wish
     to skip the first 50 sets of data points then you would
     specify the band offset to be 50.  This provides the user
     with a flexible way of selecting exactly what part of the
     file they wish to convert to VIFF format.

     Row & Column increment factor The row and column increment
     factor allows the user to sub-sample the data before con-
     verting it to a VIFF file.  The default is an increment fac-
     tor of one for both rows and columns, which will read every
     point starting from the band offset.  If you wish to read
     every fourth row and column then the increment factor should
     be set the row and column increment factor to four.  If you
     wish to read every third row and fifth column then you would
     set the row increment to three and the column increment to
     five.

     data type The data type is used to indicate what type of
     data the raw file has in it.  The raw data file can be any
     of the following types: byte, short, integer, float, or com-
     plex format.  The VIFF file that is created will be of the
     same type.  Thus, if the raw data file is of type short,
     then the resulting VIFF type will  also be of type short.

     machine type This toggle selection allows the user to
     specify the machine the raw data originated on. The selec-
     tion "local machine" refers to the current machine the user
     is working on. The raw data will be converted from the
     specified machine type to the local machine type before
     creating the VIFF output image.

REQUIRED ARGUMENTS
     -i     type: infile
            desc: input raw data file

     -o     type: outfile
            desc: resulting output image (viff file)

     -r     type: integer
            desc: number of rows

     -c     type: integer
            desc: number of columns

OPTIONAL ARGUMENTS
     -l     type: boolean
            desc: if yes the input file is supposed to be inter-
            leaved; if no (default) it is considered as not
            interleaved
            default: false

     -m     type: integer
            desc: increment factor for skipping rows
            default: 1
            bounds: value >= 0

     -n     type: integer
            desc: increment factor for skipping columns
            default: 1
            bounds: value >= 0

     -b     type: integer
            desc: specify the number of data bands in the image
            default: 1
            bounds: value > 0

     -d     type: integer
            desc: specify the number of location bands or the
            dimension
            default: 0
            bounds: value >= 0

     -h     type: integer
            desc: number of points to offset from the start of
            the data file
            default: 0
            bounds: value >= 0

     -s     type: integer
            desc: number of points to offset from the first point
            of each band
            default: 0
            bounds: value >= 0

     -t     type: string
            desc: lets user choose output data type
            allowed values:
             'byte' (choose byte data type),
             'bit' (choose bit data type),
             'short' (choose short data type),
             'int' (choose integer data type),
             'float' (choose float data type),
             'complex' (choose complex data type),
              or 'double' (choose double data type)

     -mt    type: string
            desc: choose input data machine type
            allowed values:
             'Local Machine' (choose machine type),
             'DECstation' (choose machine type),
             'Mips cpu, big endian mode' (choose machine type),
             'Encore, Sequent, NS32000' (choose machine type),
             'MIPS' (choose machine type),
             'MC680x0' (choose machine type),
             'Sun' (choose machine type),
             'MacII' (choose machine type),
             'NeXT' (choose machine type),
             'Sony News' (choose machine type),
             'Vax' (choose machine type),
             'Cray' (choose machine type),
             'Convex' (choose machine type),
             'Apollo' (choose machine type),
             'Silicon Graphics' (choose machine type),
             'Titan' (choose machine type),
             'IBM RT' (choose machine type),
             'IBM032' (choose machine type),
             'RISC 6000' (choose machine type),
             'Motorola 88000' (choose machine type),
             'hp9000' (choose machine type),
              or 'Data General' (choose machine type)

EXAMPLES
     The following example will produce a single band image.  The
     image is an implicit image (no location data) with one band
     of 64 by 64 float point values.
       % raw2viff -i raw_file -o image_file -c 64 -r 64 -b 1 -t
     float

     The following example will again produce a single band
     image, but offset 1024 points from the beginning of the file
     before reading the data.
       % raw2viff -i raw_file -o image_file -c 64 -r 64 -b 1 -h
     1024 -t float

     The following example will produce a single band image with
     two location bands.  The image is an explicit image (two
     location bands) with one band of (64 by 64) or 4096 float
     point values.  The data is also interleaved.  This is an
     example that could be used with xprism3 for plotting a three
     dimensional image.  The two location bands would be used as
     the x and y location information, where as the band data
     would be used as the z value.

     The data is expected to be in the following format (4096 "x
     y z" pairs):

       % raw2viff -i raw_file -o image_file -c 64 -r 64 -b 1 -d 2
     -l 1 -t float
             x1  y1  z1
             x2  y2  z2
             x3  y3  z3
                ....

     If the data was not interleaved then it would be in the fol-
     lowing format:

       % raw2viff -i raw_file -o image_file -c 64 -r 64 -b 1 -d 2
     -l 0 -t float
             x1  x2  x3  ....  x4095  x4096
             y1  y2  y3  ....  y4095  y4096
             z1  z2  z3  ....  z4095  z4096

     The following example will produce a single band image with
     two location bands.  The image is an implicit image with
     three band of (64 by 64) or 4096 float point values.  The
     data is also interleaved.  This is an example of how to
     input the RGB example described in the data band descrip-
     tion.

     The data is expected to be in the following format (4096 "x
     y z" pairs):

       % raw2viff -i raw_file -o image_file -c 64 -r 64 -b 3 -d 0
     -l 1 -t float
             R1  G1  B1
             R2  G2  B2
             R3  G3  B3
                ....

     If the data was not interleaved then it would be in the following format:

       % raw2viff -i raw_file -o image_file -c 64 -r 64 -b 3 -d 0 -l 0 -t float
             R1  R2  R3  ....  R4095  R4096
             G1  G2  G3  ....  G4095  G4096
             B1  B2  B3  ....  B4095  B4096

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

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

Khoros                    Release: 1.0                          1

